agentscope-harness

One-stop configuration for distributed and persistent storage components.

HarnessAgent is the user-facing harness API that wraps a `ReActAgent` with workspace / filesystem / sandbox / subagent / skill / plan-mode / MCP orchestration.

Controls how agent state is isolated and shared across calls.

A single artifact delivery request issued by the `deliver_artifact` tool.

Result of an `ArtifactDeliveryTarget#deliver` attempt.

SPI for delivering artifacts produced by an agent (typically inside a sandbox) to a destination outside the agent filesystem — the host, a project artifact store, an object store, WebDAV, etc.

Tracks the lifecycle of an async tool execution that has been offloaded to the background.

Registry for tracking async tool executions that have been offloaded to the background.

A single entry read from a `MessageBus` queue or log.

Live message transport for coordinating work across sessions and processes.

`AsyncToolRegistry` backed by `AbstractFilesystem`.

`MessageBus` implementation backed by `AbstractFilesystem`.

JVM-local `PeriodicGate` backed by a process-wide `ConcurrentHashMap` and CAS updates.

Coordinates periodic background work across callers (and optionally across nodes) using a minimum-gap throttle.

Distributed `PeriodicGate` backed by `BaseStore#putIfVersion`.

Abstract filesystem API for agents: list, read, write, edit, grep, glob, upload, download.

Filesystem wrapper that substitutes a fixed `RuntimeContext` on every delegated call, ignoring whatever RC the caller supplies.

Routes file operations to different `AbstractFilesystem` stores by path prefix.

A layered filesystem that overlays a user-specific "upper" layer on top of a shared "lower" layer, providing copy-on-write semantics.

Overlay variant that routes writes to the *project* directory for non-workspace paths, while keeping workspace metadata (memory, sessions, skills, etc.) in the upper (workspace) layer.

Prefix-routed filesystem that preserves shell execution on the primary sandbox backend.

`AbstractFilesystem` implementation that reads and writes files on the local disk.

Filesystem with unrestricted local shell command execution.

Result of a file edit (string replacement) operation.

Result of code/shell execution.

Data structure for storing file contents with metadata.

Result of a single file download operation.

Structured file listing info.

Result of a single file upload operation.

Result from abstract filesystem glob operations.

A single match from a grep search.

Result from abstract filesystem grep operations.

Result from abstract filesystem ls (directory listing) operations.

Result from abstract filesystem read operations.

Result of a file write operation.

`AbstractFilesystem` backed by a `BaseStore` (persistent, cross-thread).

Abstract interface for a namespace-based key-value store.

Thread-safe in-memory implementation of `BaseStore`.

Factory that produces a namespace tuple for `BaseStore` operations at call time.

A single item retrieved from a `BaseStore`.

Filesystem abstraction that adds shell command execution (sandbox or remote host).

Abstract base sandbox implementation with `#execute` as the core abstract method.

`SandboxBackedFilesystem` that holds a fixed `Sandbox` reference for the lifetime of the instance.

A `BaseSandboxFilesystem` that delegates execution to a live `Sandbox`.

Specification for the local filesystem mode (with shell execution).

Specification for the non-sandbox "composite" filesystem mode.

Declarative sandbox filesystem configuration.

Shared utility functions for filesystem implementations.

Registry and lifecycle manager for `Channel` adapters.

Gateway-style entrypoint: route inbound turns by `MsgContext`, and bind the primary `HarnessAgent` for announce delivery.

Multi-agent + channel routing bootstrap.

Default `Gateway` implementation.

Default single-process `SubagentRegistry`.

Process-local fair per-key mutual exclusion for gateway turns.

Routing context for inbound turns (direct API, channel adapter, group/room/thread).

Deterministic session-ID derivation.

Per-key mutual exclusion for gateway turns (user/channel inbound runs and subagent notification).

Distributed `SubagentRegistry` backed by a `BaseStore`.

Bridge between `io.agentscope.harness.agent.tool.AgentSpawnTool` and the gateway layer.

Rebuilds a subagent `Agent` instance from its type id.

Durable, recovery-oriented descriptor of an exposed subagent.

Durable registry of exposed subagents, keyed by `subagentId`.

