@agent-compose/sdk 0.4.0 → 0.5.1

package/dist/client.d.ts

@@ -50,6 +50,10 @@ export interface RegisterWorkflowInput {
     version?: string;
     schedule?: string;
     runtimes?: RuntimeSourceInput[];
+    /** Human-readable description declared via
+     *  `defineWorkflow({ description })`. Stored in template metadata and
+     *  surfaced on the dashboard template card. */
+    description?: string;
     networkPolicy?: unknown;
     placeholders?: Record<string, string>;
     /** All snapshot config — `bootFrom` (where to restore at run start),

package/dist/index.js

@@ -547,10 +547,12 @@ function isWorkflow(value) {
 // src/types/workflow.ts
 function compileRunForm(def, metadata) {
   const unknownSchema = z2.unknown();
+  const inputSchema = def.input ?? unknownSchema;
+  const outputSchema = def.output ?? unknownSchema;
   const step = {
     name: "run",
-    input: unknownSchema,
-    output: unknownSchema,
+    input: inputSchema,
+    output: outputSchema,
     run: async (stepCtx) => {
       const workflowCtx = {
         input: stepCtx.input,
@@ -570,8 +572,8 @@ function compileRunForm(def, metadata) {
   };
   const workflow = {
     id: "@run-form",
-    input: unknownSchema,
-    output: unknownSchema,
+    input: inputSchema,
+    output: outputSchema,
     steps: Object.freeze([step]),
     metadata
   };
@@ -1067,6 +1069,7 @@ async function bundleWorkflow(workflowPath, overrides) {
     workflowPlan: plan,
     networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
     placeholders: overrides?.placeholders ?? metadata.placeholders,
+    ...metadata.description !== undefined ? { description: metadata.description } : {},
     ...inputSchema !== undefined ? { inputSchema } : {},
     ...outputSchema !== undefined ? { outputSchema } : {},
     ...metadata.snapshots !== undefined ? { snapshots: metadata.snapshots } : {},
@@ -1596,13 +1599,14 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
     sandboxId: sb.sandboxId,
     commands: {
       async run(cmd, opts) {
+        const sudo = opts?.sudo === true;
         if (opts?.background) {
-          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }).catch((err) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
+          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true, ...sudo ? { sudo: true } : {} }).catch((err) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
           return { exitCode: 0, stdout: "" };
         }
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
         let stdout = "";
-        const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal });
+        const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...sudo ? { sudo: true } : {} });
         await pRetry(async (attempt) => {
           const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
           for await (const log of h.logs()) {
@@ -1641,8 +1645,9 @@ function makeLocalSandboxProvider() {
     sandboxId: "local",
     commands: {
       run(cmd, opts) {
+        const finalCmd = opts?.sudo ? `sudo ${cmd}` : cmd;
         return new Promise((resolve, reject) => {
-          const proc = spawn("sh", ["-c", cmd], {
+          const proc = spawn("sh", ["-c", finalCmd], {
             ...opts?.cwd ? { cwd: opts.cwd } : {},
             env: { ...process.env, ...opts?.envs ?? {} },
             stdio: ["ignore", "pipe", "pipe"]

package/dist/runtimes/openai-desktop.js

@@ -547,10 +547,12 @@ function isWorkflow(value) {
 // src/types/workflow.ts
 function compileRunForm(def, metadata) {
   const unknownSchema = z2.unknown();
+  const inputSchema = def.input ?? unknownSchema;
+  const outputSchema = def.output ?? unknownSchema;
   const step = {
     name: "run",
-    input: unknownSchema,
-    output: unknownSchema,
+    input: inputSchema,
+    output: outputSchema,
     run: async (stepCtx) => {
       const workflowCtx = {
         input: stepCtx.input,
@@ -570,8 +572,8 @@ function compileRunForm(def, metadata) {
   };
   const workflow = {
     id: "@run-form",
-    input: unknownSchema,
-    output: unknownSchema,
+    input: inputSchema,
+    output: outputSchema,
     steps: Object.freeze([step]),
     metadata
   };
@@ -1067,6 +1069,7 @@ async function bundleWorkflow(workflowPath, overrides) {
     workflowPlan: plan,
     networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
     placeholders: overrides?.placeholders ?? metadata.placeholders,
+    ...metadata.description !== undefined ? { description: metadata.description } : {},
     ...inputSchema !== undefined ? { inputSchema } : {},
     ...outputSchema !== undefined ? { outputSchema } : {},
     ...metadata.snapshots !== undefined ? { snapshots: metadata.snapshots } : {},
@@ -1596,13 +1599,14 @@ function makeVercelSandboxProvider(sb, globalEnvs) {
     sandboxId: sb.sandboxId,
     commands: {
       async run(cmd, opts) {
+        const sudo = opts?.sudo === true;
         if (opts?.background) {
-          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }).catch((err) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
+          sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true, ...sudo ? { sudo: true } : {} }).catch((err) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
           return { exitCode: 0, stdout: "" };
         }
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
         let stdout = "";
-        const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal });
+        const handle = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...sudo ? { sudo: true } : {} });
         await pRetry(async (attempt) => {
           const h = attempt === 1 ? handle : await sb.getCommand(handle.cmdId);
           for await (const log of h.logs()) {
@@ -1641,8 +1645,9 @@ function makeLocalSandboxProvider() {
     sandboxId: "local",
     commands: {
       run(cmd, opts) {
+        const finalCmd = opts?.sudo ? `sudo ${cmd}` : cmd;
         return new Promise((resolve, reject) => {
-          const proc = spawn("sh", ["-c", cmd], {
+          const proc = spawn("sh", ["-c", finalCmd], {
             ...opts?.cwd ? { cwd: opts.cwd } : {},
             env: { ...process.env, ...opts?.envs ?? {} },
             stdio: ["ignore", "pipe", "pipe"]

package/dist/types/sandbox.d.ts

@@ -10,6 +10,11 @@ export interface SandboxCommandRunOptions {
     onStdout?: (data: string) => void;
     onStderr?: (data: string) => void;
     background?: boolean;
+    /** Run the command with root privileges. Vercel maps this to its native
+     *  `sudo` flag; E2B runs the command as `user: "root"`; the local provider
+     *  prepends `sudo`. Defaults to false. Requires the sandbox image to grant
+     *  the command root (Vercel's runtimes do — passwordless). */
+    sudo?: boolean;
 }
 export interface SandboxCommandResult {
     exitCode: number;

package/dist/types/workflow.d.ts

@@ -13,6 +13,7 @@
  * LLM agent loops live in `agent(opts)` (sdk/src/agent/run-agent.ts).
  * Invoking other workflows uses `AgentComposeClient.invoke[AndWait](...)`.
  */
+import { z } from "zod";
 import type { SandboxNetworkPolicy } from "../sandbox.js";
 import type { SandboxProvider } from "./sandbox.js";
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
@@ -70,6 +71,17 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
     /** One-line, human-readable description of what this workflow does.
      *  Surfaced on the dashboard template tile + run page header. */
     description?: string;
+    /** Zod schema for the workflow's `input`. When declared, the SDK
+     *  bundler captures it as JSON-Schema-shaped `inputSchema` in
+     *  template metadata, the dashboard playground renders a typed
+     *  form, and the engine validates dispatched payloads against it
+     *  at the step boundary. Omit to leave inputs as `unknown` (the
+     *  legacy default — playground falls back to a freeform JSON
+     *  textarea). */
+    input?: z.ZodType<TInput>;
+    /** Same as `input`, for the workflow's return value. Captured into
+     *  `outputSchema` metadata and rendered in the IO panel. */
+    output?: z.ZodType<TOutput>;
     run: WorkflowFn<TOutput, TInput>;
     /**
      * All snapshot config — boot source plus capture mode.

package/dist/utils/bundler.d.ts

@@ -49,6 +49,10 @@ export declare class WorkflowSourceValidationError extends Error {
 export interface BundledWorkflow {
     source: string;
     manifest: WorkflowManifest;
+    /** One-line, human-readable description declared via
+     *  `defineWorkflow({ description })`. Surfaced on the dashboard
+     *  template card + run header. */
+    description?: string;
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     /** Snapshot config from the workflow definition — `bootFrom` (where to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {

package/src/client.ts

@@ -85,6 +85,10 @@ export interface RegisterWorkflowInput {
   version?: string;
   schedule?: string;
   runtimes?: RuntimeSourceInput[];
+  /** Human-readable description declared via
+   *  `defineWorkflow({ description })`. Stored in template metadata and
+   *  surfaced on the dashboard template card. */
+  description?: string;
   networkPolicy?: unknown;
   placeholders?: Record<string, string>;
   /** All snapshot config — `bootFrom` (where to restore at run start),

package/src/sandbox.ts

@@ -200,16 +200,20 @@ function makeVercelSandboxProvider(sb: any, globalEnvs?: Record<string, string>)
     sandboxId: sb.sandboxId,
     commands: {
       async run(cmd, opts) {
+        // Vercel's runCommand takes a native `sudo` flag — pass it on the `sh`
+        // invocation so the whole shell (and every command it spawns) runs as
+        // root, matching `sb.runCommand({ cmd, args, sudo: true })` semantics.
+        const sudo = opts?.sudo === true;
         if (opts?.background) {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          void (sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true }) as Promise<any>)
+          void (sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts.cwd, env: mergeEnvs(opts.envs), detached: true, ...(sudo ? { sudo: true } : {}) }) as Promise<any>)
             .catch((err: unknown) => console.error(`[sandbox] background command failed: ${err instanceof Error ? err.message : String(err)}`));
           return { exitCode: 0, stdout: "" };
         }
         const signal = opts?.timeoutMs ? AbortSignal.timeout(opts.timeoutMs) : undefined;
         let stdout = "";
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const handle: any = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal });
+        const handle: any = await sb.runCommand({ cmd: "sh", args: ["-c", cmd], cwd: opts?.cwd, env: mergeEnvs(opts?.envs), detached: true, signal, ...(sudo ? { sudo: true } : {}) });
         // Reconnect to the already-running command on transient stream failures (e.g. BrotliDecompressionError).
         await pRetry(async (attempt) => {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -261,8 +265,13 @@ export function makeLocalSandboxProvider(): SandboxProvider {
     sandboxId: "local",
     commands: {
       run(cmd, opts) {
+        // Prepend `sudo` so the command runs as root. The local provider
+        // targets the runner's own host VM (used by defineSandboxEnvironment
+        // recipes); harmless when the host is already root or has passwordless
+        // sudo, which is the only context it runs in.
+        const finalCmd = opts?.sudo ? `sudo ${cmd}` : cmd;
         return new Promise((resolve, reject) => {
-          const proc = spawn("sh", ["-c", cmd], {
+          const proc = spawn("sh", ["-c", finalCmd], {
             ...(opts?.cwd ? { cwd: opts.cwd } : {}),
             env: { ...process.env, ...(opts?.envs ?? {}) },
             stdio: ["ignore", "pipe", "pipe"],

package/src/types/sandbox.ts

@@ -11,6 +11,11 @@ export interface SandboxCommandRunOptions {
   onStdout?: (data: string) => void;
   onStderr?: (data: string) => void;
   background?: boolean;
+  /** Run the command with root privileges. Vercel maps this to its native
+   *  `sudo` flag; E2B runs the command as `user: "root"`; the local provider
+   *  prepends `sudo`. Defaults to false. Requires the sandbox image to grant
+   *  the command root (Vercel's runtimes do — passwordless). */
+  sudo?: boolean;
 }
 
 export interface SandboxCommandResult {

package/src/types/workflow.ts

@@ -92,6 +92,17 @@ export interface WorkflowDefinition<
   /** One-line, human-readable description of what this workflow does.
    *  Surfaced on the dashboard template tile + run page header. */
   description?: string;
+  /** Zod schema for the workflow's `input`. When declared, the SDK
+   *  bundler captures it as JSON-Schema-shaped `inputSchema` in
+   *  template metadata, the dashboard playground renders a typed
+   *  form, and the engine validates dispatched payloads against it
+   *  at the step boundary. Omit to leave inputs as `unknown` (the
+   *  legacy default — playground falls back to a freeform JSON
+   *  textarea). */
+  input?:  z.ZodType<TInput>;
+  /** Same as `input`, for the workflow's return value. Captured into
+   *  `outputSchema` metadata and rendered in the IO panel. */
+  output?: z.ZodType<TOutput>;
   run: WorkflowFn<TOutput, TInput>;
   /**
    * All snapshot config — boot source plus capture mode.
@@ -168,15 +179,25 @@ export interface WorkflowDefinition<
  * under that one step. Authors keep the same source; the dashboard sees
  * the same timeline shape.
  */
+// TODO: collapse run-form into pure sugar over step-form. Run-form
+// already compiles to step-form-with-one-step here, so maintaining two
+// authoring surfaces is API duplication that periodically drifts (see
+// the input/output thread-through bug fixed on 2026-05-20: step-form
+// preserved schemas, run-form silently stamped z.unknown()). Cleaner:
+// turn `defineWorkflow({ run })` into a thin wrapper that calls the
+// step builder with a synthesised `{name:"run", input, output, run}`
+// step, then delete this function. Runtime stays identical.
 function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
   def: WorkflowDefinition<TOutput, TInput>,
   metadata: WorkflowMetadata,
 ): Workflow<TInput, TOutput> {
   const unknownSchema = z.unknown() as z.ZodType<unknown>;
+  const inputSchema:  z.ZodType<TInput>  = def.input  ?? (unknownSchema as z.ZodType<TInput>);
+  const outputSchema: z.ZodType<TOutput> = def.output ?? (unknownSchema as z.ZodType<TOutput>);
   const step: Step<TInput, TOutput> = {
     name:   "run",
-    input:  unknownSchema as z.ZodType<TInput>,
-    output: unknownSchema as z.ZodType<TOutput>,
+    input:  inputSchema,
+    output: outputSchema,
     run: async (stepCtx) => {
       // Proxy the legacy WorkflowCtx hooks to the step's collector-backed
       // implementations. The engine harvests the snapshot after execute
@@ -198,8 +219,8 @@ function compileRunForm<TOutput, TInput extends Record<string, unknown>>(
   };
   const workflow: Workflow<TInput, TOutput> = {
     id:     "@run-form",
-    input:  unknownSchema as z.ZodType<TInput>,
-    output: unknownSchema as z.ZodType<TOutput>,
+    input:  inputSchema,
+    output: outputSchema,
     steps:  Object.freeze([step]),
     metadata,
   };

package/src/utils/bundler.ts

@@ -63,6 +63,10 @@ export class WorkflowSourceValidationError extends Error {
 export interface BundledWorkflow {
   source: string;
   manifest: WorkflowManifest;
+  /** One-line, human-readable description declared via
+   *  `defineWorkflow({ description })`. Surfaced on the dashboard
+   *  template card + run header. */
+  description?: string;
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?: Record<string, string>;
   /** Snapshot config from the workflow definition — `bootFrom` (where to
@@ -292,6 +296,7 @@ export async function bundleWorkflow(
     workflowPlan: plan,
     networkPolicy: overrides?.networkPolicy ?? metadata.networkPolicy,
     placeholders:  overrides?.placeholders  ?? metadata.placeholders,
+    ...(metadata.description     !== undefined ? { description:  metadata.description }  : {}),
     ...(inputSchema              !== undefined ? { inputSchema }                        : {}),
     ...(outputSchema             !== undefined ? { outputSchema }                       : {}),
     ...(metadata.snapshots       !== undefined ? { snapshots:    metadata.snapshots }    : {}),