@agent-compose/sdk 0.5.5 → 0.5.7

package/README.md

@@ -64,7 +64,7 @@ export default defineWorkflow({
 ```
 
 `defineWorkflow` is a thin sugar — it returns the bare `run` function with
-`networkPolicy` / `placeholders` / `snapshots` / `memory` / `postRunHooks`
+`networkPolicy` / `placeholders` / `snapshots`
 attached as metadata that the bundler picks up at registration time. A
 plain `export default async (ctx, sandbox) => {...}` is also valid; you
 just lose the metadata channel.
@@ -183,7 +183,7 @@ await client.register({
   runtimes:    bundled.runtimes,        // [{ name, source }] — embedded so the runner has them locally
   schedule:    "*/30 * * * *",          // optional cron
   factorySlug: "default",                // optional — defaults to "default"
-  // snapshots, memory, postRunHooks, networkPolicy, placeholders — all optional
+  // snapshots, networkPolicy, placeholders — all optional
 });
 ```
 
@@ -217,7 +217,7 @@ separate `metadata` field — useful for "side-channel" facts (PR url, plan
 url) without polluting the structured return.
 
 `invoke` and `invokeAndWait` both accept `{ factorySlug, snapshots,
-memory, postRunHooks, networkPolicy, placeholders, parentRunId }` as the
+networkPolicy, placeholders, parentRunId }` as the
 third argument. Per-invocation `snapshots` merges field-by-field with
 the registered default. `factorySlug` defaults to `"default"`.
 
@@ -379,7 +379,7 @@ CLI equivalents: `agentc snapshot list` / `agentc snapshot delete <run-id> <snap
 
 ### Per-invocation overrides merge field-by-field
 
-The `snapshots` object on `invoke()` is **merged** with the registered template's `snapshots` config — you can override `bootFrom` alone without losing `saveLatest`, or vice versa. Same for `memory` (boolean) and `postRunHooks` (string[]).
+The `snapshots` object on `invoke()` is **merged** with the registered template's `snapshots` config — you can override `bootFrom` alone without losing `saveLatest`, or vice versa.
 
 ---
 

package/dist/agent/agent-loop-contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/agent-loop.d.ts

@@ -8,7 +8,7 @@ import type { AgentStatus, AgentMessage } from "./protocol.js";
 import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { type SteerPayload } from "./steer-control.js";
-export declare const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+export declare const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 export declare function parseAgentStatus(text: string): AgentStatus | null;
 export interface AgentLoopResult<TResponse = unknown> {
     agentId: string;

package/dist/client.d.ts

@@ -13,20 +13,13 @@
 import type { SandboxNetworkPolicy } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
 import type { WorkflowPlan } from "./types/workflow-plan.js";
-import type { SnapshotConfig, IOSchema } from "./types/workflow-metadata.js";
+import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "./types/workflow-metadata.js";
 import type { WorkflowManifest } from "./utils/bundler.js";
 export interface RegisterResult {
     id: string;
     name: string;
     version: string;
     runtimes?: RegisteredRuntime[];
-    /** Non-fatal advisories from the server. Surfaced at register time so the
-     *  operator sees them while still in front of the terminal — currently
-     *  covers "memory extraction is configured but its workflow is not
-     *  registered in this factory". Empty/undefined when registration was
-     *  cleanly resolved against everything the workflow declares it
-     *  depends on. */
-    warnings?: string[];
 }
 export interface RegisteredRuntime {
     id: string;
@@ -37,6 +30,18 @@ export interface RuntimeSourceInput {
     name: string;
     source: string;
 }
+/** GitHub provenance for a registered template's source file — stored as
+ *  `metadata.source` on the registration. `cloud-build` stamps the built
+ *  commit's sha; the dashboard's manual link path writes `sha: "manual"`. */
+export interface TemplateSourceRef {
+    owner: string;
+    repo: string;
+    branch: string;
+    /** Repo-relative file path, e.g. `.agentc/workflows/workflow-deploy.ts`. */
+    path: string;
+    /** Commit sha the version was built from, or `"manual"` for hand-links. */
+    sha: string;
+}
 export interface RegisterWorkflowInput {
     name: string;
     source: string;
@@ -48,6 +53,9 @@ export interface RegisterWorkflowInput {
      *  executed on the server. */
     manifest: WorkflowManifest;
     version?: string;
+    /** Where the source file lives on GitHub — stored as `metadata.source`.
+     *  Named `sourceRef` because `source` is the bundled code itself. */
+    sourceRef?: TemplateSourceRef;
     schedule?: string;
     runtimes?: RuntimeSourceInput[];
     /** Human-readable description declared via
@@ -61,13 +69,16 @@ export interface RegisterWorkflowInput {
     snapshots?: SnapshotConfig;
     /** Provider-neutral execution plan detected by the CLI bundler. */
     workflowPlan?: WorkflowPlan;
-    /** Run the built-in memory extractor after this workflow completes.
-     *  Opt-in; defaults to false when omitted. */
-    memory?: boolean;
-    /** Ordered list of workflow names that run as post-hooks after this
-     *  workflow completes. The memory extractor (when `memory: true`)
-     *  runs as an additional hook alongside these. */
-    postRunHooks?: readonly string[];
+    /** Connector requirements declared via `defineWorkflow({ connectors })`
+     *  (ADR-0007). Validated against the server's provider registry at
+     *  registration; tokens are injected at the network layer at dispatch. */
+    connectors?: ConnectorRequirements;
+    /** Connector-catalogue operation tag — see `ConnectorOperationTag`. */
+    connectorOperation?: ConnectorOperationTag;
+    /** Tier-1 invoke ACL declared via `defineWorkflow({ invokePolicy })`.
+     *  Only meaningful when the workflow also declares `connectors` — the
+     *  server gates dispatch on it before binding any grant. */
+    invokePolicy?: InvokePolicy;
     /** Input schema extracted from the workflow's `input` zod schema. */
     inputSchema?: IOSchema;
     /** Output schema extracted from the workflow's `output` zod schema. */
@@ -90,19 +101,16 @@ export interface InvokeWorkflowOptions {
      *  vars after brokering. Replaces the template-level placeholders for
      *  this run only — registered metadata is not mutated. */
     placeholders?: Record<string, string>;
-    /** Per-invocation memory-extractor override — `false` skips the
-     *  built-in memory hook for this run; omitting leaves the registered
-     *  default in place. */
-    memory?: boolean;
-    /** Per-invocation post-hook override — replaces the registered
-     *  `postRunHooks` array for this run only. */
-    postRunHooks?: readonly string[];
     /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
     parentRunId?: string | null;
     /** Agent loop inside the parent run that caused this invoke, when applicable. */
     agentId?: string | null;
     /** Factory slug. Defaults to `"default"`. */
     factorySlug?: string;
+    /** Idempotency key — sent as the `Idempotency-Key` header. A repeat invoke
+     *  with the same key inside the server's dedup window returns the original
+     *  run instead of starting a new one (matches `resumePause`'s pattern). */
+    idempotencyKey?: string;
 }
 export interface InvokeAndWaitOptions extends InvokeWorkflowOptions {
     timeoutMs?: number;
@@ -182,6 +190,13 @@ export interface RunStatus<TOutput = unknown> {
     id: string;
     status: RunState;
     output?: TOutput;
+    /** The run's latest (`saveLatest`) snapshot id, populated once the run has
+     *  succeeded — the boot source to fork this run's evolved filesystem from
+     *  (pass as `snapshots.bootFrom` on a follow-up invoke). `null` while the run
+     *  is still in flight or when it captured no snapshot. Lets an orchestrator
+     *  fork a child straight off the `invokeChild` result without a separate
+     *  `listRunSnapshots` call. */
+    latestSnapshotId?: string | null;
 }
 /** ADR-0006 step 10 — actor record returned on a successful resume.
  *  Shape mirrors the server's `PauseResumeActor` type after the row
@@ -317,6 +332,20 @@ export interface EventRow {
     idempotencyKey: string | null;
     createdAt: string;
 }
+export interface RunArtifactRow {
+    path: string;
+    factorySlug: string | null;
+    sizeBytes: number | null;
+    lastWriteAt: string;
+    /** Opening text of the file (≤320 chars) — null for binary/empty. */
+    preview: string | null;
+}
+export interface FactoryFileWriteResult {
+    path: string;
+    contentHash: string;
+    sizeBytes: number;
+    created: boolean;
+}
 export interface ReportEventInput {
     name: string;
     body: unknown;
@@ -331,7 +360,7 @@ export interface ListEventsOptions {
     factorySlug?: string;
     limit?: number;
     /** Case-insensitive substring match. Server uses `ILIKE %name%`, so
-     *  `"mem"` matches `memory.fact`, `memory.usage`, etc. Pass the
+     *  `"site"` matches `site.created`, `site.failed`, etc. Pass the
      *  full event name for an effectively-exact filter (any string is a
      *  substring of itself). */
     name?: string;
@@ -580,6 +609,19 @@ export declare class AgentComposeClient {
      * like quality.accepted, defect.regression, or intervention.override. */
     reportEvent(runId: string, input: ReportEventInput): Promise<EventRow>;
     listRunEvents(runId: string): Promise<EventRow[]>;
+    /** Files the run wrote on the factory drive — run-attributed revisions,
+     *  latest write per path, paths the run later deleted excluded. */
+    listRunArtifacts(runId: string): Promise<RunArtifactRow[]>;
+    /** Write (create or overwrite) one file on a factory's drive. */
+    putFactoryFile(path: string, content: string | Uint8Array, opts?: {
+        factorySlug?: string;
+        contentType?: string;
+    }): Promise<FactoryFileWriteResult>;
+    /** Read one file's current content (or a specific revision) as text. */
+    getFactoryFile(path: string, opts?: {
+        factorySlug?: string;
+        revision?: number;
+    }): Promise<string>;
     /** List events ingested into a factory, newest first. Supports
      *  case-insensitive substring filter (`name`) and timestamp-cursor
      *  pagination (`before`). Returns `{ events, has_more }` — the

package/dist/index.d.ts

@@ -16,7 +16,8 @@ export type { WorkflowDefinition } from "./types/workflow.js";
 export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
 export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
 export type { AgentRuntime, McpServerConfig, ModelExecutionContract, ToolCallGateResult, RuntimeOptions, } from "./types/runtime.js";
-export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema, WorkflowMemoryConfig, } from "./types/workflow.js";
+export type { WorkflowFn, WorkflowCtx, WorkflowRun, AgentBudget, WorkflowHooks, SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema, } from "./types/workflow.js";
+export type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 export type { RunSnapshotEntry } from "./client.js";
 export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
@@ -27,7 +28,7 @@ export type { Processor, ProcessorContext, ProcessorVerdict, ToolCall, } from ".
 export type { AgentMessage, AgentMessageInit, AgentMessageText, AgentMessageThinking, AgentMessageToolUse, AgentMessageToolResult, AgentMessageDone, AgentMessageError, AgentMessageUsage, AgentStatus, } from "./types/protocol.js";
 export type { SandboxProvider, DesktopSandboxProvider, } from "./types/sandbox.js";
 export { AgentComposeClient } from "./client.js";
-export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, } from "./client.js";
+export type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult, RunLogLine, ListRunLogsOptions, RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse, ApiKey, ApiKeyCreated, UsageRollupRow, UsageResponse, CancelRunResponse, RequestAgentPauseOptions, RequestAgentPauseResponse, SendAgentMessageOptions, SendAgentMessageResponse, AnswerSteerOptions, ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor, } from "./client.js";
 export { parseSseStream } from "./sse.js";
 export { AgentComposeError } from "./errors.js";
 export { formatError } from "./utils/errors.js";
@@ -50,6 +51,7 @@ export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/in
 export type { CodingTool } from "./tools/index.js";
 export type { RunEvent } from "./types/events.js";
 export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById, getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, makeSandboxProvider, makeDesktopSandboxProvider, parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
+export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 export type { SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName, SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox, ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult, } from "./sandbox.js";
 export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
 export type { WorkflowResult, RunWorkflowOptions, EngineSubsystem } from "./workflows/engine.js";