@agent-compose/sdk 0.8.5 → 0.8.6

package/dist/types/api-scopes.d.ts

@@ -32,9 +32,10 @@ export type DocumentCapability = "read" | "write";
  *  regardless of call context — read-only, never act. */
 export type TemplateCapability = "read" | "write" | "invoke" | "see_runs";
 /** One grant on an artifact scope. `team`/`user` are the editable tiers
- *  carried on a PUT (full-replace); `session`/`project` are DERIVED,
- *  read-only arms that appear only on READ payloads (the routes that manage
- *  them own their mutation — a scope PUT rejects them, 400 `invalid_principal`).
+ *  carried on a PUT (full-replace); `session`/`project`/`conversation`/
+ *  `worker` are DERIVED, read-only arms that appear only on READ payloads
+ *  (the routes that manage them own their mutation — a scope PUT rejects
+ *  them, 400 `invalid_principal`).
  *
  *  Session and project grants carry FIXED capabilities `['read','write']`:
  *  the fs-gateway is concealment-only (no read/write dimension at the mount),
@@ -62,6 +63,30 @@ export type ScopeGrant = {
      *  being a project member (share implies unshare). Null only for
      *  transitional/legacy rows. */
     projectObjectId: string | null;
+    /** The people in the project: the row's reach. */
+    memberCount: number;
+    capabilities: string[];
+}
+/** A chat's grant (scope-at-birth, documents): reach derives LIVE from the
+ *  chat's tier and member rows. `memberCount` is null for a public channel,
+ *  whose audience is the whole team rather than its member rows. */
+ | {
+    principal: "conversation";
+    conversationId: string;
+    conversationTitle: string | null;
+    memberCount: number | null;
+    capabilities: string[];
+}
+/** The grant a chat's WORKER session holds on what it wrote: not a group
+ *  of people. The readers of the chat it works for (`chatId`) reach the
+ *  file through it while the worker's project boundary holds. `title` is
+ *  the work's (the session's) title. */
+ | {
+    principal: "worker";
+    conversationId: string;
+    title: string | null;
+    chatId: string;
+    chatTitle: string | null;
     capabilities: string[];
 };
 /** An artifact's share scope (documents and templates — one model).
@@ -74,6 +99,10 @@ export interface ArtifactScope {
     /** Templates only — the owning conversation binding (a grant source:
      *  members of that conversation reach the template via their role). */
     conversationId?: string | null;
+    /** Documents only — born of a shared chat's work (Ivy's publish, a
+     *  worker's output for a chat). Such a document is shared by the people
+     *  who can edit it, whoever its owner is; so is one with no owner. */
+    bornOfChatWork?: boolean;
     grants: ScopeGrant[];
 }
 /** The call context stamped on a run at dispatch (ADR-0045 §3) — the

package/dist/types/conversation-stream.d.ts

@@ -119,6 +119,11 @@ export interface ConversationTurnStateEvent {
     pendingCount: number;
     at: number;
     partial: true;
+    /** The running turn is WRITING words that will be sent — the typing
+     *  indicator's one signal (a running turn that thinks, calls tools,
+     *  reacts or notes is not writing). Absent when the emitter cannot know;
+     *  consumers inherit their previous frame's value, and `idle` resets it. */
+    writing?: boolean;
     /** When the open turn started (ms) — carried by the connect-time
      *  snapshot frame only; absent on live transition frames. */
     startedAt?: number | null;

package/dist/types/execution-context.d.ts

@@ -1,4 +1,4 @@
-/** Shared execution context capabilities for workflow functions and steps. */
+/** Shared execution context capabilities for workflow steps. */
 import type { InvokeAndWaitOptions, RunStatus } from "./api-runs.js";
 import type { RequestContext } from "../request-context/request-context.js";
 import type { PauseRequest } from "../pause/pause-core.js";

package/dist/types/protocol.d.ts

@@ -71,6 +71,21 @@ export interface AgentMessageError extends AgentMessageBase {
     type: "error";
     text: string;
 }
