@introspection-ai/recipes 0.21.0 → 0.22.1

package/dist/tool-search.js

@@ -0,0 +1,176 @@
+import { Type } from "typebox";
+export const RECIPE_TOOL_SEARCH_NAME = "tool_search";
+export const LEGACY_MCP_TOOL_SEARCH_NAME = "mcp_search";
+function words(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function schemaSearchTerms(schema) {
+    const propertyNames = [];
+    const propertyDescriptions = [];
+    const visited = new Set();
+    const visit = (value) => {
+        if (!value || typeof value !== "object" || visited.has(value))
+            return;
+        visited.add(value);
+        const record = value;
+        if (record.properties && typeof record.properties === "object") {
+            for (const [name, property] of Object.entries(record.properties)) {
+                propertyNames.push(name);
+                if (property && typeof property === "object") {
+                    const description = property.description;
+                    if (typeof description === "string") {
+                        propertyDescriptions.push(description);
+                    }
+                }
+                visit(property);
+            }
+        }
+        for (const keyword of [
+            "allOf",
+            "anyOf",
+            "oneOf",
+            "items",
+            "additionalProperties",
+        ]) {
+            const nested = record[keyword];
+            if (Array.isArray(nested)) {
+                for (const entry of nested)
+                    visit(entry);
+            }
+            else {
+                visit(nested);
+            }
+        }
+    };
+    visit(schema);
+    return {
+        propertyNames: propertyNames.join(" ").toLowerCase(),
+        propertyDescriptions: propertyDescriptions.join(" ").toLowerCase(),
+    };
+}
+function scoreTool(tool, query) {
+    const normalizedQuery = query.trim().toLowerCase();
+    if (!normalizedQuery)
+        return 0;
+    const name = tool.name.toLowerCase();
+    const label = (tool.label ?? tool.name).toLowerCase();
+    const description = tool.description.toLowerCase();
+    const { propertyNames, propertyDescriptions } = schemaSearchTerms(tool.parameters);
+    let score = 0;
+    if (name === normalizedQuery)
+        score += 500;
+    if (label === normalizedQuery)
+        score += 300;
+    if (name.includes(normalizedQuery))
+        score += 120;
+    if (label.includes(normalizedQuery))
+        score += 100;
+    if (description.includes(normalizedQuery))
+        score += 60;
+    const nameTerms = new Set(words(name));
+    const labelTerms = new Set(words(label));
+    const propertyNameTerms = new Set(words(propertyNames));
+    for (const term of words(normalizedQuery)) {
+        if (nameTerms.has(term))
+            score += 40;
+        else if (name.includes(term))
+            score += 20;
+        if (labelTerms.has(term))
+            score += 30;
+        else if (label.includes(term))
+            score += 15;
+        if (description.includes(term))
+            score += 16;
+        if (propertyNameTerms.has(term))
+            score += 12;
+        else if (propertyNames.includes(term))
+            score += 6;
+        if (propertyDescriptions.includes(term))
+            score += 6;
+    }
+    return score;
+}
+export function createRecipeToolSearch(options) {
+    const toolsByName = new Map(options.tools.map((tool) => [tool.name, tool]));
+    const deferred = [...new Set(options.deferredToolNames)].map((name) => {
+        const tool = toolsByName.get(name);
+        if (!tool) {
+            throw new Error(`Recipe deferred tool '${name}' was not registered before tool search`);
+        }
+        return tool;
+    });
+    if (deferred.length === 0)
+        return undefined;
+    if (toolsByName.has(RECIPE_TOOL_SEARCH_NAME)) {
+        throw new Error(`Recipe tool name '${RECIPE_TOOL_SEARCH_NAME}' is reserved by the session`);
+    }
+    return {
+        name: RECIPE_TOOL_SEARCH_NAME,
+        label: "Tool search",
+        description: "Search inactive tools allowed for this Recipe and enable the best matches for the next model request.",
+        parameters: Type.Object({
+            query: Type.String({
+                description: "Capability or task to find a tool for.",
+            }),
+            limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 10, default: 3 })),
+        }),
+        executionMode: "sequential",
+        async execute(_toolCallId, params) {
+            const input = params;
+            const query = typeof input.query === "string" ? input.query : "";
+            const limit = typeof input.limit === "number" ? input.limit : 3;
+            const active = new Set(options.activation.getActiveTools());
+            const matches = deferred
+                .filter((tool) => !active.has(tool.name))
+                .map((tool) => ({ tool, score: scoreTool(tool, query) }))
+                .filter((match) => match.score > 0)
+                .sort((left, right) => right.score - left.score ||
+                left.tool.name.localeCompare(right.tool.name))
+                .slice(0, limit);
+            const added = matches.map((match) => match.tool.name);
+            if (added.length > 0) {
+                options.activation.setActiveTools([...active, ...added]);
+            }
+            const details = {
+                matches: matches.map(({ tool }) => ({
+                    name: tool.name,
+                    label: tool.label ?? tool.name,
+                    description: tool.description,
+                })),
+                added,
+            };
+            const text = matches.length === 0
+                ? `No inactive Recipe tools matched "${query}".`
+                : [
+                    `Enabled ${matches.length} Recipe tool(s) for the next model request:`,
+                    ...matches.map(({ tool }) => `- ${tool.name}${tool.description ? `: ${tool.description}` : ""}`),
+                ].join("\n");
+            return {
+                content: [{ type: "text", text }],
+                details,
+            };
+        },
+    };
+}
+export function createRecipeToolSearchTools(options, includeLegacyMcpAlias) {
+    const search = createRecipeToolSearch(options);
+    if (!search)
+        return [];
+    if (!includeLegacyMcpAlias)
+        return [search];
+    if (options.tools.some((tool) => tool.name === LEGACY_MCP_TOOL_SEARCH_NAME)) {
+        throw new Error(`Recipe tool name '${LEGACY_MCP_TOOL_SEARCH_NAME}' is reserved by the session`);
+    }
+    return [
+        search,
+        {
+            ...search,
+            name: LEGACY_MCP_TOOL_SEARCH_NAME,
+            label: "MCP search",
+        },
+    ];
+}
+//# sourceMappingURL=tool-search.js.map

