@stackbone/sdk 0.1.0-alpha.5 → 0.1.0-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/sdk",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "license": "UNLICENSED",
   "description": "Official TypeScript SDK for Stackbone — the marketplace and managed runtime for containerized AI agents.",
   "type": "module",
@@ -28,6 +28,26 @@
         "default": "./db/index.cjs"
       }
     },
+    "./workflow": {
+      "import": {
+        "types": "./workflow.d.ts",
+        "default": "./workflow.js"
+      },
+      "require": {
+        "types": "./workflow.d.cts",
+        "default": "./workflow.cjs"
+      }
+    },
+    "./connect": {
+      "import": {
+        "types": "./connect.d.ts",
+        "default": "./connect.js"
+      },
+      "require": {
+        "types": "./connect.d.cts",
+        "default": "./connect.cjs"
+      }
+    },
     "./db/testing": {
       "import": {
         "types": "./db/testing/index.d.ts",
@@ -106,5 +126,17 @@
     "postgres": "3.4.9",
     "unpdf": "^0.12.1",
     "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "eve": "*",
+    "workflow": "*"
+  },
+  "peerDependenciesMeta": {
+    "eve": {
+      "optional": true
+    },
+    "workflow": {
+      "optional": true
+    }
   }
 }

package/workflow-scheduler-DXCNKDOS.d.cts

@@ -0,0 +1,119 @@
+/**
+ * Augmentable registry of the workspace's eve agent NAMES. By default it is
+ * empty, so `eveAgent(name)` accepts any `string` (today's behavior, validated
+ * only at runtime against the injected `AGENT_URLS` map). `stackbone dev`
+ * generates an ambient `.stackbone/agents.d.ts` from the project's
+ * `stackbone.config.ts` agent list and augments this interface so the names
+ * become a closed set:
+ *
+ *   declare module '@stackbone/sdk/workflow' {
+ *     interface AgentRegistry {
+ *       support: true;
+ *       'lead-qualifier': true;
+ *     }
+ *   }
+ *
+ * Once augmented, `eveAgent('lead-qualifier')` is fine and `eveAgent('typo')` is
+ * a compile error — the editor also autocompletes the declared names. Mirrors the
+ * `ConfigRegistry` augmentable-interface pattern used for `client.config`.
+ */
+interface AgentRegistry {
+}
+/**
+ * The set of agent names `eveAgent` accepts, derived from the augmentable
+ * `AgentRegistry`. The tuple wrap (`[X] extends [never]`) defeats the
+ * conditional-type distributivity a bare `keyof AgentRegistry extends never`
+ * would trigger:
+ *
+ * - empty registry  -> `string` (today's loose behavior: any name, checked at
+ *   runtime when the workflow resolves it against `AGENT_URLS`);
+ * - augmented registry -> the union of declared agent names (typo = compile error).
+ */
+type AgentName = [keyof AgentRegistry] extends [never] ? string : keyof AgentRegistry;
+
+/**
+ * Queue-level options for a workflow trigger.
+ *
+ * NOTE: `delaySeconds` and `idempotencyKey` are typed for forward-compatibility
+ * but NOT wired in v1. The native WDK `start()` primitive (the sanctioned
+ * trigger path) does not expose queue-level delay or dedup — those live one
+ * layer down on the World's raw producer, and reaching it means re-implementing
+ * run creation against `@workflow/core` internals. Deferred to a follow-up when
+ * the WDK exposes them. Within-run idempotency already comes from `"use step"`
+ * memoization, so a step replay never double-enqueues.
+ */
+interface WorkflowTriggerOptions {
+    /** Defer the triggered start by N seconds. Reserved — not wired in v1. */
+    readonly delaySeconds?: number;
+    /** Dedup key so a retry does not start the target twice. Reserved — not wired in v1. */
+    readonly idempotencyKey?: string;
+}
+/** What a fire-and-forget trigger resolves to: the started child run's id. */
+interface WorkflowStartHandle {
+    /** The independent run id of the workflow that was started. */
+    readonly runId: string;
+}
+/**
+ * The runtime-injected bridge the trigger helpers reach. Built by the runtime on
+ * first dispatch (closing over the name→ref registry, the validators, the WDK
+ * `start` primitive, and the run projection) and planted with
+ * {@link setWorkflowStarter}.
+ */
+interface WorkflowStarter {
+    /**
+     * Fire-and-forget: resolve `name`, validate `input`, enqueue the start on the
+     * `flows` queue, and resolve with the new independent run's id. Does NOT wait
+     * for the started workflow to finish.
+     */
+    start(name: string, input: unknown, opts?: WorkflowTriggerOptions): Promise<WorkflowStartHandle>;
+    /**
+     * Durable sub-workflow: resolve `name`, validate `input`, start the run, then
+     * suspend until it reaches a terminal state and resolve with its terminal
+     * output (validated against the target's declared output schema). Backed by the
+     * WDK's native `Run.returnValue` poll-until-terminal primitive.
+     */
+    startAndWait(name: string, input: unknown, opts?: WorkflowTriggerOptions): Promise<unknown>;
+}
+/**
+ * Plant (or clear, with `undefined`) the ambient starter. The runtime calls this
+ * on first dispatch with the bridge it built; tests pass a fake. Idempotent —
+ * the last write wins.
+ */
+declare function setWorkflowStarter(starter: WorkflowStarter | undefined): void;
+/**
+ * Return the bound ambient starter, or throw a clear error when none is bound —
+ * which means a trigger helper was called OUTSIDE a running workflow (the
+ * runtime binds the starter only on first dispatch).
+ */
+declare function getWorkflowStarter(): WorkflowStarter;
+
+/** One active scheduled trigger, as `listSchedules()` reports it. */
+interface ScheduledWorkflow {
+    /** The workflow this trigger starts on each tick. */
+    readonly name: string;
+    /** The cron expression driving the cadence. */
+    readonly cron: string;
+    /** The input each tick passes to the workflow. */
+    readonly input: unknown;
+    /** `'declarative'` (harvested from the workflow, reconciled on boot) or
+     *  `'dynamic'` (registered at run time via `scheduleWorkflow`). */
+    readonly source: 'declarative' | 'dynamic';
+}
+/** The runtime-injected bridge the imperative cron helpers reach. */
+interface WorkflowScheduler {
+    /** Register (or upsert) a DYNAMIC repeatable trigger that starts `name` with
+     *  `input` on the `cron` cadence. Idempotent by `name`. */
+    schedule(name: string, input: unknown, cron: string): Promise<void>;
+    /** Cancel a dynamic trigger by `name`. Resolves whether or not one existed. */
+    unschedule(name: string): Promise<void>;
+    /** List the active triggers — declarative + dynamic. */
+    listSchedules(): Promise<ScheduledWorkflow[]>;
+}
+/** Plant (or clear, with `undefined`) the ambient scheduler. The runtime calls
+ *  this on first dispatch; tests pass a fake. Last write wins. */
+declare function setWorkflowScheduler(scheduler: WorkflowScheduler | undefined): void;
+/** Return the bound ambient scheduler, or throw a clear error when none is bound
+ *  (the imperative cron API was reached outside a running workflow runtime). */
+declare function getWorkflowScheduler(): WorkflowScheduler;
+
+export { type AgentName as A, type ScheduledWorkflow as S, type WorkflowTriggerOptions as W, type WorkflowStartHandle as a, type AgentRegistry as b, type WorkflowScheduler as c, type WorkflowStarter as d, getWorkflowStarter as e, setWorkflowStarter as f, getWorkflowScheduler as g, setWorkflowScheduler as s };