+/** One model's share of a harness's turn-end report (claude-code
+ *  `result.modelUsage[<model>]`): the same four token classes as the turn
+ *  totals, plus what the harness reports beside them. `costUsd` is the
+ *  harness's OWN estimate at its price table — never a bill. Fields the
+ *  harness did not report are absent, never zeroed. */
+export interface AgentMessageModelUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    /** Thinking tokens, already counted inside `outputTokens`. */
+    thinkingTokens?: number;
+    webSearchRequests?: number;
+    costUsd?: number;
+}
 export interface AgentMessageUsage extends AgentMessageBase {
     type: "usage";
     inputTokens: number;
@@ -79,6 +94,53 @@ export interface AgentMessageUsage extends AgentMessageBase {
     cacheCreationTokens: number;
     durationMs: number;
     numTurns: number;
+    /** Reasoning tokens, already counted inside `outputTokens` (codex
+     *  `turn.completed.usage.reasoning_output_tokens`). Absent when the
+     *  harness reports no such class. */
+    reasoningOutputTokens?: number;
+    /** Per-model totals the harness reported beside the turn totals
+     *  (claude-code `result.modelUsage`): every model the query pipeline
+     *  called — main loop, subagents, compaction. As the CLI reports them:
+     *  CUMULATIVE for the guest session (a streaming-input or resumed
+     *  session carries its earlier turns), so a per-turn share is the
+     *  difference from the previous report of the same session. Absent when
+     *  the harness reports none. */
+    byModel?: Record<string, AgentMessageModelUsage>;
+    /** The harness's own cost estimate for the same scope as `byModel`
+     *  (claude-code `result.total_cost_usd`): list-price arithmetic, an
+     *  estimate and never a billing statement. */
+    costUsd?: number;
+}
+/** The harness's reading of the account's PLAN LIMITS (claude-code
+ *  `rate_limit_event`, emitted whenever its rate-limit information changes
+ *  — subscription-funded sessions only; the headers it reads exist for
+ *  claude.ai plans). `status` is the verdict for the request just made:
+ *  `rejected` means the plan's wall, with `resetsAt` the authoritative
+ *  reset. `window` names which window the verdict speaks for (the CLI's
+ *  `rateLimitType`: five_hour, seven_day, seven_day_opus, …). `utilization`
+ *  is carried only once a window crosses a warning threshold (the CLI omits
+ *  it while plainly allowed), as the CLI reports it — a 0..1 fraction of
+ *  the window. Everything the event did not carry is absent; nothing is
+ *  invented. Additive kind: existing producers never emit it. */
+export interface AgentMessagePlanLimits extends AgentMessageBase {
+    type: "plan_limits";
+    status: "allowed" | "allowed_warning" | "rejected";
+    window?: string;
+    /** ISO time the named window resets. */
+    resetsAt?: string;
+    utilization?: number;
+    /** The warning threshold the window crossed (as the CLI reports it). */
+    surpassedThreshold?: number;
+    /** The plan's extra-usage (overage) lane, when the event spoke of it. */
+    overage?: {
+        status?: "allowed" | "allowed_warning" | "rejected";
+        resetsAt?: string;
+        disabledReason?: string;
+        inUse?: boolean;
+    };
+    /** Which spend limit blocked the request when not the member's own cap. */
+    limitScope?: string;
+    errorCode?: string;
 }
 /** LIVE-ONLY incremental usage off the harness's raw provider stream — the
  *  `text_delta` of token counts. claude-code's `--include-partial-messages`
@@ -109,7 +171,8 @@ export interface AgentMessagePlan extends AgentMessageBase {
     type: "plan";
     entries: {
         content: string;
-        priority: "high" | "medium" | "low";
+        /** ACP names one; codex's `--json` plan names none. */
+        priority?: "high" | "medium" | "low";
         status: "pending" | "in_progress" | "completed";
     }[];
 }
@@ -273,7 +336,7 @@ export interface AgentMessageSubagentUserMessage extends AgentMessageBase {
     text: string;
     parentToolUseId: string;
 }
