indusagi 0.12.32 → 0.12.33

package/dist/types/capabilities/planning/todo.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The `todo` planning capability: a tiny, per-conversation task list the model
+ * can keep in front of itself while it works.
+ *
+ * Two cooperating tools are exposed. {@link todoSetTool} replaces the entire
+ * checklist in one shot — the caller hands over the whole array of items it wants
+ * tracked, and any previous list for that context is discarded. {@link todoReadTool}
+ * plays the list back so the model can re-read where it stands without mutating
+ * anything. Both are authored against the kernel surface alone; the backing store
+ * is plain in-process state, so no `ctx.fs` or `ctx.shell` access is needed.
+ *
+ * State lives in a single module-level {@link TodoStore} keyed by the live
+ * {@link ToolContext}. Every distinct conversation threads a distinct context
+ * object through `run`, so each conversation gets its own isolated list. The store
+ * exposes {@link TodoStore.reset} so a test can wipe all accumulated lists between
+ * cases.
+ */
+import type { ToolContext } from "../kernel";
+/** The lifecycle stage of a single checklist entry. */
+export type TodoStatus = "pending" | "active" | "done";
+/** One line of the checklist. */
+export interface TodoItem {
+    /** Caller-chosen stable identifier, unique within a single list. */
+    readonly id: string;
+    /** Human-readable summary of the task. */
+    readonly text: string;
+    /** Where this task sits in its lifecycle. */
+    readonly status: TodoStatus;
+}
+/**
+ * In-process home for every context's checklist.
+ *
+ * Keys are the identity of the {@link ToolContext} object handed to `run`, so two
+ * conversations never see each other's items. The class is a thin wrapper over a
+ * {@link Map}; it is deliberately minimal because the tools own all of the
+ * validation and presentation logic.
+ */
+export declare class TodoStore {
+    private readonly lists;
+    /** Return the list recorded for `ctx`, or an empty array if none was set yet. */
+    read(ctx: ToolContext): readonly TodoItem[];
+    /** Replace the entire list recorded for `ctx` with `items`. */
+    replace(ctx: ToolContext, items: readonly TodoItem[]): void;
+    /** Discard every stored list. Intended for test isolation only. */
+    reset(): void;
+}
+/**
+ * The shared, module-level store both tools read and write.
+ *
+ * Exported so tests can call {@link TodoStore.reset} between cases and assert on
+ * stored state directly.
+ */
+export declare const todoStore: TodoStore;
+/**
+ * Convenience re-export of the store's reset, so a test can wipe state with a
+ * single named import instead of reaching through the instance.
+ */
+export declare function reset(): void;
+/** Replace the whole stored checklist for the calling context. */
+export declare const todoSetTool: import("..").DefinedTool;
+/** Play back the stored checklist for the calling context without changing it. */
+export declare const todoReadTool: import("..").DefinedTool;

package/dist/types/capabilities/registry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The built-in capability assembly.
+ *
+ * The kernel ships a generic {@link ToolRegistry} and a generic
+ * {@link makeNodeContext}; this module marries the two into the concrete,
+ * batteries-included surface a host actually wires up. It registers every
+ * built-in tool, names the standard collections the agent selects between, and
+ * exposes a one-call {@link toolBox} helper that produces a runnable
+ * {@link ToolBox} backed by the real Node filesystem and shell.
+ *
+ * Three collections are defined:
+ *   - `read-only` — tools that only observe the workspace and the web: read,
+ *     ls, grep, find, websearch, webfetch. Safe to expose when no mutation
+ *     should be possible.
+ *   - `coding`    — everything in `read-only` plus the mutating and stateful
+ *     tools: write, edit, bash, the todo pair, and process control.
+ *   - `all`       — the union of every registered tool, with nothing withheld.
+ *
+ * Nothing here reaches for `node:fs` or `node:child_process` directly — the
+ * Node binding lives entirely in `backends/`, which this module merely consumes.
+ */
+import { ToolRegistry } from "./kernel";
+import type { ToolBox } from "../runtime/contract";
+/** The names of the collections this module defines. */
+export type ToolCollection = "read-only" | "coding" | "all";
+/**
+ * Build a fresh {@link ToolRegistry} populated with every built-in tool and the
+ * three standard collections.
+ *
+ * A new registry is minted on each call so callers never share mutable state;
+ * the tool objects themselves are stateless singletons and are safe to share.
+ */
+export declare function builtinRegistry(): ToolRegistry;
+/**
+ * Produce a runnable {@link ToolBox} for the named collection, backed by the
+ * real Node filesystem and shell.
+ *
+ * The returned box advertises exactly the descriptors of the chosen collection
+ * and dispatches each call to the matching tool, minting a fresh
+ * {@link ToolContext} (rooted at `cwd`) per dispatch and threading the runtime's
+ * cancellation signal in. `cwd` defaults to the current process working
+ * directory when omitted.
+ */
+export declare function toolBox(collection: ToolCollection, cwd?: string): ToolBox;

