@agent-compose/sdk 0.2.4 → 0.3.0

package/src/utils/bundler.ts

@@ -24,7 +24,7 @@ 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 } from "../types/workflow.js";
+import type { WorkflowMemoryConfig, SnapshotConfig } from "../types/workflow.js";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import { isWorkflow } from "../workflow-steps/workflow.js";
 import type { Workflow } from "../workflow-steps/types.js";
@@ -65,15 +65,20 @@ export interface BundledWorkflow {
   manifest: WorkflowManifest;
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?: Record<string, string>;
-  /** Run UUID, workflow name, or `name@version` referencing the snapshot
-   *  this workflow's runner boots from, if declared via the `snapshot`
-   *  field on `defineWorkflow`. */
-  snapshot?: string;
-  /** Default capture-on-success flag from the workflow definition. */
-  saveSnapshot?: boolean;
+  /** Snapshot config from the workflow definition — `bootFrom` (where to
+   *  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;
+  /** Same for the workflow's output zod schema. */
+  outputSchema?: import("../types/workflow-metadata.js").IOSchema;
 }
 
 async function bundle(path: string, label: string): Promise<string> {
@@ -120,11 +125,19 @@ async function extractFromBundle<T>(
 /**
  * Bun bundles `import { defineWorkflow }` to a local identifier — usually
  * the exact name, or a numeric suffix like `defineWorkflow2` to disambiguate
- * scopes. Match exactly that pattern, NOT `startsWith("defineWorkflow")` —
+ * scopes. Match exactly those patterns, NOT `startsWith("defineWorkflow")` —
  * the latter would also accept `defineWorkflowAttacker`. The runtime brand
  * check is the second gate, but the syntactic check should be tight.
+ *
+ * `defineSandboxEnvironment` is sugar over `defineWorkflow` (see
+ * `src/types/sandbox-environment.ts`) and is explicitly registerable via
+ * `agentc register setup.ts --build` to capture a snapshot. The AST gate
+ * accepts it for the same reason it accepts `defineWorkflow`: the bundled
+ * default export is a CallExpression to a known SDK identifier, and the
+ * runtime brand check downstream catches anything that lies about being a
+ * workflow.
  */
-const DEFINE_WORKFLOW_CALLEE = /^defineWorkflow\d*$/;
+const DEFINE_WORKFLOW_CALLEE = /^(?:defineWorkflow|defineSandboxEnvironment)\d*$/;
 
 function isDefineWorkflowCall(node: CallExpression): boolean {
   if (node.callee.type === "Identifier") {
@@ -262,14 +275,76 @@ export async function bundleWorkflow(
     bundlerVersion:  BUNDLER_VERSION,
   };
 
+  // Input + output schemas: the workflow's `input` / `output` zod
+  // schemas → compact JSON-Schema-shaped descriptions carried in
+  // template metadata. Used by the dashboard's "Registered" panel to
+  // render schema tables and (eventually) client-side validation in
+  // the playground. Run-form workflows stamp `z.unknown()` for both
+  // — `extractIOSchema` filters those down to undefined so the
+  // dashboard renders the "no declared schema" empty state instead
+  // of a meaningless empty table.
+  const inputSchema  = extractIOSchema(workflow.input);
+  const outputSchema = extractIOSchema(workflow.output);
+
   return {
     source,
     manifest,
     workflowPlan: plan,
     networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
     placeholders:  overrides?.placeholders  ?? metadata.placeholders,
-    ...(metadata.snapshot     !== undefined ? { snapshot:     metadata.snapshot }     : {}),
-    ...(metadata.saveSnapshot !== undefined ? { saveSnapshot: metadata.saveSnapshot } : {}),
-    ...(metadata.memory       !== undefined ? { memory:       metadata.memory }       : {}),
+    ...(inputSchema              !== undefined ? { inputSchema }                        : {}),
+    ...(outputSchema             !== undefined ? { outputSchema }                       : {}),
+    ...(metadata.snapshots       !== undefined ? { snapshots:    metadata.snapshots }    : {}),
+    ...(metadata.memory          !== undefined ? { memory:       metadata.memory }       : {}),
+    ...(metadata.postRunHooks    !== undefined ? { postRunHooks: metadata.postRunHooks } : {}),
   };
 }
+
+/** Convert a workflow's `input` or `output` zod schema into a compact,
+ *  serialisable description for template metadata. Uses Zod 4's
+ *  `toJSONSchema` and trims the result to fields the dashboard
+ *  renders — full draft 2020-12 schemas have refs / unions / nested
+ *  allOf chains that are noisier than the dashboard needs.
+ *
+ *  Returns undefined when:
+ *    - The schema can't be serialised (corrupt / unknown variant)
+ *    - The schema is effectively `unknown` (the run-form sugar default —
+ *      no meaningful contract to render). */
+function extractIOSchema(
+  zodSchema: { _zod?: unknown } | unknown,
+): import("../types/workflow-metadata.js").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;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const z = require("zod") as { toJSONSchema?: (s: unknown) => Record<string, unknown> };
+    if (!z.toJSONSchema) return undefined;
+    json = z.toJSONSchema(zodSchema);
+  } catch {
+    return undefined;
+  }
+  if (!json || typeof json !== "object") return undefined;
+
+  // `z.unknown()` serialises to `{}` (no type, no properties). Skip that
+  // — 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 = {};
+  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") {
+    const props: Record<string, { type?: string | string[]; description?: string }> = {};
+    for (const [key, raw] of Object.entries(json.properties as Record<string, unknown>)) {
+      if (raw && typeof raw === "object") {
+        const r = raw as Record<string, unknown>;
+        props[key] = {};
+        if (r.type        !== undefined) props[key].type        = r.type as string | string[];
+        if (r.description !== undefined) props[key].description = String(r.description);
+      }
+    }
+    if (Object.keys(props).length > 0) out.properties = props;
+  }
+  if (Array.isArray(json.required)) out.required = json.required.map(String);
+  return out;
+}

package/src/workflow-steps/workflow.ts

@@ -23,6 +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 { SandboxNetworkPolicy } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
 
@@ -46,8 +47,9 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
   output: z.ZodType<TOutput>;
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?:  Record<string, string>;
-  snapshot?:      string;
-  saveSnapshot?:  boolean;
+  snapshots?:     SnapshotConfig;
+  memory?:        WorkflowMemoryConfig;
+  postRunHooks?:  readonly string[];
   processors?:    readonly Processor[];
 }
 

package/src/workflows/invoke-child.ts

@@ -18,7 +18,7 @@ export function buildInvokeChild(
     if (!baseUrl || !apiKey) {
       throw new Error("ctx.invokeChild requires AGENT_COMPOSE_URL and AGENT_COMPOSE_API_KEY");
     }
-    childClient = new AgentComposeClient(baseUrl, apiKey);
+    childClient = new AgentComposeClient({ apiKey, baseUrl });
     return childClient;
   };
   return (name, input, childOpts) => getChildClient().invokeAndWait(name, input, {