@introspection-ai/recipes 0.22.1 → 0.24.0

package/docs/channels.md

@@ -1,90 +1,186 @@
 # Channel tools
 
 A Recipe that answers a chat message declares a **channel connector**. The host
-then registers a fixed set of `channel_*` tools, named and shaped identically
-for every provider, and bound to the one conversation the task came from.
+then registers one `channels` tool with a `command` discriminator, shaped identically
+for every provider. Reply defaults to the origin; adapters can opt into explicit
+read/send destinations within the same credential session.
 
 Two properties follow from that, and both are structural rather than
 conventional:
 
-- **The agent cannot address anything else.** No `channel_*` tool takes a
-  channel, thread, workspace, or user argument. The conversation is closed over
-  by the host from the task origin, so a compromised prompt has no vocabulary
-  for "post this somewhere else". The invariant is asserted by a test that
-  walks every registered tool's input schema.
-- **A tool that the provider cannot support is absent, not failing.** Each
+- **Explicit targeting is a capability.** `targeting: true` adds `channels send`
+  and channel/thread arguments to `channels read`. Adapters without it retain
+  bound schemas. Reply, attach, and document tools still use the origin.
+- **A command that the provider cannot support is absent, not failing.** Each
   adapter declares a capability descriptor, and registration filters on it.
-  For example, an adapter with no history API has no `channel_read` tool.
+  For example, an adapter with no history API has no `read` command.
 
-Before the first model call, the channel extension adds origin metadata to the
-system prompt. The metadata contains the provider, the conversation name and
-permalink when the adapter can resolve them, whether the origin is a thread,
-and the available channel tools. It contains no provider conversation IDs and
-no messages. The injected guidance tells the agent to deliver its user-facing
-response with `channel_reply`, because a normal final assistant response is not
-delivered to the originating channel. `channel_read` remains the only way to
-fetch earlier messages when the provider supports it.
+Agents select `tools: [channels]`. By default this exposes all operations supported
+by the adapter. To restrict commands for the recipe, set an allowlist on the
+connector in `package.json`:
 
-## The tools
+```json
+{"pi":{"channels":[{"provider":"slack","commands":["list","read","reply"]}]}}
+```
 
-| Tool | Model arguments | Requires |
+The allowlist applies to all agents using this connector; an empty list exposes
+no channel tool. Unknown or unsupported commands fail at registration. Commands
+outside the allowlist and invalid command arguments are rejected before provider
+calls. The host API uses `registerChannelTools(..., { commands: [...] })` for the
+same restriction.
+
+### Required replies
+
+`requireReply` defaults to `true` when channel tools are enabled: inbound turns
+must deliver a successful final `reply`. Set `requireReply: false` explicitly to
+opt out, for example for a read-only command allowlist. UI and automation turns
+without an origin are unaffected. Disabled channel tools remain disabled;
+an enabled connector with required replies must expose `reply`.
+
+`reply` accepts `final` (default `true`). Use `final: false` for progress updates.
+Only a successful final reply satisfies the guard, not reactions or explicit
+sends. The extension adds delivery instructions and queues one corrective
+follow-up if the agent finishes without replying. If that also finishes without
+a reply, a visible `channel-delivery-failed` message records the failure locally.
+It never automatically publishes private assistant text. Aborted and provider-error
+runs are not retried by this guard. Hosts must wait for `agent_settled`, not an
+intermediate `agent_end`, before declaring a run complete.
+
+Migration: rename `pi.connectors` to `pi.channels`, replace agent `channel_*` tool names with `channels`, and move any
+operation restrictions to `commands` (without the `channel_` prefix). This is a
+breaking interface change; old individual tool names are not registered.
+
+Before each agent run, the extension adds origin metadata to the system prompt:
+provider, channel/thread IDs, conversation scope, and optional name/permalink.
+Labels are untrusted metadata; normal assistant output is not delivered to the
+channel. Recipe instructions decide when to reply, stay silent, read history,
+or send elsewhere; tool descriptions explain how.
+
+User messages are not rewritten. Cloud ingress retains per-message `from`,
+`message_id`, and `sent_at` attribution. Legacy custom origin entries are
+filtered from model context when resuming older sessions.
+For required replies, the single corrective reminder repeats the origin metadata
+so a failed or omitted delivery can be retried against the correct destination.
+An uncertain delivery must be checked before retrying to avoid duplicates.
+Origin fields are JSON inside a single `<channel_context>` wrapper. JSON Unicode
+escapes for `<`, `>`, and `&` keep provider labels from breaking the wrapper while
+preserving valid JSON and the original values when parsed.
+
+The context message is not an authorization boundary. Tools continue to resolve
+the origin from host state, never from message text, and validate explicit targets
+through the host's policy. Non-channel triggers receive no channel context.
+
+## Test channel recipes
+
+Use `introspection dev` to test local recipe files through the platform's
+provider proxy. Standalone `SLACK_BOT_TOKEN` credentials and local destination
+aliases are no longer supported. Originless web and automation runs can still
+use explicit channel targets with the connected provider credentials.
+
+## Commands
+
+| Command (`channels` + `command`) | Additional arguments | Requires |
 | --- | --- | --- |
