@polyweave/gatto-agent-harness (1.0.2)

Published 2026-07-10 23:46:27 +00:00 by Dvorak

Set up this registry in your project .npmrc file:

@polyweave:registry=https://hub.kl1.tenere.ai/api/packages/Polyweave/npm/

To install the package using npm, run the following command:

npm install @polyweave/gatto-agent-harness@1.0.2

or add it to the package.json file:

"@polyweave/gatto-agent-harness": "1.0.2"

For more information on the npm registry, see the documentation.

gatto-agent-harness

Task-level agent harness for Gatto — push-stream Duplex agent execution loop with tool registry. Integrates with @polyweave/jj-provider for per-BT-node workspace isolation.

Published as @polyweave/gatto-agent-harness.

Synopsis

import { createAgentHarness } from '@polyweave/gatto-agent-harness';

const harness = createAgentHarness({
  maxTurns: 50,
  tools: [myTool1, myTool2],
  jjProvider: myJjProvider,
  durability: { enabled: true, wrapperId: 'agent-1' }
});

harness.initialize({ workspace: myWorkspace, task: 'Build the component' });
harness.source.pipe(myOutputSink);
harness.start();

Install

npm install @polyweave/gatto-agent-harness

Description

The gatto-agent-harness provides a task-level agent execution loop built on Polyweave push-streams and observable state from @polyweave/core. An agent receives a workspace and task, iterates through turns using registered tools, and maintains observable state including history, status, and turn count.

The harness integrates with @polyweave/jj-provider for per-behavior-tree-node workspace isolation — each BT node gets its own agent harness instance with an isolated workspace. Optional durability via createObservableState provides wrapper-level state persistence for recovery.

Tools are managed through a tool registry that supports push-stream output buffering, backpressure, and async tool routing via @polyweave/tools. Frame constructors (createStartFrame, createTextFrame, createThinkingFrame, etc.) use the GattoFrameType enum for the Gatto-specific frame protocol.

API

`createAgentHarness(options)`

Creates a Gatto agent harness.

Parameters:

options.maxTurns — Maximum agent turns (default 100).
options.tools — Array of tool adapter objects to register.
options.jjProvider — JJ provider for workspace isolation.
options.durability — { enabled: boolean, wrapperId: string, wrapperType: string }.

Returns: An agent harness object with the following:

Properties

source — Push-stream source for output frames.
sink — Control sink accepting frames (TICK, CANCEL, ABORT, TOOL_CALL, etc.).
state — Observable state — subscribe to changes.
toolRegistry — The internal tool registry.

Methods

initialize({ workspace, task, nodeId, sessionId }) — Sets up the harness with workspace and task.
start() — Begins the agent execution loop.
stop() — Stops execution gracefully.
cancel() — Cancels execution.
abort(err) — Aborts execution with error.
getHistory() — Returns the agent's interaction history.
getStatus() — Returns current status: 'idle', 'running', 'done', 'error'.
registerTool(tool) — Registers a new tool in the registry.
dispose() — Cleans up resources.

`createToolRegistry(initialTools)`

Creates a push-stream-capable tool registry.

Parameters:

initialTools — Array of tool adapter objects to register initially.

Returns: A tool registry with { source, sink, registerTool, getTools, getTool, pause, resume, abort }.

`GattoFrameType`

Enum of Gatto-specific frame types: START, END, PARAM, DATA, PROGRESS, ERROR, TEXT, TOOL_CALL, TOOL_RESULT, THINKING.

Frame Constructors

createStartFrame(opts) — { type, streamId, content }
createEndFrame(opts) — { type, streamId }
createParamFrame(key, value, opts) — Parameter frame.
createDataFrame(data, opts) — Data payload frame.
createProgressFrame(payload, opts) — Progress update frame.
createErrorFrame(error, opts) — Error frame.
createTextFrame(text, opts) — Text content frame.
createToolCallFrame(name, args, opts) — Tool call frame.
createToolResultFrame(result, opts) — Tool result frame.
createThinkingFrame(text, opts) — Thinking/reasoning frame.

All frame constructors accept an optional opts object with streamId, id, timestamp.

Examples

// Subscribe to state changes
harness.state.subscribe((changes) => {
  console.log('State changed:', changes);
});

// With durability enabled for recovery
const harness = createAgentHarness({
  maxTurns: 25,
  tools: [shellTool, fileTool],
  durability: { enabled: true, wrapperId: 'task-42', wrapperType: 'gattoAgentHarness' }
});

harness.initialize({ workspace: ws, task: 'Fix the build errors' });
harness.sink.write({ type: 'START' });

harness.state.subscribe((changes) => {
  if (changes.status === 'done') {
    console.log('History:', harness.getHistory());
  }
});

Tests

npm test

Tests cover harness initialization, lifecycle (start/stop/cancel/abort), tool registration and execution through the tool registry, observable state subscription, history accumulation, frame construction, durability wrappers, and push-stream backpressure handling.

Requirements

Node.js 18 or later. ESM only.

Caveats

The harness is designed to be driven by push-stream frames (TICK, TOOL_CALL) rather than autonomous execution. External tick scheduling is required for step-by-step advancement.
JJ provider integration is optional; without it, workspace isolation is not enforced per BT node.
Durability relies on createObservableState from @polyweave/core. State is persisted only if the observable state wrapper supports it.

License

MIT

Dependencies

ID	Version
@polyweave/jj-provider	*
@polyweave/tools	*

Development Dependencies

ID	Version
@rigor/core	*

Peer Dependencies

ID	Version
@polyweave/core	*

polyweave gatto agent harness llm push-stream

Details

npm

2026-07-10 23:46:27 +00:00

John Dvorak

SEE LICENSE IN LICENSE

6.6 KiB

Assets (1)

gatto-agent-harness-1.0.2.tgz 6.6 KiB

Versions (3) View all

1.0.5

2026-07-11

1.0.2

2026-07-10

1.0.1