indusagi 0.12.32 → 0.12.34

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

@@ -0,0 +1,53 @@
+/**
+ * Content-hash cache keys for the SaaS bridge.
+ *
+ * The bridge dedupes work by *request shape*: two discovery or session requests
+ * that describe the same thing should hit the same cache slot regardless of how
+ * their fields happened to be ordered in memory. Rather than carry a recursive
+ * canonical-string serializer around as the key, we fold any value into a short,
+ * fixed-width SHA-256 digest of its canonical JSON. The digest *is* the key — a
+ * compact, collision-resistant string that captures the whole request shape.
+ *
+ * Canonicalization is the only subtlety: JSON key order is incidental, so before
+ * hashing we rewrite every object with its keys sorted. Arrays keep their order
+ * (it is meaningful); scalars pass through; `undefined` is dropped the way
+ * `JSON.stringify` already drops it. The result feeds `crypto`'s SHA-256 and we
+ * keep the hex digest.
+ *
+ * {@link HashCache} is the tiny Map-backed store that uses these keys. It memoizes
+ * *promises*, not resolved values, so concurrent callers asking for the same key
+ * share one in-flight computation instead of racing to produce duplicates.
+ */
+/**
+ * Derive a stable content-hash key from an arbitrary value.
+ *
+ * The value is canonicalized (so key order does not matter), JSON-encoded, and
+ * reduced to a hex SHA-256 digest. Equal request shapes always yield the same
+ * key; differing shapes practically never collide.
+ */
+export declare function hashKey(value: unknown): string;
+/**
+ * A minimal promise-memoizing cache keyed by content hash.
+ *
+ * Lookups go through {@link HashCache.take}, which either returns the
+ * already-stored promise for a request shape or runs the supplied factory once
+ * and stores its promise. Storing the promise (rather than awaiting first) is what
+ * collapses concurrent identical requests into a single backing computation.
+ */
+export declare class HashCache<V> {
+    private readonly slots;
+    /**
+     * Return the cached promise for `shape`, creating it via `factory` on first
+     * request. If the factory's promise rejects, the slot is evicted so a later
+     * call can retry rather than re-serving the failure forever.
+     */
+    take(shape: unknown, factory: () => Promise<V>): Promise<V>;
+    /** Whether a slot for this request shape currently exists. */
+    has(shape: unknown): boolean;
+    /** Drop the slot for this request shape, if any; returns whether one existed. */
+    drop(shape: unknown): boolean;
+    /** Evict every entry. */
+    clear(): void;
+    /** How many slots are currently populated. */
+    get size(): number;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The dependency-inverted CORE of the SaaS connector bridge — public surface.
+ *
+ * Everything exported here depends only on the {@link SaasBackend} PORT and our
+ * own contracts (the kernel's `defineTool`/`DefinedTool`, the gateway's
+ * `JsonSchema`). No `@composio/core` symbol crosses this barrel; the single vendor
+ * adapter that satisfies the port lives outside this `core/` folder.
+ */
+export type { SaasBackend, ToolkitInfo, RemoteTool, RemoteResult, ConnectedAccount, ConnectionStatus, ConnectionRequest, ConnectionState, ExecuteOptions, InitiateOptions, } from "./port";
+export { ScopePlanner } from "./scope-planner";
+export type { ResolvedScope, ScopeKind } from "./scope-planner";
+export { hashKey, HashCache } from "./cache";
+export { buildRemoteTool, buildControlTools, CONNECTOR_TOOLS, readStringList, } from "./builder";
+export type { ToolDeps, ControlToolSpec } from "./builder";

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

@@ -0,0 +1,157 @@
+/**
+ * The `SaasBackend` PORT — the dependency-inversion seam of the SaaS connector
+ * bridge.
+ *
+ * The whole point of this file is to name, in *our* vocabulary, the minimal
+ * surface the rest of the bridge (the gateway, the scope planner, the remote-tool
+ * builder) is allowed to lean on. It deliberately knows nothing about
+ * `@composio/core`: every shape below is ours, hand-shaped to be exactly what the
+ * core logic consumes and no more. A single adapter elsewhere will satisfy this
+ * port by translating to and from the vendor SDK — that adapter is the *only*
+ * place the third-party catalog leaks in. Everything that imports this file talks
+ * to an interface, never to a vendor.
+ *
+ * The six methods cover the three jobs the bridge does: **discovery**
+ * ({@link SaasBackend.listToolkits}, {@link SaasBackend.listTools}), **execution**
+ * ({@link SaasBackend.execute}), and **linking / auth**
+ * ({@link SaasBackend.listConnectedAccounts}, {@link SaasBackend.initiateConnection},
+ * {@link SaasBackend.checkConnection}). Each returns one of the plain record types
+ * defined here, so a fake backend for tests is a few object literals away.
+ */
+import type { JsonSchema } from "../../../llmgateway/contract";
+/**
+ * A connectable third-party product (GitHub, Gmail, Slack, …) as the catalog
+ * advertises it. `slug` is the stable machine identifier the rest of the bridge
+ * keys on; `name` and `description` are for the model and humans. `connected`,
+ * when the backend can cheaply tell, summarizes whether any account is linked.
+ */
+export interface ToolkitInfo {
+    /** Stable machine identifier for the toolkit (e.g. `"github"`). */
+    readonly slug: string;
+    /** Human-facing toolkit name. */
+    readonly name: string;
+    /** One-line summary of what the toolkit covers. */
+    readonly description: string;
+    /** Whether the backend believes at least one account is currently linked. */
+    readonly connected?: boolean;
+}
+/**
+ * One callable operation exposed by a toolkit, in the shape the bridge needs to
+ * mint a native agent tool from it. `inputSchema` is a JSON Schema object —
+ * structurally the same `JsonSchema` the gateway hands the model for every other
+ * tool — so a remote tool advertises its parameters identically to a built-in.
+ */
+export interface RemoteTool {
+    /** The fully-qualified operation slug used to invoke it (e.g. `"GITHUB_CREATE_ISSUE"`). */
+    readonly name: string;
+    /** The toolkit this operation belongs to (its {@link ToolkitInfo.slug}). */
+    readonly toolkit: string;
+    /** Model-facing description of the operation. */
+    readonly description: string;
+    /** JSON-Schema object describing the operation's parameters. */
+    readonly inputSchema: JsonSchema;
+}
+/**
+ * The outcome of running a {@link RemoteTool}.
+ *
+ * `ok` is the success/failure discriminant the bridge maps onto a tool result's
+ * `isError`. `data` is the raw structured payload the operation returned (shown to
+ * the model as JSON); `error`, when present, is a single human-readable line. A
+ * backend that has a correlation/log handle may surface it as `logId` for tracing.
+ */
+export interface RemoteResult {
+    /** True when the operation completed without an error. */
+    readonly ok: boolean;
+    /** The structured payload the operation produced, if any. */
+    readonly data?: unknown;
+    /** A single-line failure description when `ok` is false. */
+    readonly error?: string;
+    /** Optional backend-side correlation handle for tracing. */
+    readonly logId?: string;
+}
+/**
+ * A credential link the user has established with a toolkit. The bridge inspects
+ * these to decide whether a connect flow is needed and which account to execute
+ * under. `status` is normalized to our small {@link ConnectionState.status}
+ * vocabulary by the adapter, not the vendor's enum.
+ */
+export interface ConnectedAccount {
+    /** The account's stable identifier, used as the `accountId` on execute. */
+    readonly id: string;
+    /** The toolkit slug this account links. */
+    readonly toolkit: string;
+    /** Normalized lifecycle status of the link. */
+    readonly status: ConnectionStatus;
+    /** ISO-8601 timestamp of the most recent update, when the backend reports it. */
+    readonly updatedAt?: string;
+}
+/**
+ * The normalized lifecycle of a connection, ours rather than the vendor's. The
+ * adapter folds the catalog's richer enum down to these four buckets so the core
+ * logic only ever branches on a closed set it owns.
+ */
+export type ConnectionStatus = "active" | "pending" | "expired" | "failed";
+/**
+ * What {@link SaasBackend.initiateConnection} hands back: a freshly opened (or
+ * re-opened) connection attempt. `authUrl` is the actionable redirect the model
+ * should surface to the user when present; `id` is the request handle to poll via
+ * {@link SaasBackend.checkConnection}.
+ */
+export interface ConnectionRequest {
+    /** Identifier of the connection request, pollable for state. */
+    readonly id: string;
+    /** The toolkit the request targets. */
+    readonly toolkit: string;
+    /** Current normalized status at the moment the request was created. */
+    readonly status: ConnectionStatus;
+    /** OAuth/redirect URL the user must visit to authorize, when one applies. */
+    readonly authUrl?: string;
+}
+/**
+ * A point-in-time snapshot of a connection request's progress, returned by
+ * {@link SaasBackend.checkConnection}. Once `status` reaches `"active"` the
+ * resulting `accountId` is the linked account to execute under.
+ */
+export interface ConnectionState {
+    /** The request identifier this snapshot describes. */
+    readonly id: string;
+    /** Normalized status at the time of the check. */
+    readonly status: ConnectionStatus;
+    /** The connected-account id, present once the link has gone active. */
+    readonly accountId?: string;
+    /** A still-pending authorization URL, if the user has yet to act. */
+    readonly authUrl?: string;
+}
+/** Per-call execution knobs the gateway threads down to the backend. */
+export interface ExecuteOptions {
+    /** Pin execution to a specific connected account; omit to let the backend pick. */
+    readonly accountId?: string;
+}
+/** Optional inputs for opening a connection request. */
+export interface InitiateOptions {
+    /** Reuse a known auth-config rather than the toolkit's default, when supported. */
+    readonly authConfigId?: string;
+    /** Caller-supplied redirect to return the user to after authorizing. */
+    readonly callbackUrl?: string;
+}
+/**
+ * The minimal backend surface the SaaS bridge depends on.
+ *
+ * This is the inverted dependency: core modules accept a `SaasBackend` and never
+ * reach for the vendor SDK. One adapter implements it; tests implement it with
+ * plain objects.
+ */
+export interface SaasBackend {
+    /** Enumerate the connectable toolkits the catalog offers. */
+    listToolkits(): Promise<ToolkitInfo[]>;
+    /** Enumerate the callable operations exposed by one toolkit. */
+    listTools(toolkit: string): Promise<RemoteTool[]>;
+    /** Run a single operation by its slug, with already-parsed arguments. */
+    execute(toolName: string, args: unknown, opts: ExecuteOptions): Promise<RemoteResult>;
+    /** List the user's existing credential links across toolkits. */
+    listConnectedAccounts(): Promise<ConnectedAccount[]>;
+    /** Begin (or re-open) a connection/authorization flow for a toolkit. */
+    initiateConnection(toolkit: string, opts?: InitiateOptions): Promise<ConnectionRequest>;
+    /** Poll a previously initiated connection request for its current state. */
+    checkConnection(id: string): Promise<ConnectionState>;
+}

package/dist/types/connectors-saas/saas/core/scope-planner.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The {@link ScopePlanner} — a fluent, immutable builder that decides which
+ * toolkits and tools are in scope for a hydration or discovery request.
+ *
+ * The thing this replaces was a priority cascade: a method that looked at an
+ * options bag and, through a chain of `if` branches, picked "explicit tool slugs,
+ * else the toolkit union, else the auth-config set, else throw." That structure is
+ * both hard to read and easy to fingerprint. Here the decision is expressed as
+ * *accumulated intent* instead: the caller declares what they want
+ * (`.include(toolkit)`, `.only(toolNames)`), and a single {@link ScopePlanner.plan}
+ * step resolves that intent into one of three explicit {@link ScopeKind} shapes —
+ * `byTools`, `byToolkits`, or `empty` — with no nested branching.
+ *
+ * Every mutator returns a *new* planner; the receiver is never changed. That makes
+ * a planner safe to share, fork, and reuse as a base for several requests. The
+ * builder holds only normalized data (deduped, trimmed); resolution into a
+ * {@link ResolvedScope} happens once, at `plan()`.
+ */
+/**
+ * The three resolved shapes a scope can take, discriminated by `kind`.
+ *
+ * - `byTools` — an explicit set of fully-qualified tool slugs (the most specific
+ *   intent; toolkits are implied by the slugs and carried alongside for context).
+ * - `byToolkits` — one or more whole toolkits, every tool in scope.
+ * - `empty` — nothing was declared; the caller must treat this as "no scope".
+ */
+export type ResolvedScope = {
+    readonly kind: "byTools";
+    readonly tools: readonly string[];
+    readonly toolkits: readonly string[];
+} | {
+    readonly kind: "byToolkits";
+    readonly toolkits: readonly string[];
+} | {
+    readonly kind: "empty";
+};
+/** The discriminant tag of a {@link ResolvedScope}. */
+export type ScopeKind = ResolvedScope["kind"];
+/**
+ * An immutable builder of connector scope.
+ *
+ * Construct one with {@link ScopePlanner.create}, narrow it with the fluent
+ * mutators, and resolve it with {@link ScopePlanner.plan}. No mutator alters the
+ * instance it is called on.
+ */
+export declare class ScopePlanner {
+    private readonly toolkits;
+    private readonly tools;
+    private constructor();
+    /** Start from an empty scope — nothing included, nothing pinned. */
+    static create(): ScopePlanner;
+    /**
+     * Add one or more toolkits to the scope. Returns a new planner with those
+     * toolkits unioned into the existing set; duplicates and blanks are dropped.
+     */
+    include(...toolkits: string[]): ScopePlanner;
+    /**
+     * Pin the scope to specific tool slugs. Returns a new planner whose tool set is
+     * the union of the prior pinned tools and these. Pinned tools take precedence
+     * over a bare toolkit list when the scope is resolved.
+     */
+    only(...toolNames: string[]): ScopePlanner;
+    /** Whether anything at all has been declared. */
+    isEmpty(): boolean;
+    /**
+     * Resolve the accumulated intent into one explicit {@link ResolvedScope}.
+     *
+     * Pinned tools win: if any were declared, the scope is `byTools` (carrying the
+     * included toolkits as context). Otherwise, if toolkits were included, it is
+     * `byToolkits`. With nothing declared the scope is `empty` — callers decide
+     * whether that is an error in their context.
+     */
+    plan(): ResolvedScope;
+}

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

@@ -0,0 +1,133 @@
+/**
+ * The {@link SaasGateway} — the stateful façade that assembles the SaaS connector
+ * bridge into one runnable object.
+ *
+ * The `core/` layer is deliberately stateless: a port, a scope planner, a content
+ * hash cache, a single remote-tool builder, a declarative control-tool table. The
+ * `render/` layer is pure. What was missing was the thing that *owns state* and
+ * wires those pieces together: a live {@link ToolRegistry} that hydrated remote
+ * tools are registered into, a {@link ScopePlanner} that records what is in scope,
+ * a {@link HashCache} that dedupes repeated `enableToolkit` work by content hash,
+ * and the {@link CONNECT_RULES}-driven connection driver. That is this gateway.
+ *
+ * It exposes three tool surfaces and the verbs the control tools delegate to:
+ *
+ * - {@link SaasGateway.controlToolBox} — just the four control tools
+ *   (`saas_enable` / `saas_execute` / `saas_connect` / `saas_status`), the surface
+ *   an agent starts with before any toolkit is hydrated.
+ * - {@link SaasGateway.enableToolkit} — list a toolkit's remote operations, wrap
+ *   each into a native {@link DefinedTool} via the core builder, register them into
+ *   the live registry, and content-hash-cache the resulting defs so a second enable
+ *   of the same shape is a no-op that returns the very same tools.
+ * - {@link SaasGateway.toolBox} — the control tools plus every remote tool hydrated
+ *   so far, the surface to hand the model once toolkits are live.
+ *
+ * Nothing here imports the vendor SDK: the gateway depends only on the
+ * {@link SaasBackend} port. {@link createComposioGateway} is the one convenience
+ * that pairs this gateway with the real Composio adapter.
+ */
+import type { DefinedTool, ToolResult } from "../../capabilities";
+import type { ToolBox } from "../../runtime/contract";
+import { type SaasBackend, type ConnectedAccount } from "./core/index";
+import { type AwaitOptions } from "./control/connect";
+/**
+ * The outcome of hydrating a toolkit, returned by {@link SaasGateway.enable} and
+ * rendered by the `saas_enable` control tool. `hydrated` is the model-facing names
+ * of the tools now callable; `tools` are the {@link DefinedTool}s themselves.
+ */
+export interface EnableReport {
+    /** The toolkit that was hydrated. */
+    readonly toolkit: string;
+    /** The model-facing names of the now-callable remote tools. */
+    readonly hydrated: readonly string[];
+    /** The hydrated tool objects (same identities a second cached enable returns). */
+    readonly tools: readonly DefinedTool[];
+    /** True when this enable was served entirely from the content-hash cache. */
+    readonly cached: boolean;
+}
+/**
+ * The outcome of driving a connection flow, returned by {@link SaasGateway.connect}
+ * and rendered by the `saas_connect` control tool. `action` mirrors the terminal
+ * {@link ConnectOutcome} the rule-table driver settled on.
+ */
+export interface ConnectReport {
+    /** The toolkit the connection targeted. */
+    readonly toolkit: string;
+    /** The terminal disposition of the attempt. */
+    readonly action: "done" | "await-auth" | "expired" | "failed";
+    /** The connection request id that was driven. */
+    readonly requestId: string;
+    /** The authorization URL to surface, when the user still has to act. */
+    readonly authUrl?: string;
+    /** The connected-account id, once the link went active. */
+    readonly accountId?: string;
+    /** A human-readable failure reason when `action` is `"failed"`. */
+    readonly reason?: string;
+}
+/** A point-in-time snapshot of the bridge's connection + scope state. */
+export interface StatusReport {
+    /** The user's connected accounts, as the backend reports them. */
+    readonly accounts: readonly ConnectedAccount[];
+    /** The model-facing names of every remote tool currently in scope. */
+    readonly enabledTools: readonly string[];
+}
+/** Tuning knobs for {@link createSaasGateway}. */
+export interface SaasGatewayOptions {
+    /** Pin all remote execution to one connected account; omit to let the backend pick. */
+    readonly accountId?: string;
+    /** Connection-driver pacing/bounding, forwarded to {@link initiateAndAwait}. */
+    readonly connect?: Pick<AwaitOptions, "pollIntervalMs" | "maxPolls" | "sleep">;
+}
+/**
+ * The stateful façade over the SaaS connector bridge.
+ *
+ * The verbs ({@link SaasGateway.enable}, {@link SaasGateway.execute},
+ * {@link SaasGateway.connect}, {@link SaasGateway.status}) are what the control
+ * tools delegate to; the three `*ToolBox` / `enableToolkit` methods are the
+ * assembly surface a host wires into an agent session.
+ */
+export interface SaasGateway {
+    /** The backend port this gateway drives. */
+    readonly backend: SaasBackend;
+    /** A {@link ToolBox} of just the four control tools. */
+    controlToolBox(): ToolBox;
+    /** A {@link ToolBox} of the control tools plus every hydrated remote tool. */
+    toolBox(): ToolBox;
+    /**
+     * Hydrate a toolkit's remote operations into the live registry and return the
+     * minted tools. Content-hash-cached: a second call with the same shape returns
+     * the identical tool defs without re-listing or re-registering.
+     */
+    enableToolkit(name: string, only?: readonly string[]): Promise<DefinedTool[]>;
+    /** The verb behind `saas_enable`: hydrate a toolkit and report on it. */
+    enable(toolkit: string, only?: readonly string[]): Promise<EnableReport>;
+    /** The verb behind `saas_execute`: run one remote operation directly by slug. */
+    execute(tool: string, args: unknown, accountId?: string): Promise<ToolResult>;
+    /** The verb behind `saas_connect`: drive an authorization flow to a terminal state. */
+    connect(toolkit: string, opts?: {
+        callbackUrl?: string;
+        authConfigId?: string;
+    }): Promise<ConnectReport>;
+    /** The verb behind `saas_status`: the current connection + scope picture. */
+    status(): Promise<StatusReport>;
+}
+/**
+ * Assemble a {@link SaasGateway} over a {@link SaasBackend}.
+ *
+ * The gateway owns a fresh {@link ScopePlanner}-driven scope, a live
+ * {@link ToolRegistry}, and the content-hash enable cache from the moment it is
+ * built; the four control tools are registered immediately so
+ * {@link SaasGateway.controlToolBox} is usable before any toolkit is hydrated.
+ */
+export declare function createSaasGateway(backend: SaasBackend, opts?: SaasGatewayOptions): SaasGateway;
+/**
+ * Convenience: assemble a {@link SaasGateway} wired to the real Composio adapter.
+ *
+ * This is the one place the gateway touches the vendor seam, and it does so only
+ * transitively — {@link createComposioBackend} is the lone `@composio/core`
+ * importer. Hand it an API key and the returned gateway is ready to enable
+ * toolkits against the live catalog.
+ */
+export declare function createComposioGateway(opts: {
+    apiKey: string;
+}): SaasGateway;

package/dist/types/connectors-saas/saas/render/format.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Human-readable text rendering for the SaaS bridge's discovery and linking views.
+ *
+ * Where {@link "./summarizers"} answers "what did *one* result say in a line", this
+ * module answers "how do I show a *list* of remote tools, or the current connection
+ * picture, as a readable block". These are the formatters the control tools and the
+ * gateway reach for when they want prose rather than raw JSON — a toolkit roster, an
+ * operation catalog, a connected-account summary, a freshly opened link request.
+ *
+ * Everything here is pure: data in, string out, no I/O and no backend. Each function
+ * returns a single text block (lines joined by `\n`) so callers can drop it straight
+ * into a `{ kind: "text", text }` content block. The formatting is deliberately
+ * plain — aligned-ish lists and short headers — so it reads well both in a terminal
+ * and when handed back to the model.
+ */
+import type { ToolkitInfo, RemoteTool, ConnectedAccount, ConnectionRequest, ConnectionState } from "../core/port";
+/**
+ * Render the connectable-toolkit roster.
+ *
+ * One line per toolkit: a connection mark when the backend reported `connected`,
+ * the slug, the human name, and a clipped description. An empty catalog renders a
+ * single explanatory line rather than a bare header.
+ */
+export declare function formatToolkitList(toolkits: readonly ToolkitInfo[]): string;
+/**
+ * Render the operations one toolkit exposes.
+ *
+ * One line per operation: its invocation slug and a clipped description. The header
+ * names the toolkit (taken from the first entry) so the block is self-describing.
+ */
+export declare function formatToolList(tools: readonly RemoteTool[]): string;
+/**
+ * Render the user's connected accounts.
+ *
+ * One line per account: its normalized status, the toolkit it links, its id, and the
+ * last-updated timestamp when the backend supplied one. An empty list renders a
+ * single line inviting a connect flow.
+ */
+export declare function formatConnectedAccounts(accounts: readonly ConnectedAccount[]): string;
+/**
+ * Render a freshly opened connection request.
+ *
+ * Surfaces the actionable bit first: an `authUrl` to visit when one is present, an
+ * "already active" note when it is, or the raw status otherwise. The request id is
+ * always shown so the user can poll it via saas.status.
+ */
+export declare function formatConnectionRequest(request: ConnectionRequest): string;
+/**
+ * Render a polled connection-request snapshot.
+ *
+ * Shows the request's current status and, depending on where it is, either the
+ * linked account id (once active) or a still-pending authorization URL.
+ */
+export declare function formatConnectionState(state: ConnectionState): string;

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

@@ -0,0 +1,19 @@
+/**
+ * The render layer of the SaaS connector bridge — public surface.
+ *
+ * This barrel gathers the two presentation concerns of the bridge so callers can
+ * pull either from one place:
+ *
+ * - **Summarization** ({@link "./summarizers"}) — the pluggable {@link SUMMARIZERS}
+ *   registry and {@link summarizeResult}, which fold one operation's
+ *   {@link RemoteResult} into a single dedupe-aware line.
+ * - **Formatting** ({@link "./format"}) — the pure functions that render a toolkit
+ *   roster, an operation catalog, or the connection picture into readable text
+ *   blocks.
+ *
+ * Nothing here touches the vendor SDK; everything reads the bridge's own `core/`
+ * vocabulary and returns plain strings.
+ */
+export { SUMMARIZERS, summarizeResult, defaultSummarizer, toolkitOf, } from "./summarizers";
+export type { Summarizer } from "./summarizers";
+export { formatToolkitList, formatToolList, formatConnectedAccounts, formatConnectionRequest, formatConnectionState, } from "./format";

package/dist/types/connectors-saas/saas/render/summarizers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The pluggable result-summarizer registry.
+ *
+ * When a remote operation returns, the bridge wants *one short line* describing
+ * what came back — for a log entry, a status header, or a glance in the tool list.
+ * Different toolkits want different one-liners: a mail send is best summarized by
+ * its recipient, a list endpoint by its row count, a search by its top hit. Rather
+ * than bake a tower of `if (toolkit === …)` branches into one formatter, the choice
+ * is a lookup: {@link SUMMARIZERS} maps a toolkit slug (or a `prefix:*` glob) to a
+ * `(result) => string`, and {@link summarizeResult} picks the most specific match,
+ * falling back to a generic compact JSON preview.
+ *
+ * The default summarizer is the interesting one. It produces a short preview of the
+ * payload while **deduping repeated blobs**: large structured responses often carry
+ * the same nested object many times (the same author on every row, the same schema
+ * on every field), and naively previewing them buries the signal. So the default
+ * walks the payload *iteratively* — an explicit stack, never recursion, so a deep or
+ * cyclic response can never blow the call stack — content-hashes every object and
+ * array it meets, and replaces any repeat with a back-reference to where it first
+ * appeared. The result is a compact, de-duplicated sketch of the shape.
+ */
+import type { RemoteResult } from "../core/port";
+/**
+ * A function that renders one {@link RemoteResult} into a single human-readable
+ * line. Registered against a toolkit slug or a `prefix:*` pattern in
+ * {@link SUMMARIZERS} and selected by {@link summarizeResult}.
+ */
+export type Summarizer = (result: RemoteResult) => string;
+/**
+ * The toolkit slug a `<toolkit>_<operation>` (or `<toolkit>.<operation>`) tool name
+ * implies, lower-cased. Plain names with no separator are returned whole. This is
+ * what {@link summarizeResult} keys the registry lookup on.
+ */
+export declare function toolkitOf(toolName: string): string;
+/**
+ * The fallback summarizer used when no toolkit-specific entry matches.
+ *
+ * A failure renders as its error line; a success renders as a deduped JSON preview
+ * of its payload (see {@link previewPayload}). The line is always length-clamped.
+ */
+export declare function defaultSummarizer(result: RemoteResult): string;
+/**
+ * The summarizer registry: toolkit slug (or `prefix:*` glob) → {@link Summarizer}.
+ *
+ * Exact slugs win over globs, and globs win over the built-in default. Entries are
+ * added here (or at runtime via the exported map) to teach the bridge how to phrase
+ * a given product's results. The starter rows below are illustrative, declarative
+ * data — extend the table, don't fork the formatter.
+ */
+export declare const SUMMARIZERS: Map<string, Summarizer>;
+/**
+ * Summarize one operation's result in a single line.
+ *
+ * Selection is most-specific-first: an exact toolkit-slug entry, then a `prefix:*`
+ * glob whose prefix the slug starts with (longest prefix wins), then the built-in
+ * {@link defaultSummarizer}. The chosen summarizer is handed the raw result.
+ */
+export declare function summarizeResult(toolName: string, result: RemoteResult): string;

package/dist/types/facade/agent.d.ts

@@ -0,0 +1 @@
+export * from "./bot/index";

package/dist/types/facade/ai.d.ts

@@ -0,0 +1 @@
+export * from "./ml/index";

package/dist/types/facade/bot/actions/bash.d.ts

@@ -0,0 +1,56 @@
+import type { AgentTool } from "../types.js";
+import type { HookRunner } from "./kit/hook-runner.js";
+import { type TruncationResult } from "./truncate.js";
+export interface BashSecurityConfig {
+    /** Patterns that, when matched, stop a command from running. */
+    blockedPatterns?: RegExp[];
+}
+declare const bashSchema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TString;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>;
+export interface BashToolDetails {
+    truncation?: TruncationResult;
+    fullOutputPath?: string;
+}
+/**
+ * Pluggable execution backend for the bash tool. Provide a custom implementation
+ * to dispatch commands somewhere other than the local shell, for instance to a
+ * remote host over a transport layer.
+ */
+export interface BashOperations {
+    /**
+     * Execute a command, relaying its output back through a callback as it streams in.
+     * @param command - The command line to execute
+     * @param cwd - Working directory for the command
+     * @param options - Streaming callback, cancellation signal, timeout, and env overrides
+     * @returns A promise resolving to the exit code, or null if the process was terminated
+     */
+    exec: (command: string, cwd: string, options: {
+        onData: (data: Buffer) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+        env?: NodeJS.ProcessEnv;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+}
+export interface BashToolOptions {
+    /** Backend hook for running commands. When omitted, the local shell is used. */
+    operations?: BashOperations;
+    /** Text glued to the front of every command (e.g. "shopt -s expand_aliases" to enable aliases). */
+    commandPrefix?: string;
+    /** Dispatcher consulted for the shell.env hook so callers can inject env vars. */
+    hookRunner?: HookRunner;
+    /** Settings that decide which commands are allowed to run. */
+    security?: BashSecurityConfig;
+    /** Optional log that collects the commands as they are issued. */
+    commandHistory?: string[];
+}
+export declare function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema>;
+/** Ready-made bash tool bound to the process working directory. */
+export declare const bashTool: AgentTool<import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TString;
+    timeout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+}>, any>;
+export {};

package/dist/types/facade/bot/actions/composio/accounts.d.ts

@@ -0,0 +1,22 @@
+import type { AgentTool } from "../../types.js";
+import { ComposioService } from "./client.js";
+import type { ComposioToolFactoryOptions } from "./types.js";
+declare const composioAccountsSchema: import("@sinclair/typebox").TObject<{
+    toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    statuses: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    authConfigIds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+}>;
+export type ComposioAccountsToolDetails = Awaited<ReturnType<ComposioService["listAccounts"]>> & {
+    userId: string;
+};
+export declare function createComposioAccountsTool(options?: ComposioToolFactoryOptions): AgentTool<typeof composioAccountsSchema, ComposioAccountsToolDetails>;
+export declare const composioAccountsTool: AgentTool<import("@sinclair/typebox").TObject<{
+    toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    statuses: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    cursor: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    authConfigIds: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+}>, ComposioAccountsToolDetails>;
+export {};