-| `channel_reply` | `text` (Markdown) | always |
-| `channel_read` | `limit?`, `cursor?` | `read` |
-| `channel_react` | `message`, `emoji`, `action?` (`add` or `remove`) | `react` |
-| `channel_edit` | `message`, `text` | `edit` |
-| `channel_retract` | `message` | `retract` |
-| `channel_attach` | `path`, `title?`, `comment?` | `attach` |
-| `channel_fetch_file` | `file` (a `file_…` handle), `variant?` | `fetch_file` |
-| `channel_post_document` | `title`, `markdown` | `documents` |
-
-`channel_reply`, `channel_read`, and `channel_react` are active by default when
-the provider supports them. The other selected tools start inactive, and the
-model can find them through `tool_search`.
+| `channels reply` | `text` (Markdown), `final?` (default `true`) | always |
+| `channels send` | `channel_id`, `thread_id?`, `text` | `targeting` |
+| `channels list` | none | `list` |
+| `channels read` | `channel_id?`, `thread_id?`, `limit?`, `cursor?` | `read`; addressing requires `targeting` |
+| `channels react` | `message`, `emoji`, `action?` (`add` or `remove`) | `react` |
+| `channels edit` | `message`, `text` | `edit` |
+| `channels retract` | `message` | `retract` |
+| `channels attach` | `path`, `title?`, `comment?` | `attach` |
+| `channels fetch_file` | `file` (a `file_…` handle), `variant?` | `fetch_file` |
+| `channels post_document` | `title`, `markdown` | `documents` |
+
+`channels` is active immediately. Its command schema includes only supported,
+allowed operations; no tool search is needed.
 
 Reply content is **Markdown**. Each adapter renders it in the provider's own
 format. There is no raw provider payload because the same tool contract must
 work with every adapter.
 
+### Targets and pagination
+
+- `channels({command: "list"})` returns the channels available to the provider credential session.
+- `channels({command: "read"})` reads the origin conversation.
+- `channels({command: "read", channel_id: "C2"})` reads that channel's timeline.
+- `channels({command: "read", channel_id: "C2", thread_id: "123.4"})` reads that thread.
+- `channels({command: "read", thread_id: null})` reads the origin channel timeline.
+- `channels({command: "send", channel_id: "C2", text: "Update"})` posts at channel level;
+  supplying `thread_id` posts inside that thread.
+
+An explicit channel does not require an origin, but still requires a working
+provider credential. Sending/reading never changes `channels reply`'s origin.
+Thread IDs are provider-native roots/topics, not opaque message handles or
+generic quoted-reply IDs. Quoted replies are not introduced in this first pass.
+
+Read results include `target`, optional message `thread_id`/`reply_count`, and
+`next_direction` when the adapter supplies it. Pages are chronological. Repeat
+the same target with a cursor; cross-target cursors fail. Page size may change.
+
+### Access boundary
+
+Each adapter and reference store belongs to **one credential session**. Never
+reuse either across installations. The connector loader creates fresh instances.
+No model argument switches credentials or customer connections.
+
+Hosts can supply `validateTarget(target, operation)` on a connector session or
+to `registerChannelTools`. It runs for every operation, including mutations and
+file downloads using existing references. Without it, explicit targets rely on
+the existing credential's provider permissions.
+
+This is a **tool-layer policy, not a sandbox-wide security boundary**. Direct
+shell/API calls can bypass it if the sandbox has broader credentials. Binding
+enforcement, credential selection, durable receipts, and cross-channel reply
+routing are separate platform work. Sending elsewhere does not imply that
+subsequent replies resume the originating task.
+
 ### Message and file references
 
