@coltonkirsten/a12s 0.2.1 → 0.4.0

package/dist/src/types.d.ts

@@ -8,28 +8,124 @@ export interface Harness {
     version: string;
     model?: string;
 }
-/** A parsed fleet.yaml. a12s validates it; the client passes it through. */
-export type Fleet = Record<string, unknown> & {
-    metadata: {
+export interface AgentComputerSpec {
+    harness?: {
+        kind: "claude-code" | "codex" | (string & {});
+        version?: string;
+        model?: string;
+    };
+    image?: string;
+    instructions?: string;
+    /** File contents by path, written into the agent computer's home. */
+    files?: Record<string, string>;
+    resources?: {
+        cpu?: string | number;
+        memory?: string | number;
+    };
+    home?: {
+        size?: string | number;
+        preset?: string;
+    };
+    autonomy?: "full" | "restricted";
+    /** Credential names; their values come from `a12s up` or the credentials API. */
+    credentials?: string[];
+    drives?: Array<{
+        name: string;
+        at: string;
+        readOnly?: boolean;
+    }>;
+    egress?: {
+        allow?: string[];
+    };
+    /** `seccomp` is the profile JSON itself. */
+    security?: {
+        seccomp?: Record<string, unknown>;
+    };
+    inbox?: {
+        maxMessages?: number;
+        maxBytes?: string;
+        intro?: string;
+    };
+    power?: {
+        sleepAfterIdle?: string;
+        wakeOnMessage?: {
+            from: string[];
+            maxWakesPerHour?: number;
+        };
+    };
+    uses?: Array<string | {
         name: string;
+        mcp?: boolean;
+    }>;
+    grants?: {
+        send?: string[];
     };
+}
+/** A JSON merge patch of T: a key set to null is deleted. */
+export type MergePatch<T> = {
+    [K in keyof T]?: T[K] | null;
 };
+/** A Fleet as written: the defaults and each agent computer before the defaults are merged in. */
+export interface FleetSpec {
+    apiVersion: string;
+    kind: string;
+    metadata: {
+        name: string;
+    };
+    egress?: {
+        enforcement?: string;
+        allowPrivate?: string[];
+    };
+    defaults?: AgentComputerSpec;
+    drives?: Record<string, {
+        size?: string | number;
+        access: string;
+    }>;
+    agent_computers: Record<string, AgentComputerSpec>;
+    services?: Record<string, Record<string, unknown>>;
+}
+export interface Change {
+    op: "create" | "update" | "remove" | (string & {});
+    kind: "agentComputer" | "service" | (string & {});
+    name: string;
+    /** "idle" for an update that waits for a busy agent computer's next idle boundary. */
+    when: "now" | "idle" | (string & {});
+    /** The top-level spec fields that differ, for an update. */
+    fields?: string[];
+}
+export interface FleetResponse {
+    version: number;
+    fleet: FleetSpec | null;
+    /** What changed through the API since the last whole-Fleet write: `a12s up` from the file undoes it. */
+    drift: Change[];
+}
+export interface AgentComputerData {
+    name: string;
+    /** As written. */
+    spec: AgentComputerSpec;
+    /** With the Fleet's defaults merged in. */
+    effective: AgentComputerSpec;
+    status: ComputerStatus;
+}
+export interface AgentComputersResponse {
+    agentComputers: AgentComputerData[];
+}
 export interface Lock {
     a12s?: string;
     images: Record<string, string>;
     bundles: Record<string, string>;
     presets: Record<string, string>;
     services?: Record<string, string>;
+    /** Each security.seccomp profile's digest, by its path in the Fleet file. */
+    seccomp?: Record<string, string>;
 }
 export interface PutFleetRequest {
-    fleet: Fleet;
+    fleet: FleetSpec;
     lock?: Lock;
     /** Credential values by name, base64-encoded (Go []byte). Kept in the Controller's memory only. */
     credentials?: Record<string, string>;
     asleep?: boolean;
     refresh?: string[];
-    /** Home presets as base64 tar streams, keyed by their path in the Fleet. */
-    presets?: Record<string, string>;
 }
 export interface ServiceChanges {
     created: string[] | null;
@@ -37,6 +133,10 @@ export interface ServiceChanges {
     removed: string[] | null;
 }
 export interface PutFleetResponse {
+    /** The Fleet's version after the write; unchanged by a dry run or a write that changed nothing. */
+    version: number;
+    dryRun?: boolean;
+    changes: Change[];
     created: string[] | null;
     updated: string[] | null;
     staged: string[] | null;
@@ -45,6 +145,10 @@ export interface PutFleetResponse {
     errors?: Record<string, string>;
     warnings?: string[];
     services: ServiceChanges;
+    /** The written agent computer, after a PUT or PATCH of one. */
+    agentComputer?: AgentComputerData;
+    /** The written Service, after a PUT or PATCH of one. */
+    service?: ServiceStatus;
 }
 export interface LimitValue {
     value: number;
@@ -97,6 +201,8 @@ export interface ComputerStatus {
     activeTurn?: string;
     harness: Harness;
     image: string;
+    /** The Fleet's security.seccomp path, when the Computer runs with a custom seccomp profile. */
+    seccomp?: string;
     autonomy: string;
     generation: number;
     stagedGeneration?: number;
@@ -140,10 +246,14 @@ export interface ServiceStatus {
     stateDrive?: string;
     egressMode?: string;
     warnings?: string[];
+    /** The Service as written in the Fleet. */
+    spec?: Record<string, unknown>;
 }
 export interface StatusResponse {
     fleet: string;
     egressEnforcement: string;
+    agentComputers: ComputerStatus[];
+    /** @deprecated `agentComputers` under its old name. */
     computers: ComputerStatus[];
     orphanedDrives?: DriveRow[];
     credentialsLoaded: boolean;
@@ -207,10 +317,12 @@ export interface InboxListOptions {
     bodies?: boolean;
     after?: number;
 }
-/** The fields every journal event has. `seq` is the Computer's journal position and the SSE id. */
+/** The fields every event has. `seq` is the agent computer's journal position (0 for the Controller's own events). */
 export interface EventEnvelope {
     v: number;
-    /** The Computer that journaled it. */
+    /** The agent computer it is about; absent on `fleet.changed` and in journals older than the field. */
+    agentComputer?: string;
+    /** `agentComputer` under its old name, for one release. */
     computer: string;
     session: string;
     /** The Turn it belongs to; "" for events outside a Turn. */
@@ -258,8 +370,34 @@ export interface TurnFinishedData {
     status: "completed" | "failed" | "interrupted";
     /** The harness's own usage object (tokens, cost), or null. */
     usage: unknown;
+    /** The same usage, normalized across harnesses, when the harness reported it. */
+    tokens?: TokenUsage;
     error?: string;
 }
+/** A Turn's token usage, the same for every harness. `input` excludes cached input. */
+export interface TokenUsage {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}
+/** The egress proxy refused a connection. */
+export interface EgressDeniedData {
+    host: string;
+    port: number;
+    reason?: string;
+}
+/** The Fleet's version moved; `names` are the agent computers and Services the write changed. */
+export interface FleetChangedData {
+    version: number;
+    /** Who wrote it. */
+    by: string;
+    names: string[];
+}
+export interface PhaseData {
+    phase: Phase;
+    error?: Failure;
+}
 export interface ToolStartedData {
     id: string;
     /** MCP tools are named `mcp__<server>__<tool>`, e.g. `mcp__a12s__send`. */
@@ -325,10 +463,15 @@ 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>;
+/** 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. */
+export type PhaseEvent = Ev<"agent_computer.phase", PhaseData>;
 /** 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 a Computer's journal. 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 | GapEvent;
+/** 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 | 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 {
@@ -340,6 +483,8 @@ export interface ToolCall {
 }
 /** A finished Turn: what `turns()` yields and `prompt()` returns. */
 export interface Turn {
+    agentComputer: string;
+    /** `agentComputer` under its old name, for one release. */
     computer: string;
     /** The Turn id. */
     id: string;
@@ -353,24 +498,47 @@ export interface Turn {
     /** The tools it called, in order, with their input and output: what it `send`s to other Computers is here. */
     tools: ToolCall[];
     usage: unknown;
+    tokens?: TokenUsage;
     startedAt?: string;
     finishedAt: string;
 }
+/** Past Turns, newest first, as GET /v1/agent-computers/{name}/turns sends them. */
+export interface TurnsResponse {
+    turns: Array<Omit<Turn, "computer" | "tools"> & {
+        tools: Array<Omit<ToolCall, "isError"> & {
+            isError?: boolean;
+        }>;
+    }>;
+}
 export interface ApiErrorBody {
     code: string;
     message: string;
     fix?: string;
     details?: Record<string, string>;
 }
+export type TokenAction = "send" | "inbox" | "status" | "events" | "power" | "stop";
+/** Either `prefix`, or `actions` on `computers` (agent computer names, or "*"). */
 export interface TokenRequest {
     name: string;
-    actions: Array<"send" | "inbox" | "status" | "events" | "power" | "stop">;
-    computers: string[];
+    actions?: TokenAction[];
+    computers?: string[];
+    /** Every power over agent computers, Services and credentials whose names start with it; none outside. */
+    prefix?: string;
+}
+/** A credential's name, whether it has a value, and who uses it. */
+export interface CredentialInfo {
+    name: string;
+    set: boolean;
+    usedBy?: string[];
+}
+export interface CredentialsResponse {
+    credentials: CredentialInfo[];
 }
 export interface Token {
     name: string;
     actions: string[];
     computers: string[];
+    prefix?: string;
     createdAt: string;
     secret?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coltonkirsten/a12s",
-  "version": "0.2.1",
+  "version": "0.4.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",