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

package/index.d.ts

@@ -1,4 +1,4 @@
-import { PublishJobResponse, ScheduleJobResponse, UnscheduleJobResponse, ListSchedulesResponse, ContractResponse } from '@stackbone/validators';
+import { AgentConnectionListResponse, InvokeConnectorActionResponse, PublishJobResponse, ScheduleJobResponse, UnscheduleJobResponse, ListSchedulesResponse, ContractResponse } from '@stackbone/validators';
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import { Sql } from 'postgres';
 import { IngestJobWriter, IngestRequest, IngestResponse, RagIngestProgress, DeleteOptions, DeleteResponse, RetrieveRequest, RetrieveHit, ChunkOptions, ParseInput, ParseOptions } from '@stackbone/rag-core';
@@ -267,6 +267,18 @@ declare const SDK_ERROR_CODE_PREFIXES: {
      * only calls these endpoints.
      */
     readonly queues: readonly ["forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
+    /**
+     * `client.connections` — the agent → control plane connectors proxy. Both
+     * methods (`list`, `invoke`) hit the `/api/v1/agent/connections/*` endpoints
+     * over `HttpClient`, so the full status→domain remap (`connections_unauthorized`,
+     * `connections_not_found`, `connections_unavailable`, …) is in play. The agent
+     * never holds a credential — it only calls these endpoints; the control plane
+     * resolves the workspace connection and runs the connector action. `ambiguous`
+     * is the 409 the proxy returns when the workspace holds several connections of
+     * the same connector and `invoke` carried no `{ connection }` selector to pick
+     * one — the error message lists the candidate names/ids so the author can.
+     */
+    readonly connections: readonly ["ambiguous", "forbidden", "invalid_request", "invalid_response", "not_found", "rate_limited", "timeout", "unauthorized", "unavailable"];
     /**
      * `client.prompts` — AGENT-LOCAL facade. Reads
      * `stackbone_platform.prompts` / `prompt_versions` over the shared
@@ -1180,124 +1192,6 @@ declare class StorageBucket {
     private resolve;
 }
 
-/**
- * Where a memory lives. Default `'user'`. `'session'` is short-lived and
- * collapsed (or dropped) by `endSession()`; `'agent'` is shared across every
- * user of the agent.
- */
-type MemoryScope = 'user' | 'session' | 'agent';
-/**
- * Either raw text or an OpenAI-shaped conversation. The future mem0 backend
- * accepts both: strings ingest verbatim, message arrays are summarised into
- * one or more facts.
- */
-type MemoryContent = string | ChatCompletionMessageParam[];
-interface AddMemoryRequest {
-    userId: string;
-    /** Conversation/session bucket. Required when `scope: 'session'`. */
-    sessionId?: string;
-    /** Default `'user'`. */
-    scope?: MemoryScope;
-    metadata?: Record<string, unknown>;
-}
-interface MemoryItem {
-    id: string;
-    content: string;
-    userId: string;
-    sessionId?: string;
-    scope: MemoryScope;
-    metadata?: Record<string, unknown>;
-    /** ISO 8601 UTC timestamp. */
-    createdAt: string;
-    updatedAt: string;
-}
-interface SearchMemoryOptions {
-    userId?: string;
-    sessionId?: string;
-    /** 1..100. Default 10. */
-    limit?: number;
-    /** Minimum cosine similarity in [0, 1]. Hits below this are dropped. */
-    threshold?: number;
-    /** Metadata predicates AND-ed to the semantic match. */
-    filters?: Record<string, unknown>;
-    /** Restrict the search to a subset of scopes. Default: every scope. */
-    includeScopes?: readonly MemoryScope[];
-}
-interface MemoryHit extends MemoryItem {
-    /** Cosine similarity in [0, 1]. */
-    score: number;
-}
-interface ListMemoryRequest {
-    userId: string;
-    /** 1..100. Default 50. */
-    limit?: number;
-    cursor?: string;
-}
-interface ListMemoryResult {
-    items: readonly MemoryItem[];
-    nextCursor?: string;
-}
-interface UpdateMemoryOptions {
-    content?: string;
-    /** Shallow-merged onto the existing metadata (mem0 semantics). */
-    metadata?: Record<string, unknown>;
-}
-interface DeleteAllMemoryRequest {
-    userId: string;
-}
-type MemoryHistoryEvent = 'created' | 'updated' | 'accessed' | 'deleted';
-interface MemoryHistoryEntry {
-    id: string;
-    memoryId: string;
-    event: MemoryHistoryEvent;
-    /** ISO 8601 UTC timestamp. */
-    at: string;
-    /** Identifier of who triggered the event (user id, agent id, etc.). */
-    actor?: string;
-    /** Content snapshot before the event. Only set for `updated`/`deleted`. */
-    before?: string;
-    /** Content snapshot after the event. Only set for `created`/`updated`. */
-    after?: string;
-    metadata?: Record<string, unknown>;
-}
-interface EndSessionOptions {
-    /** Persist session-scoped facts to long-term (`'user'`) memory before closing. Default `true`. */
-    persist?: boolean;
-}
-interface EndSessionResult {
-    sessionId: string;
-    /** Number of session memories promoted to long-term storage. `0` when `persist: false`. */
-    persisted: number;
-}
-/**
- * `client.memory` — long-term memory for the agent. The first iteration is a
- * scaffolding placeholder: every method returns `not_implemented`. The real
- * backend will be mem0 (`mem0ApiKey` / `MEM0_API_KEY`) and the public surface
- * defined here is the contract callers can already type against.
- *
- * Contract gating: not gated. Memory targets mem0 (a non-Stackbone partner),
- * so there is no Stackbone Agent Protocol capability to assert against. No
- * entry in `MODULE_CAPABILITIES` per the rule documented in
- * `contract/capability-registry.ts`. When/if the runtime moves to a
- * Stackbone-served backend we add the capability and wire the gate.
- */
-declare class MemoryModule {
-    constructor(_resolved: ResolvedConfig);
-    add(_content: MemoryContent, _request: AddMemoryRequest): Promise<Result<MemoryItem>>;
-    search(_query: string, _options?: SearchMemoryOptions): Promise<Result<readonly MemoryHit[]>>;
-    delete(_memoryId: string): Promise<Result<{
-        id: string;
-    }>>;
-    deleteAll(_request: DeleteAllMemoryRequest): Promise<Result<{
-        deleted: number;
-    }>>;
-    get(_memoryId: string): Promise<Result<MemoryItem>>;
-    list(_request: ListMemoryRequest): Promise<Result<ListMemoryResult>>;
-    update(_memoryId: string, _options: UpdateMemoryOptions): Promise<Result<MemoryItem>>;
-    history(_memoryId: string): Promise<Result<readonly MemoryHistoryEntry[]>>;
-    endSession(_sessionId: string, _options?: EndSessionOptions): Promise<Result<EndSessionResult>>;
-}
-
 /** Subset of `RequestInit['body']` we serialize without modification. */
 type SerializedBody = NonNullable<RequestInit['body']>;
 /**
@@ -1432,6 +1326,176 @@ declare class HttpClient {
     private computeBackoff;
 }
 
+/** Options for `invoke`. */
+interface InvokeOptions {
+    /**
+     * Selector to disambiguate when the workspace holds several connections of the
+     * same connector. Accepts a connection **id** or a unique **name** (both are
+     * returned by `list()`). Omitted → the proxy resolves the sole connection, or
+     * fails `connections_ambiguous` when there is more than one.
+     */
+    connection?: string;
+}
+/**
+ * `client.connections` — the agent's handle on the workspace's connector
+ * connections. The credentials never enter the agent container: each method
+ * makes an authenticated call to the control plane (the connector executor owns
+ * the resolved credential, in a platform process).
+ *
+ * - `list` returns the workspace's connections (connector id, label, auth kind,
+ *   health) — never any credential material — so the agent can adapt to what the
+ *   customer has connected.
+ * - `invoke(connector, action, args)` runs a connector action imperatively. The
+ *   control plane resolves the workspace's connection for `connector`, validates
+ *   `args` against the action's input schema, executes it, and returns the
+ *   validated output verbatim. `args` is opaque — the SDK forwards it untouched.
+ *
+ * Authentication reuses the existing `STACKBONE_AGENT_JWT` channel injected at
+ * provisioning (the `HttpClient` attaches the bearer + install header), so the
+ * control plane scopes every call to the agent's own install → organization.
+ *
+ * Contract gating: every method awaits the `connections.actions` module gate
+ * before touching the network, so a stale datapath / missing capability surfaces
+ * as a gating error rather than a failed request.
+ */
+declare class ConnectionsModule {
+    private readonly _http;
+    private readonly _gate;
+    constructor(resolved: ResolvedConfig, _http: HttpClient, 
+    /** Test seam — see `ModuleGate`. Defaults to the lazy contract gate. */
+    gate?: ModuleGate);
+    /** List the workspace's connections (no credentials). */
+    list(): Promise<Result<AgentConnectionListResponse>>;
+    /**
+     * Invoke a connector action against the workspace's connection for that
+     * connector. `args` is forwarded opaquely; the control plane validates it
+     * against the action's own input schema and returns the validated output.
+     *
+     * When the workspace holds several connections of the same connector, pass
+     * `{ connection }` (a connection id or unique name) to pick one; omitting it
+     * with more than one connection fails `connections_ambiguous`.
+     */
+    invoke(connector: string, action: string, args: unknown, opts?: InvokeOptions): Promise<Result<InvokeConnectorActionResponse>>;
+}
+
+/**
+ * Where a memory lives. Default `'user'`. `'session'` is short-lived and
+ * collapsed (or dropped) by `endSession()`; `'agent'` is shared across every
+ * user of the agent.
+ */
+type MemoryScope = 'user' | 'session' | 'agent';
+/**
+ * Either raw text or an OpenAI-shaped conversation. The future mem0 backend
+ * accepts both: strings ingest verbatim, message arrays are summarised into
+ * one or more facts.
+ */
+type MemoryContent = string | ChatCompletionMessageParam[];
+interface AddMemoryRequest {
+    userId: string;
+    /** Conversation/session bucket. Required when `scope: 'session'`. */
+    sessionId?: string;
+    /** Default `'user'`. */
+    scope?: MemoryScope;
+    metadata?: Record<string, unknown>;
+}
+interface MemoryItem {
+    id: string;
+    content: string;
+    userId: string;
+    sessionId?: string;
+    scope: MemoryScope;
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 UTC timestamp. */
+    createdAt: string;
+    updatedAt: string;
+}
+interface SearchMemoryOptions {
+    userId?: string;
+    sessionId?: string;
+    /** 1..100. Default 10. */
+    limit?: number;
+    /** Minimum cosine similarity in [0, 1]. Hits below this are dropped. */
+    threshold?: number;
+    /** Metadata predicates AND-ed to the semantic match. */
+    filters?: Record<string, unknown>;
+    /** Restrict the search to a subset of scopes. Default: every scope. */
+    includeScopes?: readonly MemoryScope[];
+}
+interface MemoryHit extends MemoryItem {
+    /** Cosine similarity in [0, 1]. */
+    score: number;
+}
+interface ListMemoryRequest {
+    userId: string;
+    /** 1..100. Default 50. */
+    limit?: number;
+    cursor?: string;
+}
+interface ListMemoryResult {
+    items: readonly MemoryItem[];
+    nextCursor?: string;
+}
+interface UpdateMemoryOptions {
+    content?: string;
+    /** Shallow-merged onto the existing metadata (mem0 semantics). */
+    metadata?: Record<string, unknown>;
+}
+interface DeleteAllMemoryRequest {
+    userId: string;
+}
+type MemoryHistoryEvent = 'created' | 'updated' | 'accessed' | 'deleted';
+interface MemoryHistoryEntry {
+    id: string;
+    memoryId: string;
+    event: MemoryHistoryEvent;
+    /** ISO 8601 UTC timestamp. */
+    at: string;
+    /** Identifier of who triggered the event (user id, agent id, etc.). */
+    actor?: string;
+    /** Content snapshot before the event. Only set for `updated`/`deleted`. */
+    before?: string;
+    /** Content snapshot after the event. Only set for `created`/`updated`. */
+    after?: string;
+    metadata?: Record<string, unknown>;
+}
+interface EndSessionOptions {
+    /** Persist session-scoped facts to long-term (`'user'`) memory before closing. Default `true`. */
+    persist?: boolean;
+}
+interface EndSessionResult {
+    sessionId: string;
+    /** Number of session memories promoted to long-term storage. `0` when `persist: false`. */
+    persisted: number;
+}
+/**
+ * `client.memory` — long-term memory for the agent. The first iteration is a
+ * scaffolding placeholder: every method returns `not_implemented`. The real
+ * backend will be mem0 (`mem0ApiKey` / `MEM0_API_KEY`) and the public surface
+ * defined here is the contract callers can already type against.
+ *
+ * Contract gating: not gated. Memory targets mem0 (a non-Stackbone partner),
+ * so there is no Stackbone Agent Protocol capability to assert against. No
+ * entry in `MODULE_CAPABILITIES` per the rule documented in
+ * `contract/capability-registry.ts`. When/if the runtime moves to a
+ * Stackbone-served backend we add the capability and wire the gate.
+ */
+declare class MemoryModule {
+    constructor(_resolved: ResolvedConfig);
+    add(_content: MemoryContent, _request: AddMemoryRequest): Promise<Result<MemoryItem>>;
+    search(_query: string, _options?: SearchMemoryOptions): Promise<Result<readonly MemoryHit[]>>;
+    delete(_memoryId: string): Promise<Result<{
+        id: string;
+    }>>;
+    deleteAll(_request: DeleteAllMemoryRequest): Promise<Result<{
+        deleted: number;
+    }>>;
+    get(_memoryId: string): Promise<Result<MemoryItem>>;
+    list(_request: ListMemoryRequest): Promise<Result<ListMemoryResult>>;
+    update(_memoryId: string, _options: UpdateMemoryOptions): Promise<Result<MemoryItem>>;
+    history(_memoryId: string): Promise<Result<readonly MemoryHistoryEntry[]>>;
+    endSession(_sessionId: string, _options?: EndSessionOptions): Promise<Result<EndSessionResult>>;
+}
+
 /**
  * Enqueue a one-shot (or deferred) job. The opaque `payload` is whatever the
  * agent's `receive` handler expects — the core never inspects it.
@@ -1541,6 +1605,7 @@ declare class StackboneClient {
     private _secrets?;
     private _config?;
     private _queues?;
+    private _connections?;
     private _memory?;
     private _prompts?;
     private _httpClient?;
@@ -1563,6 +1628,15 @@ declare class StackboneClient {
      * as the other gated surfaces.
      */
     get queues(): QueuesModule;
+    /**
+     * Live surface — the agent's handle on the workspace's connector connections.
+     * `list` / `invoke` make authenticated calls to the control-plane connectors
+     * proxy (`/api/v1/agent/connections/*`); the credentials never enter the agent
+     * container. Gated against `connections.actions` so the handshake-blocked /
+     * capability-missing paths are exercised the same way as the other gated
+     * surfaces.
+     */
+    get connections(): ConnectionsModule;
     /**
      * Pending surface — runtime not built. Every method returns
      * `not_implemented`. Mem0 is a third-party integration, not a Stackbone
@@ -2046,4 +2120,4 @@ interface JsonSchemaDocument {
  */
 declare const analyzeAgentSchemas: (pair: AgentSchemaPair) => SchemaIntrospectionResult;
 
-export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };
+export { type AddMemoryRequest, type AgentSchemaPair, type AgentSpec, type AnyCapability, type ApprovalListOptions, type ApprovalListResult, type ApprovalRecord, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalStatus, type ApprovalTool, type ApprovalToolSpec, type ApprovalTopic, type ApproverInfo, type ClientConfig, type CompilePromptResult, type ConsoleLike, type CreatePromptRequest, type Decision, type DecisionStatus, type DeleteAllMemoryRequest, type DeletePromptOptions, type DeletePromptResult, type EndSessionOptions, type EndSessionResult, type FatalConstruct, type GeneratedImage, type GetPromptOptions, INVOCATION_ID_HEADER, INVOKE_TIMEOUT_HARD_CAP_MS, type ImageGenerateParams, type ImagesResponse, type IngestAsyncHandle, type InstallConsoleCaptureOptions, type InvocationContext, type InvokeCapability, type InvokeContext, type InvokeEnvelopeError, type InvokeErrorEnvelope, type InvokeOptions, type InvokeRequest, type InvokeResponse, type InvokeSuccessEnvelope, type JobCapability, type JsonSchemaDocument, type ListMemoryRequest, type ListMemoryResult, type ListOptions, type ListPromptsOptions, type ListPromptsResult, type LoadSystemSecretsArgs, type LogSink, type Logger, type LoggerBindings, type MemoryContent, type MemoryHistoryEntry, type MemoryHistoryEvent, type MemoryHit, type MemoryItem, type MemoryScope, type ModelsListResponse, type OpenRouterModel, type Prompt, type PublishRequest, RESERVED_ERROR_CODES, RESERVED_HANDLER_NAMES, RUN_ID_HEADER, type ReservedErrorCode, type Result, STORED_TO_SDK_ENV, type ScheduleRequest, type SchemaDiagnostic, type SchemaHalf, type SchemaIntrospectionResult, type SdkError, type SdkErrorCode, type SearchMemoryOptions, type SignedUrl, type SignedUrlOptions, StackboneClient, type StorageBody, type StorageObject, type StructuredLoggerOptions, type SystemSecretRow, type SystemSecretsReader, type UnscheduleRequest, type UpdateMemoryOptions, type UpdatePromptOptions, type UploadOptions, type VerifyOptions, type WarnConstruct, analyzeAgentSchemas, createClient, createStructuredLogger, defineAgent, getInvocationContext, installInvocationConsoleCapture, invokeRequestSchema, isReservedErrorCode, isSdkErrorCode, loadSystemSecretsIntoEnv, rehydrateSystemSecretsRows, runWithInvocationContext };