@aefree/pi-plastic 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project follows semantic versioning for public package releases.
 
 ## Unreleased
 
+## [0.7.0] - 2026-09-16
+
+### Fixed
+
+- Infer tool arguments from the schemas in `src/tool-definition.ts`, retaining required fields, optional fields, arrays, and literal enums instead of implicit `any` parameters.
+- Use TypeBox schema guards and array-based unions in the adapter, and narrow Bash tool events directly in both safety guards.
+- Add a pinned strict typecheck before the test suite, covering production sources, extensions, and compile-only argument-inference regressions.
+
+### Changed
+
+- Present Plastic tools and capability search with compact action headers, operation targets, and structured result summaries in Pi's existing tool boxes.
+- Keep previews, blocked checkins, cancelled switches, uncertain server effects, unavailable comparisons, and output omissions visible; retain full returned evidence and colored diff hunks on expansion.
+- Use Pi's wrapping components and configured expansion hint instead of manual character truncation and a fixed shortcut. Preserve original JSON numeric text and mask common credential assignments in display output.
+- Add an offline tool preview and behavioral renderer tests covering outcomes, exact evidence, redaction, keybindings, registration, and narrow terminals.
+
+## [0.6.1] - 2026-09-14
+
+### Fixed
+
+- Clarify that `cm cat --file` writes to and can overwrite its destination, including when stdout is redirected. Route ordinary baseline reviews through typed diff tools, require new external temporary destinations for necessary manual exports, and distinguish changeset numbers from file revision IDs.
+
 ## [0.6.0] - 2026-09-14
 
 ### Added

package/README.md

@@ -2,6 +2,14 @@
 
 Pi tools, footer status, and skill guidance for Plastic SCM / Unity Version Control workflows.
 
+## Tool presentation
+
+Plastic tools use compact action headers inside Pi's standard tool boxes. Headers show the workspace name and the branch, file, revision pair, or query being acted on; command previews are labeled explicitly. Collapsed results summarize structured status counts, diff availability, patch output, and server-merge outcomes. Blocked checkins, unresolved effects, omitted results, and unavailable comparisons remain visible without expansion. Plain CLI output stays neutral rather than implying a verified mutation.
+
+Expand a result using your configured tool-expansion shortcut to see the workspace, request, colored diff hunks, and complete original returned evidence. The display preserves JSON identifiers and numeric text, masks common credential assignments, and removes terminal control sequences. Rendering does not change tool execution or model-facing output; it is not a general source-code secret scanner.
+
+Run `npm run preview:tools` from a repository checkout for offline examples. The preview uses plain colors and a test expansion binding; Pi supplies the live theme, box, and configured shortcut.
+
 ## Plastic branch footer status
 
 When Pi starts inside a Plastic workspace, this package adds a themed `Plastic <branch>` status to Pi's built-in footer. It discovers the nearest enclosing `.plastic/plastic.workspace` and reads either the selector's `smartbranch` or `br` form as the credential-free branch source. A bounded `cm status` call is used only when the selector has no valid branch. Selector changes and successful same-workspace `plastic_*` tools refresh the status; sibling workspaces are ignored.
@@ -64,7 +72,7 @@ For controlled comparisons, set `PI_PLASTIC_TOOL_LOADING_MODE` before starting P
 ```bash
 PI_PLASTIC_TOOL_LOADING_MODE=balanced    # default production candidate
 PI_PLASTIC_TOOL_LOADING_MODE=loader-only # maximum initial schema reduction
-PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 29 currently exposed tools; loader omitted
+PI_PLASTIC_TOOL_LOADING_MODE=all-active  # all 30 currently exposed tools; loader omitted
 ```
 
 Pi 0.82 and newer use canonical `sourceInfo` provenance to identify this package's effective tools before deferring, restoring, or activating them. If canonical provenance or ownership of the effective loader cannot be proven, `pi-plastic` fails safe: it preserves the complete current active set exactly, does not defer, remove, or activate any `plastic_*` name, and an effective package loader can only report known tools that are already active rather than activating inactive names. On sourceInfo-capable Pi instances, providers without native deferred definitions still receive the complete current active set after a loader call. Reload or restart Pi after source edits; source files are not watched automatically.
@@ -111,13 +119,13 @@ pi install npm:@aefree/pi-plastic
 Install a pinned GitHub release over HTTPS:
 
 ```bash
-pi install git:github.com/aefreedman/pi-plastic@v0.6.0
+pi install git:github.com/aefreedman/pi-plastic@v0.7.0
 ```
 
 Equivalent SSH install:
 
 ```bash
-pi install git:git@github.com/aefreedman/pi-plastic@v0.6.0
+pi install git:git@github.com/aefreedman/pi-plastic@v0.7.0
 ```
 
 To intentionally track the moving default branch instead of a release tag:
