@agent-compose/sdk 0.5.5 → 0.5.7

package/dist/sandbox-errors.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Sandbox-infrastructure error.
+ *
+ * Distinct from `StepExecutionError` (the user/runner step-failure wrapper):
+ * that's the workflow author's problem. A `SandboxUnavailableError` means the
+ * sandbox itself couldn't carry the step — the provider refused a command, the
+ * sandbox was reclaimed (idle/lifetime timeout, eviction), an API blip, or the
+ * connection dropped mid-stream. None of these are a fault in the customer's
+ * code, so they're surfaced as "infrastructure issue, retry" rather than
+ * blaming the user.
+ *
+ * ## Retryability is about *when*, not *which error*
+ *
+ * The Vercel provider (`sandbox.ts`) decides `retryable` purely from *where* it
+ * caught the error — not by inspecting status codes or error vocabularies:
+ *   - `retryable: true`  — caught before the runner launched the step (file
+ *     write / command launch / reconnect refused). No user code ran, so
+ *     re-provisioning a fresh sandbox and re-running the step is safe. ANY
+ *     error here qualifies (sandbox reclaimed, 429, 5xx, network blip).
+ *   - `retryable: false` — caught while/after the runner streamed, so user code
+ *     may already have executed side effects. Surfaced honestly as an infra
+ *     failure, but NOT auto-retried.
+ *
+ * ## Cross-process contract
+ *
+ * The thrown error crosses the Temporal activity→workflow serialisation
+ * boundary, which preserves the error **message** but discards custom instance
+ * fields. So the retryability signal is encoded IN the message via a stable
+ * prefix — `[sandbox-unavailable:retryable]` or `[sandbox-unavailable:terminal]`
+ * — following the same `[kind] …` convention `StepExecutionError` uses. The
+ * server (`utils/transient-errors.ts`) matches this prefix with a pure regex to
+ * classify the failure and decide whether the workflow re-provisions and
+ * retries. A unit test pins the SDK-produced string against the server matcher
+ * so the two can't drift.
+ */
+/** Stable message prefix. Both variants share this leading token so a single
+ *  server-side regex recognises the class; the `:retryable` / `:terminal`
+ *  suffix carries the recovery decision. */
+export declare const SANDBOX_UNAVAILABLE_PREFIX = "[sandbox-unavailable";
+export declare class SandboxUnavailableError extends Error {
+    /** True when caught before any user code ran (safe to re-provision + retry);
+     *  false when the sandbox died mid/after execution. */
+    readonly retryable: boolean;
+    readonly sandboxId: string | undefined;
+    constructor(detail: string, opts: {
+        retryable: boolean;
+        sandboxId?: string;
+    });
+}

package/dist/sandbox.d.ts

@@ -7,20 +7,29 @@
 import { Sandbox } from "e2b";
 import { Sandbox as Desktop } from "@e2b/desktop";
 import type { SandboxProvider, DesktopSandboxProvider, SandboxCommandResult } from "./types/sandbox.js";