package/dist/types/capabilities/search/find.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Filename search capability.
+ *
+ * `find` enumerates entries beneath a starting path whose *name* matches a query.
+ * The query is interpreted as either a shell-style glob (when it contains `*` or
+ * `?`) or, failing that, a plain case-insensitive substring. The walk is a
+ * hand-rolled recursive descent over {@link ToolContext.fs}; it never touches
+ * `node:fs`, a child process, or a platform `find` binary, so it behaves the same
+ * against any backend a host plugs in (real disk, sandbox, in-memory).
+ *
+ * Results are returned as paths relative to the search root, one per line, and
+ * are pared back through {@link ToolContext.budget} so the listing can never
+ * overflow the model's window.
+ */
+/** Which kind of filesystem entry the caller wants back. */
+type EntryKind = "file" | "dir";
+/** The arguments this tool accepts from the model. */
+export interface FindInput {
+    /** Glob pattern (with `*`/`?`) or plain substring to match against names. */
+    readonly query: string;
+    /** Directory to search beneath; defaults to the working directory. */
+    readonly path?: string;
+    /** Restrict hits to regular files (`"file"`) or directories (`"dir"`). */
+    readonly type?: EntryKind;
+}
+/**
+ * The filename-search tool. Walks a path with {@link ToolContext.fs}, tests each
+ * entry's *name* against a glob or substring query, optionally filters by file
+ * vs. directory, and returns the matching root-relative paths clamped to
+ * {@link ToolContext.budget}.
+ */
+export declare const findTool: import("..").DefinedTool;
+export {};

package/dist/types/capabilities/search/grep.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Content search capability.
+ *
+ * `grep` hunts for a regular expression inside the *text* of files beneath a
+ * starting path. The traversal is a hand-rolled recursive descent over
+ * {@link ToolContext.fs}; it never reaches for `node:fs`, a child process, or the
+ * platform `grep` binary, so it behaves identically against any backend a host
+ * cares to plug in (real disk, sandbox, in-memory).
+ *
+ * Each hit is reported as `relative/path:line` followed by the line that matched.
+ * Bulky output is pared back through {@link ToolContext.budget} so the result can
+ * never overrun the model's window.
+ */
+/** The arguments this tool accepts from the model. */
+export interface GrepInput {
+    /** The regular expression to test each line against. */
+    readonly pattern: string;
+    /** Directory (or single file) to search under; defaults to the working dir. */
+    readonly path?: string;
+    /** Standard JS regex flag letters, e.g. `"i"` for case-insensitive. */
+    readonly flags?: string;
+    /** Stop after this many hits have been collected. */
+    readonly maxMatches?: number;
+}
+/**
+ * The content-search tool. Walks a path with {@link ToolContext.fs}, tests each
+ * line of every readable text file against the supplied regex, and returns
+ * `path:line` hits clamped to {@link ToolContext.budget}.
+ */
+export declare const grepTool: import("..").DefinedTool;