-`channel_react`, `channel_edit`, and `channel_retract` take a `message`, which is
+`channels react`, `channels edit`, and `channels retract` take a `message`, which is
 an opaque handle minted by the host for the current session. It is not a Slack
 timestamp or another provider message ID. Handles come back from
-`channel_reply` and `channel_read`, so the model can only act on a message that
+`channels reply`, `channels send`, and `channels read`, so the model can only act on a message that
 a channel tool returned.
 
-`channel_react` adds a reaction when `action` is omitted. Set `action` to
+`channels react` adds a reaction when `action` is omitted. Set `action` to
 `remove` to remove the agent's reaction with the same emoji.
 
 Edit and retract have an extra check. They accept only a handle for a message
 that this agent posted. Reading the same message again keeps its original
 handle and authorship record.
+Each reference resolves its own destination. Handles are session-local; editing
+a previous session's message is not supported.
 
-`channel_fetch_file` works the same way. Attachments returned by `channel_read`
+`channels fetch_file` works the same way. Attachments returned by `channels read`
 carry a `file_…` handle, and that is the only value the tool accepts. A bot can
 usually read files from every conversation it belongs to, so accepting a raw
-provider file ID would let the model reach files outside the bound conversation.
-
-### Enrichment, not lookup tools
-
-Author names and permalinks are resolved by the adapter in trusted code and
-attached to what the agent is already reading: `channel_read` rows carry
-`author.display_name`, and `channel_reply` returns a `permalink` where the
+provider file ID would bypass the requirement to observe the file first.
+File handles also retain the channel/thread read scope where they were observed.
+Fetching revalidates that scope; observing the same file through another scope
+creates a separate handle rather than changing the authority of an earlier one.
+
+### Listing and enrichment
+
+`channels list` returns provider channel IDs and names for explicitly targeted
+reads and sends. When the host supplies `validateTarget`, every listed channel
+is checked with the `list` operation and denied entries are omitted before any
+IDs or names become model-visible. Author names and permalinks are resolved by the adapter in trusted code and
+attached to what the agent is already reading: `channels read` rows carry
+`author.display_name`, and `channels reply` returns a `permalink` where the
 provider has one. There is no `resolve_user` or `get_permalink` tool, because
 each would require another model turn. Each lookup would also take an
 addressing argument.
 
 ### Unsupported operations
 
-Workspace search, channel listing and joining, directory lookup, and posting to
-another conversation are unsupported. The proposal does not choose an API or
-access model for those operations. A separate proposal can define them when a
-concrete use case requires them.
+Search, individual channel-info lookup, thread listing, channel joining, and directory
+lookup are deferred. Explicit IDs can come from task context; thread IDs can
+also come from channel reads.
 
 Typing indicators and presence are runtime effects rather than model decisions.
-Streaming controls how a reply is delivered. The runtime derives idempotency
-keys, and the webhook already removes duplicate inbound events.
+Streaming controls how a reply is delivered. These tools do not add durable
+send idempotency or claim exactly-once delivery.
 
 ## Declare a channel connector
 