+import type { ConnectorRequestRules } from "./types/workflow-metadata.js";
+import type { NetworkPolicy as VercelNetworkPolicy } from "@vercel/sandbox";
 export type { SandboxProvider, DesktopSandboxProvider, SandboxCommandRunOptions, SandboxCommandResult } from "./types/sandbox.js";
 export type SandboxProviderName = "vercel" | "e2b" | "e2b-desktop";
 export declare const AGENT_COMPOSE_TAG: string;
 /**
- * Vercel-compatible network policy for outbound HTTPS requests.
- * When a sandbox makes a request matching a domain in `allow`, the Vercel
- * firewall injects the specified headers before forwarding — credentials never
- * exist inside the VM. E2B ignores this field (future self-hosted mapping TBD).
+ * Network policy for outbound HTTPS requests — ONE shape for every provider;
+ * only the enforcement point differs. When a sandbox makes a request matching
+ * a domain in `allow`, the egress layer injects the specified headers before
+ * forwarding — credentials never exist inside the VM. Vercel's firewall
+ * enforces this natively (`requestRules` translate to native `match` rules);
+ * E2B enforces it via the embedded iron-proxy, which pulls the identical
+ * resolved policy from the server.
  */
 export interface SandboxNetworkHeaderTransform {
     headers?: Record<string, string>;
 }
 export interface SandboxNetworkAllowRule {
     transform?: SandboxNetworkHeaderTransform[];
+    /** Tier-2 request gate (method/path) — the transform (and, on iron-proxy,
+     *  the request itself) only applies when the request matches. Present on
+     *  connector-auth rules; see `ConnectorRequestRules`. */
+    requestRules?: ConnectorRequestRules;
 }
 export interface SandboxNetworkSubnetPolicy {
     allow?: string[];
@@ -34,15 +43,22 @@ export interface SandboxCreateOpts {
     envs: Record<string, string>;
     metadata: Record<string, string>;
     timeoutMs: number;
-    /** Provider-specific template/snapshot identifier. E2B: template ID; Vercel: snapshot ID. */
+    /** Provider-specific template/snapshot identifier. E2B: template id or
+     *  snapshot id (omit → E2B's default base). Vercel: snapshot id (omit → node24). */
     template?: string;
-    /** Outbound request policy. Vercel only — E2B silently ignores. */
+    /** Outbound request policy with header transforms — ONE shape for every
+     *  provider; only the enforcement point differs. Vercel's firewall
+     *  enforces + injects natively from this value. E2B enforces it via an
+     *  EMBEDDED iron-proxy inside the VM (loopback DNS + iptables, started
+     *  at boot), which fetches the identical resolved policy from the
+     *  server's per-run egress-policy endpoint — so this field is not passed
+     *  to E2B's API. See server/src/sandbox/iron-proxy.ts. */
     networkPolicy?: SandboxNetworkPolicy;
 }
 /**
  * What the provider reports as "currently alive" — the single input to orphan
  * reconciliation. `metadata` is best-effort: E2B populates it from sandbox
- * labels, Vercel leaves it empty (the API has no metadata field). Callers
+ * labels, Vercel from sandbox tags (max 5, stamped at create). Callers
  * that need runId correlation cross-reference `sandboxId` against their own
  * state (server: `workflow_runs.sandbox_id` + `run_agent_sandboxes.provider_sandbox_id`).
  */
@@ -60,18 +76,17 @@ interface SandboxProviderDef {
      * Returns the number of sandboxes currently running against this provider.
      * Used for quota observability — account-wide, not per-instance.
      *
-     * E2B scopes by our AGENT_COMPOSE_TAG metadata so each machine only reports
-     * its own sandboxes; DD aggregates across instances with `sum by {provider}`.
-     * Vercel has no user metadata support, so it counts every running sandbox in
-     * the configured project (assumed dedicated to agent-compose).
+     * Both providers scope by our AGENT_COMPOSE_TAG (E2B metadata labels,
+     * Vercel tags) so each fleet only reports its own sandboxes; DD aggregates
+     * across instances with `sum by {provider}`.
      */
     getActiveCount?: (env: Record<string, string>) => Promise<number>;
     /**
      * Provider's view of what's currently alive for our account/fleet.
      * The reconciliation SoT — a sandbox missing from this list IS dead,
      * regardless of what our DB says. Implemented by listing the provider's
-     * running sandboxes; E2B filters by metadata tag, Vercel lists the whole
-     * project (it has no metadata search). 200-row cap applies to Vercel.
+     * running sandboxes; E2B filters by metadata tag, Vercel by the `executor`
+     * sandbox tag.
      */
     listOwned?: (env: Record<string, string>) => Promise<OwnedSandbox[]>;
     /**
@@ -93,6 +108,46 @@ export interface ParseSseExecStreamOptions {
  * Used by the agent sandbox broker in runner.ts.
  */
 export declare function parseSseExecStream(body: ReadableStream<Uint8Array>, opts?: ParseSseExecStreamOptions): Promise<SandboxCommandResult>;
+/** Matches a path containing a dot-dot segment — literal (`/../`) or
+ *  percent-encoded (`%2e%2e`, `%2f` boundaries). `DOT_SEGMENT_PATH_RE2` is
+ *  the RE2 form handed to Vercel's matcher: wrapped in `.*` so it behaves
+ *  identically under search and full-match semantics (RE2 has no lookaround,
+ *  so the guard is a positive match on the traversal pattern, used as a
+ *  credential-stripping first rule). `DOT_SEGMENT_RE` is the local JS twin
+ *  used to validate DECLARED prefixes. */
+export declare const DOT_SEGMENT_PATH_RE2 = ".*(?:^|/|%2[fF])(?:\\.|%2[eE]){2}(?:/|%2[fF]|$).*";
+/**
+ * Translate our policy shape into Vercel's native `NetworkPolicy`.
+ *
+ * The shapes are identical except for Tier-2: our `requestRules`
+ * (`{ methods, pathPrefixes }`) become Vercel `match` rules
+ * (`{ method, path: { startsWith } }`) — one rule per path prefix, since a
+ * Vercel matcher carries a single path.
+ *
+ * Dot-segment defense: prefix matching is raw — `/repos/acme/../../user`
+ * starts with `/repos/acme/` but the origin normalizes it to `/user`, riding
+ * the credential outside its declared scope. We don't get to assume the
+ * enforcer RFC-3986-normalizes before matching, so every domain with a path
+ * gate gets a transform-free FIRST rule matching dot-segment paths
+ * (first-match-wins ⇒ such requests go out credential-free), and declared
+ * prefixes themselves are validated (must start with "/", no dot-segments).
+ *
+ * Accepted divergence from iron-proxy (E2B): off-gate requests to an allowed
+ * domain pass WITHOUT the transform (Vercel terminates TLS only for
+ * transform-bearing domains and applies first-match-wins) — iron-proxy
+ * REFUSES them instead. Reachability differs; the property that matters is
+ * preserved on both substrates: the brokered credential rides only declared
+ * method/path combinations. Pinned by vercel-network-policy.test.ts.
+ */
+export declare function toVercelNetworkPolicy(policy: SandboxNetworkPolicy): VercelNetworkPolicy;
+/** Vercel caps sandbox tags at 5. Build the tag set with the fleet `executor`
+ *  tag always present and always winning over caller metadata — `listOwned` /
+ *  orphan reconciliation scope on it, so a clobbered or dropped executor tag
+ *  makes the sandbox invisible to cleanup. When metadata overflows the cap,
+ *  keep executor + the lexicographically-first 4 metadata keys, so what gets
+ *  dropped is deterministic rather than dependent on object insertion order. */
+export declare const VERCEL_MAX_TAGS = 5;
+export declare function buildVercelTags(metadata: Record<string, string>): Record<string, string>;
 /** Minimal SandboxProvider that targets the current process's host VM.
  *  `commands.run` → `child_process.spawn`; `files.write` → `fs.writeFile`;
  *  `kill` is a no-op because the caller IS the VM. Used by

package/dist/step-invocation/protocol.d.ts

@@ -54,3 +54,9 @@ export declare function stepInputPath(stepIndex: number): string;
  *  context. The serveStep reads from this exact path; both halves use
  *  this helper. */
 export declare function requestContextPath(stepIndex: number): string;
+/** Sandbox-side path where the runner persists the sentinel line as a
+ *  FILE, keyed by the per-invocation token (unique even across resumes
+ *  of the same step index). stdout is the fast path, but providers can
+ *  drop the tail of a heavy stdout stream — the invoker falls back to
+ *  reading this file when no sentinel is found on stdout. */
+export declare function stepResultFilePath(token: string): string;

package/dist/types/sandbox-environment.d.ts

@@ -45,17 +45,8 @@ export interface SandboxEnvironmentDefinition {
      *  useful — an env with no snapshot can't be referenced as a
      *  `bootFrom` on another workflow). */
     snapshots?: SnapshotConfig;
-    /** Override the sugar's `memory: false` default. Setup workflows
-     *  don't typically benefit from memory extraction; opt in explicitly
-     *  when they do. */
-    memory?: boolean;
 }
 /** Sugar over `defineWorkflow` for setup-only workflows that exist to
  *  capture a snapshot. The workflow takes no meaningful input and returns
- *  nothing — its value is the side effect on the sandbox VM.
- *
- *  Defaults `memory: false` because sandbox environments emit setup
- *  output (npm installs, command exit codes) rather than agent traces
- *  worth memorising. Authors can opt in explicitly via `env.memory:
- *  true` if their environment somehow does want extraction. */
+ *  nothing — its value is the side effect on the sandbox VM. */
 export declare function defineSandboxEnvironment(env: SandboxEnvironmentDefinition): Workflow<Record<string, unknown>, void>;

package/dist/types/sandbox.d.ts

@@ -2,6 +2,7 @@
  * Sandbox abstraction — the compute environment an agent runs inside.
  * Provider-agnostic: E2B, Vercel, Docker, or any other backend implements this.
  */
+import type { SandboxNetworkPolicy } from "../sandbox.js";
 /** Base compute interface — pure I/O, no filesystem path or git concerns. */
 export interface SandboxCommandRunOptions {
     cwd?: string;
@@ -20,6 +21,22 @@ export interface SandboxCommandResult {
     stdout: string;
     stderr: string;
 }
+/**
+ * A sandbox provider implements the RAW provider operations only. It does NOT
+ * implement transient-failure retry/backoff: reconnecting and snapshotting both
+ * pause/resume/transition the sandbox and race with it being reclaimed/stopped
+ * under load (E2B "Paused sandbox not found", Vercel stopping-sandbox calls,
+ * 5xx/429, dropped connections). That resilience is supplied centrally —
+ * `reconnectSandbox` runs every provider's `reconnect` through
+ * `withSandboxRetry` (generic p-retry backoff, gated by
+ * `isTransientSandboxError`), and `createSandbox`/`reconnectSandbox` wrap the
+ * returned provider's `snapshot` the same way (via `withSnapshotRetry`).
+ * `create` is deliberately NOT retried: a create whose response is lost would
+ * mint a second billed sandbox and orphan the first; provision failures are
+ * re-attempted at the workflow layer instead. So: a NEW provider only writes
+ * the happy-path call; the abstraction guarantees the robust pattern, and no
+ * provider re-implements it.
+ */
 export interface SandboxProvider {
     sandboxId: string;
     /** Working directory for the agent process. Set by onStart after environment setup. */
@@ -31,9 +48,9 @@ export interface SandboxProvider {
         write(path: string, content: string): Promise<void>;
     };
     kill(): Promise<void>;
-    /** Capture the running sandbox's state as a reusable snapshot. Vercel
-     *  supports it natively; E2B's model is Dockerfile-based and doesn't map
-     *  cleanly — `undefined` on providers that don't. Used by the server's
+    /** Capture the running sandbox's state as a reusable snapshot. Vercel and E2B
+     *  both support it natively (E2B via `createSnapshot()`); providers without a
+     *  live-snapshot primitive return `undefined`. Used by the server's
      *  `--build` flow to stamp the snapshot id on the workflow row.
      *
      *  `sizeBytes` is the on-disk footprint reported by the provider. May
@@ -43,6 +60,13 @@ export interface SandboxProvider {
         snapshotId: string;
         sizeBytes?: number;
     }>;
+    /** Replace the live sandbox's egress policy in place. Vercel implements
+     *  it via `sandbox.update({ networkPolicy })` (2.x) so the server can
+     *  push a freshly resolved policy — with re-minted connector access
+     *  tokens — before each step instead of relying on the policy baked at
+     *  create. Providers whose enforcement lives inside the VM (E2B
+     *  iron-proxy) leave it undefined. */
+    updateNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
 }
 /** Stateless provider-level snapshot deletion — no live sandbox needed,
  *  called from customer-initiated `DELETE /workflows/:runId/snapshot`. */

package/dist/types/workflow-metadata.d.ts

@@ -18,28 +18,32 @@ import type { Processor } from "../processors/processor.js";
  * The bundler reads these from the default export at registration time
  * and forwards them to the server's POST /api/v1/templates payload.
  */
-/** Whether the built-in Workflow Memory extractor should run after this
- *  workflow completes. Boolean toggle — custom post-run workflows live
- *  in the separate `postRunHooks` array on `WorkflowMetadata`. */
-export type WorkflowMemoryConfig = boolean;
-/** Where a run boots from. The snapshot id is the unit of identity —
- *  each captured snapshot already records the workflow + version it
- *  came from on the snapshot row, so there's no separate "latest of
- *  workflow X" resolution at dispatch time. Operators pick a snapshot
- *  from the dashboard snapshot list (or `agentc snapshot list`) and
- *  paste the id here.
- *
- *  Omit `bootFrom` entirely to boot a fresh base sandbox. */
+/** Boot from a specific captured snapshot, addressed by its id. Operators
+ *  pick one from the dashboard snapshot list (or `agentc snapshot list`) and
+ *  paste the id here. */
 export type BootSnapshot = {
     snapshotId: string;
 };
+/** Boot from this workflow's OWN most recent snapshot, scoped to its content
+ *  hash. The first run — and the first after a re-register changes the source
+ *  — finds none and boots a fresh base sandbox; `"reuse"` also implies
+ *  `saveLatest`, so that run captures a snapshot and every run after it boots
+ *  from it. This lets a runtime install its tooling once (e.g. a CLI-agent
+ *  runtime `npm i -g`'ing its CLI) and skip the install on every later run,
+ *  with no hardcoded snapshot id to manage. Re-registering with changed
+ *  source rolls the content hash, which transparently invalidates the cache
+ *  and re-installs on the next run. */
+export type ReuseSnapshot = "reuse";
 /** Snapshot configuration — boot source plus capture knobs. One object
  *  per workflow / per invocation; collapsing boot + capture under a
  *  single key reads as "all snapshot config lives here." */
 export interface SnapshotConfig {
-    /** Where the runner restores from at run start. Structured (workflow
-     *  ref or snapshot id) so the intent is explicit at the call site. */
-    bootFrom?: BootSnapshot;
+    /** Where the runner restores from at run start:
+     *  - `{ snapshotId }` — a specific captured snapshot.
+     *  - `"reuse"` — this workflow's own latest snapshot (content-hash scoped);
+     *    fresh on the first run / after a re-register. Implies `saveLatest`.
+     *  - omitted — a fresh base sandbox. */
+    bootFrom?: BootSnapshot | ReuseSnapshot;
     /** Capture the sandbox state on terminal success. The latest pointer
      *  on `workflow_runs.vercel_snapshot_id` always tracks the most
      *  recent capture; without `retainSteps`, prior captures are deleted
@@ -71,6 +75,65 @@ export interface IOSchema {
 /** Alias kept for backwards source-compatibility with the original
  *  output-only release. New code should prefer `IOSchema`. */
 export type OutputSchema = IOSchema;
+/** Per-connector HTTP request matcher (Tier-2 capability narrowing). The
+ *  iron-proxy / firewall consults these when deciding whether to attach the
+ *  brokered Authorization header to an outbound request. A request to the
+ *  connector host whose method is not in `methods`, or whose path matches no
+ *  entry in `pathPrefixes`, is refused (403) and the token is WITHHELD. */
+export interface ConnectorRequestRules {
+    /** Allowed HTTP methods (upper-case). Omit = any method (subject to
+     *  `access`). */
+    methods?: string[];
+    /** Allowed path prefixes (matched against the request path, case-
+     *  sensitive). Omit = any path. */
+    pathPrefixes?: string[];
+}
+/** One provider entry in a workflow's `connectors` declaration (ADR-0007).
+ *  Scopes are the provider-side OAuth scopes the workflow's API calls
+ *  need; registration warns when no installed grant covers them. */
+export interface ConnectorRequirement {
+    scopes?: string[];
+    /** Coarse capability bound on the brokered token. `"read"` defaults the
+     *  allowed methods to GET/HEAD/OPTIONS (unless `request.methods` overrides)
+     *  and, for the GitHub App provider, narrows the minted installation token
+     *  to `contents: read`. `"write"` permits all methods. Omit = `"write"`
+     *  (unchanged broad behaviour). */
+    access?: "read" | "write";
+    /** Fine-grained per-request matcher enforced at the egress proxy. */
+    request?: ConnectorRequestRules;
+}
+/** Map of provider key (`github`, `slack`, …) → requirement. Declaring a
+ *  provider here makes the server resolve an authorized grant at dispatch
+ *  and inject a fresh access token at the network layer — workflow code
+ *  calls the provider API with plain fetch/SDKs and never sees the token. */
+export type ConnectorRequirements = Record<string, ConnectorRequirement>;
+/** Marks this workflow as a catalogue OPERATION of a connector — e.g. the
+ *  `create-issue` operation of the `github` connector. Operations are
+ *  ordinary workflows (deterministic or agent-driven) that declare the
+ *  matching `connectors` requirement; the tag is what groups them under
+ *  the connector in the dashboard catalogue and the agent-facing
+ *  operation listing. Together with `description` + `input`/`output`
+ *  schemas this gives every operation MCP-tool-like self-description:
+ *  what it does, what it takes, what it produces. */
+export interface ConnectorOperationTag {
+    provider: string;
+    operation: string;
+}
+/** Tier-1 invoke ACL. When a workflow brokers a connector credential AND
+ *  declares an `invokePolicy`, dispatch evaluates the calling principal
+ *  against it BEFORE binding any grant. A caller matching ANY provided
+ *  clause passes; matching none → HTTP 403. Omit = whole team (unchanged).
+ *
+ *  Each clause is OR-combined:
+ *   - `users`: `"owner"` (only the registering user) or an array of user
+ *     ids / emails the caller must be one of.
+ *   - `apiKeys`: api-key ids permitted to invoke.
+ *   - `workflows`: parent workflow names permitted to child-invoke this one. */
+export interface InvokePolicy {
+    users?: "owner" | string[];
+    apiKeys?: string[];
+    workflows?: string[];
+}
 export interface WorkflowMetadata {
     /** One-line, human-readable description of what the workflow does.
      *  Surfaced on the dashboard template tile + run page header. Authors
@@ -92,14 +155,16 @@ export interface WorkflowMetadata {
     /** All snapshot config — boot source + capture mode. */
     snapshots?: SnapshotConfig;
     processors?: readonly Processor[];
-    /** 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 after this workflow
-     *  completes. The runtime dispatches them in declaration order; the
-     *  built-in memory extractor (when `memory: true`) runs as a separate
-     *  hook alongside whatever's declared here. */
-    postRunHooks?: readonly string[];
+    /** Connector requirements — providers whose APIs this workflow calls.
+     *  Dispatch resolves an authorized grant per provider and injects a
+     *  fresh access token at the network layer (ADR-0007). */
+    connectors?: ConnectorRequirements;
+    /** Catalogue tag marking this workflow as an operation of a connector.
+     *  See `ConnectorOperationTag`. */
+    connectorOperation?: ConnectorOperationTag;
+    /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
+     *  See `InvokePolicy`. */
+    invokePolicy?: InvokePolicy;
 }
 /**
  * Pull the server-readable declarations off a source object (run-form

package/dist/types/workflow.d.ts

@@ -21,13 +21,14 @@ import type { Processor } from "../processors/processor.js";
 import type { StepWorkflowDefinition } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
 import type { BaseExecutionContext } from "./execution-context.js";
+import { type ConnectorRequirements, type ConnectorOperationTag, type InvokePolicy } from "./workflow-metadata.js";
 export type { WorkflowRun, InvokeChild, BaseExecutionContext } from "./execution-context.js";
 export type { WorkflowMetadata } from "./workflow-metadata.js";
 export interface AgentEventSink {
     emit(event: AgentLifecycleEvent): void | Promise<void>;
 }
-import type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
-export type { WorkflowMemoryConfig, SnapshotConfig, BootSnapshot, IOSchema, OutputSchema };
+import type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema } from "./workflow-metadata.js";
+export type { SnapshotConfig, BootSnapshot, ReuseSnapshot, IOSchema, OutputSchema };
 /** Turn/iteration budget for `agent(opts)`. Re-exported here so authors
  *  can type per-invoke budget overrides they pass as workflow input. */
 export interface AgentBudget {
@@ -135,14 +136,41 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      * }
      */
     placeholders?: Record<string, string>;
-    /** Run the built-in memory extractor after this workflow completes.
-     *  Opt-in; defaults to false when omitted. */
-    memory?: WorkflowMemoryConfig;
-    /** Ordered list of workflow names to dispatch as post-hooks after
-     *  this workflow completes. Each hook receives the source run's
-     *  context. The memory extractor (when `memory: true`) runs as an
-     *  additional hook alongside these. */
-    postRunHooks?: readonly string[];
+    /**
+     * Connector requirements (ADR-0007). Declaring a provider makes the
+     * server resolve an authorized OAuth grant for the calling principal at
+     * dispatch time and inject a fresh access token at the network layer —
+     * workflow code talks to the provider API with plain fetch/SDKs and
+     * never holds the credential.
+     *
+     * @example
+     * connectors: { github: { scopes: ["repo"] } }
+     */
+    connectors?: ConnectorRequirements;
+    /**
+     * Marks this workflow as a catalogue OPERATION of a connector — e.g.
+     * the `create-issue` operation of the `github` connector. Pair with
+     * `description` + `input`/`output` schemas so the operation is fully
+     * self-describing (MCP-tool-like) to humans and agents browsing the
+     * connector catalogue.
+     *
+     * @example
+     * connectorOperation: { provider: "github", operation: "create-issue" }
+     */
+    connectorOperation?: ConnectorOperationTag;
+    /**
+     * Tier-1 invoke ACL (connector credential boundary). When this workflow
+     * declares `connectors` (it brokers a credential) AND an `invokePolicy`,
+     * the server evaluates the calling principal against the policy BEFORE
+     * binding any grant — a caller matching no clause is refused with HTTP
+     * 403. Has no effect on workflows that declare no connectors. Omit to
+     * leave the workflow invokable by the whole team.
+     *
+     * @example
+     * connectors: { github: { access: "read" } },
+     * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
+     */
+    invokePolicy?: InvokePolicy;
 }
 /**
  * Declare a workflow. Two forms; both return a `Workflow` whose

package/dist/utils/bundler.d.ts

@@ -19,14 +19,40 @@
  * this function returns alongside the bundled bytes, and cross-checks the
  * manifest's `sourceHash` against the source it received.
  */
-import type { WorkflowMemoryConfig, SnapshotConfig } from "../types/workflow.js";
+import type { SnapshotConfig } from "../types/workflow.js";
+import type { IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { type WorkflowPlan } from "../types/workflow-plan.js";
 /** Bumped when the manifest contract changes in a way the server should
  *  notice. The server pins its manifest schema to this exact value (no
  *  `>=` accepted) so a manifest forged with a future version is refused
- *  by zod before any other validation runs. */
-export declare const BUNDLER_VERSION = 1;
+ *  by zod before any other validation runs. NOTE: this gates NEW
+ *  registrations only — nothing re-validates stored `workflows.metadata`
+ *  rows, so a non-additive metadata change ALSO needs a server-side
+ *  warning for already-registered workflows (see `warnRetiredMetadataKeys`
+ *  in server/src/engine/dispatch.ts).
+ *
+ *  v2: `memory` / `postRunHooks` registration options removed — bundles
+ *  from CLIs that still emit them are refused at register.
+ *
+ *  TODO(registration-versioning): turn this constant into a real migration
+ *  policy so breaking changes start with a number, not an investigation:
+ *    1. Server keeps a MIN_SUPPORTED_BUNDLER_VERSION alongside the exact
+ *       pin — versions in [min, current] keep dispatching; below min gets
+ *       an ACTIONABLE 409 naming the agentc version to re-register with
+ *       (today, pre-enforcement templates with no manifest at all 409 with
+ *       no migration path — see dispatch.ts).
+ *    2. Stamp the SDK version into the manifest at registration, so
+ *       runtime-compat breaks (not just bundler-format breaks) are also
+ *       queryable per stored workflow.
+ *    3. Operator audit = one query: workflows whose
+ *       metadata.manifest.bundlerVersion < current (or missing), grouped
+ *       by team/owner — the definitive "who needs migration" list before
+ *       any breaking release.
+ *    4. Dashboard badge on stale templates: "registered with an older
+ *       toolchain — re-register to update" (pairs with the template
+ *       connector/metadata card work). */
+export declare const BUNDLER_VERSION = 2;
 /**
  * Manifest emitted alongside the bundled source. Fully serialisable JSON;
  * the server validates its shape with zod and never inspects the source
@@ -59,16 +85,19 @@ export interface BundledWorkflow {
      *  restore at run start), `save`, `retain`. */
     snapshots?: SnapshotConfig;
     workflowPlan: WorkflowPlan;
-    /** Workflow Memory extractor config. */
-    memory?: WorkflowMemoryConfig;
-    /** Ordered post-hook workflow names declared on the workflow. */
-    postRunHooks?: readonly string[];
     /** Compact JSON-Schema-shaped description of the workflow's input
      *  type. Extracted from the workflow's declared `input` zod schema
      *  at bundle time; undefined when the schema is `z.unknown()`. */
-    inputSchema?: import("../types/workflow-metadata.js").IOSchema;
+    inputSchema?: IOSchema;
     /** Same for the workflow's output zod schema. */
-    outputSchema?: import("../types/workflow-metadata.js").IOSchema;
+    outputSchema?: IOSchema;
+    /** Connector requirements declared on the workflow (ADR-0007). */
+    connectors?: ConnectorRequirements;
+    /** Connector-catalogue operation tag, when this workflow is one. */
+    connectorOperation?: ConnectorOperationTag;
+    /** Tier-1 invoke ACL — who may dispatch this connector-brokering
+     *  workflow (`defineWorkflow({ invokePolicy })`). */
+    invokePolicy?: InvokePolicy;
 }
 /**
  * Parse the bundled source and assert the default export is a CallExpression

package/dist/workflow-steps/workflow.d.ts

@@ -20,7 +20,7 @@
  */
 import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
-import type { SnapshotConfig, WorkflowMemoryConfig } from "../types/workflow-metadata.js";
+import type { SnapshotConfig } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 export interface WorkflowBuilder<TInput, TCurrent> {
@@ -46,8 +46,6 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     snapshots?: SnapshotConfig;
-    memory?: WorkflowMemoryConfig;
-    postRunHooks?: readonly string[];
     processors?: readonly Processor[];
 }
 export declare function createStepWorkflow<TInput, TOutput>(opts: StepWorkflowDefinition<TInput, TOutput>): WorkflowBuilder<TInput, TInput>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
@@ -64,7 +64,7 @@
     "@babel/parser": "^7.29.3",
     "@babel/types": "^7.29.0",
     "@e2b/desktop": "^1.1.2",
-    "@vercel/sandbox": "^1.10.0",
+    "@vercel/sandbox": "^2.2.0",
     "ai": "^6.0.175",
     "e2b": "^2.3.0",
     "ofetch": "^1.5.1",