pi-system-one 1.1.3 → 1.1.4

package/README.md

@@ -7,4 +7,23 @@ pi install npm:pi-system-one
 export SYSTEM_ONE_BASE_URL=http://localhost:8008
 ```
 
-TypeSafe: `SYSTEM_ONE_BASE_URL=https://api.typesafe.ai SYSTEM_ONE_API_KEY=... SYSTEM_ONE_MODEL=jev-latest`.
+**Configuration**
+
+The extension provides a `/so` command for configuring the System One client:
+
+- `SYSTEM_ONE_BASE_URL` – required endpoint URL.
+- `SYSTEM_ONE_MODEL` – optional default model name.
+- `SYSTEM_ONE_API_KEY` – optional API key.
+
+When you run `/so config`, you can:
+
+- **Enter a new API key** – it is stored in memory only and will be lost when the session ends.
+- **Enter `-`** – forget the memory‑only key. If an `SYSTEM_ONE_API_KEY` environment variable is present, the client will fall back to it; otherwise the key becomes absent.
+- **Leave the input empty** – keep the existing value.
+
+The current configuration can be inspected with `/so status`.
+
+---
+
+For further details see the source code and comments in `src/commands.ts`.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-system-one",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "System One decisions for Pi. Plug in TypeSafe Jev, Reflex, or your own provider.",
   "type": "module",
   "license": "MIT",

package/src/commands.ts

