@agent-compose/sdk 0.3.0 → 0.4.0

package/dist/client.d.ts

@@ -132,6 +132,27 @@ export interface UpdateFactoryInput {
     name?: string;
     description?: string;
 }
+export interface ScheduleRow {
+    id: string;
+    name: string;
+    workflowName: string;
+    cron: string;
+    createdAt: string;
+    updatedAt: string;
+    nextFireAt: string | null;
+    lastFireAt: string | null;
+}
+export interface CreateScheduleInput {
+    /** Human-friendly schedule name. Unique within the factory. */
+    name: string;
+    /** The workflow this schedule should fire. Must already be registered
+     *  in the same factory. */
+    workflow: string;
+    /** Cron expression (UTC). */
+    cron: string;
+    /** Factory to attach the schedule to. Defaults to `"default"`. */
+    factorySlug?: string;
+}
 export interface SecretOptions {
     factorySlug?: string;
 }
@@ -424,6 +445,21 @@ export declare class AgentComposeClient {
     /** Delete a factory. Refuses `default` and any factory still
      *  containing workflows. */
     deleteFactory(slug: string): Promise<void>;
+    /** List every schedule in a factory, with the engine-reported next/last
+     *  fire times merged in. */
+    listSchedules(factorySlug?: string): Promise<ScheduleRow[]>;
+    /** Create a new schedule. `name` is per-factory unique; the server
+     *  returns 409 on collision. */
+    createSchedule(payload: CreateScheduleInput): Promise<{
+        id: string;
+        name: string;
+        workflow: string;
+        cron: string;
+    }>;
+    /** Delete a schedule by id. Best-effort: a transient engine error is
+     *  logged server-side but the DB row is removed regardless — the boot
+     *  reconciler reconverges on next start. */
+    deleteSchedule(id: string, factorySlug?: string): Promise<void>;
     /** Create or update a workflow secret. Value is stored in GCP Secret Manager. */
     setSecret(workflowName: string, key: string, value: string, opts?: SecretOptions): Promise<SetSecretResult>;
     /** List secret keys registered for a workflow (metadata only — values are never returned). */

package/dist/index.js

@@ -477,6 +477,8 @@ var WORKFLOW_BRAND = Symbol.for("@agent-compose/sdk.Workflow");
 // src/types/workflow-metadata.ts
 function extractMetadata(source) {
   const out = {};
+  if (source.description !== undefined)
+    out.description = source.description;
   if (source.networkPolicy !== undefined)
     out.networkPolicy = freezeMetadataValue(source.networkPolicy);
   if (source.placeholders !== undefined)
@@ -587,6 +589,7 @@ function defineSandboxEnvironment(env) {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow({
+    ...env.description !== undefined ? { description: env.description } : {},
     snapshots: env.snapshots ?? { saveLatest: true },
     memory: env.memory ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox)
@@ -858,6 +861,20 @@ class AgentComposeClient {
   deleteFactory(slug) {
     return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
   }
+  async listSchedules(factorySlug = "default") {
+    const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules`);
+    return body.schedules;
+  }
+  createSchedule(payload) {
+    const factorySlug = payload.factorySlug ?? "default";
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules`, {
+      method: "POST",
+      body: { name: payload.name, workflow: payload.workflow, cron: payload.cron }
+    });
+  }
+  deleteSchedule(id, factorySlug = "default") {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules/${encodeURIComponent(id)}`, { method: "DELETE" });
+  }
   setSecret(workflowName, key, value, opts) {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {

package/dist/runtimes/openai-desktop.js

@@ -477,6 +477,8 @@ var WORKFLOW_BRAND = Symbol.for("@agent-compose/sdk.Workflow");
 // src/types/workflow-metadata.ts
 function extractMetadata(source) {
   const out = {};
+  if (source.description !== undefined)
+    out.description = source.description;
   if (source.networkPolicy !== undefined)
     out.networkPolicy = freezeMetadataValue(source.networkPolicy);
   if (source.placeholders !== undefined)
@@ -587,6 +589,7 @@ function defineSandboxEnvironment(env) {
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow({
+    ...env.description !== undefined ? { description: env.description } : {},
     snapshots: env.snapshots ?? { saveLatest: true },
     memory: env.memory ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox)
@@ -858,6 +861,20 @@ class AgentComposeClient {
   deleteFactory(slug) {
     return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
   }
+  async listSchedules(factorySlug = "default") {
+    const body = await this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules`);
+    return body.schedules;
+  }
+  createSchedule(payload) {
+    const factorySlug = payload.factorySlug ?? "default";
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules`, {
+      method: "POST",
+      body: { name: payload.name, workflow: payload.workflow, cron: payload.cron }
+    });
+  }
+  deleteSchedule(id, factorySlug = "default") {
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules/${encodeURIComponent(id)}`, { method: "DELETE" });
+  }
   setSecret(workflowName, key, value, opts) {
     const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
     return this.fetch(templatePath(factorySlug, workflowName, "secrets"), {

package/dist/types/sandbox-environment.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Regression test: `defineSandboxEnvironment.description` must reach
+ * the workflow's metadata so the dashboard template tile shows it
+ * instead of "No description.".
+ *
+ * Earlier the wrapper dropped the field on the floor — `agent-env`
+ * literally had `description: "..."` in source but the dashboard
+ * rendered "No description." because nothing propagated it through to
+ * `WorkflowMetadata.description`.
+ */
+export {};

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

@@ -72,6 +72,11 @@ export interface IOSchema {
  *  output-only release. New code should prefer `IOSchema`. */
 export type OutputSchema = IOSchema;
 export interface WorkflowMetadata {
+    /** One-line, human-readable description of what the workflow does.
+     *  Surfaced on the dashboard template tile + run page header. Authors
+     *  set it via `defineWorkflow({ description: "..." })` (either shape)
+     *  or `defineSandboxEnvironment({ description: "..." })`. */
+    description?: string;
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     /** Input schema captured at bundle time from the workflow's

package/dist/types/workflow.d.ts

@@ -67,6 +67,9 @@ export type WorkflowFn<TOutput = unknown, TInput extends Record<string, unknown>
  * works — the workflow just runs with secrets passed directly in env.
  */
 export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<string, unknown> = Record<string, unknown>> {
+    /** One-line, human-readable description of what this workflow does.
+     *  Surfaced on the dashboard template tile + run page header. */
+    description?: string;
     run: WorkflowFn<TOutput, TInput>;
     /**
      * All snapshot config — boot source plus capture mode.

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

@@ -38,6 +38,9 @@ export interface WorkflowBuilder<TInput, TCurrent> {
 }
 export interface StepWorkflowDefinition<TInput, TOutput> {
     id: string;
+    /** One-line, human-readable description of what this workflow does.
+     *  Surfaced on the dashboard template tile + run page header. */
+    description?: string;
     input: z.ZodType<TInput>;
     output: z.ZodType<TOutput>;
     networkPolicy?: SandboxNetworkPolicy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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

@@ -177,6 +177,29 @@ export interface UpdateFactoryInput {
   description?: string;
 }
 
+export interface ScheduleRow {
+  id:           string;
+  name:         string;
+  workflowName: string;
+  cron:         string;
+  createdAt:    string;
+  updatedAt:    string;
+  nextFireAt:   string | null;
+  lastFireAt:   string | null;
+}
+
+export interface CreateScheduleInput {
+  /** Human-friendly schedule name. Unique within the factory. */
+  name:         string;
+  /** The workflow this schedule should fire. Must already be registered
+   *  in the same factory. */
+  workflow:     string;
+  /** Cron expression (UTC). */
+  cron:         string;
+  /** Factory to attach the schedule to. Defaults to `"default"`. */
+  factorySlug?: string;
+}
+
 export interface SecretOptions {
   factorySlug?: string;
 }
@@ -668,6 +691,40 @@ export class AgentComposeClient {
     return this.fetch(`/api/v1/factories/${encodeURIComponent(slug)}`, { method: "DELETE" });
   }
 
+  // ── Schedules ─────────────────────────────────────────────────────────────
+  // Cron schedules attached to a registered workflow. One workflow can have
+  // N schedules with distinct names + cadences; runs the schedule triggers
+  // are tagged with the schedule's id and name in their metadata.
+
+  /** List every schedule in a factory, with the engine-reported next/last
+   *  fire times merged in. */
+  async listSchedules(factorySlug = "default"): Promise<ScheduleRow[]> {
+    const body = await this.fetch<{ schedules: ScheduleRow[] }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules`,
+    );
+    return body.schedules;
+  }
+
+  /** Create a new schedule. `name` is per-factory unique; the server
+   *  returns 409 on collision. */
+  createSchedule(payload: CreateScheduleInput): Promise<{ id: string; name: string; workflow: string; cron: string }> {
+    const factorySlug = payload.factorySlug ?? "default";
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules`, {
+      method: "POST",
+      body: { name: payload.name, workflow: payload.workflow, cron: payload.cron },
+    });
+  }
+
+  /** Delete a schedule by id. Best-effort: a transient engine error is
+   *  logged server-side but the DB row is removed regardless — the boot
+   *  reconciler reconverges on next start. */
+  deleteSchedule(id: string, factorySlug = "default"): Promise<void> {
+    return this.fetch(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/schedules/${encodeURIComponent(id)}`,
+      { method: "DELETE" },
+    );
+  }
+
   // ── Secrets ────────────────────────────────────────────────────────────────
   // Scoped to (factory, workflow, key). Stored in GCP Secret Manager;
   // `factorySlug` defaults to `"default"`.

package/src/types/sandbox-environment.ts

@@ -69,6 +69,7 @@ export function defineSandboxEnvironment(
     throw new Error(`defineSandboxEnvironment(${env.name}): 'setup' must be a function`);
   }
   return defineWorkflow<void, Record<string, unknown>>({
+    ...(env.description !== undefined ? { description: env.description } : {}),
     snapshots: env.snapshots ?? { saveLatest: true },
     memory:    env.memory    ?? false,
     run: async (_ctx, sandbox) => env.setup(sandbox),

package/src/types/workflow-metadata.ts

@@ -74,6 +74,11 @@ export interface IOSchema {
 export type OutputSchema = IOSchema;
 
 export interface WorkflowMetadata {
+  /** One-line, human-readable description of what the workflow does.
+   *  Surfaced on the dashboard template tile + run page header. Authors
+   *  set it via `defineWorkflow({ description: "..." })` (either shape)
+   *  or `defineSandboxEnvironment({ description: "..." })`. */
+  description?:   string;
   networkPolicy?: SandboxNetworkPolicy;
   placeholders?:  Record<string, string>;
   /** Input schema captured at bundle time from the workflow's
@@ -117,6 +122,7 @@ export interface WorkflowMetadata {
  */
 export function extractMetadata(source: Partial<WorkflowMetadata>): WorkflowMetadata {
   const out: WorkflowMetadata = {};
+  if (source.description   !== undefined) out.description   = source.description;
   if (source.networkPolicy !== undefined) out.networkPolicy = freezeMetadataValue(source.networkPolicy);
   if (source.placeholders  !== undefined) out.placeholders  = Object.freeze({ ...source.placeholders });
   if (source.inputSchema   !== undefined) out.inputSchema   = freezeMetadataValue(source.inputSchema);

package/src/types/workflow.ts

@@ -89,6 +89,9 @@ export interface WorkflowDefinition<
   TOutput = unknown,
   TInput extends Record<string, unknown> = Record<string, unknown>,
 > {
+  /** One-line, human-readable description of what this workflow does.
+   *  Surfaced on the dashboard template tile + run page header. */
+  description?: string;
   run: WorkflowFn<TOutput, TInput>;
   /**
    * All snapshot config — boot source plus capture mode.

package/src/workflow-steps/workflow.ts

@@ -43,6 +43,9 @@ export interface WorkflowBuilder<TInput, TCurrent> {
 
 export interface StepWorkflowDefinition<TInput, TOutput> {
   id:     string;
+  /** One-line, human-readable description of what this workflow does.
+   *  Surfaced on the dashboard template tile + run page header. */
+  description?:   string;
   input:  z.ZodType<TInput>;
   output: z.ZodType<TOutput>;
   networkPolicy?: SandboxNetworkPolicy;