@aefree/pi-plastic 0.4.0 → 0.5.0

package/src/plastic-tool-loading.ts

@@ -27,7 +27,8 @@ export const PLASTIC_SEARCH_CATALOG: readonly PlasticSearchCatalogEntry[] = [
   { name: "plastic_undo", aliases: ["undo changes", "revert changes", "discard changes"], tags: ["changes", "mutation", "destructive"], guidance: ["Confirm the exact paths before discarding pending changes."] },
   { name: "plastic_resolveDeleteChangeConflict", aliases: ["resolve delete conflict", "deleted conflict"], tags: ["merge", "conflict", "resolution"], guidance: ["Inspect the conflict and choose whether files should remain on disk before resolving it."] },
   { name: "plastic_patch", aliases: ["patch", "generate patch", "review patch"], tags: ["diff", "patch", "export"], guidance: ["Inspect generated patches before sharing because they can include source, paths, or secrets."] },
-  { name: "plastic_diffFile", aliases: ["diff", "diff file", "file diff", "workspace diff", "compare file"], tags: ["diff", "file", "workspace", "inspect"], guidance: ["For the common workspace diff, pass path and omit revision; use a documented changeset, branch, label, file-qualified, or global revision only when needed."] },
+  { name: "plastic_diffFile", aliases: ["diff", "diff file", "file diff", "compare one file", "compare file"], tags: ["diff", "file", "workspace", "inspect"], guidance: ["For one workspace file, pass path and omit revision; use a documented changeset, branch, label, file-qualified, or global revision only when needed."] },
+  { name: "plastic_workspaceDiff", aliases: ["workspace diff", "pending review", "review pending changes", "review workspace changes", "diff pending files"], tags: ["diff", "workspace", "review", "inspect"], guidance: ["For pending-change review, runs status once and returns bounded per-file outcomes. Private files are excluded unless explicitly selected or includePrivate=true."] },
   { name: "plastic_diffRevisions", aliases: ["diff revisions", "compare revisions", "revision diff"], tags: ["diff", "revision", "inspect"], guidance: ["Use this only for two explicit file-qualified revision specifications."] },
   { name: "plastic_branchCreate", aliases: ["create branch", "new branch"], tags: ["branch", "mutation", "workflow"], guidance: ["Create normal work branches beneath an intended parent, which may differ from the loaded branch. Use allowRootBranch only for intentional top-level branches."] },
   { name: "plastic_switchBranch", aliases: ["switch branch", "checkout branch", "change branch"], tags: ["branch", "workspace", "mutation"], guidance: ["Check pending changes and choose how to handle them before switching branches."] },

package/evals/tool-loading/README.md

@@ -1,38 +0,0 @@
-# Dynamic tool-loading behavioral eval
-
-This package-local eval compares `all-active`, `balanced`, and `loader-only` Plastic tool-loading modes through fresh Pi 0.83 JSON subprocesses. It is intentionally **not** a skill eval: skills, prompt templates, built-in tools, discovered extensions, context files, and sessions are disabled.
-
-## What it measures
-
-- Required Plastic tool calls for status, branch listing, read-only switch/checkin preflight, compound branch list + `/main` verification, no-operation, ambiguous branch discovery, and two implicit contextual discovery prompts (inspect branches; find code reviews) that name neither the loader nor the target public tool.
-- Loader behavior: exactly one `plastic_tool_search` only when a required tool is initially deferred; none for all-active, balanced cases whose target is already active, or the negative case. Whenever a loader is expected, the runner requires its activation result to be exactly the case's smallest sufficient deferred target set.
-- Tool errors, assistant errors, call/output/time bounds, maximum four activation results, and no destructive activation in negative or ambiguous discovery cases. An eval-only extension blocks every destructive Plastic call unless that tool's registered schema supports `preflight` and the call supplies `preflight: true`.
-- JSONL events, assistant usage/cache totals, wall time, initial provider `tools` serialization size, and native `tool_search_call` / `tool_search_output` markers when Pi/provider payloads expose them.
-
-`baseline.json` preserves the legacy 29-tool measurement for comparison. The current all-active mode omits the loader and exposes `28 / 21071` after withholding workspace creation; balanced records `3 / 2133` (89.93% legacy reduction), and loader-only records `1 / 1121` (94.71%). The loader's prompt metadata is 278 characters; the untouched legacy baseline has none.
-
-## Run
-
-A live run requires an explicit approved model and **both** sandbox attestations. `PI_PLASTIC_EVAL_SANDBOX` must resolve to a dedicated workspace containing `.pi-plastic-eval-sandbox` whose complete, exact UTF-8 content is `pi-plastic-eval-sandbox` followed by one LF newline (no other bytes):
-
-```text
-pi-plastic-eval-sandbox
-```
-
-For example, create the marker with `printf 'pi-plastic-eval-sandbox\n' > /absolute/path/to/sandbox/.pi-plastic-eval-sandbox`. Also set `PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox`; this explicit opt-in prevents accidentally targeting an ordinary workspace. Dry runs validate configuration and do **not** require either attestation.
-
-```bash
-PI_PLASTIC_EVAL_SANDBOX=/absolute/path/to/sandbox PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox npm run eval:tool-loading -- --model openai-codex/gpt-5.6-luna
-PI_PLASTIC_EVAL_SANDBOX=/absolute/path/to/sandbox PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox npm run eval:tool-loading -- --model openai-codex/gpt-5.6-terra:medium --condition balanced --cases branch-listing,compound-list-branches-verify-main --trials 2
-```
-
-Only `openai-codex/gpt-5.6-(luna|terra|sol)` with an optional supported thinking level such as `:medium` is accepted. Trials are sequential and bounded to 1–5. Never target an ordinary production workspace.
-
-Validate the configuration without calling a model:
-
-```bash
-npm run eval:tool-loading -- --dry-run
-npm run eval:tool-loading -- --help
-```
-
-Each trial writes provider payloads only to a unique system-temp capture file, never stdout. The runner deletes raw captures by default. Pass `--keep` only when you explicitly need those sensitive raw payloads. Sanitized timestamped summaries are written to ignored `results/`; use `--include-events` to include event type/tool-name crumbs only.

package/evals/tool-loading/RESULTS.md

@@ -1,57 +0,0 @@
-# Dynamic tool-loading pilot results
-
-Date: 2026-07-25  
-Package: `@aefree/pi-plastic`  
-Pi: 0.82.0  
-Model: `openai-codex/gpt-5.6-terra:medium`  
-Sandbox: dedicated `plastic-tool-sandbox` repository
-
-## Decision
-
-The Plastic pilot passes its rollout criteria. Keep the balanced initial set as the production default: `plastic_tool_search`, `plastic_status`, and `plastic_currentBranch`.
-
-- Existing 29 public Plastic tools retain their names and behavior; the loader is additive.
-- Balanced public metadata is 2,117 serialized characters versus the untouched 21,192-character legacy baseline, a 90.01% reduction.
-- Stable live provider payloads contained 1,908 serialized initial tool characters in balanced mode versus 22,120 in the 29-tool legacy all-active mode, a 91.37% reduction.
-- A deferred capability added exactly one loader call/provider round trip and no repeated loader call after activation.
-- Native OpenAI deferred-loading markers (`tool_search_call` and `tool_search_output`) appeared in every deferred GPT-5.6 case and were absent when no loader call was expected.
-- Core outcomes, preflight argument checks, negative controls, and ambiguous branch discovery passed.
-
-## Behavioral evidence
-
-The final expanded diagnostic matrix passed 27/27 trials: nine explicit, implicit, contextual, ambiguous, compound, preflight, and negative cases under all-active, balanced, and loader-only conditions. Five stable status, branch, switch-preflight, checkin-preflight, and compound branch cases passed 45/45 trials over three repetitions per condition. A focused three-trial loader-only regression for contextual branch discovery also passed 3/3 after plural/domain query coverage was added.
-
-Stable-trial measurements:
-
-| Condition | Pass | Initial provider tool chars | Median wall time | Mean wall time | Mean reported total tokens | Mean tool calls |
-|---|---:|---:|---:|---:|---:|---:|
-| all-active | 15/15 | 22,120 | 8.78 s | 9.39 s | 7,180 | 1.20 |
-| balanced | 15/15 | 1,908 | 10.50 s | 10.41 s | 3,295 | 2.00 |
-| loader-only | 15/15 | 832 | 10.23 s | 10.84 s | 3,183 | 2.20 |
-
-The balanced median added about 1.73 seconds (19.7%) in these short cases while reducing initial provider tool serialization by 91.37% and mean reported total tokens by about 54%. Mean provider requests were 2.0 all-active, 2.8 balanced, and 3.0 loader-only; deferred cases account for the accepted first-use loader request, while balanced status remained immediate. Results remain separate because cache reads, input tokens, wall time, and provider requests have different cost/latency implications.
-
-The first diagnostic attempt used a 24,000-character JSONL capture bound and terminated normal Pi event streams before their follow-up tool turn. Raising the bounded capture limit to 2 MiB corrected the harness; no package behavior changed for the passing diagnostic and stable runs. Final live runs also required a sandbox marker, an explicit authorization environment value, and an eval-only guard that blocked mutation-capable tools unless the tool supported and received `preflight: true`.
-
-## Session and compatibility evidence
-
-A persisted loader-only session first called `plastic_tool_search` and `plastic_branchList`. Its tool result stored `addedToolNames: ["plastic_branchList"]`. A fresh Pi process resumed that session, restored `plastic_branchList`, called it directly, and made no second loader call.
-
-Package harness coverage also verifies additive activation without Pi 0.82 `sourceInfo`, representing older/fallback active-list behavior. Pi/provider fallback serialization itself is owned by Pi; this package does not claim a live non-GPT-5.6 provider test.
-
-## Sandbox mutation evidence
-
-The dedicated sandbox was used for real branch, changeset, shelveset, review, merge, conflict-signal, and cleanup operations:
-
-- Created and switched to disposable branch `/dynamic-tool-loading-eval-20260725-1538`.
-- Added a synthetic fixture and created disposable changeset `cs:4`.
-- Created, listed, previewed/applied, undid, and deleted shelveset `sh:2`.
-- Created, found, updated, and deleted code review `21`.
-- Attempted a merge to `/main`; Plastic reported an evil-twin directory conflict before establishing merge state. Explicit source finalization also stopped on that directory conflict, demonstrating the existing safe failure signal rather than silently checking in.
-- Deleted the disposable branch and changeset after the stopped merge.
-
-Final verification found `/main` active, no pending or merge state, and no remaining test branch, shelveset, or review. The private `.pi-plastic-eval-sandbox` attestation marker was removed after the eval; future guarded runs must recreate it deliberately. Workspace creation was not exercised because the package exposes create/list but no paired workspace-delete tool; leaving an account-level test workspace would not improve loader evidence.
-
-## Scope
-
-This result covers the `pi-plastic` pilot only. The recorded seven-case live matrix predates the current two implicit contextual discovery cases, exact smallest-sufficient activation assertion, eval-only preflight mutation guard, and marker/authorization sandbox attestations; no live re-run is implied by those later harness hardenings. Future live runs require `PI_PLASTIC_EVAL_SANDBOX` to contain the documented `.pi-plastic-eval-sandbox` marker and `PI_PLASTIC_EVAL_ALLOW=dedicated-sandbox`. It does not authorize package publishing or version changes, and it does not begin the separate Codecks guidance design or any skill evaluation.

package/evals/tool-loading/baseline.json

@@ -1,34 +0,0 @@
-{
-  "schemaVersion": 1,
-  "measurement": "serializedSchemaChars is JSON.stringify of public registered tool metadata (name, description, parameters, prompt metadata, constrainedSampling); estimated tokens are chars / 4 rounded up. Live provider payload tool serialization is recorded separately by the eval runner.",
-  "legacyBaseline": {
-    "label": "untouched legacy public Plastic tools",
-    "toolCount": 29,
-    "serializedSchemaChars": 21192,
-    "estimatedTokens": 5298,
-    "promptMetadataChars": 0
-  },
-  "implementedConditions": {
-    "all-active": {
-      "toolCount": 28,
-      "serializedSchemaChars": 21071,
-      "estimatedTokens": 5268,
-      "promptMetadataChars": 0,
-      "legacySchemaReductionPercent": 0.57
-    },
-    "balanced": {
-      "toolCount": 3,
-      "serializedSchemaChars": 2133,
-      "estimatedTokens": 534,
-      "promptMetadataChars": 278,
-      "legacySchemaReductionPercent": 89.93
-    },
-    "loader-only": {
-      "toolCount": 1,
-      "serializedSchemaChars": 1121,
-      "estimatedTokens": 281,
-      "promptMetadataChars": 278,
-      "legacySchemaReductionPercent": 94.71
-    }
-  }
-}

package/evals/tool-loading/cases.json

@@ -1,70 +0,0 @@
-{
-  "schemaVersion": 2,
-  "cases": [
-    {
-      "id": "status-inspection",
-      "prompt": "In the dedicated Plastic sandbox, inspect the workspace status now. Call plastic_status exactly once, do not call any other Plastic operation unless plastic_tool_search is required to make plastic_status available, then reply with a one-sentence status summary.",
-      "requiredTools": ["plastic_status"],
-      "minimalActivatedTools": ["plastic_status"],
-      "forbiddenTools": []
-    },
-    {
-      "id": "branch-listing",
-      "prompt": "In the dedicated Plastic sandbox, list the available branches. Call plastic_branchList exactly once. If it is not active, first call plastic_tool_search exactly once and activate only plastic_branchList. Do not mutate the workspace; then give a short result.",
-      "requiredTools": ["plastic_branchList"],
-      "minimalActivatedTools": ["plastic_branchList"],
-      "forbiddenTools": []
-    },
-    {
-      "id": "preflight-branch-switch",
-      "prompt": "Preview, but do not perform, switching the dedicated Plastic sandbox to /main. Call plastic_switchBranch exactly once with branch /main, pendingChanges cancel, preflight true, and the sandbox workdir. If the tool is inactive, first call plastic_tool_search exactly once to activate only plastic_switchBranch. Do not call any other Plastic operation, then summarize the preview.",
-      "requiredTools": ["plastic_switchBranch"],
-      "minimalActivatedTools": ["plastic_switchBranch"],
-      "requiredPreflightTools": ["plastic_switchBranch"],
-      "forbiddenTools": ["plastic_status", "plastic_currentBranch", "plastic_branchCreate", "plastic_merge"]
-    },
-    {
-      "id": "preflight-checkin",
-      "prompt": "Preview, but do not perform, a checkin in the dedicated Plastic sandbox. Call plastic_checkin exactly once with message 'dynamic-loader eval preflight', preflight true, includeAll true, and the sandbox workdir. If the tool is inactive, first call plastic_tool_search exactly once to activate only plastic_checkin. Do not add, undo, or otherwise mutate anything, then summarize the preview.",
-      "requiredTools": ["plastic_checkin"],
-      "minimalActivatedTools": ["plastic_checkin"],
-      "requiredPreflightTools": ["plastic_checkin"],
-      "forbiddenTools": ["plastic_add", "plastic_undo"]
-    },
-    {
-      "id": "compound-list-branches-verify-main",
-      "prompt": "In the dedicated Plastic sandbox, list branches and verify whether /main exists. Call plastic_branchList and plastic_branchExists once each; use /main as the branch-existence argument. If either is inactive, make exactly one plastic_tool_search call that activates both exact tools together. Do not mutate the workspace, then give a short answer.",
-      "requiredTools": ["plastic_branchList", "plastic_branchExists"],
-      "minimalActivatedTools": ["plastic_branchList", "plastic_branchExists"],
-      "forbiddenTools": []
-    },
-    {
-      "id": "negative-no-operation",
-      "prompt": "No Plastic operation is requested. Do not call plastic_tool_search or any plastic_* tool. Reply exactly: NO_OPERATION.",
-      "requiredTools": [],
-      "minimalActivatedTools": [],
-      "forbiddenTools": []
-    },
-    {
-      "id": "ambiguous-branch-discovery",
-      "prompt": "In the dedicated Plastic sandbox, safely discover branch information for a later decision. Prefer a read-only branch listing and call plastic_branchList exactly once. If it is inactive, call plastic_tool_search exactly once with a branch discovery request and activate only read-only branch tools. Do not create, switch, merge, or delete branches; then give a short answer.",
-      "requiredTools": ["plastic_branchList"],
-      "minimalActivatedTools": ["plastic_branchList"],
-      "forbiddenTools": ["plastic_branchCreate", "plastic_switchBranch", "plastic_merge", "plastic_mergeToBranch", "plastic_branchDelete"]
-    },
-    {
-      "id": "contextual-branch-inspection",
-      "prompt": "Before choosing a branch for later work, inspect all available branches in the dedicated sandbox exactly once and give a short read-only summary. Use only the smallest sufficient capability; do not change anything.",
-      "requiredTools": ["plastic_branchList"],
-      "minimalActivatedTools": ["plastic_branchList"],
-      "forbiddenTools": ["plastic_branchCreate", "plastic_switchBranch", "plastic_merge", "plastic_mergeToBranch", "plastic_branchDelete"]
-    },
-    {
-      "id": "contextual-review-discovery",
-      "prompt": "Before planning follow-up work, find the existing code reviews in the dedicated sandbox exactly once and summarize them briefly. Use only the smallest sufficient read-only capability; do not change anything.",
-      "requiredTools": ["plastic_codeReviewFind"],
-      "minimalActivatedTools": ["plastic_codeReviewFind"],
-      "forbiddenTools": ["plastic_codeReviewCreate", "plastic_codeReviewUpdate", "plastic_codeReviewDelete"]
-    }
-  ]
-}

package/evals/tool-loading/config.json

@@ -1,19 +0,0 @@
-{
-  "schemaVersion": 2,
-  "piVersionPrefix": "0.83.",
-  "sandboxCwdEnv": "PI_PLASTIC_EVAL_SANDBOX",
-  "sandboxMarkerFile": ".pi-plastic-eval-sandbox",
-  "sandboxMarkerContent": "pi-plastic-eval-sandbox\n",
-  "sandboxAuthorizationEnv": "PI_PLASTIC_EVAL_ALLOW",
-  "sandboxAuthorizationValue": "dedicated-sandbox",
-  "timeoutMs": 90000,
-  "maxToolCalls": 12,
-  "maxOutputChars": 2097152,
-  "conditions": ["all-active", "balanced", "loader-only"],
-  "destructiveTools": [
-    "plastic_add", "plastic_checkin", "plastic_undo", "plastic_resolveDeleteChangeConflict",
-    "plastic_branchCreate", "plastic_switchBranch", "plastic_merge", "plastic_mergeToBranch",
-    "plastic_finalizeMerge", "plastic_branchDelete", "plastic_shelvesetCreate", "plastic_shelvesetApply",
-    "plastic_shelvesetDelete", "plastic_codeReviewCreate", "plastic_codeReviewUpdate", "plastic_codeReviewDelete"
-  ]
-}

package/evals/tool-loading/mutation-guard.ts

@@ -1,30 +0,0 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-/**
- * Eval-only defense in depth. Live trials may exercise only Plastic operations
- * that expose a preflight parameter and explicitly request that preview mode.
- */
-const DESTRUCTIVE_PLASTIC_TOOLS = new Set([
-  "plastic_add", "plastic_checkin", "plastic_undo", "plastic_resolveDeleteChangeConflict",
-  "plastic_branchCreate", "plastic_switchBranch", "plastic_merge", "plastic_mergeToBranch",
-  "plastic_finalizeMerge", "plastic_branchDelete", "plastic_shelvesetCreate", "plastic_shelvesetApply",
-  "plastic_shelvesetDelete", "plastic_codeReviewCreate", "plastic_codeReviewUpdate", "plastic_codeReviewDelete",
-]);
-
-function supportsPreflight(parameters: unknown): boolean {
-  if (!parameters || typeof parameters !== "object") return false;
-  const properties = (parameters as { properties?: unknown }).properties;
-  return Boolean(properties && typeof properties === "object" && Object.prototype.hasOwnProperty.call(properties, "preflight"));
-}
-
-export default function evalMutationGuard(pi: ExtensionAPI): void {
-  pi.on("tool_call", (event) => {
-    if (!DESTRUCTIVE_PLASTIC_TOOLS.has(event.toolName)) return;
-    const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);
-    if (supportsPreflight(tool?.parameters) && event.input.preflight === true) return;
-    return {
-      block: true,
-      reason: `Eval mutation guard blocked ${event.toolName}: live evals allow destructive Plastic tools only when their schema supports preflight and the call includes preflight: true.`,
-    };
-  });
-}

package/evals/tool-loading/provider-capture.ts

@@ -1,22 +0,0 @@
-import { appendFileSync } from "node:fs";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-/**
- * Eval-only provider payload capture. The runner gives each subprocess a unique
- * temporary file and deletes it unless --keep is requested. Never log payloads:
- * JSON mode stdout must remain a clean Pi event stream.
- */
-const CAPTURE_ENV = "PI_PLASTIC_EVAL_PROVIDER_CAPTURE";
-
-export default function providerCapture(pi: ExtensionAPI): void {
-  const capturePath = process.env[CAPTURE_ENV];
-  if (!capturePath) return;
-
-  pi.on("before_provider_request", (event) => {
-    try {
-      appendFileSync(capturePath, `${JSON.stringify({ timestamp: Date.now(), payload: event.payload })}\n`, { encoding: "utf8", mode: 0o600 });
-    } catch {
-      // Capture must not make a model trial fail or contaminate stdout.
-    }
-  });
-}

package/evals/tool-loading/results/.gitignore

@@ -1,3 +0,0 @@
-*
-!.gitignore
-!.npmignore