@agent-compose/sdk 0.5.7 → 0.5.8

package/dist/agent/__tests__/run-agent-liveness.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * run-agent working-dir liveness probe (the degraded-FUSE-wedge fix).
+ *
+ * `agent()` delivers the platform context file (AGENTS.md / CLAUDE.md /
+ * GEMINI.md) to the working dir AND uses that write as a bounded liveness
+ * probe of the dir. AGENT_COMPOSE_RUN_DIR points at the /factory FUSE drive,
+ * whose writes HANG uninterruptibly (no timeout) when the mount degraded —
+ * launching the agent there wedges it silently with zero output. The probe
+ * bounds the write at 15s and falls back to /workspace (always present +
+ * writable) when the run dir is wedged.
+ *
+ * These tests pin: (1) the happy path keeps RUN_DIR; (2) a RUN_DIR whose write
+ * hangs forever still selects /workspace within the deadline. `agentLoop` is
+ * mocked so we observe only the `cwd` the loop is launched with; fake timers
+ * drive the 15s deadline without waiting in real time.
+ */
+export {};

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

@@ -0,0 +1,67 @@
+/**
+ * Harness-agnostic agent context delivery.
+ *
+ * Every coding-agent harness we drive (Claude Code, Codex, Amp, Gemini, …)
+ * looks for an instruction file in its working directory — but they disagree
+ * on the NAME (Codex/Amp read `AGENTS.md`; Claude reads `CLAUDE.md`; Gemini
+ * reads `GEMINI.md`). So `agent()` writes the SAME platform manual under all
+ * three names at the agent's working dir, and every harness finds the one it
+ * knows. The manual is the single source of truth here; `base-env` bakes a
+ * static copy at `/workspace/AGENTS.md` for plain shell sessions, but the
+ * per-run copy `agent()` writes is the authoritative one — it carries the
+ * live connector list and lands at the run's working dir.
+ */
+import type { SandboxProvider } from "../types/sandbox.js";
+/**
+ * The platform manual delivered to every agent, regardless of harness.
+ * Covers the three things an agent must know: where files go (the factory
+ * drive + the persist-by-default working dir), how to pause for a human, and
+ * that credentials are network-injected (never in the env). The live
+ * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
+ */
+export declare const AGENT_COMPOSE_MANUAL = "# Working inside an Agent Compose sandbox\n\nYou are an agent running in a per-run sandbox on the Agent Compose platform.\nUse the **`agentc` CLI** and the **`@agent-compose/sdk`** for everything below \u2014\ndo NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on\nyour PATH and already authenticated from the environment\n(`AGENT_COMPOSE_URL` / `AGENT_COMPOSE_API_KEY` / `AGENT_COMPOSE_FACTORY` are\ninjected for this run), so commands just work \u2014 no login, no keys to manage.\n\nThe `/ac:*` skills are installed as Claude Code slash commands (`/ac:invoke`,\n`/ac:events`, `/ac:logs`, `/ac:register`, \u2026) \u2014 reach for them too.\n\n## Files \u2014 your outputs persist by default\n\nYour working directory defaults to **`$AGENT_COMPOSE_RUN_DIR`** \u2014 a per-run\ndirectory on the shared factory drive\n(`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/`) the platform\ncreates and attributes to this run. **Files you write here persist by\ndefault** \u2014 they show up in the dashboard's Files tab and the run's Artifacts\ncard, with no API calls to save them. The dir already exists and is writable.\n\nNeed throwaway scratch \u2014 heavy build output, package caches, temp files?\n`cd /tmp` (or any path outside `/factory`): anything off the factory drive is\nephemeral and discarded when the sandbox ends. In short: **stay in your working\ndir to keep something, `cd` out to throw it away.**\n\nThe whole shared drive is POSIX-mounted at `/factory`; the dashboard-visible\nroot is `$AGENT_COMPOSE_FACTORY_DIR` (`/factory/files`). Earlier versions and\nruns live in sibling dirs under\n`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/` \u2014 read them for prior\ncontext. Other workflows' dirs are present but not your concern.\n\n## Events \u2014 the factory timeline\n\nRecord something on the run/factory timeline (the dashboard renders these)\nwith the CLI \u2014 your run id is `$RUN_ID`:\n\n    agentc events send \"$RUN_ID\" <name> --summary \"<one line>\" [--body '<json>']\n\nNames like `note.created` / `brief.posted` surface in the Workbench;\n`agentc events list` reads them back. `/ac:events` is the skill equivalent.\n\n## Runs\n\n    agentc list                          # registered workflows  (/ac:list)\n    agentc logs \"$RUN_ID\"                # a run's logs           (/ac:logs)\n    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)\n\n## Writing workflow / agent code \u2014 the SDK\n\n`@agent-compose/sdk` is installed in `/workspace` \u2014 import it from any script\nyou write there:\n\n    import { defineWorkflow, agent, AgentComposeClient } from \"@agent-compose/sdk\";\n\nUse `/ac:generate-workflow` / `/ac:generate-agent` to scaffold, then\n`agentc register <file.ts>` (or `/ac:register`).\n\n## Pausing to ask the human \u2014 `agentc pause`\n\nWhen you can't or shouldn't proceed without a human, run `agentc pause`. It\nblocks until they answer on the dashboard, then prints their answer to stdout:\n\n    ANSWER=$(agentc pause --reason \"Notion returned 401 \u2014 connect Notion to continue\" \\\n                          --option retry --option skip)\n\nReach for it the moment you hit \u2014 or foresee \u2014 any of these:\n- **A wall only a human can clear:** a 401/403, a missing credential, an\n  unconnected provider, a host the network refuses. Do NOT retry blindly or try\n  to work around it \u2014 pause and say what needs enabling.\n- **A durable or outward-facing action that needs sign-off:** registering a\n  workflow, deploying, sending email/messages, deleting or overwriting shared\n  data, spending money. Prepare everything, then pause for approval BEFORE you\n  commit it.\n- **A judgment call only the human can settle:** an under-specified request,\n  several valid paths, a conflict with existing state, missing input only they have.\n\nYou compose the `--reason` (the ask) yourself; pass `--option` choices when\nthere are clear ones, omit them for a free-form answer. Read the printed answer\nand act on it. Each agent pauses independently \u2014 pausing doesn't stop the others.\n\n## Credentials\n\nConnector credentials (Google, GitHub, \u2026) are NEVER in your environment.\nThey're injected at the network layer when you call an allowed host \u2014 make the\nrequest **without** an Authorization header and the platform adds it. Don't try\nto read or exfiltrate tokens; they aren't here. The \"Connectors & access\"\nsection below (when present) lists exactly which providers this run can reach.\n\n## Tools in this environment\n\n- `agentc` \u2014 Agent Compose CLI (your primary interface; authed from env)\n- `@agent-compose/sdk` \u2014 installed in /workspace for writing workflows\n- `/ac:*` Claude Code skills \u2014 slash commands for the above\n- `archil` (factory drive), `rtk`, `bun`\n- A world-writable `/workspace` working directory";
+/**
+ * One connector this run can reach, as the agent should see it. Strictly
+ * NON-SECRET — hosts, methods, paths, identity only. The access token is
+ * injected at the network layer and never appears here. The server builds
+ * this list at dispatch from the run's connector grants × the provider
+ * catalogue and delivers it as the `AGENT_COMPOSE_CONNECTORS` env (JSON array).
+ */
+export interface AgentConnectorInfo {
+    /** Provider key (`github`, `notion`, …). */
+    provider: string;
+    /** Human label ("GitHub", "Notion"). */
+    name?: string;
+    /** API hosts the credential is injected for. */
+    hosts?: string[];
+    /** Allowed HTTP methods (Tier-2 narrowing). Empty/absent = any. */
+    methods?: string[];
+    /** Allowed path prefixes (Tier-2 narrowing). Empty/absent = any. */
+    pathPrefixes?: string[];
+    /** GitHub: the repository the minted token is scoped to. */
+    repository?: string;
+    /** Coarse capability the token was minted with. */
+    access?: string;
+    /** Human scope descriptions, when the provider declares them. */
+    scopes?: string[];
+}
+/** Compose the full per-run agent doc: the static manual + the live
+ *  connectors section read from `AGENT_COMPOSE_CONNECTORS` (a JSON array;
+ *  malformed/absent → no section). */
+export declare function buildAgentContextDoc(env: Record<string, string | undefined>): string;
+/**
+ * Write the platform context at the agent's working dir under every harness's
+ * instruction-file name, so whichever CLI runs finds the one it reads. Codex
+ * and Amp read `AGENTS.md` natively; Claude reads `CLAUDE.md`; Gemini reads
+ * `GEMINI.md` — we write identical content to all three rather than detect the
+ * harness (the runtime's `kind` isn't known until after spawn, and a few extra
+ * small files in our own run dir are harmless).
+ *
+ * Best-effort: a write failure logs and is swallowed — never fail an agent
+ * because its context file couldn't be written.
+ */
+export declare function writeAgentContext(args: {
+    sandbox: Pick<SandboxProvider, "files">;
+    cwd: string;
+    env: Record<string, string | undefined>;
+}): Promise<void>;

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

