Agent behavior

This page collects the runtime behavior that affects an agent regardless of which API starts it. It describes the model-visible tool contract, queueing, context composition, cancellation, and terminal outcomes. Authoring types and signatures remain in the API reference.

SDK entry points

The default @fabric-harness/sdk entry point supplies documented headless defaults for finite agents. @fabric-harness/sdk/strict does not silently inject them: finite agents must configure their model and sandbox explicitly. Persistent createAgent() definitions render their resources for each delivered interaction on both entry points.

A session has one sandbox environment at a time. Without an executable/filesystem-capable sandbox, the corresponding built-in tools either are absent or fail capability discovery. Skills describe behavior but never grant filesystem, command, network, credential, or connector permissions.

Built-in tools

The model-facing built-ins are bounded even though host-side session.fs and SandboxEnv methods remain whole-file, programmatic APIs.

read

Parameters are path, optional offset, and optional limit. offset is a 1-indexed line number.

• Output contains at most 2,000 lines or 50 KiB, whichever is reached first.
• Ordinary lines are never split. Truncated output names the shown line range and the next offset.
• An offset past EOF is an error that includes the actual line count.
• If the first requested line alone exceeds 50 KiB, its first valid UTF-8 prefix is returned with a warning that the rest of that line cannot be reached through line-based paging.

write and edit

write replaces a file with the supplied string or bytes. edit performs exact text replacement using path, oldText, newText, and optional replaceAll.

Without replaceAll, oldText must occur exactly once. Zero matches report an exact-match error; multiple matches ask for more surrounding context. With replaceAll, every occurrence is replaced. Writes and edits targeting the same resolved path are serialized in dispatch order. Mutations to different paths remain concurrent. A shell process modifying the same path does not participate in this in-process lock.

bash

Parameters are command, optional cwd, env, and timeout in milliseconds.

• Combined stdout/stderr is bounded to the last 2,000 lines or 50 KiB while exit metadata remains available in the ShellResult.
• A tool-requested timeout is returned as recoverable exit code 124 so the model can react.
• A host cancellation still throws and ends the turn. If a remote process cannot confirm cancellation, the error says it may still be running and its eventual settlement is observed out of band rather than entering model context.

grep

Parameters are pattern, optional path, include, ignoreCase, literal, and maxMatches. The tool probes for rg once per sandbox and falls back to POSIX grep. Results contain file path, line number, and text. The framework returns at most 100 matches and 500 characters per result line, even if a larger maxMatches is requested.

glob

Parameters are pattern, optional cwd, and maxMatches. Patterns match file names rather than full paths, following find -name semantics. Results are deterministically sorted and capped at 1,000 paths.

Message admission and ordering

Persistent interactions are admitted durably as submissions before model work starts. Submissions for the same agent instance and named session are FIFO; separate sessions may run concurrently. One attempt owns a submission at a time through a fenced lease.

When a delivery arrives while a response is active, it may join at the next model-turn boundary. If it misses that boundary or joining is disabled, it remains queued as its own submission. A joined delivery records which host submission answered it, and tenant, actor, instance, and named-session boundaries are never crossed.

Every admitted submission reaches one canonical terminal outcome:

• completed — canonical work finished successfully.
• failed — a permanent error, exhausted retry budget, or execution timeout terminated the work.
• aborted — durable user/operator abort intent won before terminal settlement.

Terminal reservation and finalization are idempotent. A stale or orphaned attempt cannot overwrite the first canonical outcome.

Cancellation, timeout, and recovery

Cancellation propagates through the submission, session, model, tool, sandbox, and deployment adapter when those layers support signals. A signal-aware operation receives one macrotask to surface its own cancellation result. A signal-deaf tool is then abandoned: its late fulfillment or rejection is consumed, discarded, and cannot append output to terminal history.

A live submission cannot extend its execution deadline by heartbeating indefinitely. At the first observed timeout or durable abort, the coordinator signals the active attempt. If it still has not settled after 60 seconds, a storage-only supervisor rechecks ownership and force-settles it. Abort takes precedence over timeout when both are present; already-completed canonical work remains completed. Node and generated Cloudflare runtimes use the same observable state machine.

Context composition

At session initialization the runtime composes instructions from agent/session/call roles, with precedence call > session > agent. Roles are system-prompt overlays, not persisted user messages. The runtime also contributes the available tool, skill, subagent, and sandbox workspace context.

Dynamic resources are recalculated at model-turn boundaries. Changes are appended as resource signals so prior turns keep the instructions and tool set they actually observed. Conditional tool additions caused by a tool-result batch are anchored to that batch's final tool result for providers that support deferred tool loading; the marker is persisted so restart and replay build the same provider history.

Default SDK sessions use model-aware compaction near the context window, keeping recent messages verbatim and folding older history into a summary. Strict sessions compact only when explicitly configured. Deterministic Temporal paths apply their documented replay restrictions.

Telemetry and sensitive data

Submission, attempt, turn, and tool correlation metadata is available by default. Prompt, model, tool, and credential content remains opt-in and is sanitized before observer export. Settlement is a telemetry backstop: any span still open for that submission is closed with fabric.span.forced_close=settlement; normally closed spans do not carry the attribute.

Secrets are resolved only at the narrow trusted runtime boundary. Raw secret values must not enter model context, events, traces, checkpoints, generated projects, or terminal errors.

Target differences

Backend capabilities are discovered rather than assumed. Node, Cloudflare, Docker, Kubernetes, Databricks, and hosted sandboxes may differ in process, filesystem, network, persistence, snapshot, and cleanup support, but unsupported operations fail explicitly. See the capability matrix and sandbox matrix before relying on a backend-specific feature.