@agent-compose/sdk 0.5.5 → 0.5.7

package/src/step-invocation/invoker.ts

@@ -23,8 +23,9 @@
 
 import { randomBytes } from "node:crypto";
 import { z } from "zod";
+import { SandboxUnavailableError } from "../sandbox-errors.js";
 import type { SandboxProvider } from "../types/sandbox.js";
-import { RUNNER_COMMAND, STEP_ENV, stepResultLinePrefix, stepPauseLinePrefix, requestContextPath, stepInputPath } from "./protocol.js";
+import { RUNNER_COMMAND, STEP_ENV, stepResultLinePrefix, stepPauseLinePrefix, requestContextPath, stepInputPath, stepResultFilePath } from "./protocol.js";
 import { StepPauseRequestSchema } from "./types.js";
 import type { StepRequest, StepResult } from "./types.js";
 import type { StepObservability } from "../workflow-steps/observability.js";
@@ -113,6 +114,20 @@ export function parseStepResult<TOutput = unknown>(
     if (pauseLine && resultLine) break;
   }
 
+  // Fallback: a concurrent writer whose chunk ended WITHOUT a newline can
+  // glue noise onto the front of the sentinel ("…noise__AC_STEP_…"),
+  // defeating the line-anchored scan. The per-invocation token is
+  // unguessable, so matching the prefix mid-line is equally sound —
+  // extract from the prefix to that line's end.
+  const midLine = (prefix: string): string | undefined => {
+    const at = stdout.indexOf(prefix);
+    if (at === -1) return undefined;
+    const end = stdout.indexOf("\n", at);
+    return stdout.slice(at, end === -1 ? undefined : end);
+  };
+  if (!pauseLine)  pauseLine  = midLine(pausePrefix);
+  if (!resultLine) resultLine = midLine(resultPrefix);
+
   if (pauseLine) {
     try {
       const raw = JSON.parse(pauseLine.slice(pausePrefix.length));
@@ -244,18 +259,54 @@ export async function invokeStep<TOutput = unknown>(
   const stdoutSplitter = makeLineSplitter(opts?.onStdout, true);
   const stderrSplitter = makeLineSplitter(opts?.onStderr, false);
 
-  const result = await sandbox.commands.run(RUNNER_COMMAND, {
-    envs,
-    timeoutMs: 0,
-    ...(stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {}),
-    ...(stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}),
-  });
+  let result: { stdout: string; stderr: string; exitCode: number };
+  try {
+    result = await sandbox.commands.run(RUNNER_COMMAND, {
+      envs,
+      timeoutMs: 0,
+      ...(stdoutSplitter.onChunk ? { onStdout: stdoutSplitter.onChunk } : {}),
+      ...(stderrSplitter.onChunk ? { onStderr: stderrSplitter.onChunk } : {}),
+    });
+  } catch (e) {
+    // Typed sandbox-infrastructure failure: the engine's recovery contract
+    // (re-provision when retryable, honest terminal classification otherwise)
+    // keys on this error propagating INTACT — its `[sandbox-unavailable:*]`
+    // message prefix must reach the workflow as the failure leaf, not ride an
+    // embedded stderr tail that a later slice(-2000) can drop. Rethrow before
+    // the CommandExitError downgrade below.
+    if (e instanceof SandboxUnavailableError) throw e;
+    // Some providers (E2B) throw a CommandExitError on a non-zero exit instead of
+    // returning it. Recover stdout/stderr/exitCode from the error so we can STILL
+    // parse the runner's structured `__AC_STEP_RESULT__` payload — otherwise the
+    // real failure reason is lost behind a generic "exit status 1".
+    const ce = e as { stdout?: string; stderr?: string; exitCode?: number; result?: { stdout?: string; stderr?: string; exitCode?: number } };
+    result = {
+      stdout:   ce.stdout ?? ce.result?.stdout ?? "",
+      stderr:   ce.stderr ?? ce.result?.stderr ?? (e instanceof Error ? e.message : String(e)),
+      exitCode: ce.exitCode ?? ce.result?.exitCode ?? 1,
+    };
+  }
   stdoutSplitter.flush();
   stderrSplitter.flush();
 
   const parsed = parseStepResult<TOutput>(result.stdout, resultToken);
   if (parsed) return parsed;
 
+  // No sentinel on stdout. The runner also persists the sentinel line to a
+  // token-keyed file before emitting — providers drop the tail of heavy
+  // stdout streams, so read the durable copy back. Tried before exit-code
+  // classification: a runner that exited 1 after a user-step throw still
+  // wrote the file, and its `{ok:false, kind:"user-step"}` beats a generic
+  // runner-exit error. A runner killed before emitting wrote no file and
+  // falls through.
+  const fileRead = await sandbox.commands.run(
+    `cat ${stepResultFilePath(resultToken)} 2>/dev/null || true`,
+  ).catch(() => null);
+  if (fileRead?.stdout) {
+    const fromFile = parseStepResult<TOutput>(fileRead.stdout, resultToken);
+    if (fromFile) return fromFile;
+  }
+
   // No tokenised sentinel on stdout. Distinguish "runner exited badly
   // before emitting" (runner-exit) from "runner exited cleanly but didn't
   // speak the protocol" (protocol) — the exit code is the evidence.
@@ -275,8 +326,15 @@ export async function invokeStep<TOutput = unknown>(
       },
     };
   }
