@sentry/junior 0.88.0 → 0.90.0

package/dist/chat/{tools → slack/tools}/channel-capabilities.d.ts

@@ -2,6 +2,8 @@
 export interface ChannelCapabilities {
     /** Can create canvases in this channel (C/G/D channels). */
     canCreateCanvas: boolean;
+    /** Can send messages into this conversation scope (C/G/D channels). */
+    canSendMessage: boolean;
     /** Can post standalone messages to this channel (C/G channels only). */
     canPostToChannel: boolean;
     /** Can add reactions to messages (C/G/D channels). */

package/dist/chat/slack/tools/channel-list-messages.d.ts

@@ -0,0 +1,3 @@
+import type { SlackToolContext } from "@/chat/slack/tools/context";
+/** Create the active-channel history tool with preflight timestamp normalization. */
+export declare function createSlackChannelListMessagesTool(context: SlackToolContext): import("../../tools/definition").AnyToolDefinition;

package/dist/chat/{tools/slack → slack/tools}/context.d.ts

@@ -2,16 +2,17 @@ import type { ToolRuntimeContext } from "@/chat/tools/types";
 import type { SlackDestination } from "@sentry/junior-plugin-api";
 import type { SlackSource } from "@sentry/junior-plugin-api";
 import type { SlackRequester } from "@/chat/requester";
+import { type SlackChannelId, type SlackTeamId } from "@/chat/slack/ids";
 import { type SlackMessageTs } from "@/chat/slack/timestamp";
 export interface SlackToolContext {
     destination: SlackDestination;
     source: SlackSource;
     requester?: SlackRequester;
-    destinationChannelId: string;
+    destinationChannelId: SlackChannelId;
     messageTs?: SlackMessageTs;
-    sourceChannelId: string;
-    teamId: string;
-    threadTs?: string;
+    sourceChannelId: SlackChannelId;
+    teamId: SlackTeamId;
+    threadTs?: SlackMessageTs;
 }
 /** Resolve Slack-specific tool context from the active source/destination/requester. */
 export declare function getSlackToolContext(context: ToolRuntimeContext): SlackToolContext | undefined;

package/dist/chat/slack/tools/list/add-items.d.ts

@@ -0,0 +1,3 @@
+import type { ToolState } from "@/chat/tools/types";
+/** Create a tool that appends items to the active Slack list. */
+export declare function createSlackListAddItemsTool(state: ToolState): import("../../../tools/definition").AnyToolDefinition;

package/dist/chat/{tools/slack/lists.d.ts → slack/tools/list/api.d.ts}

@@ -1,3 +1,4 @@
+import type { SlackUserId } from "@/chat/slack/ids";
 import type { ListColumnMap } from "@/chat/state/artifacts";
 interface SlackListsSchemaColumnResponse {
     id: string;
@@ -23,7 +24,7 @@ export declare function addListItems(input: {
     listId: string;
     titles: string[];
     listColumnMap?: ListColumnMap;
-    assigneeUserId?: string;
+    assigneeUserId?: SlackUserId;
     dueDate?: string;
 }): Promise<{
     createdItemIds: string[];

package/dist/chat/slack/tools/list/create.d.ts

@@ -0,0 +1,3 @@
+import type { ToolState } from "@/chat/tools/types";
+/** Create a tool that provisions a new Slack todo list. */
+export declare function createSlackListCreateTool(state: ToolState): import("../../../tools/definition").AnyToolDefinition;

package/dist/chat/slack/tools/list/get-items.d.ts

@@ -0,0 +1,3 @@
+import type { ToolState } from "@/chat/tools/types";
+/** Create a tool that reads items from the active Slack list. */
+export declare function createSlackListGetItemsTool(state: ToolState): import("../../../tools/definition").AnyToolDefinition;

package/dist/chat/slack/tools/list/update-item.d.ts

@@ -0,0 +1,3 @@
+import type { ToolState } from "@/chat/tools/types";
+/** Create a tool that updates an item in the active Slack list. */
+export declare function createSlackListUpdateItemTool(state: ToolState): import("../../../tools/definition").AnyToolDefinition;

package/dist/chat/slack/tools/message-add-reaction.d.ts

@@ -0,0 +1,4 @@
+import type { SlackToolContext } from "@/chat/slack/tools/context";
+import type { ToolState } from "@/chat/tools/types";
+/** Create the tool that reacts to the current inbound Slack message. */
+export declare function createSlackMessageAddReactionTool(context: SlackToolContext, state: ToolState): import("../../tools/definition").AnyToolDefinition;

package/dist/chat/slack/tools/send-message.d.ts

@@ -0,0 +1,11 @@
+import type { SlackToolContext } from "@/chat/slack/tools/context";
+import type { SandboxFileUpload } from "@/chat/tools/sandbox/file-uploads";
+import type { ToolState } from "@/chat/tools/types";
+/** Convert a model-supplied sandbox file path into bytes safe for Slack upload. */
+export type MaterializeMessageFile = (input: {
+    path: string;
+    filename?: string;
+    mimeType?: string;
+}) => Promise<SandboxFileUpload>;
+/** Create the Slack side-effect tool for active-conversation text and file messages. */
+export declare function createSendMessageTool(context: SlackToolContext, state: ToolState, materializeFile: MaterializeMessageFile): import("../../tools/definition").AnyToolDefinition;

package/dist/chat/{tools/slack → slack/tools}/slack-message-url.d.ts

@@ -1,8 +1,10 @@
 /** Parse Slack archive URLs into structured message references. */
+import { type SlackChannelId } from "@/chat/slack/ids";
+import { type SlackMessageTs } from "@/chat/slack/timestamp";
 export interface SlackMessageReference {
-    channelId: string;
-    messageTs: string;
-    threadTs?: string;
+    channelId: SlackChannelId;
+    messageTs: SlackMessageTs;
+    threadTs?: SlackMessageTs;
 }
 type ParseResult = {
     ok: true;
@@ -11,8 +13,6 @@ type ParseResult = {
     ok: false;
     error: string;
 };
-/** Slack message timestamp format: 10 digits, dot, 6 digits. */
-export declare const SLACK_TS_PATTERN: RegExp;
 /** Parse a Slack archive URL (or mrkdwn-wrapped URL) into a message reference. */
 export declare function parseSlackMessageReference(input: string): ParseResult;
 export {};

package/dist/chat/slack/tools/thread-read.d.ts

@@ -0,0 +1,6 @@
+import { type DestinationVisibilityReader } from "@/chat/slack/tools/channel-access";
+import type { SlackToolContext } from "@/chat/slack/tools/context";
+/** Create a tool that reads a Slack thread from a shared message URL or explicit coordinates. */
+export declare function createSlackThreadReadTool(context: SlackToolContext, deps?: {
+    visibilityStore?: DestinationVisibilityReader;
+}): import("../../tools/definition").AnyToolDefinition;

package/dist/chat/slack/tools/user-lookup.d.ts

@@ -0,0 +1,2 @@
+/** Create the tool that resolves Slack users by ID, handle, or email. */
+export declare function createSlackUserLookupTool(): import("../../tools/definition").AnyToolDefinition;

package/dist/chat/slack/users.d.ts

@@ -1,3 +1,4 @@
+import type { SlackUserId } from "@/chat/slack/ids";
 /** Normalized Slack user profile with custom fields from the Slack workspace. */
 export interface SlackUserProfile {
     id: string;
@@ -20,7 +21,7 @@ export interface SlackUserProfile {
     }>;
 }
 /** Look up a Slack user by ID, returning the full profile including custom fields. */
-export declare function lookupSlackUserProfile(userId: string): Promise<SlackUserProfile>;
+export declare function lookupSlackUserProfile(userId: SlackUserId): Promise<SlackUserProfile>;
 /** Look up a Slack user by email. Returns null when no user matches. */
 export declare function lookupSlackUserByEmail(email: string): Promise<SlackUserProfile | null>;
 export interface SlackUserSearchResult {

package/dist/chat/{services → slack}/vision-context.d.ts

@@ -1,6 +1,8 @@
 import type { Attachment } from "chat";
 import type { completeText } from "@/chat/pi/client";
 import type { ThreadConversationState } from "@/chat/state/conversation";
+import { type SlackChannelId } from "@/chat/slack/ids";
+import { type SlackMessageTs } from "@/chat/slack/timestamp";
 export interface UserInputAttachment {
     data?: Buffer;
     mediaType: string;
@@ -25,8 +27,8 @@ export interface VisionContextDeps {
     completeText: typeof completeText;
     downloadFile: (url: string) => Promise<Buffer>;
     listThreadReplies: (input: {
-        channelId: string;
-        threadTs: string;
+        channelId: SlackChannelId;
+        threadTs: SlackMessageTs;
         limit?: number;
         maxPages?: number;
         targetMessageTs?: string[];

package/dist/chat/state/session-log.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { PiMessage } from "@/chat/pi/messages";
+import { type PiMessage } from "@/chat/pi/messages";
 import { type StoredSlackRequester } from "@/chat/requester";
 declare const authorizationKindSchema: z.ZodUnion<readonly [z.ZodLiteral<"plugin">, z.ZodLiteral<"mcp">]>;
 declare const transcriptRefSchema: z.ZodObject<{

package/dist/chat/tool-exposure.d.ts

@@ -0,0 +1,10 @@
+import type { AnyToolDefinition, ToolExposure } from "@/chat/tools/definition";
+export interface PlannedToolExposure {
+    catalogTools: Record<string, AnyToolDefinition>;
+    directTools: Record<string, AnyToolDefinition>;
+    excludedTools: Record<string, AnyToolDefinition>;
+}
+/** Return the runtime exposure for a tool, preserving direct compatibility. */
+export declare function effectiveToolExposure(definition: AnyToolDefinition): ToolExposure;
+/** Plan which tools are native-visible, catalog-executable, or withheld. */
+export declare function planToolExposure(tools: Record<string, AnyToolDefinition>): PlannedToolExposure;

package/dist/chat/tool-support/catalog-tool-call.d.ts

@@ -0,0 +1,10 @@
+import { type AnyToolDefinition } from "@/chat/tools/definition";
+export interface CatalogToolCall {
+    arguments: Record<string, unknown>;
+    definition: AnyToolDefinition;
+    toolName: string;
+}
+/** Resolve and validate a catalog executeTool request at runtime. */
+export declare function resolveCatalogToolCall(input: Record<string, unknown>, catalogTools: Record<string, AnyToolDefinition>): CatalogToolCall;
+/** Apply a catalog tool's own argument preparation and schema boundary. */
+export declare function prepareCatalogToolCall(call: CatalogToolCall): CatalogToolCall;

package/dist/chat/{tools/execution → tool-support}/normalize-result.d.ts

@@ -1,6 +1,9 @@
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
 /** Unwrap sandbox envelope and detect structured results. */
-export declare function normalizeToolResult(result: unknown, isSandboxResult: boolean): {
+export declare function normalizeToolResult(result: unknown, isSandboxResult: boolean, options?: {
+    requireStructuredResult?: boolean;
+    toolName?: string;
+}): {
     content: Array<TextContent | ImageContent>;
     details: unknown;
 };

package/dist/chat/{tools/agent-tools.d.ts → tool-support/pi-tool-adapter.d.ts}

@@ -5,14 +5,8 @@ import type { PluginAuthOrchestration } from "@/chat/services/plugin-auth-orches
 import type { AssistantStatusSpec } from "@/chat/slack/assistant-thread/status";
 import type { SandboxExecutor } from "@/chat/sandbox/sandbox";
 import type { SkillSandbox } from "@/chat/sandbox/skill-sandbox";
-import type { ToolDefinition } from "@/chat/tools/definition";
+import type { AnyToolDefinition } from "@/chat/tools/definition";
+import type { ToolExecutionReport } from "@/chat/tool-support/tool-execution-report";
 import type { PluginHookRunner } from "@/chat/plugins/agent-hooks";
-export interface ToolExecutionReport {
-    error?: string;
-    ok: boolean;
-    params: Record<string, unknown>;
-    result?: unknown;
-    toolName: string;
-}
 /** Wrap tool definitions into Pi Agent tool objects with logging, validation, and sandbox execution. */
-export declare function createAgentTools(tools: Record<string, ToolDefinition<any>>, sandbox: SkillSandbox, spanContext: LogContext, onStatus?: (status: AssistantStatusSpec) => void | Promise<void>, sandboxExecutor?: SandboxExecutor, pluginAuthOrchestration?: PluginAuthOrchestration, onToolCall?: (toolName: string, params: Record<string, unknown>) => void | Promise<void>, agentHooks?: PluginHookRunner, conversationPrivacy?: ConversationPrivacy, onToolResult?: (report: ToolExecutionReport) => void | Promise<void>): AgentTool[];
+export declare function createPiAgentTools(tools: Record<string, AnyToolDefinition>, sandbox: SkillSandbox, spanContext: LogContext, onStatus?: (status: AssistantStatusSpec) => void | Promise<void>, sandboxExecutor?: SandboxExecutor, pluginAuthOrchestration?: PluginAuthOrchestration, onToolCall?: (toolName: string, params: Record<string, unknown>) => void | Promise<void>, agentHooks?: PluginHookRunner, conversationPrivacy?: ConversationPrivacy, onToolResult?: (report: ToolExecutionReport) => void | Promise<void>): AgentTool[];

package/dist/chat/tool-support/schema-summary.d.ts

@@ -0,0 +1,2 @@
+/** Summarize a tool input schema for quick catalog scanning. */
+export declare function summarizeInputSchema(schema: Record<string, unknown>): string;

package/dist/chat/{tools → tool-support}/skill/mcp-tool-summary.d.ts

@@ -19,12 +19,6 @@ export interface ActiveMcpCatalogSummary {
     provider: string;
     available_tool_count: number;
 }
-/** Build a stable model-readable MCP tool signature. */
-export declare function formatMcpToolSignature(toolName: string, schema: Record<string, unknown>): string;
-/** Build the exact callMcpTool argument shape agents should use. */
-export declare function formatMcpToolCallExample(toolName: string, schema: Record<string, unknown>): ExposedToolSummary["call"];
-/** Summarize an MCP input schema for quick catalog scanning. */
-export declare function summarizeInputSchema(schema: Record<string, unknown>): string;
 /** Convert a managed MCP tool descriptor into agent-visible search output. */
 export declare function toExposedToolSummary(toolDef: ManagedMcpToolDescriptor): ExposedToolSummary;
 /** Group discovered MCP tools into provider catalogs for prompt disclosure. */

package/dist/chat/tool-support/structured-result.d.ts

@@ -0,0 +1,73 @@
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import { z } from "zod";
+export declare const juniorToolContinuationSchema: z.ZodObject<{
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const juniorToolBoundContinuationSchema: z.ZodObject<{
+    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    reason: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodString;
+}, z.core.$strict>;
+export declare const juniorToolErrorSchema: z.ZodObject<{
+    kind: z.ZodString;
+    message: z.ZodString;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const juniorToolResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    status: z.ZodEnum<{
+        error: "error";
+        success: "success";
+    }>;
+    target: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodUnknown>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    continuation: z.ZodOptional<z.ZodObject<{
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    error: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodString]>>;
+}, z.core.$loose>;
+export declare const juniorToolResultWithBoundContinuationSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    status: z.ZodEnum<{
+        error: "error";
+        success: "success";
+    }>;
+    target: z.ZodOptional<z.ZodString>;
+    data: z.ZodOptional<z.ZodUnknown>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodString;
+        message: z.ZodString;
+        retryable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodString]>>;
+    continuation: z.ZodOptional<z.ZodObject<{
+        arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        reason: z.ZodOptional<z.ZodString>;
+        tool_name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$loose>;
+export type JuniorToolResult = z.output<typeof juniorToolResultSchema>;
+export type JuniorToolResultWithBoundContinuation = z.output<typeof juniorToolResultWithBoundContinuationSchema>;
+export interface JuniorToolResultEnvelope<TDetails extends JuniorToolResult = JuniorToolResult> {
+    content: [TextContent, ...(TextContent | ImageContent)[]];
+    details: TDetails;
+}
+/** Bind continuation metadata to the exposed runtime tool name. */
+export declare function injectContinuationToolName(details: JuniorToolResult, toolName: string): JuniorToolResult | JuniorToolResultWithBoundContinuation;
+interface JuniorTextToolResultEnvelope<TDetails extends JuniorToolResult = JuniorToolResult> {
+    content: [TextContent];
+    details: TDetails;
+}
+/** Create the Pi-compatible transport envelope from one structured result object. */
+export declare function makeStructuredToolResult<TDetails extends JuniorToolResult>(details: TDetails): JuniorTextToolResultEnvelope<TDetails>;
+export declare function makeStructuredToolResult<TDetails extends JuniorToolResult>(details: TDetails, options: {
+    content: Array<TextContent | ImageContent>;
+}): JuniorToolResultEnvelope<TDetails>;
+export {};

package/dist/chat/tool-support/text-range-result.d.ts

@@ -0,0 +1,58 @@
+interface TextRangeResult {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    details: {
+        ok: true;
+        status: "success";
+        target: string;
+        data: {
+            content: string;
+            end_line?: number;
+            path: string;
+            start_line: number;
+            total_lines: number;
+        };
+        truncated: boolean;
+        continuation?: {
+            arguments: {
+                offset: number;
+                limit: number;
+                [key: string]: string | number;
+            };
+            reason: string;
+        };
+    };
+}
+interface TextRangeMissingPathResult {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    details: {
+        ok: false;
+        status: "error";
+        target: string;
+        data: {
+            content: "";
+            path: string;
+        };
+        error: {
+            kind: "not_found";
+            message: string;
+        };
+        truncated: false;
+    };
+}
+/** Return a bounded line window so large files can be read incrementally. */
+export declare function sliceFileContent(params: {
+    content: string;
+    continuationArgumentName?: string;
+    limit?: unknown;
+    offset?: unknown;
+    path: string;
+}): TextRangeResult;
+/** Return a model-visible result for expected missing read targets. */
+export declare function missingFileResult(path: string): TextRangeMissingPathResult;
+export {};

package/dist/chat/tool-support/tool-execution-report.d.ts

@@ -0,0 +1,7 @@
+export interface ToolExecutionReport {
+    error?: string;
+    ok: boolean;
+    params: Record<string, unknown>;
+    result?: unknown;
+    toolName: string;
+}

package/dist/chat/tool-support/zod-tool.d.ts

@@ -0,0 +1,27 @@
+import { z, type ZodType, type ZodTypeAny } from "zod";
+import { type JuniorToolResult } from "@/chat/tool-support/structured-result";
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { AnyToolDefinition, ToolExecuteOptions } from "@/chat/tools/definition";
+type ZodToolDefinitionBase<TInputSchema extends ZodTypeAny> = Pick<AnyToolDefinition, "identity" | "description" | "exposure" | "annotations" | "promptSnippet" | "promptGuidelines" | "executionMode"> & {
+    inputSchema: TInputSchema;
+    prepareArguments?: (args: unknown) => z.input<TInputSchema>;
+};
+type StructuredToolExecuteResult<TOutputSchema extends ZodType<JuniorToolResult>> = z.input<TOutputSchema>;
+interface ContentOnlyToolResult {
+    content: Array<TextContent | ImageContent>;
+    details?: never;
+}
+type StructuredZodToolDefinition<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<JuniorToolResult>> = ZodToolDefinitionBase<TInputSchema> & {
+    outputSchema: TOutputSchema;
+    execute?: (input: z.output<TInputSchema>, options: ToolExecuteOptions) => Promise<StructuredToolExecuteResult<TOutputSchema>> | StructuredToolExecuteResult<TOutputSchema>;
+};
+type ContentZodToolDefinition<TInputSchema extends ZodTypeAny> = ZodToolDefinitionBase<TInputSchema> & {
+    outputSchema?: undefined;
+    execute?: (input: z.output<TInputSchema>, options: ToolExecuteOptions) => Promise<ContentOnlyToolResult> | ContentOnlyToolResult;
+};
+/**
+ * Define a Junior-owned tool with Zod input parsing and JSON Schema parameters.
+ */
+export declare function zodTool<TInputSchema extends ZodTypeAny, TOutputSchema extends ZodType<JuniorToolResult>>(definition: StructuredZodToolDefinition<TInputSchema, TOutputSchema>): AnyToolDefinition;
+export declare function zodTool<TInputSchema extends ZodTypeAny>(definition: ContentZodToolDefinition<TInputSchema>): AnyToolDefinition;
+export {};

package/dist/chat/tools/advisor/tool.d.ts

@@ -3,20 +3,14 @@ import type { AdvisorConfig } from "@/chat/config";
 import { type ConversationPrivacy } from "@/chat/conversation-privacy";
 import { type LogContext } from "@/chat/logging";
 import { type AdvisorSessionStore } from "@/chat/tools/advisor/session-store";
-import { type ToolDefinition } from "@/chat/tools/definition";
+import type { AnyToolDefinition } from "@/chat/tools/definition";
 export type AdvisorErrorCode = "invalid_context" | "invalid_question" | "missing_conversation_id" | "session_unavailable" | "unavailable";
-export interface AdvisorToolResult {
-    content: [{
-        type: "text";
-        text: string;
-    }];
-    details: {
-        ok: true;
-    } | {
-        error_code: AdvisorErrorCode;
-        ok: false;
-    };
-}
+export type AdvisorToolResult = {
+    memo: string;
+    ok: boolean;
+    status: "error" | "success";
+    error_code?: AdvisorErrorCode;
+} & Record<string, unknown>;
 export interface AdvisorToolRuntimeContext {
     config: AdvisorConfig;
     conversationId?: string;
@@ -28,9 +22,6 @@ export interface AdvisorToolRuntimeContext {
     streamFn?: StreamFn;
 }
 /** Build the advisor's read-only tool definition subset. */
-export declare function createAdvisorToolDefinitions(definitions: Record<string, ToolDefinition<any>>): Record<string, ToolDefinition<any>>;
+export declare function createAdvisorToolDefinitions(definitions: Record<string, AnyToolDefinition>): Record<string, AnyToolDefinition>;
 /** Create the advisor tool backed by conversation-scoped message history. */
-export declare function createAdvisorTool(context: AdvisorToolRuntimeContext): ToolDefinition<import("@sinclair/typebox").TObject<{
-    question: import("@sinclair/typebox").TString;
-    context: import("@sinclair/typebox").TString;
-}>>;
+export declare function createAdvisorTool(context: AdvisorToolRuntimeContext): AnyToolDefinition;

package/dist/chat/tools/definition.d.ts

@@ -1,8 +1,22 @@
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { Static, TSchema } from "@sinclair/typebox";
+import { type Static, type TSchema } from "@sinclair/typebox";
 import type { ToolExecutionMode } from "@earendil-works/pi-agent-core";
 import type { ConversationPrivacy } from "@/chat/conversation-privacy";
-export interface ToolDefinition<TInputSchema extends TSchema = TSchema> {
+/**
+ * Tool definition boundary for Pi-facing agent tools.
+ */
+export interface JsonSchemaObject {
+    [key: string]: unknown;
+}
+export type ToolInputSchema = TSchema | JsonSchemaObject;
+export type ToolExposure = "direct" | "deferred" | "modelOnly" | "hidden";
+export interface ToolExecuteOptions {
+    experimental_context?: unknown;
+    signal?: AbortSignal;
+    conversationPrivacy?: ConversationPrivacy;
+    toolCallId?: string;
+}
+interface BaseToolDefinition<TInput, TInputSchema extends ToolInputSchema> {
     /** Stable internal owner-qualified identity for plugin-contributed tools. */
     identity?: {
         id: string;
@@ -10,7 +24,42 @@ export interface ToolDefinition<TInputSchema extends TSchema = TSchema> {
         plugin: string;
     };
     description: string;
+    exposure?: ToolExposure;
     inputSchema: TInputSchema;
+    outputSchema?: ToolInputSchema;
+    annotations?: ToolAnnotations;
+    /**
+     * @deprecated Put tool-selection and usage guidance directly in `description`
+     * and parameter descriptions. Retained for plugin compatibility; may be
+     * removed in a future major version.
+     */
+    promptSnippet?: string;
+    /**
+     * @deprecated Put tool-selection and usage guidance directly in `description`
+     * and parameter descriptions. Retained for plugin compatibility; may be
+     * removed in a future major version.
+     */
+    promptGuidelines?: string[];
+    prepareArguments?: (args: unknown) => TInput;
+    executionMode?: ToolExecutionMode;
+    execute?: (input: TInput, options: ToolExecuteOptions) => Promise<unknown> | unknown;
+}
+export interface ToolDefinition<TInputSchema extends TSchema = TSchema> extends BaseToolDefinition<Static<TInputSchema>, TInputSchema> {
+}
+/**
+ * Schema-erased view for heterogeneous registries after Pi validates tool input.
+ */
+export interface AnyToolDefinition {
+    /** Stable internal owner-qualified identity for plugin-contributed tools. */
+    identity?: {
+        id: string;
+        name: string;
+        plugin: string;
+    };
+    description: string;
+    exposure?: ToolExposure;
+    inputSchema: ToolInputSchema;
+    outputSchema?: ToolInputSchema;
     annotations?: ToolAnnotations;
     /**
      * @deprecated Put tool-selection and usage guidance directly in `description`
@@ -24,14 +73,12 @@ export interface ToolDefinition<TInputSchema extends TSchema = TSchema> {
      * removed in a future major version.
      */
     promptGuidelines?: string[];
-    prepareArguments?: (args: unknown) => Static<TInputSchema>;
     executionMode?: ToolExecutionMode;
-    execute?: (input: Static<TInputSchema>, options: {
-        experimental_context?: unknown;
-        signal?: AbortSignal;
-        conversationPrivacy?: ConversationPrivacy;
-        toolCallId?: string;
-    }) => Promise<unknown> | unknown;
+    execute?(input: unknown, options: ToolExecuteOptions): Promise<unknown> | unknown;
+    prepareArguments?(args: unknown): unknown;
 }
+/** Distinguish legacy TypeBox schemas from JSON Schema projected from Zod. */
+export declare function isTypeBoxInputSchema(schema: ToolInputSchema): schema is TSchema;
 /** Infer execute parameter types from the inputSchema via generic binding. */
 export declare function tool<TInputSchema extends TSchema>(definition: ToolDefinition<TInputSchema>): ToolDefinition<TInputSchema>;
+export {};

package/dist/chat/tools/execute-tool.d.ts

@@ -0,0 +1,3 @@
+export declare const EXECUTE_TOOL_NAME = "executeTool";
+/** Create the model-visible dispatcher schema for catalog tools. */
+export declare function createExecuteToolTool(): import("./definition").AnyToolDefinition;

package/dist/chat/tools/index.d.ts

@@ -1,5 +1,6 @@
 import type { SkillMetadata } from "@/chat/skills";
-import type { ToolDefinition } from "@/chat/tools/definition";
+import type { AnyToolDefinition } from "@/chat/tools/definition";
 import type { ToolHooks, ToolRuntimeContext } from "@/chat/tools/types";
 export type { ToolHooks, ToolRuntimeContext };
-export declare function createTools(availableSkills: SkillMetadata[], hooks: ToolHooks | undefined, context: ToolRuntimeContext): Record<string, ToolDefinition<any>>;
+/** Build the model-facing tool registry from runtime-owned context and capabilities. */
+export declare function createTools(availableSkills: SkillMetadata[], hooks: ToolHooks | undefined, context: ToolRuntimeContext): Record<string, AnyToolDefinition>;

package/dist/chat/tools/resource-events.d.ts

@@ -2,18 +2,8 @@ import type { ToolRuntimeContext } from "@/chat/tools/types";
 /** Return whether the current runtime can safely manage conversation subscriptions. */
 export declare function canUseResourceEventSubscriptionTools(context: ToolRuntimeContext): boolean;
 /** Create the tool that subscribes the current conversation to resource events. */
-export declare function createSubscribeToResourceEventsTool(context: ToolRuntimeContext): import("@/chat/tools/definition").ToolDefinition<import("@sinclair/typebox").TObject<{
-    resourceRef: import("@sinclair/typebox").TString;
-    provider: import("@sinclair/typebox").TString;
-    resourceType: import("@sinclair/typebox").TString;
-    label: import("@sinclair/typebox").TString;
-    events: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
-    intent: import("@sinclair/typebox").TString;
-    ttlMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
-}>>;
+export declare function createSubscribeToResourceEventsTool(context: ToolRuntimeContext): import("./definition").AnyToolDefinition;
 /** Create the tool that lists active resource subscriptions for this conversation. */
-export declare function createListResourceEventSubscriptionsTool(context: ToolRuntimeContext): import("@/chat/tools/definition").ToolDefinition<import("@sinclair/typebox").TObject<{}>>;
+export declare function createListResourceEventSubscriptionsTool(context: ToolRuntimeContext): import("./definition").AnyToolDefinition;
 /** Create the tool that cancels a current-conversation resource subscription. */
-export declare function createCancelResourceEventSubscriptionTool(context: ToolRuntimeContext): import("@/chat/tools/definition").ToolDefinition<import("@sinclair/typebox").TObject<{
-    subscriptionId: import("@sinclair/typebox").TString;
-}>>;
+export declare function createCancelResourceEventSubscriptionTool(context: ToolRuntimeContext): import("./definition").AnyToolDefinition;

package/dist/chat/tools/runtime/report-progress.d.ts

@@ -1,4 +1,2 @@
 /** Create the internal tool the model uses for sparse progress updates. */
-export declare function createReportProgressTool(): import("@/chat/tools/definition").ToolDefinition<import("@sinclair/typebox").TObject<{
-    message: import("@sinclair/typebox").TString;
-}>>;
+export declare function createReportProgressTool(): import("../definition").AnyToolDefinition;

package/dist/chat/tools/sandbox/bash.d.ts

@@ -1,5 +1,2 @@
 /** Create the sandbox shell tool definition exposed to the agent. */
-export declare function createBashTool(): import("@/chat/tools/definition").ToolDefinition<import("@sinclair/typebox").TObject<{
-    command: import("@sinclair/typebox").TString;
-    timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
-}>>;
+export declare function createBashTool(): import("../definition").AnyToolDefinition;