@@ -46,6 +46,7 @@ export type AgentMessageSummary = {
     cacheCreationTokens: number;
     durationMs: number;
     numTurns: number;
+    model?: string;
 } | {
     type: "done";
     sessionId: string;

package/dist/client.d.ts

@@ -10,10 +10,10 @@
  * `register()` accepts pre-built sources — use the CLI (`agent-compose
  * register`) or build sources yourself and pass them directly.
  */
-import type { SandboxNetworkPolicy } from "./sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
 import type { WorkflowPlan } from "./types/workflow-plan.js";
-import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "./types/workflow-metadata.js";
+import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "./types/workflow-metadata.js";
 import type { WorkflowManifest } from "./utils/bundler.js";
 export interface RegisterResult {
     id: string;
@@ -67,6 +67,8 @@ export interface RegisterWorkflowInput {
     /** All snapshot config — `bootFrom` (where to restore at run start),
      *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
     snapshots?: SnapshotConfig;
+    /** Sandbox machine size (template default). See `WorkflowMetadata.resources`. */
+    resources?: SandboxResources;
     /** Provider-neutral execution plan detected by the CLI bundler. */
     workflowPlan?: WorkflowPlan;
     /** Connector requirements declared via `defineWorkflow({ connectors })`
@@ -101,6 +103,10 @@ 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 machine-size override of the template's `resources.size`.
+     *  `small` (default) | `medium` | `large`; omit → the template default,
+     *  else `small`. Honoured on Vercel (→ vCPUs); E2B ignores it. */
+    size?: SandboxSize;
     /** 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. */
@@ -135,6 +141,53 @@ export interface TemplateRow {
 export interface ListTemplatesOptions {
     factorySlug?: string;
 }
+/** A human member of your team — the people an agent (or you) can @-flag. */
+export interface TeamMember {
+    /** Membership row id. */
+    id: string;
+    /** The user id — what you pass to `createMentions({ mentionedUserIds })`. */
+    userId: string;
+    role: string;
+    email: string;
+    name: string;
+    joinedAt: string;
+}
+/** A "you were flagged" ping, persisted server-side so it reaches the
+ *  mentioned teammate in their Workbench. */
+export interface Mention {
+    id: string;
+    factoryId: string;
+    mentionedUserId: string;
+    /** Who flagged: 'user' | 'api_key' | 'run' | 'system'. */
+    actorKind: string;
+    actorId: string | null;
+    actorLabel: string | null;
+    /** Where it lives: 'doc' | 'comment' | 'plan' | 'run'. */
+    contextKind: string;
+    contextPath: string | null;
+    /** Ready-made relative dashboard URL the Workbench card links to. */
+    contextUrl: string | null;
+    text: string;
+    runId: string | null;
+    seenAt: string | null;
+    resolvedAt: string | null;
+    createdAt: string;
+}
+export interface CreateMentionsInput {
+    /** Team-member user ids to flag (1–20). Discover them via `listMembers()`.
+     *  Non-members are dropped server-side. */
+    mentionedUserIds: string[];
+    /** The flag message shown in the teammate's Workbench. */
+    text: string;
+    contextKind: "doc" | "comment" | "plan" | "run";
+    /** Factory-relative file path or comment thread id, when applicable. */
+    contextPath?: string;
+    /** Ready-made relative dashboard URL the Workbench card links to (e.g.
+     *  `/factories/<slug>/files/view?path=<plan>`). */
+    contextUrl?: string;
+    runId?: string;
+    factorySlug?: string;
+}
 export interface CreateFactoryInput {
     slug: string;
     name: string;
@@ -622,6 +675,16 @@ export declare class AgentComposeClient {
         factorySlug?: string;
         revision?: number;
     }): Promise<string>;
+    /** List the human members of your team — the people you (or an agent) can
+     *  @-flag with `createMentions`. Each row's `userId` is what
+     *  `mentionedUserIds` expects. */
+    listMembers(): Promise<TeamMember[]>;
+    /** Flag one or more teammates — a durable ping that lands in their factory
+     *  Workbench. Use from an agent (e.g. a remediation plan that needs a human
+     *  to rotate a secret) or any team automation. Resolve `mentionedUserIds`
+     *  via `listMembers()`. When run inside a sandbox the run-callback token is
+     *  forwarded so the ping is attributed to the run ("flagged by <workflow>"). */
+    createMentions(input: CreateMentionsInput): Promise<Mention[]>;
     /** 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

@@ -28,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, 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 type { RegisterResult, RegisterWorkflowInput, RuntimeSourceInput, TemplateSourceRef, InvokeWorkflowOptions, InvokeAndWaitOptions, InvokeResult, ListSnapshotsOptions, TemplateRow, ListTemplatesOptions, CreateFactoryInput, UpdateFactoryInput, SecretOptions, SetSecretResult, SecretListEntry, CreateApiKeyInput, StreamRunLogsOptions, TeamMember, Mention, CreateMentionsInput, 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";
@@ -52,7 +52,8 @@ 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 type { SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform, SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName, SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox, SandboxSize, ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult, } from "./sandbox.js";
+export type { SandboxResources } from "./types/workflow-metadata.js";
 export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
 export type { WorkflowResult, RunWorkflowOptions, EngineSubsystem } from "./workflows/engine.js";
 export { buildInvokeChild } from "./workflows/invoke-child.js";
@@ -62,11 +63,13 @@ export { invokeStep, serveStep, parseStepResult, buildStepEnvs, StepExecutionErr
 export { PauseError, PauseExpiredError, PauseSchemaError, PauseRequestError, } from "./pause/errors.js";
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
-export type { RequestDecisionRequest, WaitForEventRequest } from "./pause/wrappers.js";
+export type { WaitForEventRequest } from "./pause/wrappers.js";
 export type { StepRequest, StepResult, StepInvocationError, StepPauseRequest, StepHandler, StepHandlerResult, ServeStepRequest, } from "./step-invocation/index.js";
 export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent-loop.js";
 export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
 export { agent } from "./agent/run-agent.js";
 export type { AgentOpts } from "./agent/run-agent.js";
+export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext } from "./agent/agent-context.js";
+export type { AgentConnectorInfo } from "./agent/agent-context.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";

package/dist/index.js

@@ -540,6 +540,8 @@ function extractMetadata(source) {
     out.outputSchema = freezeMetadataValue(source.outputSchema);
   if (source.snapshots !== undefined)
     out.snapshots = Object.freeze({ ...source.snapshots });
+  if (source.resources !== undefined)
+    out.resources = Object.freeze({ ...source.resources });
   if (source.processors !== undefined)
     out.processors = Object.freeze([...source.processors]);
   if (source.connectors !== undefined)
@@ -617,7 +619,6 @@ function compileRunForm(def, metadata) {
         agentEvents: stepCtx.agentEvents,
         checkpoint: stepCtx.checkpoint,
         pause: stepCtx.pause,
-        requestDecision: stepCtx.requestDecision,
         sleep: stepCtx.sleep,
         waitForEvent: stepCtx.waitForEvent,
         processors: metadata.processors ?? []
@@ -812,6 +813,7 @@ class AgentComposeClient {
         ...opts?.snapshots !== undefined ? { snapshots: opts.snapshots } : {},
         ...opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {},
         ...opts?.placeholders !== undefined ? { placeholders: opts.placeholders } : {},
+        ...opts?.size !== undefined ? { size: opts.size } : {},
         ...parentRunId ? { parentRunId } : {},
         ...opts?.agentId ? { agentId: opts.agentId } : {}
       }
@@ -971,6 +973,21 @@ class AgentComposeClient {
       q2.set("revision", String(opts.revision));
     return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/files/content?${q2}`, { responseType: "text" });
   }
+  async listMembers() {
+    const body = await this.fetch("/api/v1/team/members");
+    return body.members;
+  }
+  async createMentions(input) {
+    const factorySlug = input.factorySlug ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined) ?? DEFAULT_FACTORY;
+    const runToken = typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_RUN_TOKEN : undefined;
+    const { factorySlug: _omit, ...payload } = input;
+    const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/mentions`, {
+      method: "POST",
+      body: payload,
+      ...runToken ? { headers: { "x-run-token": runToken } } : {}
+    });
+    return body.mentions;
+  }
   async listFactoryEvents(opts) {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     const q2 = new URLSearchParams;
@@ -1222,6 +1239,7 @@ async function bundleWorkflow(workflowPath, overrides) {
     ...inputSchema !== undefined ? { inputSchema } : {},
     ...outputSchema !== undefined ? { outputSchema } : {},
     ...metadata.snapshots !== undefined ? { snapshots: metadata.snapshots } : {},
+    ...metadata.resources !== undefined ? { resources: metadata.resources } : {},
     ...metadata.connectors !== undefined ? { connectors: metadata.connectors } : {},
     ...metadata.connectorOperation !== undefined ? { connectorOperation: metadata.connectorOperation } : {},
     ...metadata.invokePolicy !== undefined ? { invokePolicy: metadata.invokePolicy } : {}
@@ -1853,7 +1871,7 @@ async function runControlPoller(opts) {
 // src/agent/agent-loop.ts
 var DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 var SAME_BLOCKER_ITERATIONS = 3;
-var STALL_ITERATIONS = 3;
+var STALL_ITERATIONS = 6;
 var MESSAGE_PREVIEW_CHARS = 400;
 function parseAgentStatus(text) {
   const match = text.match(/<status>([\s\S]*?)<\/status>/);
@@ -2084,7 +2102,15 @@ Re-emit the COMPLETE corrected <response> JSON now: every required field present
         }
         const msg = outputVerdict.value;
         opts.onAgentEvent?.(iteration, msg);
-        opts.onAgentLifecycleEvent?.({ event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1, message: summarizeAgentMessage(msg) });
+        const summary = summarizeAgentMessage(msg);
+        opts.onAgentLifecycleEvent?.({
+          event: "agent.message",
+          at: Date.now(),
+          agentId,
+          label,
+          iteration: iteration + 1,
+          message: summary.type === "usage" && client.model != null ? { ...summary, model: client.model } : summary
+        });
         if (msg.type === "init")
           lastSessionId = msg.sessionId;
         if (msg.type === "text")
@@ -2163,9 +2189,9 @@ raw: ${JSON.stringify(rawResponse).slice(0, 400)}
       if (!status && rawResponse === null) {
         if (++iterationsWithoutStatus >= STALL_ITERATIONS)
           throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
-        if (opts.responseSchema && schemaRetriesLeft-- > 0) {
-          lastResponseValidationError = "no <response> block found — the turn ended with neither a <status> nor a <response> block; emit the complete <response> JSON";
-          process.stdout.write(`${logLabel} no <status>/<response> emitted — corrective re-prompt (${schemaRetriesLeft} retries left)
+        if (schemaRetriesLeft-- > 0) {
+          lastResponseValidationError = "Your turn ended with no <status> block" + (opts.responseSchema ? " (and no <response> block)" : "") + ". " + "If you launched a background job (`… &`) and are waiting to be notified when it finishes — STOP: nothing will notify you here. " + "Poll it NOW (read its output / wait for it synchronously to completion), then emit your <status>" + (opts.responseSchema ? " and the complete <response> JSON." : ".");
+          process.stdout.write(`${logLabel} empty turn (no <status>) — corrective re-prompt (${schemaRetriesLeft} retries left)
 `);
           iteration--;
           continue;
@@ -2746,6 +2772,13 @@ class SandboxUnavailableError extends Error {
 // src/sandbox.ts
 var AGENT_COMPOSE_TAG = process.env.AGENT_COMPOSE_TAG ?? `agent-compose-${process.env.AGENT_COMPOSE_ENV ?? "dev"}`;
 var VERCEL_VM_LIFETIME_WINDOW_MS = 6 * 60 * 60 * 1000;
+var SANDBOX_VCPUS = {
+  "2vcpu-4gb": 2,
+  "4vcpu-8gb": 4,
+  "8vcpu-16gb": 8,
+  "32vcpu-64gb": 32
+};
+var DEFAULT_SANDBOX_SIZE = "2vcpu-4gb";
 function makeSandboxProvider(sb) {
   const commands = sb.commands;
   return {
@@ -2911,7 +2944,7 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
         let stdout = "";
         let stderr = "";
         const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...opts?.sudo ? { sudo: true } : {} }).catch((err) => asUnavailable(err, true));
-        try {
+        const collect = async () => {
           await pRetry(async (attempt) => {
             const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
             if (attempt > 1) {
@@ -2930,11 +2963,22 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
           }, { retries: 3, minTimeout: 1000, factor: 2 });
           const finished = await handle.wait();
           return { exitCode: finished.exitCode, stdout, stderr };
+        };
+        let timer;
+        const deadline = opts?.timeoutMs ? new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`command timed out after ${opts.timeoutMs}ms: ${cmd.slice(0, 200)}`)), opts.timeoutMs);
+        }) : undefined;
+        try {
+          return await (deadline ? Promise.race([collect(), deadline]) : collect());
         } catch (err) {
-          if (signal?.aborted) {
+          if (err instanceof Error && err.message.startsWith("command timed out after"))
+            throw err;
+          if (signal?.aborted)
             throw new Error(`command timed out after ${opts?.timeoutMs}ms: ${cmd.slice(0, 200)}`);
-          }
           return asUnavailable(err, false);
+        } finally {
+          if (timer)
+            clearTimeout(timer);
         }
       }
     },
@@ -3011,7 +3055,8 @@ var SANDBOX_PROVIDERS = {
       const np = opts.networkPolicy ? { networkPolicy: toVercelNetworkPolicy(opts.networkPolicy) } : {};
       const tags = buildVercelTags(opts.metadata);
       const tmpl = opts.template ?? process.env.VERCEL_DEFAULT_SNAPSHOT;
-      const sb = await VercelSandbox.create(tmpl ? { source: { type: "snapshot", snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds } : { runtime: "node24", timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, ...np, ...creds });
+      const resources = { vcpus: SANDBOX_VCPUS[opts.size ?? DEFAULT_SANDBOX_SIZE] };
+      const sb = await VercelSandbox.create(tmpl ? { source: { type: "snapshot", snapshotId: tmpl }, timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds } : { runtime: "node24", timeout: opts.timeoutMs, env: opts.envs, tags, persistent: false, resources, ...np, ...creds });
       return makeVercelSandboxProvider(sb, opts.envs);
     },
     reconnect: async (sandboxId) => {
@@ -3057,7 +3102,7 @@ var SANDBOX_PROVIDERS = {
   },
   e2b: {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
       const maxMs = e2bMaxSandboxMs();
       if (timeoutMs > maxMs) {
         console.warn(`[sandbox] e2b create timeout clamped: requested ${timeoutMs}ms exceeds the plan cap ${maxMs}ms — ` + `the sandbox dies at the cap, not the requested deadline. Raise E2B_MAX_SANDBOX_MS on plans that allow more.`);
@@ -3099,7 +3144,7 @@ var SANDBOX_PROVIDERS = {
   },
   "e2b-desktop": {
     requiredEnv: { E2B_API_KEY: "E2B API key — e2b.dev/dashboard" },
-    create: async ({ template, timeoutMs, networkPolicy: _np, ...rest }) => {
+    create: async ({ template, timeoutMs, networkPolicy: _np, size: _size, ...rest }) => {
       if (!template)
         throw new Error("E2B Desktop provider requires an explicit `template` (Dockerfile-based — no default base image)");
       return makeDesktopSandboxProvider(await Desktop.create(template, { ...rest, timeoutMs: Math.min(timeoutMs, e2bMaxSandboxMs()) }));
@@ -3283,14 +3328,6 @@ function scopedCheckpoint(scope) {
 // src/pause/wrappers.ts
 function buildPauseWrappers(pause) {
   return {
-    requestDecision(req) {
-      return pause({
-        reason: req.reason,
-        schema: req.schema,
-        ...req.payload !== undefined ? { payload: req.payload } : {},
-        ...req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}
-      }, "decision");
-    },
     sleep(durationMs) {
       return pause({
         reason: `sleep ${durationMs}ms`,
@@ -3600,7 +3637,7 @@ function buildInvokeChild(runId, opts = {}) {
   return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {
     ...childOpts,
     parentRunId: runId,
-    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
+    factorySlug: childOpts?.factorySlug ?? opts.defaultFactorySlug ?? process.env.AGENT_COMPOSE_FACTORY ?? process.env.AGENT_COMPOSE_FACTORY_SLUG ?? "default"
   });
 }
 // src/workflow-steps/step.ts
@@ -3967,6 +4004,149 @@ async function serveStep(handler) {
 import { z as z11 } from "zod";
 import { randomUUID as randomUUID2 } from "node:crypto";
 
+// src/agent/agent-context.ts
+var AGENT_COMPOSE_MANUAL = `# Working inside an Agent Compose sandbox
+
+You are an agent running in a per-run sandbox on the Agent Compose platform.
+Use the **\`agentc\` CLI** and the **\`@agent-compose/sdk\`** for everything below —
+do NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on
+your PATH and already authenticated from the environment
+(\`AGENT_COMPOSE_URL\` / \`AGENT_COMPOSE_API_KEY\` / \`AGENT_COMPOSE_FACTORY\` are
+injected for this run), so commands just work — no login, no keys to manage.
+
+The \`/ac:*\` skills are installed as Claude Code slash commands (\`/ac:invoke\`,
+\`/ac:events\`, \`/ac:logs\`, \`/ac:register\`, …) — reach for them too.
+
+## Files — your outputs persist by default
+
+Your working directory defaults to **\`$AGENT_COMPOSE_RUN_DIR\`** — a per-run
+directory on the shared factory drive
+(\`$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/\`) the platform
+creates and attributes to this run. **Files you write here persist by
+default** — they show up in the dashboard's Files tab and the run's Artifacts
+card, with no API calls to save them. The dir already exists and is writable.
+
+Need throwaway scratch — heavy build output, package caches, temp files?
+\`cd /tmp\` (or any path outside \`/factory\`): anything off the factory drive is
+ephemeral and discarded when the sandbox ends. In short: **stay in your working
+dir to keep something, \`cd\` out to throw it away.**
+
+The whole shared drive is POSIX-mounted at \`/factory\`; the dashboard-visible
+root is \`$AGENT_COMPOSE_FACTORY_DIR\` (\`/factory/files\`). Earlier versions and
+runs live in sibling dirs under
+\`$AGENT_COMPOSE_FACTORY_DIR/$AGENT_COMPOSE_WORKFLOW/\` — read them for prior
+context. Other workflows' dirs are present but not your concern.
+
+## Events — the factory timeline
+
+Record something on the run/factory timeline (the dashboard renders these)
+with the CLI — your run id is \`$RUN_ID\`:
+
+    agentc events send "$RUN_ID" <name> --summary "<one line>" [--body '<json>']
+
+Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
+\`agentc events list\` reads them back. \`/ac:events\` is the skill equivalent.
+
+## Runs
+
+    agentc list                          # registered workflows  (/ac:list)
+    agentc logs "$RUN_ID"                # a run's logs           (/ac:logs)
+    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)
+
+## Writing workflow / agent code — the SDK
+
+\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
+you write there:
+
+    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+
+Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
+\`agentc register <file.ts>\` (or \`/ac:register\`).
+
+## Pausing to ask the human — \`agentc pause\`
+
+When you can't or shouldn't proceed without a human, run \`agentc pause\`. It
+blocks until they answer on the dashboard, then prints their answer to stdout:
+
+    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                          --option retry --option skip)
+
+Reach for it the moment you hit — or foresee — any of these:
+- **A wall only a human can clear:** a 401/403, a missing credential, an
+  unconnected provider, a host the network refuses. Do NOT retry blindly or try
+  to work around it — pause and say what needs enabling.
+- **A durable or outward-facing action that needs sign-off:** registering a
+  workflow, deploying, sending email/messages, deleting or overwriting shared
+  data, spending money. Prepare everything, then pause for approval BEFORE you
+  commit it.
+- **A judgment call only the human can settle:** an under-specified request,
+  several valid paths, a conflict with existing state, missing input only they have.
+
+You compose the \`--reason\` (the ask) yourself; pass \`--option\` choices when
+there are clear ones, omit them for a free-form answer. Read the printed answer
+and act on it. Each agent pauses independently — pausing doesn't stop the others.
+
+## Credentials
+
+Connector credentials (Google, GitHub, …) are NEVER in your environment.
+They're injected at the network layer when you call an allowed host — make the
+request **without** an Authorization header and the platform adds it. Don't try
+to read or exfiltrate tokens; they aren't here. The "Connectors & access"
+section below (when present) lists exactly which providers this run can reach.
+
+## Tools in this environment
+
+- \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
+- \`@agent-compose/sdk\` — installed in /workspace for writing workflows
+- \`/ac:*\` Claude Code skills — slash commands for the above
+- \`archil\` (factory drive), \`rtk\`, \`bun\`
+- A world-writable \`/workspace\` working directory`;
+function renderConnectorsSection(connectors) {
+  if (connectors.length === 0)
+    return "";
+  const rows = connectors.map((c) => {
+    const host = c.hosts?.length ? c.hosts.join(", ") : "(host set by the platform)";
+    const verbs = c.methods?.length ? c.methods.join("/") : "any method";
+    const paths = c.pathPrefixes?.length ? ` under ${c.pathPrefixes.join(", ")}` : "";
+    const repo = c.repository ? ` — repo \`${c.repository}\` (${c.access ?? "read"})` : "";
+    const why = c.scopes?.length ? `  
+  _scopes: ${c.scopes.join(", ")}_` : "";
+    return `- **${c.name ?? c.provider}** → \`${host}\` — ${verbs}${paths}${repo}${why}`;
+  });
+  return `
+
+## Connectors & access — what this run can reach
+
+These providers are connected for this run. Call their APIs with plain
+fetch/SDKs and **no Authorization header** — the platform injects the
+credential at the network layer. Requests outside the listed method/path are
+refused (403) and the token withheld. Anything NOT listed is unreachable; if
+you need it, \`agentc pause\` and ask for it to be connected.
+
+${rows.join(`
+`)}
+`;
+}
+function buildAgentContextDoc(env) {
+  let connectors = [];
+  const raw = env.AGENT_COMPOSE_CONNECTORS;
+  if (raw) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed))
+        connectors = parsed;
+    } catch {}
+  }
+  return AGENT_COMPOSE_MANUAL + renderConnectorsSection(connectors);
+}
+async function writeAgentContext(args) {
+  const doc = buildAgentContextDoc(args.env);
+  const dir = args.cwd.replace(/\/+$/, "") || "/workspace";
+  for (const name of ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]) {
+    await args.sandbox.files.write(`${dir}/${name}`, doc);
+  }
+}
+
 // src/agent/protocol-suffix.md
 var protocol_suffix_default = '## Status Signal\n\nWhen you have finished your work or are blocked, emit a `<status>` block at the end of your response:\n\n```json\n<status>\n{\n  "summary": "one sentence describing what was done or what is blocking",\n  "completed": ["each acceptance criterion that is now fully met"],\n  "blockers": [],\n  "changed_files": ["relative/path/to/file"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Field semantics:**\n- `summary`: one sentence — what was accomplished or what is blocking\n- `completed`: acceptance criteria items that are fully done — be specific\n- `blockers`: non-empty when `exit_signal: false` — describe the exact obstacle\n- `changed_files`: relative paths of files you created or modified\n- `tests_run`: `true` if you ran any test suite (pass or fail); `false` if no tests exist or you skipped them\n- `exit_signal: true` — set when ALL acceptance criteria are met and no blockers remain\n- `exit_signal: false` — set when blocked or unfinished; `blockers` must be non-empty\n\n**If you are still actively working** and have not reached a natural stopping point, do NOT emit a `<status>` block — just keep working.\n\n**Example (done):**\n\n```json\n<status>\n{\n  "summary": "Added input validation middleware to /api/tasks with tests",\n  "completed": ["POST /api/tasks validates required fields", "Returns 400 with details on invalid input", "Unit tests passing"],\n  "blockers": [],\n  "changed_files": ["src/middleware/validate.ts", "src/routes/tasks.ts", "tests/validate.test.ts"],\n  "tests_run": true,\n  "exit_signal": true\n}\n</status>\n```\n\n**Example (blocked):**\n\n```json\n<status>\n{\n  "summary": "Implemented middleware but tests are failing due to module resolution",\n  "completed": ["Middleware created and wired into route"],\n  "blockers": ["Tests fail: cannot resolve import \'./validate\' — module resolution config unclear"],\n  "changed_files": ["src/middleware/validate.ts"],\n  "tests_run": true,\n  "exit_signal": false\n}\n</status>\n```\n';
 
@@ -4082,7 +4262,28 @@ function resolveAgentId(explicitId) {
   return `step${activeCall.stepIndex}-agent-${activeCall.callIndex}`;
 }
 async function agent(opts) {
-  const workingDir = opts.workingDir ?? "";
+  let workingDir = opts.workingDir || process.env.AGENT_COMPOSE_RUN_DIR || "/workspace";
+  const CONTEXT_WRITE_DEADLINE_MS = 15000;
+  const tryWriteContext = (cwd) => {
+    let timer;
+    return Promise.race([
+      writeAgentContext({ sandbox: opts.sandbox, cwd, env: process.env }).then(() => true),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), CONTEXT_WRITE_DEADLINE_MS);
+      })
+    ]).catch((err) => {
+      console.error(`[agent] writeAgentContext(${cwd}) failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }).finally(() => {
+      if (timer)
+        clearTimeout(timer);
+    });
+  };
+  if (!await tryWriteContext(workingDir) && workingDir !== "/workspace") {
+    console.error(`[agent] working dir ${workingDir} not writable within ${CONTEXT_WRITE_DEADLINE_MS}ms ` + `(factory drive degraded?) — falling back to /workspace so the agent can run`);
+    workingDir = "/workspace";
+    await tryWriteContext(workingDir);
+  }
   const agentId = resolveAgentId(opts.agentId);
   const callbackUrl = process.env.AGENT_COMPOSE_URL;
   const callbackToken = process.env.AGENT_COMPOSE_RUN_TOKEN;
@@ -4166,6 +4367,7 @@ async function agent(opts) {
 }
 export {
   writeTool,
+  writeAgentContext,
   stepInputPath,
   serveStep,
   runWorkflowSteps,
@@ -4213,6 +4415,7 @@ export {
   bundleWorkflow,
   buildStepEnvs,
   buildInvokeChild,
+  buildAgentContextDoc,
   bashTool,
   assertDefaultExportIsDefineWorkflow,
   amp_default as ampRuntime,
@@ -4251,6 +4454,7 @@ export {
   AgentComposeError,
   AgentComposeClient,
   AGENT_COMPOSE_TAG,
+  AGENT_COMPOSE_MANUAL,
   AC_WORKFLOW_ID,
   AC_TEAM_ID,
   AC_RUN_ID,