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

package/workflow.d.cts

@@ -0,0 +1,207 @@
+export { defineHook, sleep } from 'workflow';
+import { Client } from 'eve/client';
+import { A as AgentName, W as WorkflowTriggerOptions, a as WorkflowStartHandle, S as ScheduledWorkflow } from './workflow-scheduler-DXCNKDOS.cjs';
+export { b as AgentRegistry } from './workflow-scheduler-DXCNKDOS.cjs';
+import { RagIngestOutput } from '@stackbone/rag-core';
+export { RagIngestInput, RagIngestOutput } from '@stackbone/rag-core';
+export { C as CallConnectorOptions, a as ConnectionAccessor, b as ConnectorCallError, c as ConnectorHandle, P as Principal, S as StackboneConnections, d as callConnector, e as connection } from './call-connector-CYDw_yG5.cjs';
+
+/**
+ * Discriminator stored in `approvals.metadata.resumeKind` so the inbox /
+ * run-inspection knows a parked Workflow hook (resumed by token) backs this
+ * approval — as opposed to the legacy fire-and-forget HMAC-callback approval.
+ */
+declare const WORKFLOW_HOOK_RESUME_KIND: "workflow_hook";
+/** Fallback applied when the timeout elapses before a human decides. */
+type ApprovalFallback = 'approve' | 'reject';
+interface RequestApprovalOptions<TPayload = unknown> {
+    /**
+     * The hook resume key — unique per approval within a run. The host resumes the
+     * parked run by this token (`resumeHook(token, ...)`), so it must be stable
+     * and unguessable for the lifetime of the pause.
+     */
+    token: string;
+    /** Approval category, mirrored to `approvals.topic`. */
+    topic: string;
+    /** The data the human reviews, mirrored to `approvals.payload`. */
+    payload: TPayload;
+    /** Human-readable title surfaced in the inbox / run inspection. */
+    title?: string;
+    /** ISO 8601 duration (`'24h'`) or milliseconds. Passed to `sleep`. */
+    timeout?: string | number;
+    /** Decision applied when the timeout wins the race. Default `'reject'`. */
+    fallback?: ApprovalFallback;
+}
+/**
+ * The decision the gated step branches on. `status === 'approved'` is the only
+ * green light for the side-effect; `timedOut` is `true` only when the fallback
+ * was applied because no human decided before the timeout.
+ */
+interface ApprovalDecision<TPayload = unknown> {
+    status: 'approved' | 'rejected';
+    /** The payload the human attached when approving/rejecting, if any. */
+    payload?: TPayload;
+    /** `true` when this decision is the timeout fallback, not a human decision. */
+    timedOut: boolean;
+}
+/**
+ * Workflow-level HITL helper. PAUSES the workflow durably on a hook and returns
+ * a decision the caller gates the side-effect on. MUST be called from the
+ * workflow body, never inside a `"use step"` block.
+ */
+declare function requestApproval<TPayload = unknown>(options: RequestApprovalOptions<TPayload>): Promise<ApprovalDecision<TPayload>>;
+
+/**
+ * Resolve a sibling eve agent by name and return its `Client`, AS-IS. The name is
+ * the agent's folder name under `agents/`; the URL comes from the emulator-injected
+ * `AGENT_URLS` map. The `headers` resolver runs fresh per request, so every
+ * session-create and stream GET carries a current timestamp (always inside the
+ * 5-minute drift window).
+ *
+ * `name` is typed `AgentName` — a loose `string` by default, but narrowed to the
+ * workspace's declared agent names once `stackbone dev` has generated
+ * `.stackbone/agents.d.ts` from `stackbone.config.ts` (see `agent-registry.ts`),
+ * so a typo becomes a compile error and the editor autocompletes the real names.
+ *
+ * @deprecated Prefer the namespaced `stackbone.agent(id)` from the main
+ * `@stackbone/sdk` barrel — same signed call, same eve `Client`, one unified
+ * namespace, and the `eve` peer is pulled lazily only on first use. This top-level
+ * export still works and resolves the peer eagerly (it lives on the
+ * `@stackbone/sdk/workflow` subpath, which already imports the peer).
+ */
+declare function eveAgent(name: AgentName): Client;
+
+/**
+ * Augmentable registry of the workspace's WORKFLOW names. By default it is empty,
+ * so `startWorkflow(name, ...)` / `startWorkflowAndWait(name, ...)` accept any
+ * `string` (today's behavior, validated only at runtime against the injected
+ * name→ref registry). `stackbone dev` generates an ambient
+ * `.stackbone/workflows.d.ts` from the project's `stackbone.config.ts` workflow
+ * list and augments this interface so the names become a closed set:
+ *
+ *   declare module '@stackbone/sdk/workflow' {
+ *     interface WorkflowRegistry {
+ *       onboarding: true;
+ *       qualifyLead: true;
+ *     }
+ *   }
+ *
+ * Once augmented, `startWorkflow('qualifyLead', ...)` is fine and
+ * `startWorkflow('typo', ...)` is a compile error — the editor also autocompletes
+ * the declared names. Mirrors the `AgentRegistry` augmentable-interface pattern
+ * used for `eveAgent`.
+ */
+interface WorkflowRegistry {
+}
+/**
+ * The set of workflow names the trigger helpers accept, derived from the
+ * augmentable `WorkflowRegistry`. The tuple wrap (`[X] extends [never]`) defeats
+ * the conditional-type distributivity a bare `keyof WorkflowRegistry extends
+ * never` would trigger:
+ *
+ * - empty registry  -> `string` (today's loose behavior: any name, checked at
+ *   runtime when the workflow resolves it against the manifest);
+ * - augmented registry -> the union of declared workflow names (typo = compile error).
+ */
+type WorkflowName = [keyof WorkflowRegistry] extends [never] ? string : keyof WorkflowRegistry;
+
+/** Options for {@link startWorkflow}. See {@link WorkflowTriggerOptions}. */
+type StartWorkflowOptions = WorkflowTriggerOptions;
+
+/**
+ * Start the workflow named `name` with its own independent run and return its
+ * `{ runId }` immediately — fire-and-forget. The input is validated against the
+ * target's declared input schema BEFORE the run is enqueued; a name that does
+ * not resolve, or input that violates the schema, rejects without starting
+ * anything.
+ *
+ * `name` is typed `WorkflowName` — a loose `string` by default, narrowed to the
+ * workspace's declared workflow names once `stackbone dev` has generated
+ * `.stackbone/workflows.d.ts` (see `workflow-registry.ts`), so a typo becomes a
+ * compile error.
+ *
+ * MUST be called from inside a running workflow (the runtime binds the starter on
+ * first dispatch); calling it elsewhere throws.
+ *
+ * DURABILITY: the enqueue runs in a `"use step"`, so once it completes a parent
+ * restart resumes with the memoized `{ runId }` and does NOT re-enqueue. A crash
+ * WHILE the step is mid-flight re-runs it (at-least-once) — the same shape the
+ * eve-agent-from-step path has; for fire-and-forget fan-out this is acceptable.
+ * Use {@link startWorkflowAndWait} when you need the child's result.
+ */
+declare function startWorkflow(name: WorkflowName, input: unknown, opts?: StartWorkflowOptions): Promise<WorkflowStartHandle>;
+
+/** Options for {@link startWorkflowAndWait}. See {@link WorkflowTriggerOptions}. */
+type StartWorkflowAndWaitOptions = WorkflowTriggerOptions;
+/**
+ * Start the workflow named `name` with its own independent run and durably wait
+ * for it to finish, returning its terminal output (validated against the
+ * target's declared output schema). Use this when one workflow needs another's
+ * result to continue.
+ *
+ * The input is validated against the target's declared input schema BEFORE the
+ * run is enqueued; a name that does not resolve, or input that violates the
+ * schema, rejects without starting anything. `TOutput` lets the caller name the
+ * expected output shape (defaults to `unknown`).
+ *
+ * `name` is typed `WorkflowName` — narrowed to the workspace's declared workflow
+ * names once `stackbone dev` has generated `.stackbone/workflows.d.ts`. MUST be
+ * called from inside a running workflow.
+ */
+declare function startWorkflowAndWait<TOutput = unknown>(name: WorkflowName, input: unknown, opts?: StartWorkflowAndWaitOptions): Promise<TOutput>;
+
+/** Content the helper stages on the caller's behalf (text or raw bytes). */
+type IngestContent = string | Uint8Array;
+/** The two input shapes {@link ingestDocuments} accepts. */
+type IngestDocumentsArgs = {
+    collection: string;
+    contentType: string;
+    /** Inline content to stage + ingest. Mutually exclusive with `storageKey`. */
+    content: IngestContent;
+    storageKey?: never;
+} | {
+    collection: string;
+    contentType: string;
+    /** A pre-staged original under the `rag/` prefix. Mutually exclusive with `content`. */
+    storageKey: string;
+    content?: never;
+};
+/** Options for {@link ingestDocuments}. */
+interface IngestDocumentsOptions {
+    /**
+     * @internal Test seam — override how inline content is staged to storage,
+     * returning the resulting storage key. Production callers omit it (the default
+     * stages through the ambient `stackbone.storage`).
+     */
+    stage?: (collection: string, content: IngestContent, contentType: string) => Promise<string>;
+}
+/**
+ * Ingest a document into RAG by running the reserved `rag-ingest` workflow as a
+ * durable sub-workflow, returning its `{ documentId, chunks }` output. Pass
+ * `content` to have the helper stage it for you, or `storageKey` when it is
+ * already staged. The workflow input is validated against the well-known contract
+ * before triggering; an invalid call rejects without starting anything.
+ */
+declare function ingestDocuments(args: IngestDocumentsArgs, opts?: IngestDocumentsOptions): Promise<RagIngestOutput>;
+
+/**
+ * Register (or upsert) a dynamic recurring trigger that starts the workflow named
+ * `name` with `input` on the `cron` cadence. Idempotent by `name` — calling it
+ * again replaces the cadence/input. `name` is narrowed to the workspace's
+ * declared workflows once `stackbone dev` has generated `.stackbone/workflows.d.ts`.
+ */
+declare function scheduleWorkflow(name: WorkflowName, input: unknown, cron: string): Promise<void>;
+/**
+ * Cancel a dynamic scheduled trigger by `name`. Resolves whether or not a trigger
+ * existed. Does not touch declarative schedules (those are owned by the workflow's
+ * `export const schedules` and reconciled on deploy/boot).
+ */
+declare function unschedule(name: WorkflowName): Promise<void>;
+/**
+ * List the active scheduled triggers — both declarative (harvested from workflows)
+ * and dynamic (registered via {@link scheduleWorkflow}) — so an operator can see
+ * what recurring work is registered.
+ */
+declare function listSchedules(): Promise<ScheduledWorkflow[]>;
+
+export { type ApprovalDecision, type ApprovalFallback, type IngestContent, type IngestDocumentsArgs, type IngestDocumentsOptions, type RequestApprovalOptions, ScheduledWorkflow, type StartWorkflowAndWaitOptions, type StartWorkflowOptions, WORKFLOW_HOOK_RESUME_KIND, type WorkflowName, type WorkflowRegistry, WorkflowStartHandle, eveAgent, ingestDocuments, listSchedules, requestApproval, scheduleWorkflow, startWorkflow, startWorkflowAndWait, unschedule };

