@stackbone/sdk 0.1.0-alpha.6 → 0.1.0-alpha.8

package/workflow.d.cts

@@ -0,0 +1,128 @@
+export { defineHook, sleep } from 'workflow';
+import { Client } from 'eve/client';
+import { A as AgentName, S as ScheduledWorkflow, W as WorkflowName } from './agent-registry-BNXuj88Q.cjs';
+export { a as AgentRegistry, b as StartWorkflowAndWaitOptions, c as StartWorkflowOptions, d as WorkflowRegistry, e as WorkflowStartHandle, s as startWorkflow, f as startWorkflowAndWait } from './agent-registry-BNXuj88Q.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;
+
+/** 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, WORKFLOW_HOOK_RESUME_KIND, WorkflowName, eveAgent, ingestDocuments, listSchedules, requestApproval, scheduleWorkflow, unschedule };

package/workflow.d.ts

@@ -0,0 +1,128 @@
+export { defineHook, sleep } from 'workflow';
+import { Client } from 'eve/client';
+import { A as AgentName, S as ScheduledWorkflow, W as WorkflowName } from './agent-registry-BNXuj88Q.js';
+export { a as AgentRegistry, b as StartWorkflowAndWaitOptions, c as StartWorkflowOptions, d as WorkflowRegistry, e as WorkflowStartHandle, s as startWorkflow, f as startWorkflowAndWait } from './agent-registry-BNXuj88Q.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;
+
+/** 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, WORKFLOW_HOOK_RESUME_KIND, WorkflowName, eveAgent, ingestDocuments, listSchedules, requestApproval, scheduleWorkflow, unschedule };