@introspection-ai/recipes 0.20.0 → 0.22.0

package/README.md

@@ -129,6 +129,11 @@ tests.
 - `@introspection-ai/recipes/pi-extension` — Pi extension entrypoint
 - `@introspection-ai/recipes/extensions` — session identity and conditional
   Recipe extension helpers
+- `@introspection-ai/recipes/channels` is the provider neutral `channel_*` tool
+  contract: capability descriptors, opaque message references, and the
+  registration that binds every tool to the task's own conversation
+- `@introspection-ai/recipe-channel-slack` is the optional Slack adapter. A
+  Recipe adds it as a dependency when it declares Slack in `pi.connectors`.
 - `@introspection-ai/recipes/agents` — portable agent-run controller and tool
   contract
 - `@introspection-ai/recipes/interactions` — portable user-input and approval contract
@@ -148,10 +153,11 @@ adapters and deployment cookbooks belong outside this package.
 introspection check
 ```
 
-Every `pi --recipe` launch automatically runs the same Recipe Format validator
-before constructing a session. Invalid Recipes stop Pi rather than falling back
-to an unconfigured agent. `introspection check` remains the explicit command
-for manual and CI validation.
+Validation is an authoring and host concern, not a launch-time one. Run
+`introspection check` while authoring and in CI; a host that executes Recipes
+should validate before it starts a session, as the Introspection platform does
+when a task is created. A `pi --recipe` launch does **not** re-validate, so a
+Recipe that was never checked can start with errors the validator would catch.
 
 ## Documentation
 

package/dist/channels/index.d.ts

@@ -0,0 +1,7 @@
+export { ChannelRefStore } from "./refs.js";
+export { CHANNEL_TOOL_IDS, channelConnectorTools, channelToolIdsFor, channelToolName, registerChannelTools, } from "./tools.js";
+export type { ChannelToolHost, ChannelToolId, RegisterChannelToolsOptions, } from "./tools.js";
+export { createChannelConnectorModule } from "./module.js";
+export type { ChannelConnectorModuleOptions, ChannelConnectorSession, } from "./module.js";
+export type { ChannelAdapter, ChannelAdapterContext, ChannelAttachment, ChannelAuthor, ChannelCapabilities, ChannelCursor, ChannelFileIdentity, ChannelReadPage, ChannelLocalFile, ChannelMessage, ChannelMessageIdentity, ChannelPostResult, ChannelReactionAction, ChannelRefResolver, ChannelTarget, FileRef, MessageRef, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,aAAa,EACb,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAC3D,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,OAAO,EACP,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/channels/index.js

@@ -0,0 +1,4 @@
+export { ChannelRefStore } from "./refs.js";
+export { CHANNEL_TOOL_IDS, channelConnectorTools, channelToolIdsFor, channelToolName, registerChannelTools, } from "./tools.js";
+export { createChannelConnectorModule } from "./module.js";
+//# sourceMappingURL=index.js.map

package/dist/channels/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAMpB,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC"}

package/dist/channels/module.d.ts

@@ -0,0 +1,43 @@
+import type { RecipeConnectorModule } from "../connector-tools.js";
+import type { ChannelAdapter, ChannelCapabilities, ChannelTarget } from "./types.js";
+export interface ChannelConnectorSession {
+    readonly adapter: ChannelAdapter;
+    /** Resolved lazily so a task with no channel origin still starts. */
+    readonly target: ChannelTarget | (() => ChannelTarget);
+}
+export interface ChannelConnectorModuleOptions {
+    provider: string;
+    /**
+     * What this channel supports, as static data.
+     *
+     * Declared separately from `createSession` because the loader builds the tool
+     * catalog before any session exists. A capability discovered by failing a
+     * call would also waste an agent turn.
+     */
+    capabilities: ChannelCapabilities;
+    /**
+     * Resolve the bound conversation and a client for it.
+     *
+     * Called once per session. Throwing is the right failure for a task with no
+     * channel origin: the tools would have nowhere to act.
+     */
+    createSession(options: {
+        env: NodeJS.ProcessEnv;
+        cwd: string;
+    }): ChannelConnectorSession;
+}
+/**
+ * Build a `RecipeConnectorModule` from a channel adapter.
+ *
+ * A provider package supplies transport plus a capability descriptor; the
+ * neutral tool schemas, the opaque handles, and the capability filtering live
+ * here. Two providers therefore cannot drift into differently-shaped versions
+ * of the same operation, and neither can quietly grow an addressing argument,
+ * because neither writes a tool schema at all.
+ *
+ * The result satisfies the existing connector contract. The manifest selects
+ * the provider package, the agent list selects tools from its catalog, and
+ * `tool_search` exposes selected tools that are not active by default.
+ */
+export declare function createChannelConnectorModule(options: ChannelConnectorModuleOptions): RecipeConnectorModule;
+//# sourceMappingURL=module.d.ts.map

package/dist/channels/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/channels/module.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAQnE,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,MAAM,aAAa,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,EAAE,mBAAmB,CAAC;IAClC;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE;QACrB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;QACvB,GAAG,EAAE,MAAM,CAAC;KACb,GAAG,uBAAuB,CAAC;CAC7B;AAgBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,qBAAqB,CA+CvB"}

package/dist/channels/module.js

@@ -0,0 +1,61 @@
+import { ChannelRefStore } from "./refs.js";
+import { CHANNEL_TOOL_IDS, channelConnectorTools, registerChannelTools, } from "./tools.js";
+const channelToolIds = new Set(CHANNEL_TOOL_IDS);
+/** Whether two capability descriptors say the same thing. */
+function sameCapabilities(left, right) {
+    const keys = Object.keys(right);
+    return (Object.keys(left).length === keys.length &&
+        keys.every((key) => left[key] === right[key]));
+}
+/**
+ * Build a `RecipeConnectorModule` from a channel adapter.
+ *
+ * A provider package supplies transport plus a capability descriptor; the
+ * neutral tool schemas, the opaque handles, and the capability filtering live
+ * here. Two providers therefore cannot drift into differently-shaped versions
+ * of the same operation, and neither can quietly grow an addressing argument,
+ * because neither writes a tool schema at all.
+ *
+ * The result satisfies the existing connector contract. The manifest selects
+ * the provider package, the agent list selects tools from its catalog, and
+ * `tool_search` exposes selected tools that are not active by default.
+ */
+export function createChannelConnectorModule(options) {
+    const connectorTools = channelConnectorTools(options.capabilities);
+    const deferredToolIds = new Set(connectorTools
+        .filter((tool) => !tool.defaultActive)
+        .map((tool) => tool.id));
+    return {
+        provider: options.provider,
+        tools: connectorTools,
+        createExtension(moduleOptions) {
+            const unknown = moduleOptions.tools.filter((tool) => !channelToolIds.has(tool));
+            if (unknown.length > 0) {
+                throw new Error(`Unknown ${options.provider} channel tool(s): ${unknown.join(", ")}`);
+            }
+            const tools = moduleOptions.tools;
+            return (pi) => {
+                const session = options.createSession({
+                    env: moduleOptions.env ?? process.env,
+                    cwd: moduleOptions.cwd ?? process.cwd(),
+                });
+                if (session.adapter.provider !== options.provider) {
+                    throw new Error(`Channel adapter for '${options.provider}' returned provider '${session.adapter.provider}'`);
+                }
+                if (!sameCapabilities(session.adapter.capabilities, options.capabilities)) {
+                    // The loader selected tools from the declared catalog. An adapter
+                    // with a different capability set would register a different tool
+                    // surface. Compare values so an adapter may rebuild the descriptor.
+                    throw new Error(`Channel adapter '${options.provider}' returned capabilities that differ from its declared catalog`);
+                }
+                registerChannelTools(pi, session.adapter, {
+                    target: session.target,
+                    tools,
+                    deferredTools: tools.filter((tool) => deferredToolIds.has(tool)),
+                    refs: new ChannelRefStore(),
+                });
+            };
+        },
+    };
+}
+//# sourceMappingURL=module.js.map

package/dist/channels/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/channels/module.ts"],"names":[],"mappings":"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"}

package/dist/channels/refs.d.ts

@@ -0,0 +1,28 @@
+import type { ChannelCursor, ChannelFileIdentity, ChannelMessageIdentity, ChannelRefResolver, FileRef, MessageRef } from "./types.js";
+/**
+ * Session-scoped opaque handles for messages and pagination cursors.
+ *
+ * The model only ever sees a handle this store minted, so it cannot name a
+ * message it was never shown, and provider id formats stay out of tool schemas.
+ * The store is also where authorship lives. `resolveAuthored` is the single
+ * check behind `channel_edit` and `channel_retract`, which keeps those tools
+ * scoped to the agent's own messages rather than everything the provider
+ * credential could reach.
+ * Handles die with the session. A ref from an earlier task is unresolvable
+ * rather than dangerous.
+ */
+export declare class ChannelRefStore implements ChannelRefResolver {
+    private readonly messages;
+    private readonly byIdentity;
+    private readonly cursors;
+    private readonly files;
+    private readonly byFileIdentity;
+    message(identity: ChannelMessageIdentity): MessageRef;
+    resolveMessage(ref: MessageRef): ChannelMessageIdentity;
+    resolveAuthored(ref: MessageRef): ChannelMessageIdentity;
+    cursor(providerCursor: string): ChannelCursor;
+    resolveCursor(cursor: ChannelCursor): string;
+    file(identity: ChannelFileIdentity): FileRef;
+    resolveFile(ref: FileRef): ChannelFileIdentity;
+}
+//# sourceMappingURL=refs.d.ts.map

package/dist/channels/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/channels/refs.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,OAAO,EACP,UAAU,EACX,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,YAAW,kBAAkB;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiD;IAC1E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2C;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAE7D,OAAO,CAAC,QAAQ,EAAE,sBAAsB,GAAG,UAAU,CAiBpD;IAED,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,sBAAsB,CAQtD;IAED,eAAe,CAAC,GAAG,EAAE,UAAU,GAAG,sBAAsB,CAQvD;IAED,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAI5C;IAED,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAQ3C;IAED,IAAI,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAQ3C;IAED,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAW7C;CACF"}

package/dist/channels/refs.js

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+const MESSAGE_PREFIX = "msg_";
+const CURSOR_PREFIX = "cur_";
+const FILE_PREFIX = "file_";
+function handle(prefix) {
+    return `${prefix}${randomUUID().replaceAll("-", "").slice(0, 16)}`;
+}
+/**
+ * Session-scoped opaque handles for messages and pagination cursors.
+ *
+ * The model only ever sees a handle this store minted, so it cannot name a
+ * message it was never shown, and provider id formats stay out of tool schemas.
+ * The store is also where authorship lives. `resolveAuthored` is the single
+ * check behind `channel_edit` and `channel_retract`, which keeps those tools
+ * scoped to the agent's own messages rather than everything the provider
+ * credential could reach.
+ * Handles die with the session. A ref from an earlier task is unresolvable
+ * rather than dangerous.
+ */
+export class ChannelRefStore {
+    messages = new Map();
+    byIdentity = new Map();
+    cursors = new Map();
+    files = new Map();
+    byFileIdentity = new Map();
+    message(identity) {
+        const key = `${identity.conversation} ${identity.id}`;
+        const existing = this.byIdentity.get(key);
+        if (existing) {
+            const previous = this.messages.get(existing);
+            this.messages.set(existing, {
+                ...previous,
+                ...identity,
+                authoredByAgent: previous.authoredByAgent || identity.authoredByAgent,
+                permalink: identity.permalink ?? previous.permalink,
+            });
+            return existing;
+        }
+        const ref = handle(MESSAGE_PREFIX);
+        this.messages.set(ref, identity);
+        this.byIdentity.set(key, ref);
+        return ref;
+    }
+    resolveMessage(ref) {
+        const identity = this.messages.get(ref);
+        if (!identity) {
+            throw new Error(`Unknown message reference '${ref}'. Use a reference returned by a channel tool in this session.`);
+        }
+        return identity;
+    }
+    resolveAuthored(ref) {
+        const identity = this.resolveMessage(ref);
+        if (!identity.authoredByAgent) {
+            throw new Error(`Message '${ref}' was not sent by this agent. Only messages the agent posted can be edited or retracted.`);
+        }
+        return identity;
+    }
+    cursor(providerCursor) {
+        const cursor = handle(CURSOR_PREFIX);
+        this.cursors.set(cursor, providerCursor);
+        return cursor;
+    }
+    resolveCursor(cursor) {
+        const providerCursor = this.cursors.get(cursor);
+        if (!providerCursor) {
+            throw new Error(`Unknown cursor '${cursor}'. Use a cursor returned by a previous channel_read call.`);
+        }
+        return providerCursor;
+    }
+    file(identity) {
+        const key = `${identity.conversation} ${identity.id}`;
+        const existing = this.byFileIdentity.get(key);
+        if (existing)
+            return existing;
+        const ref = handle(FILE_PREFIX);
+        this.files.set(ref, identity);
+        this.byFileIdentity.set(key, ref);
+        return ref;
+    }
+    resolveFile(ref) {
+        const identity = this.files.get(ref);
+        if (!identity) {
+            // The whole point: a provider file id the model invented resolves to
+            // nothing, so `channel_fetch_file` can only reach files this
+            // conversation actually carried.
+            throw new Error(`Unknown file reference '${ref}'. Use a file reference from a message in this conversation.`);
+        }
+        return identity;
+    }
+}
+//# sourceMappingURL=refs.js.map

package/dist/channels/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/channels/refs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAWzC,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,aAAa,GAAG,MAAM,CAAC;AAC7B,MAAM,WAAW,GAAG,OAAO,CAAC;AAE5B,SAAS,MAAM,CAAC,MAAc;IAC5B,OAAO,GAAG,MAAM,GAAG,UAAU,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,eAAe;IACT,QAAQ,GAAG,IAAI,GAAG,EAAsC,CAAC;IACzD,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC3C,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC3C,KAAK,GAAG,IAAI,GAAG,EAAgC,CAAC;IAChD,cAAc,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE7D,OAAO,CAAC,QAAgC;QACtC,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,YAAY,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;YAC9C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE;gBAC1B,GAAG,QAAQ;gBACX,GAAG,QAAQ;gBACX,eAAe,EAAE,QAAQ,CAAC,eAAe,IAAI,QAAQ,CAAC,eAAe;gBACrE,SAAS,EAAE,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS;aACpD,CAAC,CAAC;YACH,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC9B,OAAO,GAAG,CAAC;IACb,CAAC;IAED,cAAc,CAAC,GAAe;QAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,8BAA8B,GAAG,gEAAgE,CAClG,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,eAAe,CAAC,GAAe;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,YAAY,GAAG,0FAA0F,CAC1G,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,cAAsB;QAC3B,MAAM,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;QACzC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,aAAa,CAAC,MAAqB;QACjC,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAChD,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,mBAAmB,MAAM,2DAA2D,CACrF,CAAC;QACJ,CAAC;QACD,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,CAAC,QAA6B;QAChC,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,YAAY,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;QACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QAChC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC9B,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAClC,OAAO,GAAG,CAAC;IACb,CAAC;IAED,WAAW,CAAC,GAAY;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,qEAAqE;YACrE,6DAA6D;YAC7D,iCAAiC;YACjC,MAAM,IAAI,KAAK,CACb,2BAA2B,GAAG,8DAA8D,CAC7F,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/channels/tools.d.ts

@@ -0,0 +1,56 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ChannelRefStore } from "./refs.js";
+import type { ChannelAdapter, ChannelCapabilities, ChannelTarget } from "./types.js";
+/**
+ * The neutral operation vocabulary.
+ *
+ * These ids are private to the channel implementation. An agent writes the
+ * complete `channel_<id>` name in its YAML tool list.
+ */
+export declare const CHANNEL_TOOL_IDS: readonly ["reply", "read", "react", "edit", "retract", "attach", "fetch_file", "post_document"];
+export type ChannelToolId = (typeof CHANNEL_TOOL_IDS)[number];
+export declare function channelToolName(id: ChannelToolId): string;
+/** Which operations an adapter's capabilities actually support. */
+export declare function channelToolIdsFor(capabilities: ChannelCapabilities): ChannelToolId[];
+export declare function channelConnectorTools(capabilities: ChannelCapabilities): {
+    id: "attach" | "edit" | "fetch_file" | "post_document" | "react" | "read" | "reply" | "retract";
+    name: string;
+    defaultActive: boolean;
+}[];
+export interface RegisterChannelToolsOptions {
+    /**
+     * The bound conversation, or a thunk resolving it.
+     *
+     * Resolved by the host, never from model input. A thunk defers the "this
+     * task has no channel origin" failure to the first tool call, so a Recipe
+     * that declares a channel connector still starts when the same Recipe is
+     * run from a non-channel trigger such as an automation.
+     */
+    target: ChannelTarget | (() => ChannelTarget);
+    /** Restrict registration to these ids; defaults to everything supported. */
+    tools?: readonly ChannelToolId[];
+    /** Selected tools that require `tool_search` before the model may call them. */
+    deferredTools?: readonly ChannelToolId[];
+    refs?: ChannelRefStore;
+}
+/** Host surface used here. Opaque so Pi's TypeBox copy stays behind this seam. */
+export interface ChannelToolHost {
+    registerTool(...args: never[]): unknown;
+    on: ExtensionAPI["on"];
+}
+/**
+ * Register the bound channel tools an adapter supports.
+ *
+ * Two invariants are enforced by construction rather than by review:
+ *
+ * 1. **No schema below carries a conversation, thread, workspace, or user
+ *    argument.** The conversation comes from `options.target`, closed over
+ *    here. A model that cannot name a destination cannot reach one, so an
+ *    agent bound to a thread stays bound to that thread even if the underlying
+ *    credential could reach the whole workspace.
+ * 2. **Unsupported operations are absent**, not stubs that answer "this
+ *    channel cannot do that" — such a stub costs a turn every time and teaches
+ *    the model nothing durable.
+ */
+export declare function registerChannelTools(pi: ChannelToolHost, adapter: ChannelAdapter, options: RegisterChannelToolsOptions): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/channels/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/channels/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EACV,cAAc,EAEd,mBAAmB,EAEnB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,YAC3B,OAAO,EACP,MAAM,EACN,OAAO,EACP,MAAM,EACN,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,eAAe,CACP,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAS9D,wBAAgB,eAAe,CAAC,EAAE,EAAE,aAAa,GAAG,MAAM,CAEzD;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,mBAAmB,GAChC,aAAa,EAAE,CAUjB;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,mBAAmB;;;;IAOtE;AAkCD,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;OAOG;IACH,MAAM,EAAE,aAAa,GAAG,CAAC,MAAM,aAAa,CAAC,CAAC;IAC9C,4EAA4E;IAC5E,KAAK,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACjC,gFAAgF;IAChF,aAAa,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IACxC,EAAE,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;CACxB;AA+CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,eAAe,EACnB,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,2BAA2B,GACnC,IAAI,CAsRN"}