@agent-compose/sdk 0.5.9 → 0.7.0

package/src/utils/errors.ts

@@ -1,4 +1,21 @@
-/** Convert any thrown value to a string message. */
+/** Convert any thrown value to a string message, INCLUDING its `.cause` chain.
+ *
+ *  Many wrapped errors carry the real reason on `.cause` and only a generic
+ *  summary on `.message` — the Temporal SDK's "Failed to start Workflow" is the
+ *  canonical example (its `.cause` is the actual gRPC rejection, e.g. "search
+ *  attribute X is not defined"). Returning `.message` alone swallowed that, so
+ *  failures surfaced as opaque one-liners. Walk the chain and join the messages
+ *  so the root cause is always visible. Cycle-guarded against self-referential
+ *  `cause` links. */
 export function formatError(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
+  if (!(err instanceof Error)) return String(err);
+  const parts: string[] = [err.message];
+  const seen = new Set<unknown>([err]);
+  let cause: unknown = (err as { cause?: unknown }).cause;
+  while (cause != null && !seen.has(cause)) {
+    seen.add(cause);
+    parts.push(cause instanceof Error ? cause.message : String(cause));
+    cause = cause instanceof Error ? (cause as { cause?: unknown }).cause : undefined;
+  }
+  return parts.join(": ");
 }

package/dist/agent/local-pause-request.d.ts

@@ -1,49 +0,0 @@
-/**
- * Local pause-request marker — the in-sandbox bridge from `agentc pause` to
- * the agent loop's snapshot-release pause boundary.
- *
- * `agentc pause` runs as a grandchild subprocess of the runner (the agent CLI
- * shells out to it). It cannot throw a `PauseSignal` into the loop and the
- * in-memory steer flag (`signalSteerPending`) lives in a different process, so
- * the only reliable channel is the shared sandbox filesystem. The CLI writes a
- * durable marker here; the agent loop consumes it at the end of the turn
- * (alongside the `needs_input` self-pause) and stages a real `ctx.pause` the
- * next boundary takes — which snapshots the sandbox, releases the activity
- * (compute stops), and parks the workflow. On resume the human's answer is
- * delivered as the agent's next user turn.
- *
- * This is the ONLY place the marker path + shape are defined — both the CLI
- * (writer) and the SDK loop (reader) import it, so the two halves can never
- * drift. Like the rest of the state-dir, the layout is a wire protocol between
- * the runner and the next subprocess invocation (ADR-0006). The marker is
- * consumed BEFORE the snapshot, so it never needs to survive a pause.
- *
- * Scoped by `agentId` so concurrent `agent()` calls sharing one sandbox each
- * see only their own request. When the id is unavailable (older agent env that
- * doesn't inject `AGENT_COMPOSE_AGENT_ID`) both sides fall back to a single
- * unscoped slot — correct for the common single-agent step, and the only case
- * where an unscoped marker can be ambiguous (two anonymous agents) is one the
- * old block-poll CLI couldn't handle either.
- */
-/** A choice offered to the human. A bare string is shorthand for
- *  `{ label, value }` with both equal — exactly what the dashboard's
- *  `readOptions` accepts. */
-export type PauseOption = string | {
-    label: string;
-    value: string;
-};
-/** What `agentc pause` records for the loop to turn into a `ctx.pause`. */
-export interface LocalPauseRequest {
-    /** The question shown to the human (becomes the pause `reason`). */
-    reason: string;
-    /** Optional offered choices, rendered as buttons in the dashboard. */
-    options?: PauseOption[];
-}
-/** Write the marker atomically (tmp → rename) so the loop never reads a
- *  partial file mid-write. Called by `agentc pause`. */
-export declare function writeLocalPauseRequest(agentId: string | undefined | null, req: LocalPauseRequest): void;
-/** Take-once read: returns + deletes this agent's pending pause request, else
- *  null. Checks the agent-scoped slot first, then the unscoped fallback. The
- *  loop calls this once per turn; a malformed marker is dropped (deleted +
- *  null) rather than wedging the loop. */
-export declare function consumeLocalPauseRequest(agentId: string | undefined | null): LocalPauseRequest | null;

package/src/agent/local-pause-request.ts