Thrown when a session turn gate cannot be acquired because another turn holds the lock.

A handle representing an acquired session turn slot.

Per-process dispatcher that wakes idle sessions when background work completes.

Channel adapter — ingests inbound messages from one messaging platform (or a programmatic caller), routes them through `ChannelRouter` to resolve the target agent and session, and delegates execution to `Gateway`.

One routing rule that maps a set of inbound-message conditions to a target `agentId`.

Per-channel routing configuration: default agent fallback, DM session scope, and ordered binding rules evaluated by `ChannelRouter`.

Constructs a `Channel` instance from the resolved routing config and provider-specific properties.

Resolves the target `agentId` and stable `MsgContext` for an `InboundMessage` by evaluating `ChannelBinding` rules in deterministic priority order.

Inputs available to a `ChannelRuntimeContextResolver` when resolving caller context for a Gateway turn.

Resolves a caller-provided `RuntimeContext` for a Channel / Gateway turn.

Controls how DM (`PeerKind#DIRECT`) session keys are scoped.

Normalized inbound message produced by a `Channel` adapter before routing.

Delivery target for outbound (proactive) messages.

Identifies the conversation peer: who or what is being messaged (a user DM, a channel, a group, or a thread).

Classification of the conversation peer, used for session key construction and DM-scope resolution.

Output of `ChannelRouter#resolveRoute`: the resolved agent id, the `MsgContext` to pass to `io.agentscope.harness.agent.gateway.Gateway#run`, a diagnostic `matchedBy` label indicating which binding tier (or fallback) produced the result, and the `OutboundAddress` for delivering replies back to the originating channel/peer.

Default `Channel` implementation for direct Chat UI interactions: no external transport, no webhook, no websocket — the caller submits a `ChatUiRequest` programmatically and receives the agent reply reactively.

Request object for `ChatUiChannel`.

A buffered proactive outbound message delivered to `ChatUiChannel` by the gateway.

Routing identity for `ChatUiChannel` requests.

Tracks in-flight fire-and-forget memory background tasks (flush, maintenance) so `HarnessAgent.close()` can wait for them to quiesce before releasing resources.

Unified configuration for the long-term memory pipeline (flush + consolidation + maintenance).

LLM-based consolidation of daily memory ledgers into the curated `MEMORY.md`.

Manages memory flush operations: extracting long-term memories from a conversation window and appending them to today's daily memory ledger.

Configuration for conversation compaction (summarization).

Algorithm

Utility class for estimating token count in messages.

Configuration for per-tool-result eviction of oversized outputs.

Base class for all session tree entries (pi-mono-inspired JSONL session model).

Evaluates whether a session is still "fresh" or should be reset.

Independent writer for the session transcript JSONL (`.jsonl` / `.log.jsonl`).

Manages an append-only JSONL session tree (pi-mono-inspired).

Observability middleware that logs the reasoning and execution trace of an agent.

Middleware that offloads long-running tool calls to background execution.

Expands `@path` references in user messages by reading the referenced files through the active `AbstractFilesystem` and appending an `<attached_file>` block at the end of the message.

Middleware that performs conversation compaction before each LLM reasoning call.