package/dist/tool-search.js.map

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

package/docs/channels.md

@@ -0,0 +1,167 @@
+# 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.
+
+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
+  adapter declares a capability descriptor, and registration filters on it.
+  For example, an adapter with no history API has no `channel_read` tool.
+
+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.
+
+## The tools
+
+| Tool | Model 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`.
+
+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.
+
+### Message and file references
+
+`channel_react`, `channel_edit`, and `channel_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
+a channel tool returned.
+
+`channel_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.
+
+`channel_fetch_file` works the same way. Attachments returned by `channel_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 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.
+
+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.
+
+## Declare a channel connector
+
+```json
+{
+  "dependencies": {
+    "@introspection-ai/recipe-channel-slack": "^0.1.0"
+  },
+  "pi": {
+    "connectors": [
+      {
+        "provider": "slack"
+      }
+    ]
+  }
+}
+```
+
+The connector 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]
+```
+
+The host fails when an agent selects a tool that the provider does not support.
+
+Because the vocabulary is neutral, the same declaration and the same agent
+prompt work against another provider by changing the dependency and `provider`.
+Each provider package declares the capabilities that it can support.
+
+## Write an adapter
+
+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.
+
+```ts
+import {
+  createChannelConnectorModule,
+  type ChannelAdapter,
+} from "@introspection-ai/recipes/channels";
+
+const capabilities = {
+  react: false, edit: true, retract: true, read: false,
+  attach: false, fetchFile: false,
+  documents: false, resolveAuthors: true, permalinks: false,
+};
+
+class MyAdapter implements ChannelAdapter {
+  readonly provider = "my-channel";
+  readonly capabilities = capabilities;
+  async reply(ctx, { text }) { /* post into ctx.target */ }
+  async edit(ctx, { ref, text }) { /* edit an agent-authored message */ }
+  async retract(ctx, { ref }) { /* retract an agent-authored message */ }
+}
+
+export default createChannelConnectorModule({
+  provider: "my-channel",
+  capabilities,
+  createSession: ({ 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),
+  }),
+});
+```
+
+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.
+
+## Provider pages
+
+- [Slack](slack.md)

package/docs/index.md

@@ -17,6 +17,8 @@ task lifecycle, protocols, and deployment.
 | Compose agents and subagents | [Agent composition](agent-composition.md) |
 | Ask for user input across hosts | [Interactions](interactions.md) |
 | Declare capability policy and bindings | [MCP configuration](mcp-configuration.md) |
+| Answer a chat message from a Recipe | [Channel tools](channels.md) |
+| Add Slack tools to a Recipe | [Slack channel connector](slack.md) |
 | Define portable evaluation judges | [Recipe judges](recipe-judges.md) |
 
 ## Boundary

package/docs/mcp-configuration.md

@@ -91,10 +91,12 @@ to hide all authorized tools for a server, then optionally list exact tools in
 or a sole `"*"` selector. `eager` wins when a tool matches both fields, but
 neither field can authorize a tool excluded by `include`/`exclude`.
 
-Deferred tools remain authorized and discoverable. When at least one exists,
-Recipes registers `mcp_search`; calling it searches only the authorized
-deferred catalog and adds matches to Pi's current active tool set for the next
-model request. It never grants access beyond `servers`.
+Deferred tools remain authorized and discoverable. When at least one connector
+or MCP tool is deferred, Recipes registers `tool_search`. Calling it searches
+the inactive tools already allowed for the agent and adds the best matches to
+Pi's active tool set for the next model request. It never grants access beyond
+the Recipe manifest and agent policy. Recipes also registers `mcp_search` as a
+compatibility alias when MCP tools are deferred.
 
 `defer` and `eager` are invalid in CLI mode. An omitted agent `mcp` block
 inherits its base policy. Once a child declares `mcp`, the complete block

package/docs/pi-extension.md

@@ -53,9 +53,10 @@ 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 selected skills, package prompts, and the complete Recipe extension closure;
-5. materializes declared MCP bindings from host or local configuration;
-6. exposes only the declared subagents through the shared `agent` tool.
+4. loads providers from `pi.connectors` 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.
 
 See [Recipe Format](recipe-format.md) for the authored contract and
 [Agent composition](agent-composition.md) for inheritance and selection.

package/docs/recipe-format.md

@@ -81,6 +81,43 @@ 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
+
+`pi.connectors` 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.
+
+```json
+{
+  "dependencies": {
+    "@introspection-ai/recipe-channel-slack": "^0.1.0"
+  },
+  "pi": {
+    "connectors": [
+      {
+        "provider": "slack"
+      }
+    ]
+  }
+}
+```
+
+Each provider may appear once. The host derives the package name from the
+provider. For example, `slack` resolves to
+`@introspection-ai/recipe-channel-slack`. The package owns its tool catalog
+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
+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
+[Channel tools](channels.md).
+
 ## Agents
 
 `pi.agents` may declare YAML agent definitions explicitly. When omitted,

package/docs/slack.md

@@ -0,0 +1,135 @@
+# Slack channel connector
+
+`@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.
+
+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
+task. The package does not use Socket Mode, WebSockets, or a streamed tool
+protocol.
+
+## Declare it
+
+```json
+{
+  "dependencies": {
+    "@introspection-ai/recipe-channel-slack": "^0.1.0"
+  },
+  "pi": {
+    "connectors": [
+      {
+        "provider": "slack"
+      }
+    ]
+  }
+}
+```
+
+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`.
+
+## 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`
+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
+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.
+
+## Cloud access
+
+The Recipe never receives the Slack bot token. The adapter sends the task
+locator to `INTROSPECTION_EGRESS_URL`, the provider proxy inside the
+Introspection environment, with the Slack host as the proxy route. The proxy
+verifies and removes the locator, checks the connector's granted scope and
+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`
+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.
+
+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
+`bridge_error`. It does not post again.
+
+## Test with introspection dev
+
+Run `introspection dev` from the Recipe repository. A Slack event sent to the
+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.
+
+## File downloads
+
+`channel_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
+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.
+
+## Direct host use
+
+The package exports `SlackChannelAdapter`, `createSlackChannelSession` and
+`slackChannelTarget` for custom hosts and tests, alongside the default
+`slackRecipeConnectorModule`. A normal Recipe uses `pi.connectors` instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@introspection-ai/recipes",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "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"
     },
