pi-system-one 1.2.0 → 1.2.1

package/README.md

@@ -6,6 +6,22 @@ System One decisions for Pi. Plug in TypeSafe Jev, Reflex, or your own provider.
 pi install npm:pi-system-one
 ```
 
+For Oh My Pi (OMP), install the published package with:
+
+```bash
+omp install npm:pi-system-one
+```
+
+For a local checkout, install or load the package directory directly:
+
+```bash
+omp install /path/to/pi-system-one
+# or
+omp --extension /path/to/pi-system-one
+```
+
+Set `SYSTEM_ONE_BASE_URL` before launch, or run `/so config`; the `system_one` tool is registered after the endpoint is configured.
+
 <img src="./demo.gif" alt="Description" width="640" >   
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-system-one",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "System One decisions for Pi. Plug in TypeSafe Jev, Reflex, or your own provider.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "coding-agent"
   ],
   "dependencies": {
-    "system-one-core": "^0.2.0"
+    "system-one-core": "^0.2.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -37,5 +37,10 @@
     "extensions": [
       "./src/extension.ts"
     ]
+  },
+  "omp": {
+    "extensions": [
+      "./src/extension.ts"
+    ]
   }
 }

package/src/tool.ts

@@ -176,14 +176,95 @@ function pickAlias(
   return undefined;
 }
 
+/**
+ * Copy-on-write canonicality check for one question. Returns true when
+ * running the builder below would produce a key-for-key, value-for-value
+ * identical record — in which case the caller reuses the input by
+ * reference instead of allocating a copy. Any doubt returns false (the
+ * builder then produces the correct output); false negatives only cost an
+ * allocation, never correctness.
+ *
+ * Deliberately allocation-free itself (own-key probes, no entries/keys
+ * arrays) so the defensive second normalization in execute() stays cheap.
+ */
+function isCanonicalQuestion(input: Record<string, unknown>): boolean {
+  const hasType = Object.hasOwn(input, "type");
+  // Probe only: an exact canonical spelling (alias-map value identical to
+  // the key) needs no work. Near-miss spellings report non-canonical
+  // WITHOUT running full normalization here — the builder below runs it
+  // exactly once. Non-string types pass (the builder copies them verbatim),
+  // so doubt always errs toward a wasted rebuild, never a wrong share.
+  if (
+    hasType &&
+    typeof input.type === "string" &&
+    QUESTION_TYPE_ALIASES.get(input.type) !== input.type
+  ) {
+    return false;
+  }
+  // Strings reaching here are already canonical, so the raw type doubles
+  // as the normalized one for the criteria decisions below.
+  const normalizedType = hasType ? input.type : undefined;
+  const instructions = pickAlias(input, INSTRUCTIONS_ALIASES);
+  // NOTE: no `else` for an own defined "instructions" slot — "instructions"
+  // is the first alias, so pickAlias would have returned it above; reaching
+  // here with one means it is undefined and the builder omits it too.
+  if (instructions !== undefined) {
+    // The builder emits own "instructions" with this value; canonical only
+    // if it already sits there and no sibling alias key lingers (dropped).
+    if (
+      !Object.hasOwn(input, "instructions") ||
+      input.instructions !== instructions
+    ) {
+      return false;
+    }
+  }
+  for (const alias of INSTRUCTIONS_ALIASES) {
+    if (alias !== "instructions" && Object.hasOwn(input, alias)) return false;
+  }
+  let criteria = pickAlias(input, CRITERIA_ALIASES);
+  if (normalizedType === "noul" && criteria === null) {
+    // The builder drops it; canonical only if no own alias key is dropped.
+    for (const alias of CRITERIA_ALIASES) {
+      if (Object.hasOwn(input, alias)) return false;
+    }
+    criteria = undefined;
+  }
+  if (
+    normalizedType === "choice" &&
+    Array.isArray(criteria) &&
+    (criteria as unknown[]).every((item) => typeof item === "string")
+  ) {
+    return false; // The builder folds string arrays to an object.
+  }
+  if (criteria !== undefined) {
+    if (!Object.hasOwn(input, "criteria") || input.criteria !== criteria) {
+      return false;
+    }
+  } else if (Object.hasOwn(input, "criteria")) {
+    return false; // Own undefined criteria is dropped by the builder.
+  }
+  for (const alias of CRITERIA_ALIASES) {
+    if (alias !== "criteria" && Object.hasOwn(input, alias)) return false;
+  }
+  for (const key of QUESTION_JUNK_KEYS) {
+    if (Object.hasOwn(input, key)) return false;
+  }
+  // Any other own key is preserved by reference, so it cannot differ.
+  return true;
+}
+
 /**
  * Coerce one question into the flat schema shape: canonical `type`,
  * `instructions` / `criteria` resolved through aliases, array-form choice
  * criteria (`["a", "b"]`) folded to `{"a": null, "b": null}`, and
  * naming/junk keys stripped.
+ *
+ * Pure, idempotent, non-mutating, with structural sharing: canonical input
+ * is returned by reference; only repaired questions allocate.
  */
 function normalizeQuestion(input: unknown): unknown {
   if (!isRecord(input)) return input;
+  if (isCanonicalQuestion(input)) return input;
   const out: Record<string, unknown> = {};
   if (Object.hasOwn(input, "type"))
     out.type = normalizeQuestionType(input.type);
@@ -235,13 +316,15 @@ function normalizeQuestions(input: unknown): unknown {
     };
     input.forEach((entry, index) => {
       if (isRecord(entry)) {
-        const { name, id, key, ...rest } = entry;
-        const rawName = name ?? id ?? key;
+        // No intermediate `{...rest}` copy: normalizeQuestion() already
+        // drops name/id/key as junk, so passing the entry through repairs
+        // naming metadata and aliases in a single construction pass.
+        const rawName = entry.name ?? entry.id ?? entry.key;
         const base =
           typeof rawName === "string" && rawName.trim() !== ""
             ? rawName
             : `q${index + 1}`;
-        setOwn(record, claimName(base), normalizeQuestion(rest));
+        setOwn(record, claimName(base), normalizeQuestion(entry));
       } else {
         setOwn(record, claimName(`q${index + 1}`), entry);
       }
@@ -270,9 +353,24 @@ function normalizeQuestions(input: unknown): unknown {
       );
       if (knownKind || allQuestionKeys) return { q: normalizeQuestion(input) };
     }
+    // Copy-on-write: share the map (and each canonical question) when
+    // nothing needs repair; otherwise rebuild with repaired questions and
+    // unaffected siblings shared by reference. The scan probes
+    // canonicality only — it must never build (and discard) repairs.
+    let dirty = false;
+    for (const name in input) {
+      if (!Object.hasOwn(input, name)) continue;
+      const question = input[name];
+      if (!isRecord(question) || !isCanonicalQuestion(question)) {
+        dirty = true;
+        break;
+      }
+    }
+    if (!dirty) return input;
     const record: Record<string, unknown> = {};
-    for (const [name, question] of Object.entries(input)) {
-      setOwn(record, name, normalizeQuestion(question));
+    for (const name in input) {
+      if (!Object.hasOwn(input, name)) continue;
+      setOwn(record, name, normalizeQuestion(input[name]));
     }
     return record;
   }
@@ -286,6 +384,38 @@ function normalizeQuestions(input: unknown): unknown {
  */
 export function prepareSystemOneArgs(args: unknown): SystemOneParams {
   if (!isRecord(args)) return args as SystemOneParams;
+  const questions =
+    args.questions ?? args.question ?? args.queries ?? undefined;
+  const normalizedQuestions =
+    questions !== undefined ? normalizeQuestions(questions) : undefined;
+  // Copy-on-write fast path: canonical state/questions slots, no alias keys
+  // to rename, no unknown keys to drop — return the input by reference so
+  // the defensive re-normalization in execute() allocates ~nothing.
+  const questionsCanonical =
+    normalizedQuestions === questions &&
+    (questions === undefined
+      ? !Object.hasOwn(args, "questions") &&
+        !Object.hasOwn(args, "question") &&
+        !Object.hasOwn(args, "queries")
+      : questions === args.questions &&
+        !Object.hasOwn(args, "question") &&
+        !Object.hasOwn(args, "queries"));
+  if (
+    questionsCanonical &&
+    Object.hasOwn(args, "state") &&
+    args.state !== undefined &&
+    !Object.hasOwn(args, "context") &&
+    !Object.hasOwn(args, "evidence")
+  ) {
+    let knownKeysOnly = true;
+    for (const key in args) {
+      if (Object.hasOwn(args, key) && key !== "state" && key !== "questions") {
+        knownKeysOnly = false;
+        break;
+      }
+    }
+    if (knownKeysOnly) return args as SystemOneParams;
+  }
   const out: Record<string, unknown> = {};
   if (args.state !== undefined) {
     out.state = args.state;
@@ -294,9 +424,7 @@ export function prepareSystemOneArgs(args: unknown): SystemOneParams {
   } else if (args.evidence !== undefined) {
     out.state = args.evidence;
   }
-  const questions =
-    args.questions ?? args.question ?? args.queries ?? undefined;
-  if (questions !== undefined) out.questions = normalizeQuestions(questions);
+  if (normalizedQuestions !== undefined) out.questions = normalizedQuestions;
   // Drop unknown top-level keys; a missing `state` / `questions` still
   // produces a clear error from semantic validation in execute().
   return out as SystemOneParams;

package/tests/packaging.test.ts

@@ -7,6 +7,8 @@
 
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import { describe, it } from "node:test";
 import { fileURLToPath } from "node:url";
 
@@ -32,6 +34,17 @@ function packedFiles(): string[] {
 }
 
 describe("npm package runtime resources", () => {
+  it("declares the extension entry for both Pi and OMP", () => {
+    const packageJson = JSON.parse(
+      readFileSync(join(packageRoot, "package.json"), "utf-8"),
+    ) as {
+      pi?: { extensions?: string[] };
+      omp?: { extensions?: string[] };
+    };
+    assert.deepEqual(packageJson.pi, { extensions: ["./src/extension.ts"] });
+    assert.deepEqual(packageJson.omp, { extensions: ["./src/extension.ts"] });
+  });
+
   it("packs the skill, its references, and the /judge prompt", () => {
     const files = packedFiles();
     for (const required of [

package/tests/tool.test.ts

@@ -1075,6 +1075,245 @@ describe("system_one tool", () => {
     });
   });
 
+  describe("copy-on-write normalization", () => {
+    const canonicalRequest = () => ({
+      state: { incident: "latency" },
+      questions: {
+        rollback: { type: "noul", instructions: "Roll back?" },
+        owner: {
+          type: "choice",
+          instructions: "Which team?",
+          criteria: { frontend: null, backend: null },
+        },
+      },
+    });
+
+    it("returns canonical requests, maps, and questions by reference", () => {
+      const args = canonicalRequest();
+      const out = prepareSystemOneArgs(args) as typeof args;
+      assert.equal(out, args);
+      assert.equal(out.questions, args.questions);
+      assert.equal(out.questions.rollback, args.questions.rollback);
+      assert.equal(out.questions.owner, args.questions.owner);
+      // Key order is not canonicalized: identity means "already final".
+      const reordered = {
+        state: "s",
+        questions: {
+          q: { criteria: { a: null }, instructions: "I?", type: "choice" },
+        },
+      };
+      assert.equal(prepareSystemOneArgs(reordered), reordered);
+    });
+
+    it("structurally shares unaffected siblings on partial repair", () => {
+      const args = {
+        state: "s",
+        questions: {
+          fine: { type: "noul", instructions: "OK?" },
+          sloppy: { type: "Choice", prompt: "Pick?", options: ["a", "b"] },
+        },
+      };
+      const out = prepareSystemOneArgs(args) as typeof args;
+      assert.notEqual(out, args);
+      assert.notEqual(out.questions, args.questions);
+      assert.notEqual(out.questions.sloppy, args.questions.sloppy);
+      assert.equal(out.questions.fine, args.questions.fine);
+      assert.deepEqual(out.questions.sloppy, {
+        type: "choice",
+        instructions: "Pick?",
+        criteria: { a: null, b: null },
+      });
+    });
+
+    it("is idempotent and allocates nothing new on the second pass", () => {
+      const once = prepareSystemOneArgs(canonicalRequest()) as Record<
+        string,
+        unknown
+      >;
+      const twice = prepareSystemOneArgs(once);
+      assert.deepEqual(twice, once);
+      assert.equal(twice, once);
+      // Repair once, then the repaired output is itself canonical.
+      const repairedOnce = prepareSystemOneArgs({
+        state: "s",
+        questions: [{ name: "q", type: "boolean", prompt: "Y?" }],
+      });
+      assert.equal(prepareSystemOneArgs(repairedOnce), repairedOnce);
+    });
+
+    it("never mutates its input", () => {
+      const deepFreeze = (v: unknown): void => {
+        if (typeof v === "object" && v !== null && !Object.isFrozen(v)) {
+          Object.freeze(v);
+          for (const k of Object.keys(v)) {
+            deepFreeze((v as Record<string, unknown>)[k]);
+          }
+        }
+      };
+      const sloppy = {
+        context: { incident: "latency" },
+        question: [
+          { name: "a", type: "Rating", prompt: "Rate?", levels: ["1", "5"] },
+          { id: "b", type: "noul", instructions: "OK?", extra: 1 },
+        ],
+      };
+      deepFreeze(sloppy);
+      const out = prepareSystemOneArgs(sloppy);
+      assert.deepEqual(out, {
+        state: { incident: "latency" },
+        questions: {
+          a: {
+            type: "score",
+            instructions: "Rate?",
+            criteria: ["1", "5"],
+          },
+          b: { type: "noul", instructions: "OK?", extra: 1 },
+        },
+      });
+    });
+
+    it("repairs every non-canonical shape exactly (no false sharing)", () => {
+      // [input, expected output, sharesInputRef]: the last two entries are
+      // already builder fixed points, so sharing them is correct.
+      const cases: Array<[unknown, unknown, boolean]> = [
+        // Alias type spelling.
+        [
+          {
+            state: "s",
+            questions: { q: { type: "Yes/No", instructions: "Y?" } },
+          },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+          },
+          false,
+        ],
+        // Alias field names.
+        [
+          {
+            state: "s",
+            questions: { q: { type: "choice", prompt: "P?", choices: ["a"] } },
+          },
+          {
+            state: "s",
+            questions: {
+              q: { type: "choice", instructions: "P?", criteria: { a: null } },
+            },
+          },
+          false,
+        ],
+        // Junk keys dropped.
+        [
+          {
+            state: "s",
+            questions: {
+              q: {
+                type: "noul",
+                instructions: "Y?",
+                description: "d",
+                title: "t",
+              },
+            },
+          },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+          },
+          false,
+        ],
+        // Undefined-valued lingering alias key is still dropped.
+        [
+          {
+            state: "s",
+            questions: {
+              q: { type: "noul", instructions: "Y?", prompt: undefined },
+            },
+          },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+          },
+          false,
+        ],
+        // Own undefined instructions key is preserved (builder copies it).
+        [
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: undefined } },
+          },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: undefined } },
+          },
+          true,
+        ],
+        // noul null criteria reads as omitted.
+        [
+          {
+            state: "s",
+            questions: {
+              q: { type: "noul", instructions: "Y?", criteria: null },
+            },
+          },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+          },
+          false,
+        ],
+        // Singular question alias + array form + naming metadata.
+        [
+          { context: "s", question: { type: "boolean", prompt: "Y?" } },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+          },
+          false,
+        ],
+        // Unknown top-level keys dropped; missing state preserved as-is.
+        [
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+            extra: 1,
+          },
+          {
+            state: "s",
+            questions: { q: { type: "noul", instructions: "Y?" } },
+          },
+          false,
+        ],
+        // Empty choice array still folds (every() on [] is true).
+        [
+          {
+            state: "s",
+            questions: {
+              q: { type: "choice", instructions: "P?", criteria: [] },
+            },
+          },
+          {
+            state: "s",
+            questions: {
+              q: { type: "choice", instructions: "P?", criteria: {} },
+            },
+          },
+          false,
+        ],
+        // Non-string type passes through untouched (fixed point).
+        [
+          { state: "s", questions: { q: { type: 5, instructions: "Y?" } } },
+          { state: "s", questions: { q: { type: 5, instructions: "Y?" } } },
+          true,
+        ],
+      ];
+      for (const [input, expected, sharesRef] of cases) {
+        const out = prepareSystemOneArgs(input);
+        assert.deepEqual(out, expected);
+        assert.equal(out === input, sharesRef);
+      }
+    });
+  });
+
   describe("backend minima guardrails", () => {
     function stubTool() {
       let calls = 0;