@@ -156,7 +164,9 @@ Project-local installation protects only Pi processes that load those project se
 npm test
 ```
 
-The default suite is credential-free and covers tool validation, path-resolution regressions, extension registration, OpenAI strict-schema compatibility classification, and bash guard behavior.
+`npm test` first runs `npm run typecheck` with pinned TypeScript and Node 22 types. The strict, no-emit check covers `index.ts`, `src/`, every extension, and compile-only schema-inference contracts under `tests/types/`. Runtime tests and eval harnesses execute through `tsx`.
+
+The default suite is credential-free and covers tool validation, schema conversion, path-resolution regressions, extension registration, rendering, OpenAI strict-schema compatibility classification, and bash guard behavior.
 
 Run the opt-in read-only live smoke test against a dedicated clean sandbox workspace:
 
@@ -191,6 +201,7 @@ OpenAI Codex models may advertise grammar tools without advertising strict JSON-
 - Shared workspace discovery and branch parsing live in `src/plastic-workspace.ts`.
 - `extensions/plastic-branch-status.ts` owns the additive footer status and its session-scoped refresh lifecycle.
 - `index.ts` is the Pi tool registration layer.
+- `src/plastic-renderers.ts` owns compact calls, result summaries, and expanded evidence.
 - Output shapes are intentionally stable for prompt and workflow compatibility.
 
 ## License

package/extensions/bash-cm-diff-guard.ts

@@ -42,7 +42,7 @@ export const __bashCmDiffGuardInternals = {
 
 export default function bashCmDiffGuard(pi: ExtensionAPI) {
   pi.on("tool_call", async (event, ctx) => {
-    if (!isBashToolCall(event as { toolName?: string })) return;
+    if (!isBashToolCall(event)) return;
 
     const command = typeof event.input.command === "string" ? event.input.command : "";
     if (!command || !commandRunsCmDiff(command)) return;

package/extensions/bash-cm-merge-guard.ts

@@ -36,7 +36,7 @@ export const __bashCmMergeGuardInternals = {
 
 export default function bashCmMergeGuard(pi: ExtensionAPI) {
   pi.on("tool_call", async (event, ctx) => {
-    if (!isBashToolCall(event as { toolName?: string })) return;
+    if (!isBashToolCall(event)) return;
 
     const command = typeof event.input.command === "string" ? event.input.command : "";
     if (!command || !commandRunsUnsafeCmMerge(command)) return;

package/index.ts

@@ -2,6 +2,7 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type TSchema, Type } from "typebox";
 import * as core from "./src/plastic-core";
+import { renderPlasticCall, renderPlasticResult, renderPlasticSearchResult } from "./src/plastic-renderers";
 import {
   getEffectivePlasticToolOwnership,
   getInitiallyInactivePlasticTools,
@@ -39,8 +40,8 @@ type ToolConfig = {
 
 const EXTENSION_SOURCE_PATH = fileURLToPath(import.meta.url);
 const EMPTY_PARAMETERS = Type.Object({});
-const enumSchema = <T extends readonly [string, ...string[]]>(values: T, description: string): TSchema =>
-  Type.Union(values.map((value) => Type.Literal(value)) as [TSchema, TSchema, ...TSchema[]], { description });
+const enumSchema = (values: readonly string[], description: string): TSchema =>
+  Type.Union(values.map((value) => Type.Literal(value)), { description });
 
 const OUTPUT_FORMAT_SCHEMA = enumSchema(["text", "json"], "Output format. Defaults to text.");
 const PENDING_CHANGES_SCHEMA = enumSchema(["shelve", "bring", "cancel"], "How to handle pending changes when switching branches.");
@@ -371,148 +372,11 @@ function toToolName(exportName: string): string {
   return `plastic_${exportName}`;
 }
 
-type TextLikeComponent = {
-  invalidate: () => void;
-  render: (width: number) => string[];
-};
-
-type RenderTheme = {
-  fg?: (color: string, text: string) => string;
-  bold?: (text: string) => string;
-};
-
-type PlasticToolResult = {
-  content?: Array<{ type?: string; text?: string }>;
-  details?: {
-    exportName?: string;
-    rawResult?: unknown;
-  };
-};
-
-const COLLAPSED_RESULT_LINES = 12;
-const ANSI_PATTERN = /\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]/g;
-
 function toText(result: unknown): string {
-  if (typeof result === "string") {
-    return result;
-  }
-
+  if (typeof result === "string") return result;
   return JSON.stringify(result, null, 2);
 }
 
-function visibleLength(value: string): number {
-  return value.replace(ANSI_PATTERN, "").length;
-}
-
-function truncateAnsiLine(value: string, width: number): string {
-  if (width <= 0 || !value) {
-    return "";
-  }
-
-  if (visibleLength(value) <= width) {
-    return value;
-  }
-
-  const target = Math.max(0, width - 1);
-  let visible = 0;
-  let output = "";
-  for (let index = 0; index < value.length;) {
-    const remaining = value.slice(index);
-    const ansi = remaining.match(ANSI_PATTERN);
-    if (ansi && ansi.index === 0) {
-      output += ansi[0];
-      index += ansi[0].length;
-      continue;
-    }
-
-    if (visible >= target) {
-      break;
-    }
-
-    const codePoint = value.codePointAt(index);
-    if (codePoint === undefined) {
-      break;
-    }
-
-    const char = String.fromCodePoint(codePoint);
-    output += char;
-    visible += 1;
-    index += char.length;
-  }
-
-  return `${output}…`;
-}
-
-function textComponent(text: string): TextLikeComponent {
-  return {
-    invalidate() {},
-    render(width: number) {
-      if (!text) {
-        return [];
-      }
-      return text.split(/\r?\n/).map((line) => truncateAnsiLine(line, width));
-    },
-  };
-}
-
-function themed(theme: RenderTheme, color: string, text: string): string {
-  return typeof theme.fg === "function" ? theme.fg(color, text) : text;
-}
-
-function bold(theme: RenderTheme, text: string): string {
-  return typeof theme.bold === "function" ? theme.bold(text) : text;
-}
-
-function extractTextContent(result: PlasticToolResult | undefined): string {
-  return result?.content
-    ?.filter((entry) => entry?.type === "text")
-    .map((entry) => String(entry.text ?? ""))
-    .join("\n") ?? "";
-}
-
-function trimTrailingEmptyLines(lines: string[]): string[] {
-  let end = lines.length;
-  while (end > 0 && lines[end - 1]?.trim() === "") {
-    end -= 1;
-  }
-  return lines.slice(0, end);
-}
-
-function renderPlasticCall(exportName: string, args: Record<string, unknown>, theme: RenderTheme): TextLikeComponent {
-  const target = args.workdir ?? args.branch ?? args.source ?? args.path ?? args.paths ?? args.target ?? args.shelveset ?? args.id ?? "";
-  const targetText = Array.isArray(target) ? target.join(", ") : String(target);
-  const suffix = targetText ? ` ${themed(theme, "accent", targetText)}` : "";
-  return textComponent(`${themed(theme, "toolTitle", bold(theme, toToolName(exportName)))}${suffix}`);
-}
-
-function renderPlasticResult(
-  exportName: string,
-  result: PlasticToolResult | undefined,
-  options: { expanded?: boolean; isPartial?: boolean } | undefined,
-  theme: RenderTheme,
-): TextLikeComponent {
-  if (options?.isPartial) {
-    return textComponent(themed(theme, "warning", `Running ${toToolName(exportName)}...`));
-  }
-
-  const output = extractTextContent(result);
-  const lines = trimTrailingEmptyLines(output.split(/\r?\n/).map((line) => line.replace(/\t/g, "  ")));
-  const maxLines = options?.expanded ? lines.length : COLLAPSED_RESULT_LINES;
-  const displayLines = lines.slice(0, maxLines);
-  const remaining = lines.length - displayLines.length;
-  const rendered = displayLines.map((line) => themed(theme, "toolOutput", line));
-
-  if (remaining > 0) {
-    rendered.push(themed(theme, "muted", `... (${remaining} more lines, ctrl+o to expand)`));
-  }
-
-  if (rendered.length === 0) {
-    rendered.push(themed(theme, "toolOutput", "(no output)"));
-  }
-
-  return textComponent(rendered.join("\n"));
-}
-
 function normalizeArgs(args: unknown): Record<string, unknown> {
   return args && typeof args === "object" ? { ...(args as Record<string, unknown>) } : {};
 }
@@ -563,7 +427,7 @@ function isCoreSchemaNode(value: unknown): value is CoreSchemaNode {
 
 function applySchemaMetadata(schema: TSchema, node: CoreSchemaNode): TSchema {
   const metadata = node.metadata ?? {};
-  const options: Record<string, unknown> = {};
+  const options: { description?: string; minimum?: number; maximum?: number } = {};
 
   if (metadata.description) options.description = metadata.description;
   if (metadata.min !== undefined) options.minimum = metadata.min;
@@ -571,15 +435,15 @@ function applySchemaMetadata(schema: TSchema, node: CoreSchemaNode): TSchema {
 
   let nextSchema: TSchema = schema;
   if (Object.keys(options).length > 0) {
-    if (schema.type === "string") nextSchema = Type.String(options);
-    else if (schema.type === "number" || schema.type === "integer") nextSchema = metadata.int ? Type.Integer(options) : Type.Number(options);
-    else if (schema.type === "boolean") nextSchema = Type.Boolean(options);
-    else if (schema.type === "array") nextSchema = Type.Array((schema as any).items ?? Type.Any(), options);
+    if (Type.IsString(schema)) nextSchema = Type.String(options);
+    else if (Type.IsNumber(schema) || Type.IsInteger(schema)) nextSchema = metadata.int ? Type.Integer(options) : Type.Number(options);
+    else if (Type.IsBoolean(schema)) nextSchema = Type.Boolean(options);
+    else if (Type.IsArray(schema)) nextSchema = Type.Array(schema.items, options);
     else nextSchema = Type.Unsafe({ ...schema, ...options });
   }
 
-  if (metadata.int && nextSchema.type === "number") {
-    nextSchema = Type.Integer({ description: options.description as string | undefined, minimum: options.minimum as number | undefined, maximum: options.maximum as number | undefined });
+  if (metadata.int && Type.IsNumber(nextSchema)) {
+    nextSchema = Type.Integer(options);
   }
 
   return metadata.optional ? Type.Optional(nextSchema) : nextSchema;
@@ -617,7 +481,7 @@ function convertCoreSchema(node: unknown): TSchema {
     case "enum": {
       const values = Array.isArray(node.values) ? node.values : [];
       if (values.every((value) => typeof value === "string")) {
-        const valueSet = values as string[];
+        const valueSet = values;
         if (arraysEqual(valueSet, ["text", "json"])) {
           schema = OUTPUT_FORMAT_SCHEMA;
         } else if (arraysEqual(valueSet, ["shelve", "bring", "cancel"])) {
@@ -633,17 +497,17 @@ function convertCoreSchema(node: unknown): TSchema {
         } else if (arraysEqual(valueSet, ["date", "modifieddate", "status"])) {
           schema = REVIEW_ORDER_BY_SCHEMA;
         } else {
-          schema = enumSchema(valueSet as [string, ...string[]], metadataDescription(node));
+          schema = enumSchema(valueSet, metadataDescription(node));
         }
       } else {
-        schema = Type.Union(values.map((value) => literalSchema(value)) as [TSchema, TSchema, ...TSchema[]]);
+        schema = Type.Union(values.map((value) => literalSchema(value)));
       }
       break;
     }
     case "union": {
       const values = Array.isArray(node.values) ? node.values : [];
       const converted = values.map((value) => convertCoreSchema(value));
-      schema = converted.length > 1 ? Type.Union(converted as [TSchema, TSchema, ...TSchema[]]) : (converted[0] ?? Type.Any());
+      schema = converted.length > 1 ? Type.Union(converted) : (converted[0] ?? Type.Any());
       break;
     }
     default:
@@ -712,11 +576,11 @@ export default function plasticTools(pi: ExtensionAPI) {
       description: coreTool.description ?? toToolName(exportName),
       parameters: buildParameters(coreTool.args),
       prepareArguments: config.prepareArguments,
-      renderCall(args, theme) {
-        return renderPlasticCall(exportName, (args ?? {}) as Record<string, unknown>, theme as RenderTheme);
+      renderCall(args, theme, context) {
+        return renderPlasticCall(exportName, args ?? {}, theme, context);
       },
-      renderResult(result, options, theme) {
-        return renderPlasticResult(exportName, result as PlasticToolResult | undefined, options, theme as RenderTheme);
+      renderResult(result, options, theme, context) {
+        return renderPlasticResult(exportName, result, options, theme, context);
       },
       async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         const normalizedParams = normalizeArgs(params);
@@ -730,6 +594,7 @@ export default function plasticTools(pi: ExtensionAPI) {
           details: {
             exportName,
             rawResult: result,
+            ...(typeof normalizedParams.workdir === "string" ? { workdir: normalizedParams.workdir } : {}),
           },
         };
       },
@@ -749,6 +614,12 @@ export default function plasticTools(pi: ExtensionAPI) {
       toolNames: Type.Optional(Type.Array(Type.String({ description: "Exact public Plastic tool name." }), { maxItems: 4, description: "Optional exact tool names to enable." })),
       limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 4, description: "Maximum matching tools to enable. Defaults to the single best keyword match; exact toolNames requests may enable up to four." })),
     }),
+    renderCall(args, theme, context) {
+      return renderPlasticCall("tool_search", args ?? {}, theme, context);
+    },
+    renderResult(result, options, theme, context) {
+      return renderPlasticSearchResult(result, options, theme, context);
+    },
     async execute(_toolCallId, params) {
       if (isPlasticToolBrowseRequest(params)) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-plastic",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "engines": {
     "node": ">=22.19.0"
@@ -33,7 +33,10 @@
     ]
   },
   "scripts": {
-    "test": "tsx tests/release-registry-preflight.test.ts && tsx tests/plastic-tool-validation.ts && tsx tests/plastic-status-machine-readable.test.ts && tsx tests/plastic-checkin-path-resolution.ts && tsx tests/plastic-diff-workflow.test.ts && tsx tests/plastic-workspace-diff.test.ts && tsx tests/plastic-process-lifecycle.test.ts && tsx tests/plastic-patch-command.test.ts && tsx tests/plastic-capability-diagnostics.test.ts && tsx tests/plastic-extension-registration.test.ts && tsx tests/plastic-dynamic-tool-loading.test.ts && tsx tests/plastic-tool-rendering.test.ts && tsx tests/plastic-branch-query.test.ts && tsx tests/plastic-workspace.test.ts && tsx tests/plastic-mutation-execution.test.ts && tsx tests/plastic-merge-branches.test.ts && tsx tests/file-discovery-filter.test.ts && tsx tests/file-discovery-filter-registration.test.ts && tsx tests/packed-copy-owner-conflict.test.ts && tsx tests/plastic-branch-status.test.ts && tsx tests/plastic-constrained-sampling.test.ts && tsx tests/bash-cm-diff-guard-validation.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "pretest": "npm run typecheck",
+    "test": "tsx tests/tool-definition.test.ts && tsx tests/release-registry-preflight.test.ts && tsx tests/plastic-tool-validation.ts && tsx tests/plastic-status-machine-readable.test.ts && tsx tests/plastic-checkin-path-resolution.ts && tsx tests/plastic-diff-workflow.test.ts && tsx tests/plastic-workspace-diff.test.ts && tsx tests/plastic-process-lifecycle.test.ts && tsx tests/plastic-patch-command.test.ts && tsx tests/plastic-capability-diagnostics.test.ts && tsx tests/plastic-extension-registration.test.ts && tsx tests/plastic-dynamic-tool-loading.test.ts && tsx tests/plastic-tool-rendering.test.ts && tsx tests/plastic-branch-query.test.ts && tsx tests/plastic-workspace.test.ts && tsx tests/plastic-mutation-execution.test.ts && tsx tests/plastic-merge-branches.test.ts && tsx tests/file-discovery-filter.test.ts && tsx tests/file-discovery-filter-registration.test.ts && tsx tests/packed-copy-owner-conflict.test.ts && tsx tests/plastic-branch-status.test.ts && tsx tests/plastic-constrained-sampling.test.ts && tsx tests/bash-cm-diff-guard-validation.ts",
+    "preview:tools": "tsx tests/plastic-tool-rendering.test.ts --preview",
     "test:live": "tsx tests/plastic-live-smoke.test.ts",
     "test:live:branch-create": "tsx tests/plastic-branch-create-live.test.ts",
     "eval:tool-loading": "tsx evals/tool-loading/run-eval.ts"
@@ -41,12 +44,16 @@
   "devDependencies": {
     "@aefree/pi-file-discovery": "^0.1.1",
     "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
+    "@types/node": "22.20.2",
     "tsx": "4.23.5",
-    "typebox": "^1.3.8"
+    "typebox": "^1.3.8",
+    "typescript": "7.0.2"
   },
   "peerDependencies": {
     "@aefree/pi-file-discovery": "^0.1.0",
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
   "description": "Pi tools and skills for Plastic SCM and Unity Version Control workflows.",
@@ -66,6 +73,9 @@
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "typebox": {
       "optional": true
     }

package/skills/using-plastic/SKILL.md

@@ -10,6 +10,8 @@ Purpose: PlasticSCM operations for Unity workflows.
 
 Never run `cm diff` in Pi. It may launch GUI windows and block the CLI agent.
 
+`cm cat --file=<path>` writes to that path and can overwrite existing files; `--file` is never an input selector. Never point it at a canonical workspace file during inspection or review, even when piping stdout elsewhere. Use typed diff tools for baseline comparisons. If a typed tool cannot represent a required export, read the [historical export rules](references/changeset-operations.md#historical-export-fallback) first. A changeset number is not a file revision ID; never turn `cs:<number>` into `revid:<number>`.
+
 Never run interactive `cm merge --merge` flows. Use `plastic_merge` (preferred) or explicitly pass `--nointeractiveresolution --mergetype=try` (safe default). Use source/destination policy flags only as explicit overrides.
 
 Treat `plastic_merge` success as provisional until `plastic_status` confirms there are no merge-in-progress hints. Pending merge links are expected until the merge result is checked in; merge-in-progress hints are not. If files are manually resolved and validated but checkin is blocked by Plastic merge metadata, use `plastic_finalizeMerge` with an explicit source/destination policy before retrying checkin.

package/skills/using-plastic/references/changeset-operations.md

@@ -84,6 +84,20 @@ plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevisio
 
 The typed diff tools own historical `cm cat --file` materialization and cleanup; do not create agent-authored temporary files for ordinary diffs. `cm cat --raw` is unsupported for this workflow. Use typed retrieval first; `cm cat --file` is the byte-preserving low-level fallback only when a typed tool cannot represent the case.
 
+## Historical Export Fallback
+
+Use this fallback only when typed retrieval cannot represent the required case. For an ordinary workspace-base comparison, omit `revision` from `plastic_diffFile`; for a changeset comparison, supply its `revision="cs:<number>"` argument.
+
+`cm cat <revspec> --file=<output-file>` writes historical bytes to the output file and can overwrite it. `--file` does not select the source. Piping this command to `Set-Content` or redirecting stdout does not change the destination or protect it: with `--file`, the file contents are written there rather than to stdout.
+
+Before a necessary manual export:
+
+- Verify the source selector. `revid:<id>` means an actual file revision ID, not a workspace changeset number. Use a verified repository/server-qualified revision ID, or a file-qualified `<path>#cs:<number>` selector for a file at a changeset.
+- Create a new unique temporary directory outside the workspace and select a new absolute output path within it. Confirm that the destination does not exist. Never use a canonical workspace path or an existing baseline as the export destination.
+- Export directly to that temporary destination; do not combine `--file` with a stdout pipeline to capture the content. Check command success and the exported content before comparison. Keep comparison baselines immutable.
+
+If an export overwrites a workspace file, stop further exports and edits, record the exact command and destination, and inspect pending status. A clean status after exporting base revisions can mean pending work was erased; it does not prove successful review. Report the incident before attempting recovery, and preserve unrelated user changes.
+
 ## Commit Message Format
 
 Use conventional commits from ../../_shared/references/conventional-commits.md.