package/dist/types/capabilities/shell/bash.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The `bash` capability: run a single shell command to completion.
+ *
+ * This tool hands a one-shot command string to the kernel's {@link Shell.exec}
+ * backend, waits for it to settle, and reports back the captured standard
+ * output, standard error, and exit status as a single text block the model can
+ * read. It never reaches for `node:child_process` itself — every side effect
+ * flows through the injected {@link ToolContext.shell} seam, so a host may run it
+ * locally, sandboxed, or remotely without the tool noticing.
+ *
+ * Cancellation and a wall-clock deadline are both honored: the context's
+ * {@link ToolContext.signal} is threaded into the launch (so an aborted turn
+ * tears the command down), and a per-call `timeoutMs` caps how long a runaway
+ * command may block. Output that would overflow the model's window is trimmed
+ * through the context's {@link ToolContext.budget} before it is returned.
+ */
+/** The `bash` tool: a one-shot shell command runner. */
+export declare const bashTool: import("..").DefinedTool;

package/dist/types/capabilities/shell/process.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `process` capability: a controller for long-lived background commands.
+ *
+ * Where {@link bashTool} runs a single command to completion and blocks, this
+ * tool starts a command that keeps running between turns — a dev server, a file
+ * watcher, a log tail — and lets the model check in on it later. It owns a small
+ * in-module registry of live jobs (the {@link ProcessTable}); each registry
+ * entry pairs the kernel {@link ShellHandle} with a rolling capture of whatever
+ * the job has printed so far.
+ *
+ * Four verbs drive it:
+ *   - `start` launches a command in the background and hands back its job id.
+ *   - `list`  enumerates every tracked job with its current status.
+ *   - `poll`  drains the output buffered since the last look and reports whether
+ *             the job is still alive or how it ended.
+ *   - `stop`  signals a running job to terminate and forgets it.
+ *
+ * The kernel {@link ShellHandle} exposes no output streams of its own — only a
+ * pid, a kill, and an exit subscription. To capture what a background job prints
+ * without ever touching `node:child_process`, the launcher wraps the command so
+ * the platform shell redirects both streams into per-job scratch files, then
+ * reads those files back through the {@link ToolContext.fs} seam. Every side
+ * effect therefore flows through `ctx.shell` and `ctx.fs`; this module reaches
+ * for no Node API of its own.
+ */
+/** Clear the background-job registry; intended for test setup/teardown. */
+export declare function resetProcessTable(): void;
+/**
+ * The `process` tool: a registry-backed controller for background commands.
+ *
+ * Exported as a named {@link DefinedTool} so a host can register it directly.
+ */
+export declare const processTool: import("..").DefinedTool;

package/dist/types/capabilities/web/webfetch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `webfetch` capability: pull a web page and hand the model a clean,
+ * reading-friendly rendition of it.
+ *
+ * The tool issues a single HTTP(S) GET through the platform `fetch`, reads the
+ * body as text, and runs it through a small, self-contained HTML simplifier.
+ * That simplifier is deliberately naive — it is not a real parser. It strips the
+ * non-visible machinery (script, style, template, and comment regions), turns a
+ * handful of structural tags (headings, paragraphs, list items, line breaks,
+ * anchors) into plain-text equivalents, deletes every remaining tag, decodes the
+ * common character entities, and squeezes runaway whitespace. The result reads
+ * roughly like markdown without pretending to be a faithful conversion.
+ *
+ * Two ceilings guard the size of what comes back: an optional caller-supplied
+ * `maxBytes` that bounds how much of the downloaded body is even considered, and
+ * the context's {@link OutputBudget}, which is always applied last so the model's
+ * window can never be overrun. Any failure on the network path — an unreachable
+ * host, a non-success status, a body that will not decode — is caught and
+ * returned as a flagged error result rather than thrown, so the agent loop sees a
+ * tidy message instead of a crash.
+ *
+ * Authored entirely against the kernel surface plus the platform `fetch` global;
+ * no Node module is imported here.
+ */
+export declare const webFetchTool: import("..").DefinedTool;