package/workflow.d.ts

@@ -0,0 +1,207 @@
+export { defineHook, sleep } from 'workflow';
+import { Client } from 'eve/client';
+import { A as AgentName, W as WorkflowTriggerOptions, a as WorkflowStartHandle, S as ScheduledWorkflow } from './workflow-scheduler-DXCNKDOS.js';
+export { b as AgentRegistry } from './workflow-scheduler-DXCNKDOS.js';
+import { RagIngestOutput } from '@stackbone/rag-core';
+export { RagIngestInput, RagIngestOutput } from '@stackbone/rag-core';
+export { C as CallConnectorOptions, a as ConnectionAccessor, b as ConnectorCallError, c as ConnectorHandle, P as Principal, S as StackboneConnections, d as callConnector, e as connection } from './call-connector-CYDw_yG5.js';
+
+/**
+ * Discriminator stored in `approvals.metadata.resumeKind` so the inbox /
+ * run-inspection knows a parked Workflow hook (resumed by token) backs this
+ * approval — as opposed to the legacy fire-and-forget HMAC-callback approval.
+ */
+declare const WORKFLOW_HOOK_RESUME_KIND: "workflow_hook";
+/** Fallback applied when the timeout elapses before a human decides. */
+type ApprovalFallback = 'approve' | 'reject';
+interface RequestApprovalOptions<TPayload = unknown> {
+    /**
+     * The hook resume key — unique per approval within a run. The host resumes the
+     * parked run by this token (`resumeHook(token, ...)`), so it must be stable
+     * and unguessable for the lifetime of the pause.
+     */
+    token: string;
+    /** Approval category, mirrored to `approvals.topic`. */
+    topic: string;
+    /** The data the human reviews, mirrored to `approvals.payload`. */
+    payload: TPayload;
+    /** Human-readable title surfaced in the inbox / run inspection. */
+    title?: string;
+    /** ISO 8601 duration (`'24h'`) or milliseconds. Passed to `sleep`. */
+    timeout?: string | number;
+    /** Decision applied when the timeout wins the race. Default `'reject'`. */
+    fallback?: ApprovalFallback;
+}
+/**
+ * The decision the gated step branches on. `status === 'approved'` is the only
+ * green light for the side-effect; `timedOut` is `true` only when the fallback
+ * was applied because no human decided before the timeout.
+ */
+interface ApprovalDecision<TPayload = unknown> {
+    status: 'approved' | 'rejected';
+    /** The payload the human attached when approving/rejecting, if any. */
+    payload?: TPayload;
+    /** `true` when this decision is the timeout fallback, not a human decision. */
+    timedOut: boolean;
+}
+/**
+ * Workflow-level HITL helper. PAUSES the workflow durably on a hook and returns
+ * a decision the caller gates the side-effect on. MUST be called from the
+ * workflow body, never inside a `"use step"` block.
+ */
+declare function requestApproval<TPayload = unknown>(options: RequestApprovalOptions<TPayload>): Promise<ApprovalDecision<TPayload>>;
+
+/**
+ * Resolve a sibling eve agent by name and return its `Client`, AS-IS. The name is
+ * the agent's folder name under `agents/`; the URL comes from the emulator-injected
+ * `AGENT_URLS` map. The `headers` resolver runs fresh per request, so every
+ * session-create and stream GET carries a current timestamp (always inside the
+ * 5-minute drift window).
+ *
+ * `name` is typed `AgentName` — a loose `string` by default, but narrowed to the
+ * workspace's declared agent names once `stackbone dev` has generated
+ * `.stackbone/agents.d.ts` from `stackbone.config.ts` (see `agent-registry.ts`),
+ * so a typo becomes a compile error and the editor autocompletes the real names.
+ *
+ * @deprecated Prefer the namespaced `stackbone.agent(id)` from the main
+ * `@stackbone/sdk` barrel — same signed call, same eve `Client`, one unified
+ * namespace, and the `eve` peer is pulled lazily only on first use. This top-level
+ * export still works and resolves the peer eagerly (it lives on the
+ * `@stackbone/sdk/workflow` subpath, which already imports the peer).
+ */
+declare function eveAgent(name: AgentName): Client;
+
+/**
+ * Augmentable registry of the workspace's WORKFLOW names. By default it is empty,
+ * so `startWorkflow(name, ...)` / `startWorkflowAndWait(name, ...)` accept any
+ * `string` (today's behavior, validated only at runtime against the injected
+ * name→ref registry). `stackbone dev` generates an ambient
+ * `.stackbone/workflows.d.ts` from the project's `stackbone.config.ts` workflow
+ * list and augments this interface so the names become a closed set:
+ *
+ *   declare module '@stackbone/sdk/workflow' {
+ *     interface WorkflowRegistry {
+ *       onboarding: true;
+ *       qualifyLead: true;
+ *     }
+ *   }
+ *
+ * Once augmented, `startWorkflow('qualifyLead', ...)` is fine and
+ * `startWorkflow('typo', ...)` is a compile error — the editor also autocompletes
+ * the declared names. Mirrors the `AgentRegistry` augmentable-interface pattern
+ * used for `eveAgent`.
+ */
+interface WorkflowRegistry {
+}
+/**
+ * The set of workflow names the trigger helpers accept, derived from the
+ * augmentable `WorkflowRegistry`. The tuple wrap (`[X] extends [never]`) defeats
+ * the conditional-type distributivity a bare `keyof WorkflowRegistry extends
+ * never` would trigger:
+ *
+ * - empty registry  -> `string` (today's loose behavior: any name, checked at
+ *   runtime when the workflow resolves it against the manifest);
+ * - augmented registry -> the union of declared workflow names (typo = compile error).
+ */
+type WorkflowName = [keyof WorkflowRegistry] extends [never] ? string : keyof WorkflowRegistry;
+
+/** Options for {@link startWorkflow}. See {@link WorkflowTriggerOptions}. */
+type StartWorkflowOptions = WorkflowTriggerOptions;
+
+/**
+ * Start the workflow named `name` with its own independent run and return its
+ * `{ runId }` immediately — fire-and-forget. The input is validated against the
+ * target's declared input schema BEFORE the run is enqueued; a name that does
+ * not resolve, or input that violates the schema, rejects without starting
+ * anything.
+ *
+ * `name` is typed `WorkflowName` — a loose `string` by default, narrowed to the
+ * workspace's declared workflow names once `stackbone dev` has generated
+ * `.stackbone/workflows.d.ts` (see `workflow-registry.ts`), so a typo becomes a
+ * compile error.
+ *
+ * MUST be called from inside a running workflow (the runtime binds the starter on
+ * first dispatch); calling it elsewhere throws.
+ *
+ * DURABILITY: the enqueue runs in a `"use step"`, so once it completes a parent
+ * restart resumes with the memoized `{ runId }` and does NOT re-enqueue. A crash
+ * WHILE the step is mid-flight re-runs it (at-least-once) — the same shape the
+ * eve-agent-from-step path has; for fire-and-forget fan-out this is acceptable.
+ * Use {@link startWorkflowAndWait} when you need the child's result.
+ */
+declare function startWorkflow(name: WorkflowName, input: unknown, opts?: StartWorkflowOptions): Promise<WorkflowStartHandle>;
+
+/** Options for {@link startWorkflowAndWait}. See {@link WorkflowTriggerOptions}. */
+type StartWorkflowAndWaitOptions = WorkflowTriggerOptions;
+/**
+ * Start the workflow named `name` with its own independent run and durably wait
+ * for it to finish, returning its terminal output (validated against the
+ * target's declared output schema). Use this when one workflow needs another's
+ * result to continue.
+ *
+ * The input is validated against the target's declared input schema BEFORE the
+ * run is enqueued; a name that does not resolve, or input that violates the
+ * schema, rejects without starting anything. `TOutput` lets the caller name the
+ * expected output shape (defaults to `unknown`).
+ *
+ * `name` is typed `WorkflowName` — narrowed to the workspace's declared workflow
+ * names once `stackbone dev` has generated `.stackbone/workflows.d.ts`. MUST be
+ * called from inside a running workflow.
+ */
+declare function startWorkflowAndWait<TOutput = unknown>(name: WorkflowName, input: unknown, opts?: StartWorkflowAndWaitOptions): Promise<TOutput>;
+
+/** Content the helper stages on the caller's behalf (text or raw bytes). */
+type IngestContent = string | Uint8Array;
+/** The two input shapes {@link ingestDocuments} accepts. */
+type IngestDocumentsArgs = {
+    collection: string;
+    contentType: string;
+    /** Inline content to stage + ingest. Mutually exclusive with `storageKey`. */
+    content: IngestContent;
+    storageKey?: never;
+} | {
+    collection: string;
+    contentType: string;
+    /** A pre-staged original under the `rag/` prefix. Mutually exclusive with `content`. */
+    storageKey: string;
+    content?: never;
+};
+/** Options for {@link ingestDocuments}. */
+interface IngestDocumentsOptions {
+    /**
+     * @internal Test seam — override how inline content is staged to storage,
+     * returning the resulting storage key. Production callers omit it (the default
+     * stages through the ambient `stackbone.storage`).
+     */
+    stage?: (collection: string, content: IngestContent, contentType: string) => Promise<string>;
+}
+/**
+ * Ingest a document into RAG by running the reserved `rag-ingest` workflow as a
+ * durable sub-workflow, returning its `{ documentId, chunks }` output. Pass
+ * `content` to have the helper stage it for you, or `storageKey` when it is
+ * already staged. The workflow input is validated against the well-known contract
+ * before triggering; an invalid call rejects without starting anything.
+ */
+declare function ingestDocuments(args: IngestDocumentsArgs, opts?: IngestDocumentsOptions): Promise<RagIngestOutput>;
+
+/**
+ * Register (or upsert) a dynamic recurring trigger that starts the workflow named
+ * `name` with `input` on the `cron` cadence. Idempotent by `name` — calling it
+ * again replaces the cadence/input. `name` is narrowed to the workspace's
+ * declared workflows once `stackbone dev` has generated `.stackbone/workflows.d.ts`.
+ */
+declare function scheduleWorkflow(name: WorkflowName, input: unknown, cron: string): Promise<void>;
+/**
+ * Cancel a dynamic scheduled trigger by `name`. Resolves whether or not a trigger
+ * existed. Does not touch declarative schedules (those are owned by the workflow's
+ * `export const schedules` and reconciled on deploy/boot).
+ */
+declare function unschedule(name: WorkflowName): Promise<void>;
+/**
+ * List the active scheduled triggers — both declarative (harvested from workflows)
+ * and dynamic (registered via {@link scheduleWorkflow}) — so an operator can see
+ * what recurring work is registered.
+ */
+declare function listSchedules(): Promise<ScheduledWorkflow[]>;
+
+export { type ApprovalDecision, type ApprovalFallback, type IngestContent, type IngestDocumentsArgs, type IngestDocumentsOptions, type RequestApprovalOptions, ScheduledWorkflow, type StartWorkflowAndWaitOptions, type StartWorkflowOptions, WORKFLOW_HOOK_RESUME_KIND, type WorkflowName, type WorkflowRegistry, WorkflowStartHandle, eveAgent, ingestDocuments, listSchedules, requestApproval, scheduleWorkflow, startWorkflow, startWorkflowAndWait, unschedule };