package/skills/using-plastic/references/reviewing-changes.md

@@ -33,6 +33,8 @@ plastic_diffRevisions(leftRevision="<left-file-qualified-revspec>", rightRevisio
 
 The diff tools materialize historical bytes and remove their temporary files internally. Added and explicitly selected private/new files use an empty base; an added empty file is reported as `added-empty`, not generic unchanged. Changed, moved, and deleted records use their status revision ID when available. A `--nodata` item cannot supply historical/base bytes: refresh the workspace or use two known file-qualified revisions. `plastic_workspaceDiff` requires selected paths or `allPending=true` and returns per-file unavailable outcomes instead of aborting the batch. Text-diff tools use bounded GNU/POSIX text diff, materialize backend operands to ASCII-safe package paths while preserving logical Unicode output labels, treat valid Unity YAML as text, and report genuine binary content explicitly. Do not construct `cm cat` temporary-file recipes for ordinary review. `cm cat --raw` is unsupported in this workflow; typed retrieval owns cleanup, and `cm cat --file` is the byte-preserving low-level fallback only when needed.
 
+`cm cat --file` is a filesystem write: its argument is the output destination, never the source file. Pointing it at a working file overwrites pending changes even if stdout is piped to a temporary file. Reviewers must use typed comparisons for ordinary baseline review; a necessary unsupported export must follow the [historical export rules](changeset-operations.md#historical-export-fallback), with a new absolute temporary destination outside the workspace and a verified file revision selector.
+
 ## Metadata Listing (No GUI Diff)
 
 Use changeset metadata to understand branch activity:

package/src/plastic-core.ts

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { isUtf8 } from "node:buffer";
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { tool } from "./pi-tool-compat";
+import { tool } from "./tool-definition";
 import { promises as fs, realpathSync, statSync } from "node:fs";
 import { tmpdir } from "os";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, win32 } from "path";

package/src/plastic-renderers.ts

@@ -0,0 +1,262 @@
+import { stripVTControlCharacters } from "node:util";
+import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+
+type Args = Record<string, unknown>;
+type RenderTheme = Pick<Theme, "fg" | "bold">;
+type Context = { args?: unknown; cwd?: string; isError?: boolean; lastComponent?: unknown };
+type Result = { content?: Array<{ type: string; text?: string }>; details?: unknown };
+type Options = { expanded?: boolean; isPartial?: boolean };
+type Tone = "success" | "warning" | "error" | "toolOutput";
+type Summary = { label: string; tone: Tone; notices: string[]; rows: string[] };
+const separator = " \u00b7 ";
+
+const titles: Record<string, string> = {
+  status: "Status", currentBranch: "Current branch", update: "Update", add: "Add", checkin: "Check in", undo: "Undo",
+  resolveDeleteChangeConflict: "Resolve deletion", diff: "Diff (disabled)", patch: "Review patch", diffRevisions: "Revision diff",
+  diffFile: "File diff", workspaceDiff: "Workspace diff", branchCreate: "Create branch", switchBranch: "Switch branch",
+  merge: "Merge", mergeBranches: "Server merge", mergeToBranch: "Merge and check in", finalizeMerge: "Finalize merge",
+  branchList: "Branches", branchExists: "Branch exists", branchDelete: "Delete branch", shelvesetCreate: "Create shelveset",
+  shelvesetApply: "Apply shelveset", shelvesetDelete: "Delete shelveset", shelvesetList: "Shelvesets",
+  codeReviewCreate: "Create review", codeReviewUpdate: "Update review", codeReviewDelete: "Delete reviews",
+  codeReviewFind: "Find reviews", workspaceList: "Workspaces", tool_search: "Find tools",
+};
+
+function record(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+function scalar(value: unknown): string {
+  // Parsed numbers must not turn rounded revision/changeset IDs into plausible evidence.
+  return typeof value === "string" ? value : typeof value === "number" && Number.isSafeInteger(value) ? String(value) : "";
+}
+function count(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+function records(value: unknown): Record<string, unknown>[] {
+  return Array.isArray(value) ? value.map(record) : [];
+}
+function safe(value: string): string {
+  return stripVTControlCharacters(value).replace(/\r\n/g, "\n").replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, "")
+    .replace(/("(?:token|secret|password|api[_-]?key)"\s*:\s*)"(?:\\.|[^"\\])*"/gi, '$1"[redacted]"')
+    .replace(/\b(token|secret|password|api[_-]?key)\s*([:=])\s*("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;)}\]]+)/gi, "$1$2[redacted]");
+}
+function compact(value: string, width = 180): string {
+  return truncateToWidth(safe(value).replace(/\s+/g, " ").trim(), width);
+}
+function body(result: Result): string {
+  return (result.content ?? []).filter(entry => entry.type === "text").map(entry => entry.text ?? "").join("\n");
+}
+function reuse(context: Context | undefined, text: string): Text {
+  const component = context?.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+  component.setText(text);
+  return component;
+}
+function list(value: unknown): string {
+  const items = strings(value);
+  return items.slice(0, 2).map(item => compact(item, 85)).join(", ") + (items.length > 2 ? ` (+${items.length - 2} more)` : "");
+}
+function target(name: string, args: Args): string {
+  if (name === "tool_search") return list(args.toolNames) || scalar(args.query) || "Browse capabilities";
+  if (name === "diffRevisions") return `${scalar(args.leftRevision) || "..."} -> ${scalar(args.rightRevision) || "..."}`;
+  if (name === "mergeBranches" || name === "mergeToBranch") return `${scalar(args.source) || "..."} -> ${scalar(args.target) || "parent branch"}`;
+  if (name === "patch" || name === "diff") return [scalar(args.source), scalar(args.destination)].filter(Boolean).join(" -> ");
+  if (name === "diffFile") return [scalar(args.path), args.revision ? `vs ${scalar(args.revision)}` : "vs workspace base"].join(" ");
+  return scalar(args.branch) || scalar(args.source) || scalar(args.path) || list(args.paths) || scalar(args.shelveset)
+    || list(args.ids) || scalar(args.id) || scalar(args.target) || scalar(args.nameLike) || scalar(args.titleLike)
+    || (args.allPending === true ? "All pending files" : "");
+}
+
+export function renderPlasticCall(name: string, input: unknown, theme: RenderTheme, context?: Context): Text {
+  const args = record(input);
+  const workdir = scalar(args.workdir) || context?.cwd || "";
+  const workspace = name === "mergeBranches" ? "server" : workdir.replace(/[\\/]+$/, "").split(/[\\/]/).pop();
+  let text = theme.fg("toolTitle", theme.bold(`Plastic${separator}${titles[name] ?? name}`));
+  if (workspace && name !== "tool_search") text += theme.fg("dim", `  ${compact(workspace, 60)}`);
+  if (args.preflight === true) text += theme.fg("warning", `${separator}preview`);
+  const subtitle = target(name, args);
+  if (subtitle) text += `\n${theme.fg("accent", compact(subtitle))}`;
+  return reuse(context, text);
+}
+
+function payload(result: Result, raw: string): Record<string, unknown> {
+  const rawResult = record(result.details).rawResult;
+  if (rawResult !== null && typeof rawResult === "object") return record(rawResult);
+  // Only decode the package's whole JSON envelope, never a JSON fragment in CLI or diff output.
+  const source = typeof rawResult === "string" ? rawResult : raw;
+  const json = source.match(/^## [^\r\n]+\r?\n\r?\n```json\r?\n([\s\S]*)\r?\n```\s*$/)?.[1] ?? source;
+  try { return record(JSON.parse(json)); }
+  catch (error) { if (error instanceof SyntaxError) return {}; throw error; }
+}
+
+function pending(summary: Record<string, unknown>): string {
+  const total = count(summary.totalPending);
+  if (total === undefined) return "Status returned";
+  const parts = [total === 0 ? "0 pending records" : `${total} pending`];
+  for (const key of ["changed", "added", "moved", "deleted", "private", "other"]) {
+    const amount = count(summary[key]);
+    if (amount) parts.push(`${amount} ${key}`);
+  }
+  return parts.join(separator);
+}
+
+function summarize(name: string, result: Result, raw: string, context?: Context): Summary {
+  const envelope = payload(result, raw);
+  const data = record(envelope.data);
+  const action = scalar(envelope.action);
+  const notices = strings(envelope.warnings);
+  const summary: Summary = { label: "Result returned", tone: "toolOutput", notices, rows: [] };
+  const textLines = raw.split(/\r?\n/).filter(line => line.trim());
+  const preview = record(context?.args).preflight === true || action.endsWith("-preflight") || envelope.outcome === "preflight";
+  if (context?.isError) {
+    summary.label = "Failed";
+    summary.tone = "error";
+    summary.rows = textLines.slice(0, 3);
+    return summary;
+  }
+  if (preview) {
+    const wouldRun = typeof data.wouldRun === "boolean" ? data.wouldRun : /^- Would run: no$/m.test(raw) ? false : /^- Would run: yes$/m.test(raw) ? true : undefined;
+    summary.label = wouldRun === false ? "Preview: would not run" : wouldRun === true ? "Preview: would run" : "Preview returned";
+    summary.tone = "warning";
+    summary.rows = action ? [scalar(data.reason) || scalar(data.errorCode), scalar(data.strategy)].filter(Boolean) : textLines.filter(line => /^- (?:Reason|Strategy|Command):/.test(line));
+  } else if (name === "mergeBranches" && typeof envelope.outcome === "string") {
+    summary.label = `Server merge: ${envelope.outcome}`;
+    summary.tone = envelope.outcome === "completed" ? "success" : "warning";
+    const changeset = scalar(record(data.createdChangeset).id);
+    if (changeset) summary.label += `${separator}cs:${changeset}`;
+    if (data.mergeLinkIdentity === "unverified" || data.xlinkEffects === "unverified") notices.push("Merge-link identity and Xlink effects remain unverified.");
+    if (data.effect === "uncertain" || data.effect === "not-proven") notices.unshift("Effects not proven; inspect server state before any retry.");
+    if (data.timedOut === true) notices.unshift("Command timed out; effects uncertain.");
+    if (data.aborted === true) notices.unshift("Command cancelled; effects uncertain.");
+  } else if (data.checkedIn === false || record(data.switchOutcome).kind === "canceled" || data.kind === "canceled" || data.strategy === "cancel-with-pending") {
+    summary.label = data.checkedIn === false ? "Checkin not performed" : "Switch cancelled";
+    summary.tone = "warning";
+    const reason = scalar(record(data.switchOutcome).reason) || scalar(data.reason);
+    if (reason) notices.unshift(reason);
+  } else if (envelope.ok === false) {
+    summary.label = "Operation not successful";
+    summary.tone = "error";
+  } else if (name === "status" && count(record(data.summary).totalPending) !== undefined) {
+    summary.label = pending(record(data.summary));
+    summary.rows = records(data.items).map(item => `${scalar(item.statusCode) || scalar(item.kind)}  ${scalar(item.sourcePath) ? `${scalar(item.sourcePath)} -> ` : ""}${scalar(item.path)}`);
+    const omitted = count(record(data.itemCount).omitted);
+    if (omitted) notices.push(`${omitted} status records omitted by the tool.`);
+  } else if (name === "currentBranch" && typeof data.branch === "string") {
+    summary.label = data.branch;
+  } else if (name === "branchExists" && /^(true|false)$/.test(raw.trim())) {
+    summary.label = raw.trim() === "true" ? "Branch found" : "Branch not found";
+  } else if ((name === "diffFile" || name === "diffRevisions") && typeof data.status === "string") {
+    summary.label = data.status === "unchanged" ? "No differences" : data.status === "binary-different" ? "Binary content differs" : data.status === "added-empty" ? "Added file is empty" : "Text differences";
+    if (data.binary === true) notices.push("Binary comparison; no text hunks.");
+  } else if (name === "workspaceDiff" && Array.isArray(data.outcomes)) {
+    const outcomes = records(data.outcomes);
+    const unavailable = outcomes.filter(item => item.status === "unavailable");
+    const skipped = outcomes.filter(item => item.status === "skipped-directory");
+    summary.label = `${outcomes.length} results${separator}${outcomes.filter(item => item.changed === true).length} changed${separator}${unavailable.length} unavailable`;
+    if (unavailable.length) summary.tone = "warning";
+    if (skipped.length) notices.push(`${skipped.length} directories skipped.`);
+    summary.rows = [...unavailable, ...outcomes.filter(item => item.status !== "unavailable" && item.status !== "skipped-directory"), ...skipped].map(item => `${scalar(item.path)}: ${scalar(item.status)}${item.error ? ` - ${scalar(item.error)}` : ""}`);
+    if (outcomes.some(item => item.truncated === true)) notices.push("Some file diffs were truncated by the tool.");
+    if (count(data.omittedOutcomes)) notices.push(`${data.omittedOutcomes} outcomes omitted by the tool.`);
+    if (count(data.skippedByLimit)) notices.push(`${data.skippedByLimit} pending items skipped by the file limit.`);
+  } else if (name === "patch" && typeof envelope.status === "string") {
+    summary.label = `Patch ${envelope.status}${count(envelope.bytes) !== undefined ? `${separator}${envelope.bytes} bytes` : ""}`;
+    if (envelope.binaryLimited === true) notices.push("Binary content could not be fully represented.");
+    if (envelope.truncated === true) notices.push("Patch output truncated by the tool.");
+    summary.rows = [scalar(envelope.output)].filter(Boolean);
+  } else if (data.checkedIn === true) {
+    summary.label = `Merge checked in${scalar(data.finalBranch) ? `${separator}${scalar(data.finalBranch)}` : ""}`;
+    summary.tone = "success";
+  } else if (count(data.resultCount) !== undefined) {
+    summary.label = `${data.resultCount} returned rows`;
+    summary.rows = scalar(data.rawOutput).split(/\r?\n/).filter(Boolean);
+  } else if (action) {
+    summary.label = `${titles[name] ?? action}: result returned`;
+    const outputLines = scalar(data.rawOutput).split(/\r?\n/).filter(Boolean);
+    if (outputLines.length) { summary.label = outputLines[0]; summary.rows = outputLines.slice(1); }
+    if (name === "switchBranch" && typeof data.branchAfter === "string") summary.label = `Workspace branch: ${data.branchAfter}`;
+    if (name === "merge") summary.label = "Merge command returned";
+  } else {
+    // Unknown and legacy text results stay neutral: command completion is not proof of a mutation.
+    summary.label = textLines[0]?.replace(/^#+\s*/, "") || "No output";
+    summary.rows = textLines.slice(1);
+  }
+  if (!action) {
+    const urgent = textLines.filter(line => /^(?:## .* (?:Blocked|Paused|Uncertain|Unsupported|Conflict)\b|(?:- )?(?:Unavailable:|Error:|Reason:|Effect:|.*[Cc]ancel(?:l)?ed\b))/.test(line));
+    const warnings = textLines.filter(line => /^(?:- )?(?:Warning:|Merge-link identity:|Xlink effects:)|^\[.*truncat/.test(line));
+    notices.unshift(...urgent.map(line => line.replace(/^#+\s*/, "")));
+    notices.push(...warnings);
+  }
+  if (data.truncated === true || data.outputTruncated === true) notices.push("Output truncated by the tool.");
+  const limited = data.truncated === true || data.outputTruncated === true || envelope.truncated === true
+    || Boolean(count(record(data.itemCount).omitted) || count(data.omittedOutcomes) || count(data.skippedByLimit))
+    || records(data.outcomes).some(item => item.truncated === true);
+  if (limited) summary.label += `${separator}partial output`;
+  for (const state of [record(data.mergeState), record(data.mergeStateAfterMerge), record(data.mergeStateAfterFinalize)]) {
+    if (state.hasMergeInProgress === true) notices.unshift("Merge still in progress; finalization may be required.");
+    const links = strings(state.pendingMergeLinks).length;
+    if (links) notices.push(`${links} pending merge links.`);
+  }
+  if (data.usedNoChangesRecovery === true) notices.unshift("Checkin used clean-workspace recovery; inspect original evidence.");
+  if (typeof envelope.nextSuggestedAction === "string") notices.push(envelope.nextSuggestedAction);
+  if (notices.length && summary.tone !== "error") summary.tone = "warning";
+  return summary;
+}
+
+function evidence(text: string, theme: RenderTheme): string {
+  return safe(text).split("\n").map(line => {
+    const color = line.startsWith("+") ? "toolDiffAdded" : line.startsWith("-") ? "toolDiffRemoved" : line.startsWith("@@") ? "accent" : "toolOutput";
+    return theme.fg(color, line);
+  }).join("\n");
+}
+
+export function renderPlasticResult(name: string, result: Result, options: Options, theme: RenderTheme, context?: Context): Text {
+  const raw = body(result);
+  if (options.isPartial) return reuse(context, theme.fg("warning", `Running${separator}${compact(raw || titles[name] || name)}`));
+  const summary = summarize(name, result, raw, context);
+  const symbol = summary.tone === "success" ? "\u2713" : summary.tone === "error" ? "\u2717" : summary.tone === "warning" ? "!" : "\u2022";
+  let text = theme.fg(summary.tone, `${symbol} ${compact(summary.label, 220)}`);
+  const notices = [...new Set(summary.notices)];
+  for (const notice of notices.slice(0, options.expanded ? notices.length : 2)) text += `\n${theme.fg("warning", options.expanded ? safe(notice) : compact(notice))}`;
+  if (!options.expanded) {
+    if (notices.length > 2) text += `\n${theme.fg("dim", `${notices.length - 2} more notices`)}`;
+    for (const row of summary.rows.slice(0, 2)) text += `\n${theme.fg(summary.tone === "error" ? "error" : "muted", compact(row))}`;
+    if (summary.rows.length > 2) text += `\n${theme.fg("dim", `${summary.rows.length - 2} more rows`)}`;
+    if (raw) text += `\n${theme.fg("dim", keyHint("app.tools.expand", "details"))}`;
+  } else {
+    const section = (title: string, value: string) => { if (value) text += `\n\n${theme.fg("toolTitle", theme.bold(title))}\n${value}`; };
+    const args = record(context?.args);
+    const workdir = scalar(record(result.details).workdir) || scalar(args.workdir) || context?.cwd;
+    if (workdir && name !== "mergeBranches" && name !== "tool_search") section("Workspace", theme.fg("muted", safe(workdir)));
+    if (Object.keys(args).length) section("Request", theme.fg("muted", safe(JSON.stringify(args, null, 2))));
+    const envelope = payload(result, raw);
+    const data = record(envelope.data);
+    if (typeof data.diff === "string") section("Diff", evidence(data.diff, theme));
+    for (const item of records(data.outcomes)) {
+      if (typeof item.diff === "string") section(safe(scalar(item.path)), evidence(item.diff, theme));
+    }
+    if (name === "patch" && typeof envelope.content === "string") section("Patch", evidence(envelope.content, theme));
+    // Keep original content, including JSON numeric lexemes and duplicate keys, as the evidence.
+    section("Evidence", evidence(raw, theme));
+  }
+  return reuse(context, text);
+}
+
+export function renderPlasticSearchResult(result: Result, options: Options, theme: RenderTheme, context?: Context): Text {
+  if (options.isPartial || context?.isError) return renderPlasticResult("tool_search", result, options, theme, context);
+  const details = record(result.details);
+  const added = strings(details.added);
+  const matches = strings(details.matches);
+  const unavailable = strings(details.unavailableToolNames);
+  if (!Array.isArray(details.matches)) return renderPlasticResult("tool_search", result, options, theme, context);
+  const label = details.browse === true ? "Browse Plastic capabilities" : matches.length === 0 ? "No executable tools matched" : `${added.length} activated${separator}${strings(details.alreadyActive).length} already active`;
+  const tone = details.browse === true ? "toolOutput" : unavailable.length || matches.length === 0 ? "warning" : "success";
+  let text = theme.fg(tone, `${tone === "success" ? "\u2713" : tone === "warning" ? "!" : "\u2022"} ${label}`);
+  if (unavailable.length) text += `\n${theme.fg("warning", compact(`Unavailable: ${unavailable.join(", ")}`))}`;
+  for (const name of matches) text += `\n${theme.fg("accent", compact(name))}`;
+  if (options.expanded) text += `\n\n${theme.fg("toolTitle", theme.bold("Guidance"))}\n${evidence(body(result), theme)}`;
+  else text += `\n${theme.fg("dim", keyHint("app.tools.expand", "guidance"))}`;
+  return reuse(context, text);
+}

package/src/tool-definition.ts

@@ -0,0 +1,71 @@
+export interface SchemaNode<Value = unknown> {
+  // Type-only carrier: no runtime field or validation behavior is added.
+  readonly valueType?: Value;
+  kind: string;
+  values?: unknown;
+  inner?: unknown;
+  metadata?: Record<string, unknown>;
+  optional(): SchemaNode<Value> & { readonly optionalField?: true };
+  describe(description: string): this;
+  min(value: number): this;
+  max(value: number): this;
+  int(): this;
+}
+
+type InferSchema<Node> = Node extends SchemaNode<infer Value> ? Value : Node;
+export type InferArguments<Args extends Record<string, SchemaNode>> = {
+  [Key in keyof Args as "optionalField" extends keyof Args[Key] ? never : Key]: InferSchema<Args[Key]>;
+} & {
+  [Key in keyof Args as "optionalField" extends keyof Args[Key] ? Key : never]?: InferSchema<Args[Key]>;
+};
+
+type ToolDefinition<Args extends Record<string, SchemaNode>, Result> = {
+  description: string;
+  args: Args;
+  execute: (args: InferArguments<Args>) => Result;
+};
+
+function createSchemaNode<Value>(kind: string, values?: unknown, inner?: unknown): SchemaNode<Value> {
+  const node: SchemaNode<Value> = {
+    kind,
+    values,
+    inner,
+    metadata: {},
+    optional() {
+      this.metadata = { ...(this.metadata ?? {}), optional: true };
+      return this;
+    },
+    describe(description: string) {
+      this.metadata = { ...(this.metadata ?? {}), description };
+      return this;
+    },
+    min(value: number) {
+      this.metadata = { ...(this.metadata ?? {}), min: value };
+      return this;
+    },
+    max(value: number) {
+      this.metadata = { ...(this.metadata ?? {}), max: value };
+      return this;
+    },
+    int() {
+      this.metadata = { ...(this.metadata ?? {}), int: true };
+      return this;
+    },
+  };
+  return node;
+}
+
+export const tool = Object.assign(
+  <Args extends Record<string, SchemaNode>, Result>(definition: ToolDefinition<Args, Result>): ToolDefinition<Args, Result> => definition,
+  {
+    schema: {
+      string: () => createSchemaNode<string>("string"),
+      number: () => createSchemaNode<number>("number"),
+      boolean: () => createSchemaNode<boolean>("boolean"),
+      any: () => createSchemaNode<unknown>("any"),
+      enum: <const Values extends readonly unknown[]>(values: Values) => createSchemaNode<Values[number]>("enum", [...values]),
+      union: <const Values extends readonly unknown[]>(values: Values) => createSchemaNode<InferSchema<Values[number]>>("union", [...values]),
+      array: <Inner>(inner: Inner) => createSchemaNode<InferSchema<Inner>[]>("array", undefined, inner),
+    },
+  },
+);

package/src/pi-tool-compat.ts

@@ -1,56 +0,0 @@
-type SchemaNode = {
-  kind: string;
-  values?: unknown;
-  inner?: unknown;
-  metadata?: Record<string, unknown>;
-  optional(): SchemaNode;
-  describe(description: string): SchemaNode;
-  min(value: number): SchemaNode;
-  max(value: number): SchemaNode;
-  int(): SchemaNode;
-};
-
-function createSchemaNode(kind: string, values?: unknown, inner?: unknown): SchemaNode {
-  const node: SchemaNode = {
-    kind,
-    values,
-    inner,
-    metadata: {},
-    optional() {
-      this.metadata = { ...(this.metadata ?? {}), optional: true };
-      return this;
-    },
-    describe(description: string) {
-      this.metadata = { ...(this.metadata ?? {}), description };
-      return this;
-    },
-    min(value: number) {
-      this.metadata = { ...(this.metadata ?? {}), min: value };
-      return this;
-    },
-    max(value: number) {
-      this.metadata = { ...(this.metadata ?? {}), max: value };
-      return this;
-    },
-    int() {
-      this.metadata = { ...(this.metadata ?? {}), int: true };
-      return this;
-    },
-  };
-  return node;
-}
-
-export const tool = Object.assign(
-  <T extends Record<string, unknown>>(definition: T): T => definition,
-  {
-    schema: {
-      string: () => createSchemaNode("string"),
-      number: () => createSchemaNode("number"),
-      boolean: () => createSchemaNode("boolean"),
-      any: () => createSchemaNode("any"),
-      enum: (values: readonly unknown[]) => createSchemaNode("enum", [...values]),
-      union: (values: readonly unknown[]) => createSchemaNode("union", [...values]),
-      array: (inner: unknown) => createSchemaNode("array", undefined, inner),
-    },
-  },
-);