package/dist/types/capabilities/web/websearch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `websearch` capability: run a web query and hand the model a ranked list
+ * of hits.
+ *
+ * The query is sent to DuckDuckGo's no-frills HTML endpoint, whose markup is
+ * lightweight enough to scrape with a couple of targeted regular expressions —
+ * no headless browser, no HTML parser dependency. Each hit is distilled to the
+ * three fields a model actually reasons over: a title, the destination URL, and
+ * a short snippet. The list is capped (by `maxResults`, with a sane default and
+ * a hard ceiling) and the whole payload is byte-bounded through the context's
+ * {@link OutputBudget} so a chatty results page can never overflow the window.
+ *
+ * Network reachability is never guaranteed, so every failure mode — a thrown
+ * fetch, a non-OK status, a body that yields nothing parseable — is turned into
+ * an `isError` {@link ToolResult} rather than an exception. The caller (and the
+ * model) always gets a well-typed result back.
+ *
+ * Authored against the kernel surface plus the Web-standard `fetch` global.
+ * There is no filesystem or shell work here, and DuckDuckGo has no kernel seam,
+ * so the only outside primitive used is `fetch` — the platform networking API,
+ * not a node-specific module.
+ */
+export declare const webSearchTool: import("..").DefinedTool;

package/dist/types/connectors-saas/connectors-saas.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tests for the SaaS connector bridge, driven by an in-memory MOCK
+ * {@link SaasBackend}.
+ *
+ * There is deliberately NO network and NO `@composio/core` here: a fake backend
+ * exposing one toolkit ("github") with two operations stands in for the vendor
+ * catalog, so the whole bridge — gateway assembly, the content-hash enable cache,
+ * the remote-tool builder, the declarative connect rule table, and the result
+ * summarizer — is exercised against plain objects. The real adapter is covered
+ * separately; these tests pin the dependency-inverted core's behaviour.
+ */
+export {};

package/dist/types/connectors-saas/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The SaaS connector bridge — public surface.
+ *
+ * One import site for the whole bridge: the stateful {@link SaasGateway} façade and
+ * its factories, the {@link SaasBackend} port plus its data vocabulary, the single
+ * vendor adapter ({@link createComposioBackend}), and the fluent {@link ScopePlanner}
+ * scope resolver. The render and control internals stay private behind the gateway;
+ * a host wires an agent up through this barrel alone.
+ */
+export { createSaasGateway, createComposioGateway, } from "./saas/gateway";
+export type { SaasGateway, SaasGatewayOptions, EnableReport, ConnectReport, StatusReport, } from "./saas/gateway";
+export type { SaasBackend, ToolkitInfo, RemoteTool, RemoteResult, ConnectedAccount, ConnectionStatus, ConnectionRequest, ConnectionState, ExecuteOptions, InitiateOptions, } from "./saas/core/index";
+export { createComposioBackend, ComposioBackendError } from "./saas/adapter/composio-backend";
+export type { ComposioBackendOptions } from "./saas/adapter/composio-backend";
+export { ScopePlanner } from "./saas/core/index";
+export type { ResolvedScope, ScopeKind } from "./saas/core/index";