Dynamic counterpart to `SubagentsMiddleware` that re-resolves the registered subagent set on every reasoning step, supporting per-user isolation through the workspace `AbstractFilesystem` (e.g.

Marker for middleware installed by harness runtime wiring.

Harness-native skill middleware.

Middleware that drains the message bus inbox before each reasoning step and injects the messages as `HintBlock`s into the agent's context.

Middleware that triggers memory flush and message offload at the end of each agent call.

Middleware that performs periodic memory maintenance after each agent call.

Enforces plan mode: while `AgentState.planModeContext.planActive` is `true`, mutating tool calls are denied so the agent can only read / investigate and draft a plan.

Middleware that manages the sandbox session lifecycle around each agent call.

Schedules `SkillCurator` runs after the main `call()` completes.

Bumps `SkillUsageStore` counters whenever the agent invokes a SkillBox-registered skill loader (e.g.

Descriptor for a subagent identified by agent id, with its description, `SubagentFactory`, and optional `SubagentDeclaration` (for remote URL and headers).

Middleware that provides the managed subagent mechanism.

Injects AgentTeams context into the system prompt and exposes a role-clipped `TeamTool`.

Middleware that evicts oversized tool results to the `AbstractFilesystem` before downstream reasoning sees the bloated message list.

Persists the conversation transcript at the end of every agent call.

Appends workspace context (session info, AGENTS.md, MEMORY.md, knowledge) to the system prompt via `#onSystemPrompt(Agent, RuntimeContext, String)`.

Abstract base implementation of `Sandbox` with the 4-branch workspace start logic.

Result of a sandbox command execution.

An active sandbox with a fully isolated workspace.

Result of acquiring a `Sandbox` from `SandboxManager`.

Marks a filesystem that can have its backing `Sandbox` injected at runtime.

Factory for creating and resuming `Sandbox` instances.

Base class for sandbox client configuration options.

Immutable configuration for sandbox behavior.

Error codes for sandbox operations, used in `SandboxException` and its subclasses.

Base exception for all sandbox operations.

Pluggable concurrency guard for sandbox execution slots.

Optional capability for `Sandbox` backends that support native (non-exec) file transfer, e.g.

Immutable key that uniquely identifies a sandbox state slot for a given `IsolationScope`.

A handle that represents a held execution right on a sandbox isolation slot.

Manages the lifecycle of `Sandbox` instances for the current call.

Serializable state of a sandbox, persisted by `SessionSandboxStateStore` so a sandbox can be resumed across calls.

Sandbox state store backed by the generic AgentScope `AgentStateStore` abstraction.

Securely extracts tar archives into a target directory.

Helpers for `io.agentscope.harness.agent.sandbox.layout.BindMountEntry` handling.

Builds a deterministic archive payload for workspace projection entries.

Describes the desired initial state of a sandbox workspace: root path, materialized file/directory entries, and per-exec environment variables.

Applies a `WorkspaceSpec` to a target directory by materializing declared entries (files, directories, local copies).

Sandbox filesystem spec for Docker store.

Docker `io.agentscope.harness.agent.sandbox.Sandbox` that runs commands in a container.

`SandboxClient` implementation for the Docker sandbox store.

Configuration options for the Docker sandbox client.

Serializable state for a Docker-backed `io.agentscope.harness.agent.sandbox.Sandbox`.

Registers Jackson polymorphic subtypes for `io.agentscope.harness.agent.sandbox.SandboxState`.

Declares a host directory (or file on Kubernetes) bind-mounted into the sandbox workspace at the map key path under `io.agentscope.harness.agent.sandbox.WorkspaceSpec#getRoot()`.

Layout entry that creates a directory, optionally with nested child entries.

Layout entry that creates a file with inline text content.

Layout entry that clones a Git repository into the sandbox workspace.

Layout entry that recursively copies a directory from the host filesystem into the sandbox workspace.

Layout entry that copies a single file from the host filesystem into the sandbox workspace.

Base class for entries in a `io.agentscope.harness.agent.sandbox.WorkspaceSpec`.

Layout entry that projects selected files/directories from host workspace into sandbox workspace when the `io.agentscope.harness.agent.sandbox.Sandbox` starts.

Snapshot that persists workspace archives as tar files on the local filesystem.

Snapshot spec that creates `LocalSandboxSnapshot` instances stored in a local directory.

No-op snapshot that does not persist anything.

Snapshot spec that creates `NoopSandboxSnapshot` instances.

Snapshot backed by a `RemoteSnapshotClient` (e.g.

User-implemented interface for uploading and downloading snapshot archives to/from remote storage (e.g.

Snapshot spec that creates `RemoteSandboxSnapshot` instances backed by a `RemoteSnapshotClient`.

Represents a persisted snapshot of a sandbox workspace.

Factory that creates `SandboxSnapshot` instances for a given session ID.

Optional marker for `io.agentscope.core.skill.repository.AgentSkillRepository` implementations that can supply a `SkillResources` accessor in addition to the in-memory `AgentSkill.resources` map.

Lazy resource accessor for a single skill.

`AgentSkillRepository` backed by an `AbstractFilesystem`, with lazy resource access via `LazyResourceCapable`.

Base class for visibility filters that should ONLY constrain agent-authored skills.

Visible only when the agent-created skill's name is in the allow-list.

Percentage-based rollout for agent-authored skills.

Chains multiple `SkillVisibilityFilter`s with AND semantics: the output is the intersection of every filter's output, applied in order.

Filter that admits a skill only when its sidecar's `environments` list contains the configured environment (`prod`, `staging`, …).

Single-replica HITL gate.

Pushes `SkillCandidate` metadata to an external system (Slack webhook, ticket service, Nacos config item, …).

Multi-replica gate.

Always returns `SkillPromotionGate.PromotionDecision.Defer` — promotion can only happen via an explicit `HarnessAgent.promoteSkill(...)` call from outside the gate.

Append-only audit log for the skill self-learning loop.

Material handed to a `SkillPromotionGate` when a draft skill is being considered for promotion.

Background skill maintenance orchestrator.

Configuration knobs for `SkillCurator`.

Persistent state for `SkillCurator` — kept in `skills/.curator_state.json`.

Orchestrates the promotion pipeline: locate draft → run security scan → call gate → physically move `_drafts/<name>/` to `skills/<name>/` → update sidecar.

Decides whether a draft skill is allowed to be promoted into the live skills directory.

Static-analysis scanner for SKILL.md and skill support files.

Per-skill operational telemetry plus enterprise-staging audit fields.

Sidecar telemetry store for per-skill usage and provenance.

Runtime gate that decides which skills are exposed to the model on a per-call basis.

Per-call wrapper around an `AgentSkill` carrying harness-only metadata that does not belong on the core data type.

Materialises non-workspace skill resources (Layer 1 / Layer 2 / marketplace) to `<wsRoot>/.skills-cache/<source-ns>/<skill-name>/` so that: - shell-mode HarnessAgents (sandbox or Local-with-shell) can execute the staged scripts via absolute paths - sandbox projection (which includes `.skills-cache` in `DEFAULT_WORKSPACE_PROJECTION_ROOTS`) hydrates the staged content into the sandbox at start time

Resolves the absolute `filesRoot` path emitted in `<available_skills>` and `load_skill_through_path` responses, given a skill's `StageResult` and the current shell mode.

Immutable snapshot of the skills visible to a single `onSystemPrompt` pass.

The harness-native `load_skill_through_path` `AgentTool`.

Renders the harness `<available_skills>` system-prompt block from a `SkillCatalog`.

Aggregates the singleton `SkillLoadTool` and the `SkillPromptBuilder`.

Loads `SubagentDeclaration` instances from Markdown files with YAML front matter placed in the `subagents/` directory of a workspace.

Pure agent factory and invoker — knows how to create agents from registered factories and invoke them with a prompt.

Policy for resolving a remote subagent's tool-confirmation (HITL) requests when the parent cannot forward the decision to an interactive human within this call.

Placeholder `io.agentscope.core.agent.Agent` for remote (`SubagentDeclaration`) subagents.

Declares a subagent: its identity, workspace resolution strategy, and optional capability allowlist.

Creates a new subagent instance for a single spawn or session.

LLM-driven generator for `SubagentDeclaration` markdown specs.

Controls how a declared subagent's runtime workspace root is determined.

Stable Protocol DTO for remote subagent event streaming.

User decision for a remote pending tool confirmation.

Bidirectional mapping between internal `AgentEvent`s and stable `RemoteAgentEvent` wire DTOs.

Stable wire event types for remote subagent streaming over Agent Protocol.

A single remote tool call awaiting user confirmation (HITL).

How much of a remote subagent's event stream the caller wants, sent as `context.detail`.

Minimal HTTP client for the internal AgentScope task protocol (`POST/GET /tasks/...`).

`RemoteSubagentTransport` backed by the Agent Protocol HTTP client.

Wraps a `CompletableFuture` to track background subagent task execution with status, result, error, and lifecycle metadata.

Transport abstraction for remote subagent execution (Agent Protocol today; A2A later).

Context sent with a remote task submission (permissions, streaming preferences, parent identity).

Remote endpoint identity: base URL plus optional auth/routing headers.

Status snapshot returned by the remote task HTTP API (`GET /tasks/{taskId}`).

Snapshot of a terminal-state subagent task awaiting (or undergoing) push delivery to the parent agent's reasoning loop.

Persistent metadata for a background subagent task, stored as JSON in the workspace under `agents/<parentAgentId>/tasks/<parentSessionId>.json`.

Repository for managing background subagent tasks, scoped by session.

Discriminated union describing how a background subagent task should execute.

Lifecycle status of a background subagent task.

Workspace-backed `TaskRepository` that uses `WorkspaceManager` as the authoritative truth source for task state, while maintaining in-memory `BackgroundTask` handles as a local performance overlay for tasks running on the current node.

`TeamClient` backed by `BaseStore` CAS (Claude file-lock equivalent).

Client for AgentTeams coordination (Claude-parity task board + mailbox).

Optimistic-lock / ownership conflict on the team task board.

Runtime context injected into a teammate session (mirrors Go TeamContext).

Spec for creating a local or CP-backed team.

Lightweight team record.

Team member roster entry.

Member seed for team creation.

Team mailbox message.

Shared team task board item.

Bridge from `TeamClient` implementations to whatever runtime owns teammate sessions.

Tool that generates a new subagent spec from a natural-language description and either persists it to `subagents/<name>.md` (where `io.agentscope.harness.agent.middleware.DynamicSubagentsMiddleware` will pick it up on the next reasoning step) or returns the markdown for human review.

Simple subagent tool for agent-internal use.

Agent-callable `deliver_artifact` tool: downloads a file from the agent filesystem (e.g.

File system tools backed by a `AbstractFilesystem`, exposing read/write/edit/grep/glob operations as agent-callable tools.

Tool for reading specific lines from memory files, typically used after `MemorySearchTool` to fetch surrounding context.

Dedicated tool for persisting user memories to both `MEMORY.md` and today's daily ledger (`memory/YYYY-MM-DD.md`).

Tool for searching through persisted memories (MEMORY.md and memory/*.md files).

The three model-facing tools that drive plan mode, all backed by a shared `PlanModeManager`.

Convenience tool that lets the agent propose a brand-new skill in one call: name + description + body + optional scripts.

Tool for searching past session transcripts and viewing session history.

Shell execution tool backed by a `AbstractSandboxFilesystem`.

Configuration for `SkillManageTool`.

Agent-callable tool that lets a `ReActAgent` create, edit, patch, and archive skills in its workspace.

Unified tool for background task lifecycle management.

Unified AgentTeams tool.

Tool that blocks until async results arrive, either for a specific task barrier or (legacy) until any message appears in the session inbox.

Builtin web tools (`web_fetch`, `web_search`) for Managed Agents / Harness.

Harness platform / orchestration tool names that `ToolFilter` must not strip via an ` allow` list.

A connection failure whose public message never contains endpoint credentials.

One MCP server entry under `mcpServers.<name>` in `tools.json`.

Registers MCP servers declared under `mcpServers` in `workspace/tools.json` into a `Toolkit`.

Receives the terminal result of an MCP server registration attempt.

Terminal result of registering one MCP server entry.

Applies the allow (`ToolsConfig#getAllow()`) / deny (`ToolsConfig#getDeny()`) lists from `workspace/tools.json` (or Managed Agents toolset export) against a `Toolkit`.

Workspace-level tool configuration loaded from `workspace/tools.json`.

Loads `workspace/tools.json` into a `ToolsConfig`.

`TranscriptStore` backed by a local / NAS filesystem directory.

`TranscriptStore` that writes immutable segment objects through `AbstractFilesystem` (S3/OSS/NAS/sandbox backends that implement upload).

Identifies a session transcript in a multi-tenant layout: `{tenant}/{agentId}/{sessionId}/...`.

Narrow append-oriented store for session transcripts.

Path-resolution policy mode for host-rooted filesystems (`io.agentscope.harness.agent.filesystem.local.LocalFilesystem` and friends).

Immutable allow-list of host directories that `LocalFsMode#ROOTED` accepts for absolute paths.

Path constants for the workspace directory structure.

Best-effort SQLite index for the local workspace.

Stateless accessor for workspace content using a two-layer read architecture.

Normalizes file paths to workspace-relative form by stripping the active mode's workspace prefix.

Coordinates plan mode for a single agent.