@@ -59,7 +59,7 @@ export function registerSystemOneCommands(
       return;
     }
     const apiKeyRaw = await ctx.ui.input(
-      "SYSTEM_ONE_API_KEY (empty = keep, - = forget memory key, memory-only, gone when the session closes):",
+      "SYSTEM_ONE_API_KEY (empty = keep, - = forget memory key (reverts to environment variable if set, otherwise becomes absent), memory-only, gone when the session closes):",
       "",
     );
     if (apiKeyRaw === undefined) {

package/src/tool.ts

@@ -1,87 +1,217 @@
-// biome-ignore-all lint/suspicious/noExplicitAny: intentional dynamic boundary over JSON protocol values
-// pi-system-one/src/tool.ts
-
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { SystemOne, type SystemOneProvider } from "system-one-core";
+import {
+  type QuestionMap,
+  SystemOne,
+  type SystemOneProvider,
+  type SystemOneState,
+} from "system-one-core";
 import type { Static } from "typebox";
 import { Type } from "typebox";
 import { renderSystemOneResult } from "./render.ts";
 
-const ChoiceQ = Type.Object({
-  type: Type.Literal("choice"),
-  instructions: Type.Any(),
-  criteria: Type.Record(Type.String(), Type.Union([Type.Any(), Type.Null()])),
-});
-const NoulQ = Type.Object({
-  type: Type.Literal("noul"),
-  instructions: Type.Any(),
-  criteria: Type.Optional(
-    Type.Record(Type.String(), Type.Union([Type.Any(), Type.Null()])),
-  ),
-});
-const ScoreQ = Type.Object({
-  type: Type.Literal("score"),
-  instructions: Type.Any(),
-  criteria: Type.Array(Type.Any()),
-});
-export const systemOneParams = Type.Object({
-  state: Type.Union([
+/**
+ * JSON value accepted by System One.
+ *
+ * Arrays/objects use Type.Any() recursively because tool arguments already
+ * cross a JSON boundary. Keeping the schema non-recursive also tends to be
+ * easier for tool-calling models to consume.
+ */
+const JsonValue = Type.Union(
+  [
     Type.String(),
-    Type.Record(Type.String(), Type.Any()),
+    Type.Number(),
+    Type.Boolean(),
+    Type.Null(),
     Type.Array(Type.Any()),
-  ]),
-  questions: Type.Record(Type.String(), Type.Union([ChoiceQ, NoulQ, ScoreQ])),
-  model: Type.Optional(Type.String()),
-});
+    Type.Record(Type.String(), Type.Any()),
+  ],
+  {
+    description:
+      "A JSON value: string, number, boolean, null, object, or array.",
+  },
+);
+
+const ChoiceQ = Type.Object(
+  {
+    type: Type.Literal("choice", {
+      description: "Select exactly one outcome from a bounded set.",
+    }),
+
+    instructions: JsonValue,
+
+    criteria: Type.Record(Type.String(), JsonValue, {
+      minProperties: 1,
+      description:
+        "Available choices keyed by choice label. Each value describes that choice; use null when the label is self-explanatory. The keys are the choices; do not provide a separate options field.",
+    }),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "A closed-set categorical decision. The keys of criteria are the available choices.",
+  },
+);
+
+const NoulCriteria = Type.Object(
+  {
+    true: Type.Optional(JsonValue),
+    false: Type.Optional(JsonValue),
+  },
+  {
+    additionalProperties: false,
+    minProperties: 1,
+    description: "Optional descriptions of the true/yes and false/no outcomes.",
+  },
+);
+
+const NoulQ = Type.Object(
+  {
+    type: Type.Literal("noul", {
+      description: "Estimate the likelihood of a yes/true outcome.",
+    }),
+
+    instructions: JsonValue,
+
+    criteria: Type.Optional(NoulCriteria),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "A probabilistic yes/no judgment. Omit criteria unless the true or false outcomes need clarification.",
+  },
+);
+
+const ScoreQ = Type.Object(
+  {
+    type: Type.Literal("score", {
+      description: "Score the state against an ordered rubric.",
+    }),
+
+    instructions: JsonValue,
+
+    criteria: Type.Array(JsonValue, {
+      minItems: 2,
+      description:
+        "Ordered score levels from lowest to highest. Each array item defines one level of the rubric.",
+    }),
+  },
+  {
+    additionalProperties: false,
+    description:
+      "An ordered rubric decision. Criteria are ordered from lowest to highest.",
+  },
+);
+
+const Question = Type.Union([ChoiceQ, NoulQ, ScoreQ]);
+
+export const systemOneParams = Type.Object(
+  {
+    state: Type.Union(
+      [
+        Type.String(),
+        Type.Number(),
+        Type.Boolean(),
+        Type.Null(),
+        Type.Record(Type.String(), Type.Any()),
+        Type.Array(Type.Any()),
+      ],
+      {
+        description:
+          "Shared state or evidence that all questions should be evaluated against.",
+      },
+    ),
+
+    questions: Type.Record(Type.String(), Question, {
+      minProperties: 1,
+      description:
+        "One or more named decision questions. Questions sharing the same state should be sent together.",
+    }),
+  },
+  {
+    additionalProperties: false,
+    description: "Evaluate bounded decision questions against shared state.",
+  },
+);
+
 export type SystemOneParams = Static<typeof systemOneParams>;
 
 export interface SystemOneDetails {
   answers: Record<string, unknown>;
   model?: string;
-  usage?: { inputTokens?: number; outputTokens?: number };
-  metadata: { provider: string; latencyMs?: number };
+  usage?: {
+    inputTokens?: number;
+    outputTokens?: number;
+  };
+  requestId?: string;
+  metadata: {
+    provider: string;
+    latencyMs?: number;
+  };
 }
 
-export function buildSystemOneTool(deps: { provider: SystemOneProvider }) {
-  const systemOne = new SystemOne({ provider: deps.provider });
-  const tool: ToolDefinition<typeof systemOneParams, SystemOneDetails> = {
+export function buildSystemOneTool(deps: {
+  provider: SystemOneProvider;
+}): ToolDefinition<typeof systemOneParams, SystemOneDetails> {
+  const systemOne = new SystemOne({
+    provider: deps.provider,
+  });
+
+  return {
     name: "system_one",
     label: "System One",
+
     description:
-      "Evaluate one or more bounded decision questions against shared state using the configured System One provider. " +
-      "Use this when the answer space is known and a fast probabilistic decision is preferable to generating free-form text. " +
-      "Multiple independent choice, noul, and score questions should be batched into one call when they share the same state.",
+      "Evaluate bounded choice, yes/no likelihood, and ordered score questions against shared state. " +
+      "Use this when the possible outcomes or scoring rubric are known and structured probabilistic results are useful. " +
+      "Do not use it for open-ended text generation. " +
+      "Questions that share the same state can be evaluated together in one call.",
+
     parameters: systemOneParams,
+
     promptSnippet:
-      "Perform calibrated structured decisions and classifications over state",
+      "Evaluate bounded choices, yes/no likelihoods, and ordered scores from shared state",
+
     promptGuidelines: [
-      "Use system_one to evaluate one or more bounded decision questions",
-      "Use system_one when you need structured probability, categorical choice, or scored rubric decisions rather than text generation.",
+      "Use system_one for closed-set classification, probabilistic yes/no judgments, or ordered rubric scoring.",
+      "Do not use system_one for open-ended text generation or when there is no bounded answer space or rubric.",
+      "Preserve user-specified choice labels, criteria, and score levels instead of inventing replacements.",
+      "For choice questions, the keys of criteria are the available choices; never add a separate options field.",
+      "For self-explanatory choice labels, prefer null criteria values instead of inventing definitions that could bias the decision.",
+      "For noul questions, omit criteria unless the true/yes or false/no outcomes need clarification.",
+      "For score questions, criteria must contain at least two ordered levels from lowest to highest.",
+      "Batch independent questions into one system_one call when they share the same state.",
     ],
 
-    async execute(toolCallId, params, signal, _onUpdate, _ctx) {
-      void toolCallId;
-      // Throw on failure per Pi contract — never encode errors in content.
-      // Safe to propagate unwrapped: core error messages/codes never contain secrets.
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      /*
+       * The LLM-facing TypeBox schema is intentionally separate from the
+       * provider protocol types. Cast only at this boundary instead of
+       * spreading `any` throughout the implementation.
+       */
       const response = await systemOne.evaluate(
         {
-          state: params.state as any,
-          questions: params.questions as any,
-          ...(params.model ? { model: params.model } : {}),
+          state: params.state as SystemOneState,
+          questions: params.questions as QuestionMap,
         },
         { signal },
       );
-      const text = renderSystemOneResult(response);
+
       return {
-        content: [{ type: "text" as const, text }],
+        content: [
+          {
+            type: "text" as const,
+            text: renderSystemOneResult(response),
+          },
+        ],
+
         details: {
           answers: response.answers,
           model: response.model,
           usage: response.usage,
+          requestId: response.requestId,
           metadata: response.metadata,
         },
       };
     },
   };
-  return tool;
 }

package/tests/commands.test.ts

@@ -109,8 +109,13 @@ describe("so command", () => {
     await cap.handler?.("", ctxFor(["", "", "sk-mem", ""], cap));
     assert.equal(store.session?.keyInMemory, true);
     await cap.handler?.("", ctxFor(["", "", "-", ""], cap));
+    // After forgetting the memory key, the API key should revert to the environment variable (if any).
+    // In the CI environment, SYSTEM_ONE_API_KEY may be set; otherwise it will be undefined.
     assert.equal(store.session?.keyInMemory, false);
-    assert.equal(store.session?.current.apiKey, undefined);
+    assert.equal(
+      store.session?.current.apiKey,
+      process.env.SYSTEM_ONE_API_KEY || undefined,
+    );
   });
   it("status shows current config; STATUS routes case-insensitively", async () => {
     const { pi, cap } = harness();

package/tests/tool.test.ts

@@ -94,7 +94,6 @@ describe("system_one tool", () => {
       "id-3",
       {
         state: "hi",
-        model: "jev-latest",
         questions: {
           c: {
             type: "choice",
@@ -118,7 +117,7 @@ describe("system_one tool", () => {
     assert.equal((res.details.answers.s as { score: number }).score, 1.5);
     assert.deepEqual(res.details.usage, { inputTokens: 5, outputTokens: 2 });
     assert.deepEqual(res.details.metadata, { provider: "stub" });
-    assert.equal(seenRequest.model, "jev-latest");
     assert.equal(seenOptions.signal, controller.signal);
+    assert.equal(seenRequest.state, "hi");
   });
 });