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

package/agent-registry-BNXuj88Q.d.cts

@@ -0,0 +1,198 @@
+/** 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;
+
+/**
+ * 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;
+
+/**
+ * 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>;
+
+/**
+ * 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;
+
+export { type AgentName as A, type ScheduledWorkflow as S, type WorkflowName as W, type AgentRegistry as a, type StartWorkflowAndWaitOptions as b, type StartWorkflowOptions as c, type WorkflowRegistry as d, type WorkflowStartHandle as e, startWorkflowAndWait as f, type WorkflowScheduler as g, type WorkflowStarter as h, type WorkflowTriggerOptions as i, getWorkflowScheduler as j, getWorkflowStarter as k, setWorkflowScheduler as l, setWorkflowStarter as m, startWorkflow as s };

package/agent-registry-BNXuj88Q.d.ts

@@ -0,0 +1,198 @@
+/** 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;
+
+/**
+ * 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;
+
+/**
+ * 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>;
+
+/**
+ * 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;
+
+export { type AgentName as A, type ScheduledWorkflow as S, type WorkflowName as W, type AgentRegistry as a, type StartWorkflowAndWaitOptions as b, type StartWorkflowOptions as c, type WorkflowRegistry as d, type WorkflowStartHandle as e, startWorkflowAndWait as f, type WorkflowScheduler as g, type WorkflowStarter as h, type WorkflowTriggerOptions as i, getWorkflowScheduler as j, getWorkflowStarter as k, setWorkflowScheduler as l, setWorkflowStarter as m, startWorkflow as s };

package/call-connector-CYDw_yG5.d.cts

@@ -0,0 +1,118 @@
+/**
+ * WHO a connector call is made on behalf of — the scoping principal the broker
+ * keys its credential cache/grant against. A STRUCTURAL mirror of the broker
+ * contract's `@stackbone/connect-contract` `Principal` union (app / user /
+ * client-credentials / jwt-bearer); defined locally rather than imported so the
+ * SDK connect surface stays a self-contained leaf (the sibling eve adapter follows
+ * the same discipline — it never pulls the platform contract into the published
+ * SDK tarball). It is structurally compatible, so a value typed against the
+ * contract's `Principal` is assignable here and vice-versa.
+ */
+type Principal = {
+    readonly type: 'app';
+} | {
+    readonly type: 'user';
+    readonly id: string;
+    readonly issuer: string;
+    readonly attributes?: Readonly<Record<string, string | readonly string[]>>;
+} | {
+    readonly type: 'client-credentials';
+    readonly serviceAccountId: string;
+} | {
+    readonly type: 'jwt-bearer';
+    readonly subject: string;
+    readonly issuer: string;
+};
+
+/** Options accepted by `callConnector` / `connection(...).call`. */
+interface CallConnectorOptions {
+    /**
+     * WHO the connector call is made on behalf of. Defaults to `{ type: 'app' }`
+     * (the agent's own service-account credential). A `user` principal scopes the
+     * broker token issuer to that end user; `client-credentials` / `jwt-bearer` are
+     * the broker's M2M auth modes.
+     */
+    readonly principal?: Principal;
+}
+/**
+ * An `Error` carrying the broker's machine-readable `code` so a workflow matches
+ * the failure BY CODE STRING (never `instanceof` — under bundling the SDK and the
+ * workflow can hold different class identities; the code is the stable signal).
+ */
+interface ConnectorCallError extends Error {
+    /** The broker error code (`invalid_args`, `credential_error`, `timeout`, …). */
+    readonly code: string;
+}
+/**
+ * Call a Stackbone Connect connector operation directly from a workflow.
+ *
+ * POSTs `{ connector, operation, args, principal, installationId }` to the
+ * agent-facing broker (`POST /api/connect/execute`) with HMAC scheme-A headers.
+ * On `{ ok: true, output }` it returns the operation `output`; on
+ * `{ ok: false, error }` (or any non-2xx) it THROWS a `ConnectorCallError` whose
+ * `.code` is the broker error code and `.message` the broker message.
+ *
+ * ```ts
+ * const channels = await callConnector('slack', 'conversations.list');
+ * await callConnector('slack', 'chat.postMessage', { channel: 'C123', text: 'hi' });
+ * ```
+ *
+ * @param connector The connect connector id registered in Studio.
+ * @param operation The operation / tool id to run on that connector.
+ * @param args      The operation arguments (path/query/body params). Defaults `{}`.
+ * @param opts      Optional `{ principal }` — defaults to `{ type: 'app' }`.
+ */
+declare function callConnector(connector: string, operation: string, args?: Readonly<Record<string, unknown>>, opts?: CallConnectorOptions): Promise<unknown>;
+/** The dynamic escape hatch present on every `connection(id)` handle. */
+interface ConnectorHandle {
+    /**
+     * Run ANY operation on this connector by id — the untyped escape hatch, always
+     * available (use it for an operation id that is not a JS identifier, e.g. a
+     * dotted `chat.postMessage`, or a connector with no generated types). Sugar for
+     * `callConnector(id, operation, args, opts)`.
+     */
+    call(operation: string, args?: Readonly<Record<string, unknown>>, opts?: CallConnectorOptions): Promise<unknown>;
+}
+/**
+ * Augmentable registry of TYPED connector operations, keyed by the VERBATIM
+ * connector id (`'stub-mail'`, `'slack'`). The Stackbone Connect type generator
+ * (`stackbone dev` writes `.stackbone/connect.d.ts`) MERGES one member per connector
+ * into this interface via a `declare module` augmentation, each a map of the
+ * connector's operations → typed `(args) => Promise<output>`, derived from the
+ * introspected JSON Schema. Empty by default — with no generated types,
+ * `connection(id)` offers only the dynamic `.call(...)`.
+ *
+ * Same id-keyed-registry mechanism as `eveAgent`'s `AgentRegistry`: the selection
+ * style is unified — address an entity by its verbatim id, get a typed handle.
+ */
+interface StackboneConnections {
+}
+/**
+ * The typed handle for a connector id: its generated operations (when the id is a
+ * known key of `StackboneConnections`) intersected with the dynamic `.call` escape
+ * hatch (always present). An unknown id resolves to just `ConnectorHandle`.
+ */
+type ConnectorOf<Id extends string> = (Id extends keyof StackboneConnections ? StackboneConnections[Id] : unknown) & ConnectorHandle;
+/**
+ * The exported `connection`: select a connector by its verbatim id and get a typed
+ * handle. A known id (a key of the generated `StackboneConnections`) yields its
+ * typed operations + `.call`; any other string yields the dynamic `ConnectorHandle`.
+ */
+interface ConnectionAccessor {
+    <Id extends keyof StackboneConnections>(id: Id): ConnectorOf<Id>;
+    (id: string): ConnectorHandle;
+}
+/**
+ * Call Stackbone Connect connectors. Select by verbatim id, then call an operation —
+ * typed when `.stackbone/connect.d.ts` is generated, dynamic via `.call` always:
+ *
+ * ```ts
+ * await connection('stub-mail').sendMail({ to, subject, body }); // typed
+ * await connection('slack').call('chat.postMessage', { ... });   // dynamic escape hatch
+ * ```
+ *
+ * Mirrors `eveAgent('agent-name')`: one id-keyed selection style across the SDK.
+ */
+declare const connection: ConnectionAccessor;
+
+export { type CallConnectorOptions as C, type Principal as P, type StackboneConnections as S, type ConnectionAccessor as a, type ConnectorCallError as b, type ConnectorHandle as c, callConnector as d, connection as e };

