agentbox-sdk 0.1.503 → 0.1.511

package/README.md

@@ -115,6 +115,72 @@ for await (const event of run) {
 const result = await run.finished;
 ```
 
+Claude Code can leave work running after its turn ends (`run_in_background`
+shells, `Monitor`, background subagents, scheduled wakeups) and re-prompts
+itself when that work finishes. AgentBox reports it through `background.tasks`
+events — `tasks` is the full live set after each change and `waiting` is `true`
+while the harness has ended its turn and the run stays open only for those
+tasks (or, with an empty set, for the wake-up the CLI queues for a task that
+finished mid-turn) — and settles the run on the follow-up turn's result
+instead of the first one. Once background work has been seen, a turn end
+settles the run only after a 15s grace with no new turn, and a final
+`background.tasks` with `tasks: []` and `waiting: false` precedes the settle.
+`backgroundTaskTimeoutMs` bounds the total time spent waiting across the run:
+default 30 minutes, `0` settles at the first turn end as before, `Infinity`
+waits forever. On expiry the tasks are stopped best-effort and the run
+completes with the last turn's text.
+
+Codex has no background mode of its own: its unified exec tool hands control
+back to the model early (`yield_time_ms`) and leaves the process running inside
+the app-server, where nothing wakes the model when it finishes. When a Codex
+turn ends with such a command still running, AgentBox keeps the app-server up
+and reports the command through `background.tasks` (`type: "command"`,
+`description` is the command line). Once every leftover command has finished
+while the model was idle, AgentBox starts a follow-up turn on the same thread
+carrying each command's exit code, duration and the last 4000 characters of
+output, asking the model to verify the outcome and finish without restarting
+the command; that turn is surfaced as a `message.injected` event and the run
+settles on its result (which may in turn leave more commands running). A
+message sent while waiting runs as a normal turn and is checked the same way; a
+command that finishes during a turn is left to the model's own polling and is
+only visible through `tool.call.completed`. A failed follow-up turn fails the
+run like any other turn. When `backgroundTaskTimeoutMs` expires, AgentBox asks
+the app-server to terminate the leftover processes
+(`thread/backgroundTerminals/list` + `terminate`, best effort) and completes
+with the last turn's text; `0` keeps the legacy settle-at-first-turn behaviour.
+Any unified-exec process still running at turn end counts — a dev server or
+watcher the model leaves running on purpose holds the run open until the
+ceiling — so hosts that expect such processes should pass a shorter
+`backgroundTaskTimeoutMs` for Codex. Spawned Codex sub-agents are not tracked:
+the parent must `wait_agent` for them within its turn. A waiting run can still
+be cancelled statelessly: `Agent.attach(...).abort()` interrupts the active turn
+when there is one and otherwise starts a turn only to interrupt it, which the
+originating run observes as an interrupted turn and reports as `run.cancelled`;
+the leftover processes are then terminated.
+
+OpenCode has no background shells, monitors, or wake-ups; its only work that
+outlives a turn is `task {background: true}`, which the server accepts only when
+it runs with `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` (or the
+`OPENCODE_EXPERIMENTAL` umbrella) in its environment. With that flag the parent
+session goes idle while the child session runs and OpenCode itself re-prompts
+the parent with the child's result. AgentBox recognises a background child from
+the parent's `task` tool call (`metadata.background`), so nothing depends on the
+caller's env: while such a child is live at the parent's idle the run stays
+open, the children are reported through `background.tasks` (`type:
+"subagent"`, `description` is the task description / child session title),
+`waiting` flips to `false` when the parent resumes, and the run settles on the
+next parent idle with nothing live — its text is the parent's last assistant
+message, never the injected result. Child liveness comes from SSE frames
+reconciled against `GET /session/status` at each parent idle and while waiting,
+and the injected `<task id=… state=…>` result also counts as the child's
+completion, so a lost frame cannot hold the run open. A child that ends without
+waking the parent settles the run after the 15s grace. `backgroundTaskTimeoutMs`
+bounds the total wait as for Claude Code; on expiry, or when the run fails with
+a child still live, the leftover subagents are stopped best-effort via
+`POST /session/:id/abort`. Aborting the run while waiting cancels the children
+through the same endpoint. Without the flag nothing changes: a parent idle is
+the end of the run.
+
 ## Agents
 
 Three agent providers are supported. Each wraps a CLI that runs inside the sandbox:
@@ -504,6 +570,81 @@ AGENTBOX_RUN_MATRIX_E2E=1 npm run test:e2e:matrix     # provider matrix
 
 Live test suites are opt-in because they provision real infrastructure.
 
+## Host execution settings
+
+Use `configuration: "native"` to run a host harness with its own configuration,
+built-in prompt, credentials, and repository instructions. AgentBox does not
+generate settings, skills, commands, subagents, hooks, plugins, or MCP definitions
+in this mode. It cannot be combined with a sandbox or AgentBox-managed skills,
+MCPs, commands, subagents, or RTK. Omit `systemPrompt` when starting a turn to keep
+the harness's built-in instructions unchanged.
+
+```ts
+const agent = new Agent("codex", {
+  cwd: "/absolute/path/to/project",
+  configuration: "native",
+  approvalMode: "interactive",
+});
+await agent.setup();
+```
+
+Start a turn with `agent.stream({ input })`, consume its async event iterator,
+and answer permission requests with `run.respondToPermission()`. Await
+`run.finished` for the result and call `agent.killServer()` to release the runtime.
+
+The default `configuration: "managed"` retains AgentBox-generated configuration
+for host and sandbox execution.
+
+`stateDirectory` selects a private, persistent directory for generated agent
+configuration and session state on the host. It must be an absolute path and
+cannot be combined with `sandbox`. Use a different directory for each execution
+environment to prevent unrelated local jobs from overwriting configuration.
+This setting does not copy credentials from the user's account.
+
+With native configuration, Codex uses the user's sandbox and approval settings.
+Managed host execution defaults to read-only. An explicit
+`provider: { sandboxMode: "workspace-write" }` enables a host write policy;
+`writableRoots` adds allowed directories and `networkAccess` enables network
+access for that policy (disabled by default). The shared
+`approvalMode: "interactive"` routes permission requests to the caller; it does
+not itself change the native harness's policy. Cloud sandbox defaults are unchanged.
+
+Host Claude runs the Anthropic SDK with the SDK-matched CLI by default.
+`provider.binary` explicitly selects another compatible CLI. Sign-in and session
+storage remain CLI-owned. Managed configuration loads generated skills, commands,
+and subagents as a private local plugin. Native configuration loads user, project,
+and local settings instead. Neither mode copies the CLI's credentials. When
+`backgroundTaskTimeoutMs` expires, host Claude stops the leftover background
+tasks through the SDK; in a sandbox the daemon lets the CLI wind down on
+disconnect, bounded by `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=30000`, which
+AgentBox sets in the CLI environment unless `env` already defines it.
+
+Each host OpenCode Agent owns an authenticated loopback server on an ephemeral
+port. Managed configuration uses an isolated configuration directory; native
+configuration preserves the user's configuration paths. `killServer()` stops
+only that Agent's process. It never discovers or kills another server by port number.
+
+All three providers normalize interactive questions into `permission.requested`
+events with `kind: "question"`. Respond with `decision: "allow"` and an `answers`
+array containing each `questionId` and its selected or custom `values`, or use
+`decision: "deny"` to skip. Invalid answers leave the request pending for correction.
+Question answers cannot modify unrelated tool arguments. Ordinary tool requests
+use the same API without `answers`.
+
+Native runtimes own a POSIX process group by default. Termination is bounded and
+escalates to SIGKILL if the process ignores SIGTERM. A supervisor that launches
+each run in its own process group can set `processGroup: "inherited"`; that
+supervisor is then responsible for stopping the complete group before reporting
+that a run has stopped. This option is unavailable for cloud sandboxes.
+
+## Packaging
+
+`npm pack` builds the package from maintained TypeScript source before creating
+the archive. Host execution includes the pinned Anthropic SDK and its Zod peer
+as runtime dependencies; consumers do not need package-manager extensions.
+Run `npm run check` before publishing. Provider integration tests use fake local
+CLIs and SDK mocks; live tests remain opt-in.
+
 ## License
 
 MIT

package/dist/agents/index.d.ts

@@ -1,5 +1,5 @@
-import { o as AgentProviderName, h as AgentOptions, t as AgentRunConfig, s as AgentRun, r as AgentResult, a4 as RawAgentEvent, b as AgentAttachRequest, y as AttachedRun, ab as SetupLayout } from '../types-3VRJIiW0.js';
-export { a as AgentApprovalMode, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, u as AgentRunSink, v as AgentSetupRequest, w as AgentSkillConfig, x as AgentSubAgentConfig, C as ClaudeCodeAgentOptions, z as ClaudeCodeHookConfig, B as ClaudeCodeHookEvent, D as ClaudeCodeHookHandler, E as ClaudeCodeHookMatcherGroup, F as ClaudeCodeHooksConfig, G as ClaudeCodeProviderOptions, H as CodexAgentOptions, I as CodexCommandHook, J as CodexHookEvent, K as CodexHookMatcherGroup, L as CodexHooksConfig, M as CodexModelProviderConfig, N as CodexProviderOptions, O as DataContent, P as EmbeddedSkillConfig, Q as FilePart, R as ImagePart, Y as OpenCodeAgentOptions, Z as OpenCodePluginConfig, _ as OpenCodePluginEvent, $ as OpenCodePluginHookConfig, a0 as OpenCodeProviderOptions, a1 as OpenRouterPlugin, a6 as RepoSkillConfig, ad as TextPart, ah as UserContent, ai as UserContentPart } from '../types-3VRJIiW0.js';
+import { o as AgentProviderName, h as AgentOptions, t as AgentRunConfig, s as AgentRun, r as AgentResult, a9 as RawAgentEvent, b as AgentAttachRequest, B as AttachedRun, ag as SetupLayout, am as UserContent } from '../types-B4yy80AJ.js';
+export { a as AgentApprovalMode, c as AgentCommandConfig, d as AgentCostData, e as AgentExecutionRequest, f as AgentLocalMcpConfig, g as AgentMcpConfig, i as AgentOptionsBase, j as AgentOptionsMap, k as AgentPermissionDecision, l as AgentPermissionKind, m as AgentPermissionResponse, n as AgentProviderAdapter, p as AgentReasoningEffort, q as AgentRemoteMcpConfig, u as AgentRunSink, v as AgentSetupRequest, w as AgentSkillConfig, x as AgentSubAgentConfig, y as AgentUserAnswer, z as AgentUserQuestion, E as ClaudeCodeAgentOptions, F as ClaudeCodeHookConfig, G as ClaudeCodeHookEvent, H as ClaudeCodeHookHandler, I as ClaudeCodeHookMatcherGroup, J as ClaudeCodeHooksConfig, K as ClaudeCodeProviderOptions, L as CodexAgentOptions, M as CodexCommandHook, N as CodexHookEvent, O as CodexHookMatcherGroup, P as CodexHooksConfig, Q as CodexModelProviderConfig, R as CodexProviderOptions, S as DataContent, T as EmbeddedSkillConfig, U as FilePart, V as ImagePart, a1 as OpenCodeAgentOptions, a2 as OpenCodePluginConfig, a3 as OpenCodePluginEvent, a4 as OpenCodePluginHookConfig, a5 as OpenCodeProviderOptions, a6 as OpenRouterPlugin, ab as RepoSkillConfig, ai as TextPart, an as UserContentPart } from '../types-B4yy80AJ.js';
 import { S as Sandbox } from '../Sandbox-DcKAU-E3.js';
 export { AgentProvider } from '../enums.js';
 import 'e2b';
@@ -93,7 +93,7 @@ declare class Agent<P extends AgentProviderName = AgentProviderName> {
  *  - **Sandbox**: `/tmp/agentbox/<provider>` inside the sandbox.
  *  - **Local host**: `<os.tmpdir()>/agentbox-<provider>` on the host.
  */
-declare function agentboxRoot(provider: AgentProviderName, hasSandbox?: boolean): string;
+declare function agentboxRoot(provider: AgentProviderName, hasSandbox?: boolean, stateDirectory?: string): string;
 /**
  * Resolve the on-disk layout (config dirs per provider) for the given
  * agentbox root. Public so external consumers (e.g. agentbox-driven
@@ -124,4 +124,15 @@ declare function getAgentLayout(rootDir: string): SetupLayout;
 declare const AGENT_RESERVED_PORTS: Record<AgentProviderName, readonly number[]>;
 declare function collectAllAgentReservedPorts(): number[];
 
-export { AGENT_RESERVED_PORTS, Agent, AgentAttachRequest, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig, AttachedRun, SetupLayout, agentboxRoot, collectAllAgentReservedPorts, getAgentLayout };
+type HarnessCommand = "plan" | "agent" | "goal";
+interface HarnessCapabilities {
+    commands: HarnessCommand[];
+    planning: "explicit" | "agent-directed";
+    questions: boolean;
+    fullAccess: boolean;
+}
+/** Adapter capabilities. Runtime adapters additionally validate commands against the live harness. */
+declare function harnessCapabilities(provider: AgentProviderName): HarnessCapabilities;
+declare function resolveHarnessCommand(provider: AgentProviderName, input: UserContent): Pick<AgentRunConfig, "input" | "mode" | "goal">;
+
+export { AGENT_RESERVED_PORTS, Agent, AgentAttachRequest, AgentOptions, AgentProviderName, AgentResult, AgentRun, AgentRunConfig, AttachedRun, type HarnessCapabilities, type HarnessCommand, SetupLayout, UserContent, agentboxRoot, collectAllAgentReservedPorts, getAgentLayout, harnessCapabilities, resolveHarnessCommand };

package/dist/agents/index.js

@@ -1,13 +1,15 @@
 import {
   Agent,
   agentboxRoot,
-  getAgentLayout
-} from "../chunk-34LDITII.js";
+  getAgentLayout,
+  harnessCapabilities,
+  resolveHarnessCommand
+} from "../chunk-G3VEVR6Y.js";
 import "../chunk-775FIGGL.js";
 import {
   AGENT_RESERVED_PORTS,
   collectAllAgentReservedPorts
-} from "../chunk-AVXJMCBC.js";
+} from "../chunk-MTQ2S46C.js";
 import "../chunk-NSJM57Z4.js";
 import {
   AgentProvider
@@ -18,5 +20,7 @@ export {
   AgentProvider,
   agentboxRoot,
   collectAllAgentReservedPorts,
-  getAgentLayout
+  getAgentLayout,
+  harnessCapabilities,
+  resolveHarnessCommand
 };

package/dist/{chunk-TUBBWIOM.js → chunk-76AFK7XN.js}

@@ -10,7 +10,7 @@ import {
   sleep,
   suppressUnhandledRejection,
   time
-} from "./chunk-AVXJMCBC.js";
+} from "./chunk-MTQ2S46C.js";
 import {
   shellQuote,
   toShellCommand