@coltonkirsten/a12s 0.7.0 → 0.8.0

package/dist/src/client.d.ts

@@ -105,7 +105,10 @@ export declare class Client {
     message(computer: string, id: string): Promise<Message>;
     /** Withdraws a pending Message; a 409 A12sError names its state if it is too late. */
     withdraw(computer: string, id: string): Promise<Message>;
-    /** Interrupts a Turn (default: the active one). The Turn ends `interrupted`; nothing is replayed. */
+    /**
+     * Interrupts a Turn (default: whatever runs) and ends the session's background work. The Turn ends `interrupted`;
+     * nothing is replayed.
+     */
     stop(computer: string, turn?: string): Promise<void>;
     /**
      * Stops the agent computer's processes and keeps its disks, session and inbox. A Message from a sender its power

package/dist/src/client.js

@@ -165,11 +165,15 @@ export class Client {
     withdraw(computer, id) {
         return this.request("DELETE", `/v1/agent-computers/${enc(computer)}/inbox/${enc(id)}`);
     }
-    /** Interrupts a Turn (default: the active one). The Turn ends `interrupted`; nothing is replayed. */
+    /**
+     * Interrupts a Turn (default: whatever runs) and ends the session's background work. The Turn ends `interrupted`;
+     * nothing is replayed.
+     */
     async stop(computer, turn) {
-        const id = turn ?? (await this.computer(computer)).activeTurn;
-        if (id)
-            await this.request("POST", `/v1/agent-computers/${enc(computer)}/turns/${enc(id)}/stop`, {});
+        if (turn)
+            await this.request("POST", `/v1/agent-computers/${enc(computer)}/turns/${enc(turn)}/stop`, {});
+        else
+            await this.request("POST", `/v1/agent-computers/${enc(computer)}/stop`, {});
     }
     /**
      * Stops the agent computer's processes and keeps its disks, session and inbox. A Message from a sender its power
@@ -692,6 +696,7 @@ class TurnBuilder {
             case "turn.started":
                 t.messages = ev.data.inbox?.messages ?? [];
                 t.startedAt = ev.ts;
+                t.reason = ev.data.reason;
                 return undefined;
             case "tool.started":
                 t.afterTool = true;
@@ -716,6 +721,7 @@ class TurnBuilder {
                     id: ev.turn,
                     session: ev.session,
                     status: ev.data.status,
+                    ...(t.reason ? { reason: t.reason } : {}),
                     text: t.text,
                     ...(ev.data.error ? { error: ev.data.error } : {}),
                     messages: t.messages,

package/dist/src/fleet.d.ts

@@ -112,7 +112,7 @@ export declare class AgentComputer {
     }): Promise<InboxListResponse>;
     /** Releases a hold on its inbox. */
     resume(): Promise<InboxListResponse>;
-    /** Interrupts a Turn (default: the active one). */
+    /** Interrupts a Turn (default: whatever runs) and ends the session's background work. */
     stop(turn?: string): Promise<void>;
     inbox(opts?: InboxListOptions): Promise<InboxListResponse>;
     message(id: string): Promise<Message>;
@@ -170,8 +170,8 @@ export declare class Tokens {
     constructor(client: Client);
     /**
      * A token for another program; owner only. The secret is in the result once. With `prefix` it may do everything
-     * the owner can for names that start with it except set `security.seccomp`, and nothing outside; otherwise
-     * `actions` on `agentComputers`.
+     * the owner can for names that start with it except set `security.seccomp` or `attach`, and nothing outside;
+     * otherwise `actions` on `agentComputers`.
      */
     create(name: string, opts: {
         prefix: string;

package/dist/src/fleet.js

@@ -203,7 +203,7 @@ export class AgentComputer {
     resume() {
         return this.client.resume(this.name);
     }
-    /** Interrupts a Turn (default: the active one). */
+    /** Interrupts a Turn (default: whatever runs) and ends the session's background work. */
     stop(turn) {
         return this.client.stop(this.name, turn);
     }
@@ -313,8 +313,8 @@ export class Tokens {
     }
     /**
      * A token for another program; owner only. The secret is in the result once. With `prefix` it may do everything
-     * the owner can for names that start with it except set `security.seccomp`, and nothing outside; otherwise
-     * `actions` on `agentComputers`.
+     * the owner can for names that start with it except set `security.seccomp` or `attach`, and nothing outside;
+     * otherwise `actions` on `agentComputers`.
      */
     create(name, opts) {
         if ("prefix" in opts) {

package/dist/src/types.d.ts

@@ -37,6 +37,15 @@ export interface AgentComputerSpec {
     security?: {
         seccomp?: Record<string, unknown>;
     };
+    /**
+     * Host folders mounted at /home/agent/<name>, by name; owner only. `host` is an absolute path on the machine
+     * running a12s; `keep` paths (like node_modules) stay inside a12s, on a drive each, never in the host folder.
+     */
+    attach?: Record<string, {
+        host: string;
+        readOnly?: boolean;
+        keep?: string[];
+    }>;
     inbox?: {
         maxMessages?: number;
         maxBytes?: string;
@@ -191,11 +200,17 @@ export interface ComputerStatus {
     warnings?: string[];
     inbox?: InboxSummary;
     power?: PowerStatus;
+    /** Set while the harness session runs background work (sub-agents, shells) between Turns; it is not idle then. */
+    background?: {
+        tasks: number;
+    };
 }
 export interface DriveRow {
     name: string;
-    kind: "home" | "state";
+    kind: "home" | "state" | "keep";
     computer?: string;
+    /** Where a keep drive is mounted, e.g. /home/agent/project/node_modules. */
+    path?: string;
     service?: string;
     /** A quantity such as "10Gi". */
     size?: string;
@@ -332,9 +347,25 @@ export interface TurnStartedData {
     prompt: string;
     cwd: string;
     requestId?: string;
-    /** The Messages this Turn delivers. Absent for a continuation after `restart_harness`. */
+    /** The Messages this Turn delivers. Absent for a continuation after `restart_harness` and a background Turn. */
     inbox?: TurnInbox;
     continuation?: string;
+    /** "background": the harness started this Turn by itself when background work ended. */
+    reason?: string;
+}
+/** Background work (a sub-agent, a shell) the harness keeps running after the Turn that started it. */
+export interface TaskData {
+    id: string;
+    /** The harness's own kind: local_agent, local_bash, shell, … */
+    kind: string;
+    description: string;
+    /** On task.finished. "killed": the session ended (stop, sleep, restart, a new session) while it ran. */
+    status?: "completed" | "failed" | "stopped" | "killed";
+}
+/** POST /v1/agent-computers/{name}/stop: the Turns it stopped and how many background tasks it ended. */
+export interface StopResponse {
+    turns: string[];
+    background: number;
 }
 export interface TurnFinishedData {
     status: "completed" | "failed" | "interrupted";
@@ -445,6 +476,8 @@ export type TurnRefusedEvent = Ev<"turn.refused", {
 /** A Message that ended without delivery (cleared, withdrawn, expired, replaced), body included. */
 export type InboxDiscardedEvent = Ev<"inbox.discarded", Record<string, unknown>>;
 export type EgressDeniedEvent = Ev<"egress.denied", EgressDeniedData>;
+export type TaskStartedEvent = Ev<"task.started", TaskData>;
+export type TaskFinishedEvent = Ev<"task.finished", TaskData>;
 /** Made by the Controller, on the fleet-wide stream only. */
 export type FleetChangedEvent = Ev<"fleet.changed", FleetChangedData>;
 /** Made by the Controller, on the fleet-wide stream only. */
@@ -456,7 +489,7 @@ export type ServicePhaseEvent = Ev<"service.phase", ServicePhaseData>;
 /** Made by the SDK, never journaled: the stream could not resume from its cursor and events were lost. */
 export type GapEvent = Ev<"gap", GapData>;
 /** One event of an agent computer's journal, or the Controller's own on the fleet-wide stream. Narrow on `type` to get typed `data`. */
-export type A12sEvent = TurnStartedEvent | TurnDispatchedEvent | TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | PermissionEvent | DiagnosticEvent | TurnFinishedEvent | SessionChangedEvent | ResumeFailedEvent | LifecycleEvent | HarnessRestartedEvent | ContinuationAbandonedEvent | TurnRefusedEvent | InboxDiscardedEvent | EgressDeniedEvent | FleetChangedEvent | PhaseEvent | InboxChangedEvent | ServicePhaseEvent | GapEvent;
+export type A12sEvent = TurnStartedEvent | TurnDispatchedEvent | TextDeltaEvent | ToolStartedEvent | ToolFinishedEvent | PermissionEvent | DiagnosticEvent | TurnFinishedEvent | SessionChangedEvent | ResumeFailedEvent | LifecycleEvent | HarnessRestartedEvent | ContinuationAbandonedEvent | TurnRefusedEvent | InboxDiscardedEvent | EgressDeniedEvent | TaskStartedEvent | TaskFinishedEvent | FleetChangedEvent | PhaseEvent | InboxChangedEvent | ServicePhaseEvent | GapEvent;
 export type EventType = A12sEvent["type"];
 /** One tool call in a Turn. A `send` to another Computer is `mcp__a12s__send` with `input.body`. */
 export interface ToolCall {
@@ -473,6 +506,8 @@ export interface Turn {
     id: string;
     session: string;
     status: TurnFinishedData["status"];
+    /** "background": the harness started this Turn by itself when background work ended; it delivered no Messages. */
+    reason?: string;
     /** Everything the agent said in the Turn, concatenated. */
     text: string;
     error?: string;
@@ -505,7 +540,10 @@ export interface TokenRequest {
     name: string;
     actions?: TokenAction[];
     computers?: string[];
-    /** Every power over agent computers, Services and credentials whose names start with it but seccomp; none outside. */
+    /**
+     * Every power over agent computers, Services and credentials whose names start with it but seccomp and attach;
+     * none outside.
+     */
     prefix?: string;
 }
 /** A credential's name, whether it has a value, and who uses it. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coltonkirsten/a12s",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "TypeScript client for a12s: send work to agent Computers, stream their events and Turns, in Node or the browser",
   "license": "MIT",
   "type": "module",