+  // Carry the stdout tail: "no tokenised step result" alone is useless to
+  // an operator — the tail usually shows whether the runner finished its
+  // work (output truncated by the provider) or never got there.
+  const tail = result.stdout.trim().slice(-500);
   return {
     ok: false,
-    error: { kind: "protocol", message: "no tokenised step result found on stdout" },
+    error: {
+      kind: "protocol",
+      message: `no tokenised step result on stdout or in the result file (runner exited 0 without emitting)${tail ? `\nstdout tail:\n${tail}` : ""}`,
+    },
   };
 }

package/src/step-invocation/protocol.ts

@@ -71,3 +71,12 @@ export function stepInputPath(stepIndex: number): string {
 export function requestContextPath(stepIndex: number): string {
   return `/tmp/wf/request-context-${stepIndex}.json`;
 }
+
+/** 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 function stepResultFilePath(token: string): string {
+  return `/tmp/wf/step-result-${token}.json`;
+}

package/src/step-invocation/server.ts

@@ -21,11 +21,11 @@
  * trust nothing runs after.
  */
 
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import type { RequestContextWire } from "../request-context/request-context.js";
 import { RequestContextWireSchema } from "../request-context/request-context.js";
 import type { StepObservability } from "../workflow-steps/observability.js";
-import { STEP_ENV, STEP_PAUSE_PREFIX, STEP_RESULT_PREFIX } from "./protocol.js";
+import { STEP_ENV, STEP_PAUSE_PREFIX, STEP_RESULT_PREFIX, stepResultFilePath } from "./protocol.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 
 /** What the handler receives. The serveStep already parsed the input
@@ -76,8 +76,28 @@ function writeSentinelLine(line: string): Promise<void> {
   });
 }
 
+/** Persist the sentinel line as a token-keyed FILE before the stdout
+ *  emit. stdout is the fast path, but sandbox providers can drop the
+ *  tail of a heavy stdout stream — the invoker reads this file back as
+ *  the durable fallback. Best-effort: a write failure must never mask
+ *  the stdout emit. */
+function persistSentinelFile(token: string, line: string): void {
+  try {
+    mkdirSync("/tmp/wf", { recursive: true });
+    writeFileSync(stepResultFilePath(token), line);
+  } catch (err) {
+    process.stderr.write(`[step-server] result-file persist failed: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}
+
 function emitResult(token: string, payload: SentinelPayload): Promise<void> {
-  return writeSentinelLine(`${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}\n`);
+  const line = `${STEP_RESULT_PREFIX}${token}:${JSON.stringify(payload)}\n`;
+  persistSentinelFile(token, line);
+  // Leading \n: stdout is shared with user/agent output, and a prior write
+  // that ended WITHOUT a trailing newline would otherwise glue onto this
+  // line — the invoker's line-anchored scan then misses the sentinel
+  // ("no tokenised step result" on heavy-output runs). A blank line is free.
+  return writeSentinelLine(`\n${line}`);
 }
 
 /** Emit the tokenised pause sentinel — `__AC_STEP_PAUSE__<token>:{pauseId,
@@ -91,7 +111,10 @@ function emitPause(token: string, signal: PauseSignal): Promise<void> {
     pauseRequest: signal.pauseRequest,
     ...(signal.observability ? { observability: signal.observability } : {}),
   });
-  return writeSentinelLine(`${STEP_PAUSE_PREFIX}${token}:${body}\n`);
+  const line = `${STEP_PAUSE_PREFIX}${token}:${body}\n`;
+  persistSentinelFile(token, line);
+  // Leading \n for the same partial-line immunity as emitResult.
+  return writeSentinelLine(`\n${line}`);
 }
 
 /** Delete step-invocation transport envs so the user's workflow code

package/src/types/sandbox-environment.ts

@@ -48,20 +48,11 @@ 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 function defineSandboxEnvironment(
   env: SandboxEnvironmentDefinition,
 ): Workflow<Record<string, unknown>, void> {
@@ -71,7 +62,6 @@ export function defineSandboxEnvironment(
   return defineWorkflow<void, Record<string, unknown>>({
     ...(env.description !== undefined ? { description: env.description } : {}),
     snapshots: env.snapshots ?? { saveLatest: true },
-    memory:    env.memory    ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox),
   });
 }

package/src/types/sandbox.ts

@@ -3,6 +3,8 @@
  * 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;
@@ -23,6 +25,22 @@ export interface SandboxCommandResult {
   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. */
@@ -38,15 +56,22 @@ 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
    *  be omitted when the provider doesn't expose it; the server stores
    *  `null` for missing values rather than estimating. */
   snapshot?(): Promise<{ 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,

package/src/types/workflow-metadata.ts

@@ -20,28 +20,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
@@ -73,6 +77,70 @@ export interface IOSchema {
  *  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
@@ -94,14 +162,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;
 }
 
 /**
@@ -129,8 +199,9 @@ export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMeta
   if (source.outputSchema  !== undefined) out.outputSchema  = freezeMetadataValue(source.outputSchema);
   if (source.snapshots     !== undefined) out.snapshots     = Object.freeze({ ...source.snapshots });
   if (source.processors    !== undefined) out.processors    = Object.freeze([...source.processors]);
-  if (source.memory        !== undefined) out.memory        = source.memory;
-  if (source.postRunHooks     !== undefined) out.postRunHooks     = Object.freeze([...source.postRunHooks]);
+  if (source.connectors        !== undefined) out.connectors        = freezeMetadataValue(source.connectors);
+  if (source.connectorOperation !== undefined) out.connectorOperation = Object.freeze({ ...source.connectorOperation });
+  if (source.invokePolicy       !== undefined) out.invokePolicy       = freezeMetadataValue(source.invokePolicy);
   return Object.freeze(out);
 }
 

package/src/types/workflow.ts

@@ -24,7 +24,7 @@ import type { StepWorkflowDefinition } from "../workflow-steps/workflow.js";
 import type { Step, Workflow } from "../workflow-steps/types.js";
 import { WORKFLOW_BRAND } from "../workflow-steps/types.js";
 import type { BaseExecutionContext, WorkflowRun } from "./execution-context.js";
-import { extractMetadata, type WorkflowMetadata } from "./workflow-metadata.js";
+import { extractMetadata, type WorkflowMetadata, type ConnectorRequirements, type ConnectorOperationTag, type InvokePolicy } from "./workflow-metadata.js";
 
 export type { WorkflowRun, InvokeChild, BaseExecutionContext } from "./execution-context.js";
 // Re-export so consumers can keep importing `WorkflowMetadata` from
@@ -37,8 +37,8 @@ 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. */
@@ -156,14 +156,41 @@ export interface WorkflowDefinition<
    * }
    */
   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;
 }
 
 /**

package/src/utils/bundler.ts

@@ -24,7 +24,8 @@ import { createHash } from "node:crypto";
 import { parse as babelParse } from "@babel/parser";
 import type { File, ExportDefaultDeclaration, CallExpression, Expression, Statement } from "@babel/types";
 import { importSourceModule } from "./source-loader.js";
-import type { WorkflowMemoryConfig, SnapshotConfig } from "../types/workflow.js";
+import type { SnapshotConfig } from "../types/workflow.js";
+import type { IOSchema, OutputSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "../types/workflow-metadata.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { isWorkflow } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
@@ -33,8 +34,33 @@ import { workflowPlan, 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 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 const BUNDLER_VERSION = 2;
 
 /**
  * Manifest emitted alongside the bundled source. Fully serialisable JSON;
@@ -73,16 +99,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;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
@@ -305,8 +334,9 @@ export async function bundleWorkflow(
     ...(inputSchema              !== undefined ? { inputSchema }                        : {}),
     ...(outputSchema             !== undefined ? { outputSchema }                       : {}),
     ...(metadata.snapshots       !== undefined ? { snapshots:    metadata.snapshots }    : {}),
-    ...(metadata.memory          !== undefined ? { memory:       metadata.memory }       : {}),
-    ...(metadata.postRunHooks    !== undefined ? { postRunHooks: metadata.postRunHooks } : {}),
+    ...(metadata.connectors          !== undefined ? { connectors:          metadata.connectors }          : {}),
+    ...(metadata.connectorOperation  !== undefined ? { connectorOperation:  metadata.connectorOperation }  : {}),
+    ...(metadata.invokePolicy        !== undefined ? { invokePolicy:        metadata.invokePolicy }        : {}),
   };
 }
 
@@ -322,7 +352,7 @@ export async function bundleWorkflow(
  *      no meaningful contract to render). */
 function extractIOSchema(
   zodSchema: { _zod?: unknown } | unknown,
-): import("../types/workflow-metadata.js").IOSchema | undefined {
+): IOSchema | undefined {
   // Late require to keep this module tree-shakeable for callers that
   // don't bundle. `toJSONSchema` lives on the top-level Zod export in v4.
   let json: Record<string, unknown> | undefined;
@@ -340,7 +370,7 @@ function extractIOSchema(
   // — there's nothing useful to show.
   if (Object.keys(json).filter((k) => k !== "$schema").length === 0) return undefined;
 
-  const out: import("../types/workflow-metadata.js").OutputSchema = {};
+  const out: OutputSchema = {};
   if (json.type        !== undefined) out.type        = json.type as string | string[];
   if (json.description !== undefined) out.description = String(json.description);
   if (json.properties && typeof json.properties === "object") {

package/src/workflow-steps/workflow.ts

@@ -23,7 +23,7 @@ import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";
 import { WORKFLOW_BRAND } from "./types.js";
 import { extractMetadata } from "../types/workflow-metadata.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";
 
@@ -51,8 +51,6 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?:  Record<string, string>;
   snapshots?:     SnapshotConfig;
-  memory?:        WorkflowMemoryConfig;
-  postRunHooks?:  readonly string[];
   processors?:    readonly Processor[];
 }