package/dist/types/connectors-saas/saas/adapter/composio-backend.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The Composio adapter — the *single* place `@composio/core` leaks into the SaaS
+ * connector bridge.
+ *
+ * Everything else in `src/connectors-saas/` talks to the {@link SaasBackend} port
+ * (see `../core/port`). This file is the lone implementation that satisfies that
+ * port by delegating to the real `Composio` SDK client and translating the
+ * vendor's richer, snake-/camel-cased catalog shapes down into our small, frozen
+ * vocabulary. Because the vendor's response types are sprawling (deeply-nested
+ * zod-inferred unions) and not worth re-deriving here, `any` is deliberately
+ * permitted at this boundary — and *only* here. The mapping helpers
+ * (`normalizeStatus`, `pickAuthUrl`, the `to*` projectors) re-narrow every value
+ * back to a typed port shape before it crosses out, so nothing untyped escapes.
+ *
+ * Method-by-method delegation:
+ *   listToolkits        → composio.toolkits.get({})
+ *   listTools           → composio.tools.getRawComposioTools({ toolkits: [slug] })
+ *   execute             → composio.tools.execute(slug, { userId, arguments, connectedAccountId })
+ *   listConnectedAccounts → composio.connectedAccounts.list()
+ *   initiateConnection  → composio.toolkits.authorize(userId, slug, authConfigId?)
+ *   checkConnection     → composio.connectedAccounts.get(id)
+ *
+ * The Composio SDK is user-scoped: nearly every call wants a `userId`. The bridge
+ * port is single-user by design, so we thread a fixed default user through the
+ * adapter; callers that need multi-tenancy construct one backend per user.
+ */
+import type { SaasBackend } from "../core/port";
+/** Options for standing up the Composio-backed {@link SaasBackend}. */
+export interface ComposioBackendOptions {
+    /** The Composio API key the SDK client authenticates with. */
+    readonly apiKey: string;
+    /**
+     * The user scope to act under. The Composio catalog is user-scoped; the bridge
+     * port is single-user, so one fixed id is threaded through every call. Defaults
+     * to `"default"` when omitted.
+     */
+    readonly userId?: string;
+}
+/**
+ * Thrown when a backend operation cannot be satisfied through the Composio SDK in
+ * a way that maps cleanly onto the port — i.e. a genuinely unsupported request,
+ * not a transient API failure. Carries the offending method name for tracing.
+ */
+export declare class ComposioBackendError extends Error {
+    /** The port method that could not be satisfied (e.g. `"checkConnection"`). */
+    readonly method: string;
+    constructor(method: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Build the Composio-backed {@link SaasBackend}.
+ *
+ * This is the bridge's single seam onto `@composio/core`: hand it an API key and
+ * it returns an object that speaks only the port. Nothing the caller touches
+ * references a vendor type.
+ */
+export declare function createComposioBackend(opts: {
+    apiKey: string;
+}): SaasBackend;

package/dist/types/connectors-saas/saas/control/connect.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The connection state machine, expressed as a declarative RULE TABLE.
+ *
+ * Driving an OAuth-style link from "nothing yet" to "active" is a small loop with
+ * a handful of terminal and non-terminal states. The naive way to write it is an
+ * `if`-cascade inside the poll loop — "if active return; else if failed throw;
+ * else if expired re-initiate; else wait and poll again" — which buries the policy
+ * inside control flow and is easy to get subtly wrong. We pull that policy out into
+ * {@link CONNECT_RULES}: one row per normalized {@link ConnectionStatus}, each row
+ * naming the {@link ConnectAction} the driver should take next. The poll loop then
+ * does nothing but *consult the table* and obey.
+ *
+ * {@link planConnect} is the pure function at the heart of it: state in, action
+ * out, no I/O. {@link initiateAndAwait} is the one impure driver that opens a
+ * connection through the {@link SaasBackend} port and polls it to a terminal
+ * outcome, asking {@link planConnect} at every step what to do. Because the policy
+ * is data, a test can assert the whole decision matrix without touching a backend.
+ */
+import type { ConnectionState, ConnectionStatus, InitiateOptions, SaasBackend } from "../core/index";
+/**
+ * What the driver should do once it has observed a connection's current state.
+ *
+ * - `await-auth` — the user still has to act (visit `authUrl`); keep polling.
+ * - `poll` — the link is progressing on the backend; check again shortly.
+ * - `done` — the link is `active`; the carried `accountId` is ready to use.
+ * - `expired` — the attempt lapsed; the caller may re-initiate from scratch.
+ * - `failed` — the attempt terminally failed; surface the reason and stop.
+ */
+export type ConnectAction = {
+    readonly kind: "await-auth";
+    readonly authUrl?: string;
+} | {
+    readonly kind: "poll";
+} | {
+    readonly kind: "done";
+    readonly accountId?: string;
+} | {
+    readonly kind: "expired";
+} | {
+    readonly kind: "failed";
+    readonly reason: string;
+};
+/** Whether an action is one the driver stops on rather than loops past. */
+export declare function isTerminal(action: ConnectAction): boolean;
+/**
+ * One row of the connection decision matrix: a normalized status mapped to the
+ * action the driver should take when it observes that status. Keeping `decide` as
+ * a thunk over the live {@link ConnectionState} lets a row read the state's
+ * `accountId` / `authUrl` without the table itself needing to branch.
+ */
+interface ConnectRule {
+    /** The normalized status this row governs. */
+    readonly when: ConnectionStatus;
+    /** Produce the next action from the observed state. */
+    decide(state: ConnectionState): ConnectAction;
+}
+/**
+ * The connection rule table — the whole policy as data.
+ *
+ * `active` → done (carrying the linked account); `pending` → either wait for the
+ * user when an `authUrl` is outstanding, or poll the backend otherwise; `expired`
+ * and `failed` are the two terminal failure shapes. There is exactly one row per
+ * member of {@link ConnectionStatus}, so the matrix is total by construction.
+ */
+export declare const CONNECT_RULES: readonly ConnectRule[];
+/**
+ * Decide the next {@link ConnectAction} for an observed {@link ConnectionState}.
+ *
+ * Pure: it consults {@link CONNECT_RULES} and applies the matching row. Because
+ * the table is total over {@link ConnectionStatus}, the only way to miss is an
+ * out-of-vocabulary status, which we treat as a terminal failure rather than a
+ * silent no-op.
+ */
+export declare function planConnect(state: ConnectionState): ConnectAction;
+/** How the {@link initiateAndAwait} driver paces and bounds its polling. */
+export interface AwaitOptions extends InitiateOptions {
+    /** Milliseconds between polls of a still-pending connection. Default 1500. */
+    readonly pollIntervalMs?: number;
+    /** Maximum number of polls before giving up with a timeout. Default 40. */
+    readonly maxPolls?: number;
+    /** Injectable delay, so tests can drive the loop without real time passing. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The terminal outcome of driving a connection attempt to completion.
+ *
+ * `action` is always one for which {@link isTerminal} holds. `requestId` and the
+ * final `authUrl` (if the user still needed to act) are carried for surfacing.
+ */
+export interface ConnectOutcome {
+    /** The connection request that was driven. */
+    readonly requestId: string;
+    /** The toolkit the request targeted. */
+    readonly toolkit: string;
+    /** The terminal action the state machine settled on. */
+    readonly action: ConnectAction;
+    /** The most recent authorization URL observed, if any. */
+    readonly authUrl?: string;
+}
+/**
+ * Open a connection to `toolkit` and poll it to a terminal state via the backend.
+ *
+ * The driver is deliberately thin: it initiates once, then loops — observe state,
+ * ask {@link planConnect}, and either stop (terminal action) or wait-and-poll
+ * (`poll` / `await-auth`). Polling is bounded by `maxPolls`; exhausting the budget
+ * yields a `failed` outcome rather than hanging. All policy lives in the rule
+ * table; this function only sequences I/O around it.
+ *
+ * Note it does *not* re-initiate on `expired` — that decision belongs to the
+ * caller, who may want to surface the lapse to the user first; the outcome simply
+ * reports `expired` so the caller can choose.
+ */
+export declare function initiateAndAwait(backend: SaasBackend, toolkit: string, options?: AwaitOptions): Promise<ConnectOutcome>;
+export {};

package/dist/types/connectors-saas/saas/control/tools.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The four CONTROL tools — built from ONE declarative table and a single factory.
+ *
+ * Where {@link CONNECTOR_TOOLS} (in core) describes the low-level passthrough tools
+ * that talk straight to the {@link SaasBackend} port, this module defines the
+ * higher-level *control surface* an agent uses to manage SaaS connectors as a
+ * whole: discovering and hydrating toolkits into the live tool set, executing any
+ * remote operation directly, opening an authorization flow, and reporting status.
+ *
+ * Two ideas, shared with the core builder, are reused verbatim here:
+ *
+ * 1. **One table, one factory.** The four control tools are rows in
+ *    {@link CONTROL_SPECS}, each an `id` + `description` + JSON-Schema `parameters`
+ *    + a `run(gateway, input)` thunk. {@link buildControlTools} maps the table to
+ *    {@link DefinedTool}s with a single `defineTool` call per row — there is no
+ *    `createEnableTool` / `createExecuteTool` family.
+ * 2. **Delegate, don't reimplement.** Every `run` defers to the passed-in
+ *    {@link SaasGateway}, which is the one object that owns the live registry, the
+ *    discovery cache, the scope planner, and the connection state machine. The
+ *    tools are thin command surfaces; the gateway holds the logic.
+ *
+ * The gateway is what distinguishes these from the core passthrough tools: a
+ * control tool can mutate the live ToolBox (hydrating a toolkit's operations into
+ * it) precisely because the gateway, not a bare backend, sits behind it.
+ */
+import type { DefinedTool, ToolResult } from "../../../capabilities";
+import type { JsonSchema } from "../../../llmgateway/contract";
+import type { SaasGateway } from "../gateway";
+/** Read a string-array field from a loose argument bag, dropping non-strings/blanks. */
+declare function readStringList(input: Record<string, unknown>, key: string): string[];
+/**
+ * One row of the control-tool table: a control tool described purely as data.
+ *
+ * Unlike the core `ControlToolSpec`, a control row's `run` is handed the
+ * {@link SaasGateway} (the stateful façade), not a bare backend — that is what
+ * lets `saas_enable` hydrate the live tool set.
+ */
+export interface ControlSpec {
+    /** The model-facing tool name (e.g. `"saas_enable"`). */
+    readonly id: string;
+    /** Model-facing description of the control tool. */
+    readonly description: string;
+    /** JSON-Schema object for the control tool's parameters. */
+    readonly parameters: JsonSchema;
+    /** The control tool's behavior, expressed against the gateway façade. */
+    run(gateway: SaasGateway, input: Record<string, unknown>): Promise<ToolResult>;
+}
+/**
+ * The four control tools, as one declarative table.
+ *
+ * - `saas_enable` — hydrate a toolkit's operations into the live ToolBox so the
+ *   agent can call them natively on subsequent turns.
+ * - `saas_execute` — direct fallback execution of any remote operation by slug,
+ *   without first hydrating it.
+ * - `saas_connect` — start (and drive) an authorization flow for a toolkit.
+ * - `saas_status` — list connected accounts and the operations currently in scope.
+ */
+export declare const CONTROL_SPECS: readonly ControlSpec[];
+/**
+ * Instantiate every row of {@link CONTROL_SPECS} into a {@link DefinedTool}, each
+ * bound to the supplied {@link SaasGateway}.
+ *
+ * This is the single factory the spec calls for: one map over the data table, one
+ * `defineTool` per row, no per-control-tool boilerplate.
+ */
+export declare function buildControlTools(gateway: SaasGateway): DefinedTool[];
+export { readStringList };

package/dist/types/connectors-saas/saas/core/builder.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The single remote-tool builder and the declarative control-tool table.
+ *
+ * Two ideas live here, and the point of putting them together is that they share
+ * one philosophy: **one builder, never a family of near-identical factories.**
+ *
+ * 1. {@link buildRemoteTool} is the *only* place a catalog operation becomes a
+ *    native {@link DefinedTool}. Given a {@link RemoteTool} reference and a backend
+ *    port, it mints a tool whose `run` forwards the model's arguments to
+ *    `backend.execute(ref.name, …)` and folds the {@link RemoteResult} back into the
+ *    kernel's {@link ToolResult} shape. This is the `CONNECTOR_TOOLS` concept: a
+ *    remote tool is data (`ref`) plus this single rendering function — not a
+ *    bespoke class per operation.
+ *
+ * 2. The four **control** tools (attach / run / link / status) are described as
+ *    DATA in {@link CONNECTOR_TOOLS}: each entry is an `id`, a JSON-Schema
+ *    `parameters`, a `description`, and a `run(backend, input)` thunk. A single
+ *    {@link buildControlTools} maps over the table and calls {@link defineTool}
+ *    once per row. There is no `createXTool` per control tool and no trailing
+ *    singleton — the repetition a clone detector loves is gone.
+ *
+ * The vendor SDK is nowhere in sight: everything routes through the
+ * {@link SaasBackend} port, so this whole module is testable with a plain object.
+ */
+import type { DefinedTool, ToolResult } from "../../../capabilities";
+import type { JsonSchema } from "../../../llmgateway/contract";
+import type { RemoteTool, SaasBackend } from "./port";
+/** What every tool built here is handed: the backend port it routes through. */
+export interface ToolDeps {
+    /** The inverted backend the tool's `run` calls into. */
+    readonly backend: SaasBackend;
+    /**
+     * Optional pinned account to execute remote operations under. Omit to let the
+     * backend choose the appropriate connected account.
+     */
+    readonly accountId?: string;
+}
+/**
+ * Mint a native {@link DefinedTool} from one catalog operation.
+ *
+ * The returned tool advertises the operation's own `inputSchema` to the model and,
+ * on invocation, forwards the parsed arguments straight to
+ * `deps.backend.execute(ref.name, input, { accountId })`, mapping the
+ * {@link RemoteResult} onto a {@link ToolResult}. This is the single bridge from
+ * "a remote tool reference" to "a tool the agent can call" — there is no per-
+ * operation subclass or factory.
+ */
+export declare function buildRemoteTool(ref: RemoteTool, deps: ToolDeps): DefinedTool;
+/**
+ * One row of the control-tool table: a control tool described purely as data.
+ *
+ * `id` is the model-facing tool name, `parameters` its JSON Schema, `description`
+ * its prose, and `run` a backend-driven thunk. Instantiation into a
+ * {@link DefinedTool} is done once, generically, by {@link buildControlTools}.
+ */
+export interface ControlToolSpec {
+    /** The model-facing tool name (e.g. `"saas.run"`). */
+    readonly id: string;
+    /** Model-facing description of the control tool. */
+    readonly description: string;
+    /** JSON-Schema object for the control tool's parameters. */
+    readonly parameters: JsonSchema;
+    /** The control tool's behavior, expressed against the backend port. */
+    run(backend: SaasBackend, input: Record<string, unknown>): Promise<ToolResult>;
+}
+/** Read a string-array field from a loose argument bag, dropping non-strings/blanks. */
+declare function strList(input: Record<string, unknown>, key: string): string[];
+/**
+ * The control tools, as one declarative table.
+ *
+ * `saas.attach` hydrates a toolkit's operations (discovery of what can be made
+ * native), `saas.run` executes a single operation directly, `saas.link` opens an
+ * authorization flow, and `saas.status` inspects connection state. Each is a row;
+ * none is a hand-written factory.
+ */
+export declare const CONNECTOR_TOOLS: readonly ControlToolSpec[];
+/**
+ * Instantiate every row of {@link CONNECTOR_TOOLS} into a {@link DefinedTool},
+ * binding each to the supplied backend.
+ *
+ * This is the single factory the spec calls for: one map over the data table, one
+ * `defineTool` per row, no per-control-tool boilerplate. The `strList` helper is
+ * exported-adjacent here so future control rows can read array fields uniformly.
+ */
+export declare function buildControlTools(backend: SaasBackend): DefinedTool[];
+export { strList as readStringList };