+    "./channels": {
+      "types": "./dist/channels/index.d.ts",
+      "import": "./dist/channels/index.js"
+    },
     "./test-utils": {
       "types": "./dist/test-utils.d.ts",
       "import": "./dist/test-utils.js"
@@ -87,10 +91,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.84.2",
-    "@earendil-works/pi-ai": "0.84.2",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
+    "@earendil-works/pi-agent-core": "0.84.3",
+    "@earendil-works/pi-ai": "0.84.3",
+    "@earendil-works/pi-coding-agent": "0.84.3",
+    "@earendil-works/pi-tui": "0.84.3",
     "@types/node": "^26.1.2",
     "esbuild": "^0.28.1",
     "typebox": "^1.0.56",
@@ -98,19 +102,20 @@
     "vitest": "^4.0.18"
   },
   "optionalDependencies": {
-    "@introspection-ai/mcp-client-linux-x64": "0.21.0",
-    "@introspection-ai/mcp-client-linux-arm64": "0.21.0",
-    "@introspection-ai/mcp-client-darwin-arm64": "0.21.0",
-    "@introspection-ai/mcp-client-darwin-x64": "0.21.0"
+    "@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"
   },
   "scripts": {
     "build": "pnpm build:ts && pnpm build:native",
-    "build:ts": "rm -rf dist && tsc && node scripts/build-mcp-daemon.mjs",
+    "build:workspace-packages": "pnpm --filter './packages/**' build",
+    "build:ts": "rm -rf dist && tsc && node scripts/build-mcp-daemon.mjs && pnpm build:workspace-packages",
     "build:native": "cargo build --release -p pi-mcp-client && node scripts/package-mcp-client.mjs",
     "bench:mcp-client": "pnpm build:ts && cargo build --release -p pi-mcp-client && node scripts/benchmark-mcp-client.mjs",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json && pnpm --filter './packages/**' typecheck",
     "test": "pnpm build:ts && cargo test -p pi-mcp-client -p introspection-recipe-check && cargo build -p pi-mcp-client && MCP_CLIENT_BIN=target/debug/mcp-client node scripts/package-mcp-client.mjs && vitest run",
-    "pack:check": "pnpm pack --dry-run --json | node scripts/check-npm-pack.mjs",
+    "pack:check": "pnpm pack --dry-run --json | node scripts/check-npm-pack.mjs && pnpm --filter './packages/**' pack:check",
     "clean": "rm -rf dist .turbo node_modules target vendor/mcp-client"
   }
 }