@@ -1,90 +0,0 @@
-/**
- * Local pause-request marker — the in-sandbox bridge from `agentc pause` to
- * the agent loop's snapshot-release pause boundary.
- *
- * `agentc pause` runs as a grandchild subprocess of the runner (the agent CLI
- * shells out to it). It cannot throw a `PauseSignal` into the loop and the
- * in-memory steer flag (`signalSteerPending`) lives in a different process, so
- * the only reliable channel is the shared sandbox filesystem. The CLI writes a
- * durable marker here; the agent loop consumes it at the end of the turn
- * (alongside the `needs_input` self-pause) and stages a real `ctx.pause` the
- * next boundary takes — which snapshots the sandbox, releases the activity
- * (compute stops), and parks the workflow. On resume the human's answer is
- * delivered as the agent's next user turn.
- *
- * This is the ONLY place the marker path + shape are defined — both the CLI
- * (writer) and the SDK loop (reader) import it, so the two halves can never
- * drift. Like the rest of the state-dir, the layout is a wire protocol between
- * the runner and the next subprocess invocation (ADR-0006). The marker is
- * consumed BEFORE the snapshot, so it never needs to survive a pause.
- *
- * Scoped by `agentId` so concurrent `agent()` calls sharing one sandbox each
- * see only their own request. When the id is unavailable (older agent env that
- * doesn't inject `AGENT_COMPOSE_AGENT_ID`) both sides fall back to a single
- * unscoped slot — correct for the common single-agent step, and the only case
- * where an unscoped marker can be ambiguous (two anonymous agents) is one the
- * old block-poll CLI couldn't handle either.
- */
-
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { randomBytes } from "node:crypto";
-
-import { getStateDir } from "../pause/state-dir.js";
-
-/** A choice offered to the human. A bare string is shorthand for
- *  `{ label, value }` with both equal — exactly what the dashboard's
- *  `readOptions` accepts. */
-export type PauseOption = string | { label: string; value: string };
-
-/** What `agentc pause` records for the loop to turn into a `ctx.pause`. */
-export interface LocalPauseRequest {
-  /** The question shown to the human (becomes the pause `reason`). */
-  reason:   string;
-  /** Optional offered choices, rendered as buttons in the dashboard. */
-  options?: PauseOption[];
-}
-
-const UNSCOPED = "_unscoped";
-
-const requestsDir = () => join(getStateDir(), "pause-requests");
-const markerPath  = (agentId: string | undefined | null) =>
-  join(requestsDir(), `${slug(agentId) || UNSCOPED}.json`);
-
-/** Keep the agentId filename-safe. Agent ids are `step<idx>-agent-<n>` shaped,
- *  but defend against anything exotic so the marker can never escape the dir. */
-function slug(agentId: string | undefined | null): string {
-  return (agentId ?? "").replace(/[^a-zA-Z0-9_.-]/g, "_");
-}
-
-/** Write the marker atomically (tmp → rename) so the loop never reads a
- *  partial file mid-write. Called by `agentc pause`. */
-export function writeLocalPauseRequest(agentId: string | undefined | null, req: LocalPauseRequest): void {
-  mkdirSync(requestsDir(), { recursive: true });
-  const final = markerPath(agentId);
-  const tmp   = `${final}.${randomBytes(6).toString("hex")}.tmp`;
-  writeFileSync(tmp, JSON.stringify(req), "utf8");
-  renameSync(tmp, final);
-}
-
-/** Take-once read: returns + deletes this agent's pending pause request, else
- *  null. Checks the agent-scoped slot first, then the unscoped fallback. The
- *  loop calls this once per turn; a malformed marker is dropped (deleted +
- *  null) rather than wedging the loop. */
-export function consumeLocalPauseRequest(agentId: string | undefined | null): LocalPauseRequest | null {
-  const paths = [...new Set([markerPath(agentId), markerPath(null)])]; // dedupe when agentId is absent
-  for (const path of paths) {
-    if (!existsSync(path)) continue;
-    try {
-      const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
-      rmSync(path, { force: true });
-      if (raw && typeof raw === "object" && typeof (raw as LocalPauseRequest).reason === "string" && (raw as LocalPauseRequest).reason.trim().length > 0) {
-        const r = raw as LocalPauseRequest;
-        return { reason: r.reason.trim(), ...(Array.isArray(r.options) && r.options.length > 0 ? { options: r.options } : {}) };
-      }
-    } catch {
-      rmSync(path, { force: true }); // unreadable / partial → drop it
-    }
-  }
-  return null;
-}