-export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlan | AgentMessageTaskNotification | AgentMessageTaskProgress | AgentMessageHarnessNotice | AgentMessageCompaction | AgentMessageSubagentUserMessage;
+export type AgentMessage = AgentMessageInit | AgentMessageText | AgentMessageTextDelta | AgentMessageThinking | AgentMessageToolUse | AgentMessageToolResult | AgentMessageDone | AgentMessageError | AgentMessageUsage | AgentMessageUsageDelta | AgentMessagePlanLimits | AgentMessagePlan | AgentMessageTaskNotification | AgentMessageTaskProgress | AgentMessageHarnessNotice | AgentMessageCompaction | AgentMessageSubagentUserMessage;
 /** Status block the agent emits to signal iteration completion or blockers. */
 export interface AgentStatus {
     summary: string;

package/dist/types/runtime.d.ts

@@ -266,7 +266,14 @@ export interface ModelExecutionContract {
      *     phase, a spec/transport without stream input, ACP path).
      * Calls are serialized per turn; never throws.
      */
-    injectUserMessage?(text: string): Promise<"delivered" | "pending" | "closed" | "unsupported">;
+    injectUserMessage?(text: string, 
+    /** Who the message speaks for when it is not the session user
+     *  (MidTurnEnvelopeOptions): a relayed person, named, or the thread
+     *  agent that owns this worker. */
+    opts?: {
+        relayedFrom?: string | null;
+        fromOwnerAgent?: boolean;
+    }): Promise<"delivered" | "pending" | "closed" | "unsupported">;
     /**
      * Request an in-band STEP INTERRUPT of the currently running turn — the
      * ESC equivalent. Where `injectUserMessage` queues content for the turn
@@ -328,7 +335,7 @@ export interface ModelExecutionContract {
  * The sandbox provider (e.g. "vercel", "e2b") is an infrastructure concern
  * configured via SANDBOX_PROVIDER — not part of the runtime definition.
  * For non-sandbox agents (API calls, etc.) make the call directly in the workflow;
- * spawnAgent is a sandbox concept.
+ * `agent()` is a sandbox concept.
  */
 export interface AgentRuntime<S extends SandboxProvider = SandboxProvider> {
     create(sandbox: S, opts: RuntimeOptions): ModelExecutionContract;

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

@@ -224,10 +224,8 @@ export interface WorkflowMetadata {
      *  BUILD — a setup-only workflow whose job is to leave its VM configured and
      *  snapshot it (base-env / agent-env). Environment builds build a platform
      *  IMAGE and never use the shared factory drive, so the server SKIPS mounting
-     *  /factory for them: a live Archil mount baked into the captured snapshot
-     *  fails the NEXT boot's re-mount ("an older Archil process is still running
-     *  for this mountpoint"), degrading /factory for every workflow booting from
-     *  that snapshot. Absent on ordinary workflows — which mount /factory exactly
+     *  /factory for them and no live drive mount bakes into the captured
+     *  snapshot. Absent on ordinary workflows — which mount /factory exactly
      *  as before. Optional + additive: an ABSENT flag contributes nothing to the
      *  canonical metadata hash (frozen-metadata rule), so existing workflows are
      *  not forced to re-register. */

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

@@ -5,9 +5,7 @@
  * dispatch time. The CLI/bundler inspects the bundled module in the user's
  * environment and sends this compact plan as metadata.
  *
- * Every workflow has a step plan. Legacy `defineWorkflow({ run })`
- * workflows are wrapped at the SDK boundary as a single-step compiled
- * workflow (step name = "run"); the bundler sees the same shape regardless.
+ * Every workflow has a step plan.
  */
 /** One artifact a step promises to produce — mirrors `StepDeliverable`,
  *  restated here so the plan stays a self-contained wire shape. */

package/dist/utils/bundler.d.ts

@@ -147,6 +147,29 @@ export declare const SDK_SPECIFIER_ALIASES: readonly string[];
  *  null. The single authority: the plugin's regex filter is only a fast
  *  pre-filter, and this decides. */
 export declare function resolveSdkAlias(specifier: string): string | null;
+/**
+ * The packages the PLATFORM provides to every workflow source — the SDK and
+ * its zod peer — which therefore resolve from the platform's own install
+ * roots when the source file's directory has no node_modules of its own.
+ * The live incident (2026-09-20, a claude-code session at the drive root):
+ * `agentc invoke --source /factory/files/wf.ts` died with `Could not
+ * resolve "@agent-compose/sdk", "zod"` because Bun walked up from
+ * /factory/files and found nothing, while the baked SDK sat in
+ * /workspace/node_modules the whole time (infra/e2b-template/template.ts —
+ * "SDK into /workspace/node_modules so any script written under /workspace
+ * can import it"). A workflow's OWN third-party deps still have to be
+ * installed beside the source; only these two are platform-resolved.
+ */
+export declare const PLATFORM_RESOLVED_PACKAGES: readonly string[];
+/** Env override for the fallback roots (colon-separated, tried first) — the
+ *  test seam, and an ops knob for a sandbox image that plants the SDK
+ *  elsewhere. */
+export declare const SDK_FALLBACK_ROOTS_ENV = "AGENT_COMPOSE_SDK_FALLBACK_ROOTS";
+/** Where the platform SDK lives when the source's own walk-up finds nothing:
+ *  the env override's roots, the sandbox's baked /workspace install, then
+ *  the bundling process's cwd (the CLI's own resolution context). Exported
+ *  for the unit test. */
+export declare function sdkFallbackRoots(env?: Record<string, string | undefined>): string[];
 /**
  * The SELF-CORRECTING layer. Turns a Bun bundle failure into a message that
  * names the real fix instead of leaking Bun's internals.

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

@@ -68,9 +68,8 @@ export interface StepObservability {
  * this instance. After the step finishes, the engine calls `snapshot()`
  * to extract the bundle for transport.
  *
- * Metadata writes merge (later keys win) — matches the legacy
- * `mergeRunMetadata` semantics so authors don't see a behaviour change
- * across migrations.
+ * Metadata writes merge (later keys win), as the server's run-metadata
+ * merge does.
  */
 export declare class StepObservabilityCollector {
     private metadata;

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

@@ -6,7 +6,6 @@
  *   2. For each step:
  *      a. Optionally check `getCachedOutput(stepIndex, step.name)` — if a
  *         previous run completed this step, skip and reuse its output.
- *         (Phase 1b uses this for crash recovery.)
  *      b. Validate current input against `step.input`.
  *      c. Call `step.run({ input, ... })`.
  *      d. Validate return value against `step.output`.
@@ -17,9 +16,10 @@
  * Errors during any step bubble through `onStepFailed` and re-throw so the
  * caller can decide whether to mark the run failed.
  *
- * The cache + completion hooks are injection points — a sandbox engine
- * adapter (Phase 1c) wires them to `workflow_step_runs` rows. The default
- * is an in-process map for tests.
+ * The cache + completion hooks are injection points; without a cache every
+ * step runs. The platform's sandbox path does not walk the chain here: the
+ * Temporal `executeStep` activity runs one step per runner subprocess via
+ * `runWorkflowSingleStep` below.
  */
 import { z } from "zod";
 import type { Workflow, StepRunResult } from "./types.js";
@@ -54,13 +54,10 @@ export interface RunWorkflowStepsOpts<TInput, TOutput> {
     /**
      * Crash-recovery hook. Called before a step executes. Return the cached
      * output to skip execution; return undefined to run the step.
-     *
-     * Phase 1b implementations will look up `workflow_step_runs` rows for
-     * (runId, stepIndex, stepName) and return completed step outputs here.
      * Default: always undefined (no caching).
      */
     getCachedOutput?(stepIndex: number, stepName: string): unknown | undefined | Promise<unknown | undefined>;
-    /** Fire after a step's `execute` and output validation succeed. */
+    /** Fire after a step's `run` and output validation succeed. */
     onStepCompleted?(stepIndex: number, stepName: string, output: unknown, durationMs: number): void | Promise<void>;
     /** Fire when a step throws or fails validation. The error is re-thrown after this returns. */
     onStepFailed?(stepIndex: number, stepName: string, error: Error, durationMs: number): void | Promise<void>;

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

@@ -6,9 +6,8 @@
  *
  * Why: durable suspend/resume requires step boundaries to be addressable as
  * data, not opaque async-function bodies. Each step's input + output is
- * serialisable JSON so engine adapters (in-process, sandbox, future
- * Inngest/Temporal) can record completion and replay from the last
- * completed step.
+ * serialisable JSON so the durable engine (Temporal, one activity per step)
+ * can record completion and replay from the last completed step.
  */
 import type { z } from "zod";
 import type { BaseExecutionContext } from "../types/execution-context.js";
@@ -16,7 +15,7 @@ import type { AgentEventSink } from "../types/workflow.js";
 import type { WorkflowMetadata } from "../types/workflow-metadata.js";
 import type { StepObservability } from "./observability.js";
 /**
- * Per-step execution context. Threaded into every step's `execute(...)` so
+ * Per-step execution context. Threaded into every step's `run(...)` so
  * the step can read tenant identity and run identity, log progress, and
  * invoke sandbox commands.
  *
@@ -31,9 +30,9 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
     abortSignal: AbortSignal;
     /**
      * Merge key-value metadata onto the run record. Buffered during the
-     * step and flushed when the step completes; the durable engine writes
-     * it via the same `mergeRunMetadata` path the legacy runner used, so
-     * the dashboard sees the same shape. Later keys win.
+     * step and flushed when the step completes; the durable engine merges
+     * it into the run's metadata (`persistStepObservability`). Later keys
+     * win.
      */
     setMetadata(data: Record<string, unknown>): Promise<void>;
     /**
@@ -93,9 +92,8 @@ export interface Step<TInput, TOutput> {
     readonly deliverables?: readonly StepDeliverable[];
 }
 /**
- * The result of running one step. Engine adapters persist these into the
- * `workflow_step_runs` table (Phase 1b) so subsequent runs can skip
- * completed steps. `observability` carries the snapshot of
+ * The result of running one step, as `runWorkflowSteps` reports it per
+ * step. `observability` carries the snapshot of
  * `ctx.setMetadata` / `ctx.step` / `ctx.agentEvents` recorded during
  * the step; undefined when no hooks were used.
  */

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

@@ -16,7 +16,8 @@
  * matches the final step's `output` schema.
  *
  * Workflows-as-data — the result is consumable by any engine adapter
- * (in-process today; sandbox + Inngest/Temporal in future PRs).
+ * (in-process `runWorkflow`; the sandbox runner one step at a time under
+ * Temporal).
  */
 import type { z } from "zod";
 import type { Step, Workflow } from "./types.js";

package/dist/workflows/engine.d.ts

@@ -6,7 +6,7 @@
  * runner.
  *
  * Errors classified into `WorkflowError` (user code threw) vs `EngineError`
- * (platform problem) for the runner harness to surface upstream.
+ * (platform problem).
  */
 import type { WorkflowHooks } from "../types/workflow.js";
 import type { InvokeChild } from "../types/execution-context.js";
@@ -35,7 +35,7 @@ export declare class EngineError extends Error {
     readonly subsystem: EngineSubsystem;
     constructor(message: string, subsystem?: EngineSubsystem, options?: ErrorOptions);
 }
-/** Classify any thrown value into the wire-level `kind` expected by `/fail`. */
+/** Classify any thrown value as a `workflow` or an `engine` failure. */
 export declare function classifyError(err: unknown): "workflow" | "engine";
 export declare function parseNameVersion(ref: string): {
     name: string;
@@ -52,9 +52,7 @@ export interface RunWorkflowOptions {
     onStepStarted?: RunWorkflowStepsOpts<unknown, unknown>["onStepStarted"];
     onStepCompleted?: RunWorkflowStepsOpts<unknown, unknown>["onStepCompleted"];
     onStepFailed?: RunWorkflowStepsOpts<unknown, unknown>["onStepFailed"];
-    /** Provider-specific child workflow invocation. Temporal/Inngest providers
-     *  inject their native child-workflow primitive; the LocalProvider injects
-     *  the public Agent Compose API client. */
+    /** Child workflow invocation. Unset, a step's `invokeChild` throws. */
     invokeChild?: InvokeChild;
 }
 export declare function runWorkflow<TInput, TOutput>(wf: Workflow<TInput, TOutput>, ctx: {

package/dist/workflows/invoke-child.d.ts

@@ -18,8 +18,8 @@ import type { InvokeChild } from "../types/execution-context.js";
  */
 export declare function deriveInvokeChildIdempotencyKey(parentRunId: string, childName: string): string | null;
 /**
- * Build the public-API child workflow invoker used by legacy and sandboxed
- * workflow execution. Provider-backed engines may inject a different
+ * Build the public-API child workflow invoker used by sandboxed workflow
+ * execution (the step runner). Provider-backed engines may inject a different
  * implementation (Temporal child workflow, Inngest invoke, etc.).
  */
 export declare function buildInvokeChild(runId: string, opts?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
@@ -71,7 +71,7 @@
     "ofetch": "^1.5.1",
     "openai": "^6.33.0",
     "p-retry": "^6.2.0",
-    "sharp": "^0.34.5"
+    "sharp": "0.35.4"
   },
   "publishConfig": {
     "access": "public"