package/workflow-scheduler-DXCNKDOS.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Augmentable registry of the workspace's eve agent NAMES. By default it is
+ * empty, so `eveAgent(name)` accepts any `string` (today's behavior, validated
+ * only at runtime against the injected `AGENT_URLS` map). `stackbone dev`
+ * generates an ambient `.stackbone/agents.d.ts` from the project's
+ * `stackbone.config.ts` agent list and augments this interface so the names
+ * become a closed set:
+ *
+ *   declare module '@stackbone/sdk/workflow' {
+ *     interface AgentRegistry {
+ *       support: true;
+ *       'lead-qualifier': true;
+ *     }
+ *   }
+ *
+ * Once augmented, `eveAgent('lead-qualifier')` is fine and `eveAgent('typo')` is
+ * a compile error — the editor also autocompletes the declared names. Mirrors the
+ * `ConfigRegistry` augmentable-interface pattern used for `client.config`.
+ */
+interface AgentRegistry {
+}
+/**
+ * The set of agent names `eveAgent` accepts, derived from the augmentable
+ * `AgentRegistry`. The tuple wrap (`[X] extends [never]`) defeats the
+ * conditional-type distributivity a bare `keyof AgentRegistry extends never`
+ * would trigger:
+ *
+ * - empty registry  -> `string` (today's loose behavior: any name, checked at
+ *   runtime when the workflow resolves it against `AGENT_URLS`);
+ * - augmented registry -> the union of declared agent names (typo = compile error).
+ */
+type AgentName = [keyof AgentRegistry] extends [never] ? string : keyof AgentRegistry;
+
+/**
+ * Queue-level options for a workflow trigger.
+ *
+ * NOTE: `delaySeconds` and `idempotencyKey` are typed for forward-compatibility
+ * but NOT wired in v1. The native WDK `start()` primitive (the sanctioned
+ * trigger path) does not expose queue-level delay or dedup — those live one
+ * layer down on the World's raw producer, and reaching it means re-implementing
+ * run creation against `@workflow/core` internals. Deferred to a follow-up when
+ * the WDK exposes them. Within-run idempotency already comes from `"use step"`
+ * memoization, so a step replay never double-enqueues.
+ */
+interface WorkflowTriggerOptions {
+    /** Defer the triggered start by N seconds. Reserved — not wired in v1. */
+    readonly delaySeconds?: number;
+    /** Dedup key so a retry does not start the target twice. Reserved — not wired in v1. */
+    readonly idempotencyKey?: string;
+}
+/** What a fire-and-forget trigger resolves to: the started child run's id. */
+interface WorkflowStartHandle {
+    /** The independent run id of the workflow that was started. */
+    readonly runId: string;
+}
+/**
+ * The runtime-injected bridge the trigger helpers reach. Built by the runtime on
+ * first dispatch (closing over the name→ref registry, the validators, the WDK
+ * `start` primitive, and the run projection) and planted with
+ * {@link setWorkflowStarter}.
+ */
+interface WorkflowStarter {
+    /**
+     * Fire-and-forget: resolve `name`, validate `input`, enqueue the start on the
+     * `flows` queue, and resolve with the new independent run's id. Does NOT wait
+     * for the started workflow to finish.
+     */
+    start(name: string, input: unknown, opts?: WorkflowTriggerOptions): Promise<WorkflowStartHandle>;
+    /**
+     * Durable sub-workflow: resolve `name`, validate `input`, start the run, then
+     * suspend until it reaches a terminal state and resolve with its terminal
+     * output (validated against the target's declared output schema). Backed by the
+     * WDK's native `Run.returnValue` poll-until-terminal primitive.
+     */
+    startAndWait(name: string, input: unknown, opts?: WorkflowTriggerOptions): Promise<unknown>;
+}
+/**
+ * Plant (or clear, with `undefined`) the ambient starter. The runtime calls this
+ * on first dispatch with the bridge it built; tests pass a fake. Idempotent —
+ * the last write wins.
+ */
+declare function setWorkflowStarter(starter: WorkflowStarter | undefined): void;
+/**
+ * Return the bound ambient starter, or throw a clear error when none is bound —
+ * which means a trigger helper was called OUTSIDE a running workflow (the
+ * runtime binds the starter only on first dispatch).
+ */
+declare function getWorkflowStarter(): WorkflowStarter;
+
+/** One active scheduled trigger, as `listSchedules()` reports it. */
+interface ScheduledWorkflow {
+    /** The workflow this trigger starts on each tick. */
+    readonly name: string;
+    /** The cron expression driving the cadence. */
+    readonly cron: string;
+    /** The input each tick passes to the workflow. */
+    readonly input: unknown;
+    /** `'declarative'` (harvested from the workflow, reconciled on boot) or
+     *  `'dynamic'` (registered at run time via `scheduleWorkflow`). */
+    readonly source: 'declarative' | 'dynamic';
+}
+/** The runtime-injected bridge the imperative cron helpers reach. */
+interface WorkflowScheduler {
+    /** Register (or upsert) a DYNAMIC repeatable trigger that starts `name` with
+     *  `input` on the `cron` cadence. Idempotent by `name`. */
+    schedule(name: string, input: unknown, cron: string): Promise<void>;
+    /** Cancel a dynamic trigger by `name`. Resolves whether or not one existed. */
+    unschedule(name: string): Promise<void>;
+    /** List the active triggers — declarative + dynamic. */
+    listSchedules(): Promise<ScheduledWorkflow[]>;
+}
+/** Plant (or clear, with `undefined`) the ambient scheduler. The runtime calls
+ *  this on first dispatch; tests pass a fake. Last write wins. */
+declare function setWorkflowScheduler(scheduler: WorkflowScheduler | undefined): void;
+/** Return the bound ambient scheduler, or throw a clear error when none is bound
+ *  (the imperative cron API was reached outside a running workflow runtime). */
+declare function getWorkflowScheduler(): WorkflowScheduler;
+
+export { type AgentName as A, type ScheduledWorkflow as S, type WorkflowTriggerOptions as W, type WorkflowStartHandle as a, type AgentRegistry as b, type WorkflowScheduler as c, type WorkflowStarter as d, getWorkflowStarter as e, setWorkflowStarter as f, getWorkflowScheduler as g, setWorkflowScheduler as s };