package/call-connector-CYDw_yG5.d.ts

@@ -0,0 +1,118 @@
+/**
+ * WHO a connector call is made on behalf of — the scoping principal the broker
+ * keys its credential cache/grant against. A STRUCTURAL mirror of the broker
+ * contract's `@stackbone/connect-contract` `Principal` union (app / user /
+ * client-credentials / jwt-bearer); defined locally rather than imported so the
+ * SDK connect surface stays a self-contained leaf (the sibling eve adapter follows
+ * the same discipline — it never pulls the platform contract into the published
+ * SDK tarball). It is structurally compatible, so a value typed against the
+ * contract's `Principal` is assignable here and vice-versa.
+ */
+type Principal = {
+    readonly type: 'app';
+} | {
+    readonly type: 'user';
+    readonly id: string;
+    readonly issuer: string;
+    readonly attributes?: Readonly<Record<string, string | readonly string[]>>;
+} | {
+    readonly type: 'client-credentials';
+    readonly serviceAccountId: string;
+} | {
+    readonly type: 'jwt-bearer';
+    readonly subject: string;
+    readonly issuer: string;
+};
+
+/** Options accepted by `callConnector` / `connection(...).call`. */
+interface CallConnectorOptions {
+    /**
+     * WHO the connector call is made on behalf of. Defaults to `{ type: 'app' }`
+     * (the agent's own service-account credential). A `user` principal scopes the
+     * broker token issuer to that end user; `client-credentials` / `jwt-bearer` are
+     * the broker's M2M auth modes.
+     */
+    readonly principal?: Principal;
+}
+/**
+ * An `Error` carrying the broker's machine-readable `code` so a workflow matches
+ * the failure BY CODE STRING (never `instanceof` — under bundling the SDK and the
+ * workflow can hold different class identities; the code is the stable signal).
+ */
+interface ConnectorCallError extends Error {
+    /** The broker error code (`invalid_args`, `credential_error`, `timeout`, …). */
+    readonly code: string;
+}
+/**
+ * Call a Stackbone Connect connector operation directly from a workflow.
+ *
+ * POSTs `{ connector, operation, args, principal, installationId }` to the
+ * agent-facing broker (`POST /api/connect/execute`) with HMAC scheme-A headers.
+ * On `{ ok: true, output }` it returns the operation `output`; on
+ * `{ ok: false, error }` (or any non-2xx) it THROWS a `ConnectorCallError` whose
+ * `.code` is the broker error code and `.message` the broker message.
+ *
+ * ```ts
+ * const channels = await callConnector('slack', 'conversations.list');
+ * await callConnector('slack', 'chat.postMessage', { channel: 'C123', text: 'hi' });
+ * ```
+ *
+ * @param connector The connect connector id registered in Studio.
+ * @param operation The operation / tool id to run on that connector.
+ * @param args      The operation arguments (path/query/body params). Defaults `{}`.
+ * @param opts      Optional `{ principal }` — defaults to `{ type: 'app' }`.
+ */
+declare function callConnector(connector: string, operation: string, args?: Readonly<Record<string, unknown>>, opts?: CallConnectorOptions): Promise<unknown>;
+/** The dynamic escape hatch present on every `connection(id)` handle. */
+interface ConnectorHandle {
+    /**
+     * Run ANY operation on this connector by id — the untyped escape hatch, always
+     * available (use it for an operation id that is not a JS identifier, e.g. a
+     * dotted `chat.postMessage`, or a connector with no generated types). Sugar for
+     * `callConnector(id, operation, args, opts)`.
+     */
+    call(operation: string, args?: Readonly<Record<string, unknown>>, opts?: CallConnectorOptions): Promise<unknown>;
+}
+/**
+ * Augmentable registry of TYPED connector operations, keyed by the VERBATIM
+ * connector id (`'stub-mail'`, `'slack'`). The Stackbone Connect type generator
+ * (`stackbone dev` writes `.stackbone/connect.d.ts`) MERGES one member per connector
+ * into this interface via a `declare module` augmentation, each a map of the
+ * connector's operations → typed `(args) => Promise<output>`, derived from the
+ * introspected JSON Schema. Empty by default — with no generated types,
+ * `connection(id)` offers only the dynamic `.call(...)`.
+ *
+ * Same id-keyed-registry mechanism as `eveAgent`'s `AgentRegistry`: the selection
+ * style is unified — address an entity by its verbatim id, get a typed handle.
+ */
+interface StackboneConnections {
+}
+/**
+ * The typed handle for a connector id: its generated operations (when the id is a
+ * known key of `StackboneConnections`) intersected with the dynamic `.call` escape
+ * hatch (always present). An unknown id resolves to just `ConnectorHandle`.
+ */
+type ConnectorOf<Id extends string> = (Id extends keyof StackboneConnections ? StackboneConnections[Id] : unknown) & ConnectorHandle;
+/**
+ * The exported `connection`: select a connector by its verbatim id and get a typed
+ * handle. A known id (a key of the generated `StackboneConnections`) yields its
+ * typed operations + `.call`; any other string yields the dynamic `ConnectorHandle`.
+ */
+interface ConnectionAccessor {
+    <Id extends keyof StackboneConnections>(id: Id): ConnectorOf<Id>;
+    (id: string): ConnectorHandle;
+}
+/**
+ * Call Stackbone Connect connectors. Select by verbatim id, then call an operation —
+ * typed when `.stackbone/connect.d.ts` is generated, dynamic via `.call` always:
+ *
+ * ```ts
+ * await connection('stub-mail').sendMail({ to, subject, body }); // typed
+ * await connection('slack').call('chat.postMessage', { ... });   // dynamic escape hatch
+ * ```
+ *
+ * Mirrors `eveAgent('agent-name')`: one id-keyed selection style across the SDK.
+ */
+declare const connection: ConnectionAccessor;
+
+export { type CallConnectorOptions as C, type Principal as P, type StackboneConnections as S, type ConnectionAccessor as a, type ConnectorCallError as b, type ConnectorHandle as c, callConnector as d, connection as e };