@@ -94,7 +190,7 @@ keys, and the webhook already removes duplicate inbound events.
     "@introspection-ai/recipe-channel-slack": "^0.1.0"
   },
   "pi": {
-    "connectors": [
+    "channels": [
       {
         "provider": "slack"
       }
@@ -103,11 +199,11 @@ keys, and the webhook already removes duplicate inbound events.
 }
 ```
 
-The connector declaration enables the provider package and its supported tool
+The channel declaration enables the provider package and its supported tool
 catalog. The agent YAML file is the only place that narrows the catalog:
 
 ```yaml
-tools: [channel_reply, channel_read, channel_react, channel_edit, channel_retract, channel_fetch_file]
+tools: [channels]
 ```
 
 The host fails when an agent selects a tool that the provider does not support.
@@ -120,13 +216,15 @@ Each provider package declares the capabilities that it can support.
 
 An adapter supplies transport and a capability descriptor. It writes no tool
 schemas. The shared schema keeps providers from defining different forms of
-the same operation, and it prevents a provider from adding an addressing
-argument.
+the same operation. Set `targeting: true` and implement `send(ctx, {text})` to
+opt into the shared targeting schema; set `list: true` and implement `list()` to
+expose `channels list`. Omit these capabilities for origin-bound tools.
 
 ```ts
 import {
   createChannelConnectorModule,
   type ChannelAdapter,
+  type ChannelConfig,
 } from "@introspection-ai/recipes/channels";
 
 const capabilities = {
@@ -143,24 +241,39 @@ class MyAdapter implements ChannelAdapter {
   async retract(ctx, { ref }) { /* retract an agent-authored message */ }
 }
 
+function targetFrom(config: ChannelConfig | null) {
+  if (!config || config.provider !== "my-channel") {
+    throw new Error("No my-channel destination is configured");
+  }
+  return {
+    provider: "my-channel",
+    conversation: config.channel_ref,
+    thread: config.thread_ref,
+  };
+}
+
 export default createChannelConnectorModule({
   provider: "my-channel",
   capabilities,
-  createSession: ({ env }) => ({
+  createSession: ({ config, env }) => ({
     adapter: new MyAdapter(/* client from env */),
     // A function, so a task with no channel origin still starts: the tools
     // fail when called, the session does not fail to open.
-    target: () => resolveTargetFrom(env),
+    target: () => targetFrom(config),
   }),
 });
 ```
 
+The host resolves `ChannelConfig` once from the `INTROSPECTION_TASK_CHANNEL_*`
+environment contract. Provider packages map `channel_ref` and `thread_ref` to
+their own API fields and do not define provider-specific origin types.
+
 Registration checks that the adapter implements every method its capabilities
 claim, so a descriptor cannot promise a tool the adapter does not have.
 
-The result is an ordinary `RecipeConnectorModule`. Manifest validation, agent
-tool selection, and `tool_search` work without provider-specific code in the
-Recipe.
+The result is an ordinary `RecipeConnectorModule`. Manifest validation and agent
+tool selection work without provider-specific code in the Recipe. The unified
+tool is active immediately and does not require `tool_search`.
 
 ## Provider pages
 

package/docs/host-api.md

@@ -70,6 +70,10 @@ const handle = await createAgentSession({
   sessionManager,
   additionalSkillPaths,
   materializedSkillPaths,
+  memory: {
+    indexPath: "/workspace/memories/MEMORY.md",
+  },
+  memoryOverride,
   transformSystemPrompt,
   onDiagnostics,
   onEvent,
@@ -109,6 +113,23 @@ gateway-decorated model without reimplementing Recipe semantics. The Recipe
 continues to own model configuration and tool selection; host seams replace
 transport and materialized resources, not the portable definition.
 
+### Persistent memory context
+
+Hosts can provide one durable memory index through `memory`. Recipes loads the
+index once during session construction and bounds the injected index content to
+200 lines and 25,000 UTF-8 bytes after XML escaping by default. Missing and
+empty indexes render nothing. The host owns the directory, persistence, and
+identity scope; Recipes assumes no filesystem layout.
+
+The index should stay concise and can link to focused files in its directory.
+Recipes injects it without adding usage or precedence instructions.
+
+`memoryOverride` follows Pi's resource override pattern. It can replace, filter,
+or disable the loaded index before rendering. The exported `loadMemoryIndex`
+and `formatMemoryForPrompt` helpers let custom hosts use the same primitives.
+Recipe-specific memory behavior belongs in `SYSTEM.md` or agent
+`system_instructions`, while the host binds the actual memory resource.
+
 The default in-process subagent controller uses that same Recipe snapshot for
 every child, so no session reparses the package or observes a different source
 snapshot. Injected controllers own child selection and execution after the root

package/docs/pi-extension.md

@@ -53,7 +53,7 @@ For the selected agent, the extension:
 1. reads the root `package.json#pi` resource declarations;
 2. resolves the agent YAML, including `from:` inheritance;
 3. selects the model, thinking level, and tool allowlist;
-4. loads providers from `pi.connectors` and registers the tools selected by the agent;
+4. loads providers from `pi.channels` and registers the tools selected by the agent;
 5. loads selected skills, package prompts, and the complete Recipe extension closure;
 6. materializes declared MCP bindings from host or local configuration;
 7. exposes only the declared subagents through the shared `agent` tool.

package/docs/recipe-format.md

@@ -81,9 +81,9 @@ MUST commit one supported dependency lockfile: `package-lock.json`,
 `npm-shrinkwrap.json`, `pnpm-lock.yaml`, or `yarn.lock`. npm lockfiles MUST
 carry the same package name and version as `package.json`.
 
-## Connector tools
+## Channel tools
 
-`pi.connectors` declares official provider tools that the host may register for
+`pi.channels` declares official provider tools that the host may register for
 the Recipe. The declaration does not contain a connector ID, workspace ID, or
 credential. A host binds those values when it starts a task.
 
@@ -93,7 +93,7 @@ credential. A host binds those values when it starts a task.
     "@introspection-ai/recipe-channel-slack": "^0.1.0"
   },
   "pi": {
-    "connectors": [
+    "channels": [
       {
         "provider": "slack"
       }
@@ -109,13 +109,15 @@ and marks which tools are active by default.
 
 The provider package must be in the Recipe's production dependencies and
 lockfile. The host imports the package only when the Recipe declares the
-provider. The agent YAML file is the only place that narrows the package tool
-catalog. An agent lists each allowed tool by its full name, such as
-`channel_reply`, in its `tools` list. The host fails when the agent names a
+provider. An agent lists each allowed tool by its full name, such as
+`channels`, in its `tools` list. The host fails when the agent names a
 tool that the connector does not register.
 
 Chat providers share one connector shape. A channel connector registers the
-provider-neutral `channel_*` tools that its capabilities support. See
+provider-neutral `channels` tool with commands for supported operations. An
+optional `commands` array on the connector restricts these operations for all
+agents using it, for example `{"provider":"slack","commands":["read","reply"]}`.
+Omitting it allows supported commands; an empty list exposes no channel tool. See
 [Channel tools](channels.md).
 
 ## Agents

package/docs/slack.md

@@ -2,8 +2,8 @@
 
 `@introspection-ai/recipe-channel-slack` is the Slack adapter for the
 [channel tools](channels.md). It supplies Slack Web API transport and a
-capability descriptor; the tool names and schemas are the neutral `channel_*`
-set, so a Recipe written against it is not written against Slack.
+capability descriptor. The `channels` tool and its command schemas are
+provider-neutral, so a Recipe written against it is not written against Slack.
 
 Slack sends inbound events to the existing Events API webhook. The tools make
 ordinary HTTP requests to the Slack Web API with the bot that received the
@@ -18,7 +18,7 @@ protocol.
     "@introspection-ai/recipe-channel-slack": "^0.1.0"
   },
   "pi": {
-    "connectors": [
+    "channels": [
       {
         "provider": "slack"
       }
@@ -30,48 +30,48 @@ protocol.
 Commit the package manager lockfile. The host loads the package only for a
 Recipe that declares the connector.
 
-The connector package provides the complete Slack tool catalog. Each agent
-lists the exact `channel_*` tools it may call in its YAML file. `channel_reply`,
-`channel_read`, and `channel_react` are active from the start. Other selected
-tools are available through `tool_search`.
+The connector registers one `channels` tool. Agents select `tools: [channels]`;
+all supported commands are immediately visible. An optional connector `commands`
+allowlist restricts operations for every agent using that connector.
 
 ## What Slack registers
 
 | Tool | Slack operation |
 | --- | --- |
-| `channel_reply` | `chat.postMessage` into the origin channel and thread |
-| `channel_read` | `conversations.replies` in a thread, else `conversations.history` |
-| `channel_react` | `reactions.add` or `reactions.remove` |
-| `channel_edit` | `chat.update` for a message the agent posted |
-| `channel_retract` | `chat.delete` for a message the agent posted |
-| `channel_fetch_file` | `files.info` plus a private file download |
-
-Slack history returns at most 15 messages to the agent per call. For a thread,
-the first call reads the thread and returns the newest messages. The adapter
-keeps older messages in the current session, and the returned opaque cursor
-pages backward through that cache without another `conversations.replies`
-request.
-
-The connector uses a customer owned internal Slack app. Slack gives internal
-apps the larger `conversations.replies` page and rate limits needed to read a
-thread before selecting its newest messages. The connector does not support a
-commercially distributed Slack app outside the Slack Marketplace, because
-Slack restricts those installations to 15 replies and one request per minute.
-
-`channel_attach` and `channel_post_document` are not registered: `files.uploadV2`
+| `channels reply` | `chat.postMessage` into the origin channel and thread |
+| `channels send` | `chat.postMessage` into an explicit channel and optional thread |
+| `channels list` | paged `conversations.list` returning accessible channels |
+| `channels read` | `conversations.replies` in a thread, else `conversations.history` |
+| `channels react` | `reactions.add` or `reactions.remove` |
+| `channels edit` | `chat.update` for a message the agent posted |
+| `channels retract` | `chat.delete` for a message the agent posted |
+| `channels fetch_file` | `files.info` plus a private file download |
+
+Slack history requests at most 15 messages and makes one history request per
+tool call. Threads start at the beginning and page forward; channel timelines
+start with recent messages and page backward. Each page is chronological, and
+`next_direction` describes pagination. Repeat the target with the cursor.
+This replaces the old unbounded full-thread fetch/backward session cache.
+Provider rate limits still apply; failures are not automatically retried.
+
+`channels attach` and `channels post_document` are not registered: `files.uploadV2`
 and canvases are not implemented in this package yet, and the capability
 descriptor says so rather than registering tools that fail.
 
-None of these take a channel or thread argument. Every tool acts on the
-conversation the task came from. Author display names (`users.info`) and
+`channels list` returns all non-archived public and private channels where the
+bot is a member. `channels send` requires an explicit `channel_id` (listing first is not required); `thread_id` is
+optional. `channels read` accepts optional targets, defaulting to the origin. Explicit channel without
+thread means timeline/top-level, not the origin's thread. Reply stays bound.
+Author display names (`users.info`) and
 permalinks (`chat.getPermalink`) are resolved inside the adapter and attached to
 message rows and reply results, so there is no user lookup or permalink tool.
 Edit and retract also require an opaque reference for a message posted by this
 agent. They cannot act on another author's message.
 
-Workspace search, channel listing and joining, directory lookup, and
-cross-channel posting are unsupported. Their contract and access model are
-deferred to a separate proposal.
+Search, individual channel-info lookup, joining, and directory lookup remain deferred.
+Tools use one existing credential session; they do not select installations or
+enforce project/customer bindings. The optional host target-policy callback
+constrains these tools, not direct shell/API access.
 
 ## Cloud access
 
@@ -84,11 +84,16 @@ allowed path, and adds the bot token before the request leaves for Slack.
 The adapter refuses to send a task locator when the provider proxy URL is
 missing. It never falls back to sending the locator to Slack.
 
-After `channel_reply` succeeds in cloud, the adapter posts the `connector_posted`
+After `channels reply` succeeds in cloud, the adapter posts the `connector_posted`
 task event to the Data Plane, which checks the agent session, current run,
 provider, and origin channel before recording the new thread root. A later Slack
 reply then resumes the same task.
 
+`channels send` deliberately does not emit this origin-bound bridge event, even
+when its explicit destination matches the origin. Its result includes the
+actual target and `bridge_recorded: false`. Cross-channel continuation is not
+implemented by this tools-only change.
+
 Slack writes are attempted once. The adapter does not retry `chat.postMessage`,
 because Slack accepts no idempotency key for it. If Slack accepts the post but
 event recording fails, the tool returns the message reference and a
@@ -101,29 +106,17 @@ development runtime starts a cloud sandbox with the local Recipe overlay, so the
 adapter uses the cloud task origin and provider proxy and needs no local Slack
 credential. Use `introspection dev --logs` for sandbox logs.
 
-## Test with introspection local
-
-An `introspection local` run has no inbound Slack event, cloud task origin, or
-credential proxy. Install dependencies, then set a bot token and a conversation:
-
-```bash
-pnpm install --frozen-lockfile
-export SLACK_BOT_TOKEN='xoxb-...'
-export SLACK_CHANNEL_ID='C0123456789'
-export SLACK_THREAD_TS='1234567890.123456' # optional
-introspection local -p 'Summarise this thread and reply.'
-```
-
-Local tools call Slack directly with `SLACK_BOT_TOKEN`. Local posts create no
-inbound task or reply bridge, because no Data Plane task exists.
+Standalone channel access through `introspection local` is not supported. It
+has no webhook receiver, cloud task origin, or provider proxy. Use the same
+`introspection dev` workflow for inbound events and outbound channel tools.
 
 ## File downloads
 
-`channel_fetch_file` writes a file under the task files directory and returns its
+`channels fetch_file` writes a file under the task files directory and returns its
 path, media type, size, and SHA-256 digest. The bytes land in the workspace and
-not in model context. It accepts only a `file_…` handle from a `channel_read`
-attachment, so the bot's cross-channel file read is not reachable from model
-input. On the wire it accepts only `files.slack.com` download URLs, rejects
+not in model context. It accepts only a `file_…` handle from a `channels read`
+attachment, and resolves that reference's channel before the host policy check.
+On the wire it accepts only `files.slack.com` download URLs, rejects
 redirects, caps the body at 100 MiB, checks the declared size, and removes
 partial files after a failure. The `video_low` variant uses Slack's smaller MP4
 rendition when one exists.
@@ -132,4 +125,4 @@ rendition when one exists.
 
 The package exports `SlackChannelAdapter`, `createSlackChannelSession` and
 `slackChannelTarget` for custom hosts and tests, alongside the default
-`slackRecipeConnectorModule`. A normal Recipe uses `pi.connectors` instead.
+`slackRecipeConnectorModule`. A normal Recipe uses `pi.channels` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/recipes",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "The open format for vertical agents, built on Pi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -58,6 +58,10 @@
       "types": "./dist/api/session.d.ts",
       "import": "./dist/api/session.js"
     },
+    "./memory": {
+      "types": "./dist/api/memory.d.ts",
+      "import": "./dist/api/memory.js"
+    },
     "./channels": {
       "types": "./dist/channels/index.d.ts",
       "import": "./dist/channels/index.js"
@@ -102,10 +106,10 @@
     "vitest": "^4.0.18"
   },
   "optionalDependencies": {
-    "@introspection-ai/mcp-client-linux-x64": "0.22.1",
-    "@introspection-ai/mcp-client-linux-arm64": "0.22.1",
-    "@introspection-ai/mcp-client-darwin-arm64": "0.22.1",
-    "@introspection-ai/mcp-client-darwin-x64": "0.22.1"
+    "@introspection-ai/mcp-client-linux-x64": "0.24.0",
+    "@introspection-ai/mcp-client-linux-arm64": "0.24.0",
+    "@introspection-ai/mcp-client-darwin-arm64": "0.24.0",
+    "@introspection-ai/mcp-client-darwin-x64": "0.24.0"
   },
   "scripts": {
     "build": "pnpm build:ts && pnpm build:native",