@cr1ms0n/pi-subagent 0.9.0 → 0.10.0

package/docs/SECURITY.md

@@ -6,11 +6,11 @@ and can use tools according to their capability profile.
 
 ## What subagents can do
 
-| Profile | Default tools | Writes? |
-|---------|---------------|---------|
-| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
-| `review` | same as explore | No project-file writes |
-| `general` | Jev-chosen subset of the full available locally permitted catalog (+ Pi context tools) | Yes if the selected tools include `bash`/`edit`/`write` |
+| Profile | Finalized tools | Writes? |
+|---------|-----------------|---------|
+| `explore` | Jev-chosen subset of locally permitted read-only candidates, plus available Pi context tools | No project-file writes |
+| `review` | Same as explore | No project-file writes |
+| `general` | Jev-chosen subset of the full available locally permitted catalog, plus available Pi context tools | Yes if write-capable tools are selected |
 
 Parallel mode defaults to `explore` to avoid concurrent shared writes.
 
@@ -50,20 +50,20 @@ Parallel mode defaults to `explore` to avoid concurrent shared writes.
    (RPC mode). Extension UI dialogs raised inside a child are auto-cancelled so
    they can never hang a run — which also means a child can never obtain
    interactive consent. Prefer restricted tools for async/background runs.
-11. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
-    into a running child's conversation with user-level authority. Anything that
-    can call the subagent tool can steer any live run in the same session.
-7. **Process cleanup.** On POSIX, children run in their own process group so tree
+7. **Steering messages** (`action: "steer"` and the overlay `s` key) inject text
+   into a running child's conversation with user-level authority. Anything that
+   can call the subagent tool can steer any live run in the same session.
+8. **Process cleanup.** On POSIX, children run in their own process group so tree
    kills work for ordinary descendants. Parent (re)start reaps orphans recorded
    under `~/.pi/subagent-locks/runs/` so resume cannot race a still-alive writer.
    Grandchildren that call `setsid()` can still escape a simple process-group kill.
-8. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
+9. **Resume exclusivity.** Direct resume takes a durable per-session file lock;
    concurrent parents cannot append to the same child session.
-9. **Profiles are tool-selection policy, not a sandbox.** Children inherit
+10. **Profiles are tool-selection policy, not a sandbox.** Children inherit
    `$HOME`, SSH/cloud credentials, network access, and the parent filesystem.
    Git worktrees only isolate the checkout. For untrusted tasks, use an outer
    container/cgroup/network policy.
-10. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
+11. **`max_cost` is accounting, not a hard provider gate.** Usage arrives after a
     turn; orphans may spend money the ledger never sees. It caps provider-reported
     execution cost only: TypeSafe reports routing tokens, not currency, so selector
     cost is unreported and outside `max_cost`. Combine with provider account
@@ -81,12 +81,11 @@ and synthesis select from the new task instruction rather than the assembled
 transcript. Task text and model descriptions are user content and can themselves
 contain secrets; there is no guaranteed redaction.
 
-The TypeSafe credential is read from the environment variable named by
-`jevRouting.apiKeyEnv` (default `TYPESAFE_API_KEY`) and sent only as an
-`Authorization` header to the fixed official HTTPS endpoint, with redirects
-disabled. It is never stored in the config file, prompts, argv, logs or results.
-Rotate any credential that has been pasted into a transcript or shared in
-conversation.
+Version `0.10.0` reads the TypeSafe credential from `jevRouting.apiKey` in the private user-level `~/.pi/subagent.json`. This is plaintext storage: restrict file access and protect editor backups and synchronized copies. Same-user processes, including children with filesystem access, may read it. Profiles and worktrees do not protect this file from those processes.
+
+The transport sends the key only as an `Authorization` header to the fixed official HTTPS endpoint, with redirects disabled. It does not automatically copy the key into prompts, selector JSON bodies, argv, child manifests, logs, receipts or results. Never serialize or log the complete routing configuration. Rotate any credential pasted into a transcript or shared in conversation.
+
+Published npm `0.9.0` uses the older environment-based mechanism. In `0.10.0`, `apiKeyEnv` is rejected with manual migration guidance and no environment fallback. Unrelated `PI_SUBAGENT_*` runtime settings remain supported.
 
 New extension-managed dispatch is Pi-only. A `backend: "codex"` or
 `backend: "claude"` new task is rejected before any selector or provider work,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Community fork of Luke Parke's pi-subagent with Jev model/tool routing and verified Pi child capabilities",
   "type": "module",
   "license": "MIT",
@@ -10,6 +10,13 @@
     "cr1ms0n (fork maintainer)"
   ],
   "homepage": "https://www.npmjs.com/package/@cr1ms0n/pi-subagent",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awoaCrim/pi-smart-subagents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/awoaCrim/pi-smart-subagents/issues"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -31,6 +38,7 @@
     "skills",
     "docs",
     "README.md",
+    "README.zh-CN.md",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/skills/subagent/SKILL.md

@@ -136,7 +136,11 @@ An optional candidate `thinking` value is an opaque Pi thinking-level string;
 common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and
 `max`, but model-specific values are passed through unchanged. It is a default:
 explicit task, agent, and profile `taskDefaults.thinking` values override it.
-The extension re-reads `jevRouting` on each dispatch and injects the current
-routing guidance into the parent prompt. If `jevRouting` is missing or invalid,
-or the credential environment variable is unset, management remains available but
-new spawns, `/btw`, plan, resume, fork and synthesis are rejected.
+The extension re-reads `jevRouting` on each dispatch and injects non-secret
+routing guidance into the parent prompt. The user stores the TypeSafe credential
+in `jevRouting.apiKey` in the private `~/.pi/subagent.json`; do not read, display
+or copy the key into task text, prompts or output. Legacy `apiKeyEnv` is rejected
+with migration guidance; there is no environment fallback. If the config or key
+is missing or invalid, management remains available but new spawns, `/btw`, plan,
+resume, fork and synthesis are rejected. This config-file credential contract ships in
+npm 0.10.0; published npm 0.9.0 uses the old environment mechanism.

package/src/config.ts

@@ -61,7 +61,7 @@ export interface SubagentConfig {
   lockRetentionDays: number;
   /** Legacy per-profile defaults. Model/fallback fields are retained for config compatibility but ignored by Jev routing. */
   taskDefaults?: TaskDefaultsByProfile;
-  /** Mandatory, user-owned Jev candidate configuration. Never contains a credential. */
+  /** Private Jev configuration including apiKey. Never log or serialize the whole config. */
   jevRouting?: JevRoutingConfig;
   /** Safe migration or parse failure; existing-run management remains available. */
   jevRoutingError?: string;

package/src/jev-router.ts

@@ -2,6 +2,7 @@ import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
 import { Semaphore } from "./semaphore.js";
 import { isThinkingLevel } from "./thinking.js";
+import { normalizeRoutingApiKey } from "./routing-policy.js";
 import {
   DEFAULT_ROUTING_CONCURRENCY,
   MAX_ROUTING_MODEL_ID_LENGTH,
@@ -58,7 +59,7 @@ export type {
  * - A single logical deadline = min(config.timeoutMs, caller absolute deadline) spans every
  *   request and all limiter waiting. Concurrent HTTP requests are bounded to two by default.
  * - Only `https://api.typesafe.ai/v1/systemone` with `redirect:"error"`; the Bearer key comes
- *   from the injected environment accessor and never appears in config, results or messages.
+ *   from the private config snapshot and is never copied into request bodies, results or messages.
  * - Responses are untrusted data: shape, answer type, question set, allowed options, finite
  *   probabilities, probability sum tolerance, confidence, usage counts and selector version
  *   are validated. Valid low-confidence choices are accepted (no threshold, no substitution).
@@ -72,7 +73,7 @@ export type {
  * - Failures return a discriminated result that includes every available receipt; there is no
  *   automatic selector retry, fallback or emergency model.
  *
- * Collaborators (`fetchImpl`, `env`, `now`, `idFactory`, `limiter`, `onReceipt`) are all
+ * Collaborators (`fetchImpl`, `now`, `idFactory`, `limiter`, `onReceipt`) are all
  * injectable so the whole surface is testable offline with zero provider calls.
  */
 
@@ -82,12 +83,10 @@ export interface RoutingLimiter {
 }
 
 export interface JevRouterOptions {
-  /** Frozen per-invocation config snapshot. */
+  /** Frozen per-invocation config snapshot containing a private credential. Never log it. */
   config: JevRoutingConfig;
   /** Injected transport; defaults to global `fetch`. */
   fetchImpl?: typeof fetch;
-  /** Injected environment accessor; defaults to `process.env`. */
-  env?: (name: string) => string | undefined;
   /** Injected clock; defaults to `Date.now`. */
   now?: () => number;
   /** Injected unique-ID factory; defaults to `randomUUID`. */
@@ -411,7 +410,7 @@ function validateAnswers(body: unknown, questions: readonly QuestionSpec[]): Ans
 
 function selectorStatusFailure(status: number): { code: RoutingFailureCode; message: string } {
   if (status === 401 || status === 403) {
-    return { code: "unauthorized", message: "TypeSafe rejected the routing credential (HTTP 401/403). Check the configured apiKeyEnv environment variable." };
+    return { code: "unauthorized", message: "TypeSafe rejected the routing credential (HTTP 401/403). Check jevRouting.apiKey in your private ~/.pi/subagent.json configuration." };
   }
   if (status === 422) {
     return { code: "invalid_request", message: "TypeSafe rejected the routing request as invalid (HTTP 422). Check selectorModel and the configured candidate/tool descriptions." };
@@ -607,7 +606,6 @@ function freezeReceipt(draft: ReceiptDraft): RoutingReceipt {
 export class JevRouter {
   private readonly config: JevRoutingConfig;
   private readonly fetchImpl: typeof fetch | undefined;
-  private readonly env: (name: string) => string | undefined;
   private readonly now: () => number;
   private readonly idFactory: () => string;
   private readonly limiter: RoutingLimiter;
@@ -616,7 +614,6 @@ export class JevRouter {
   constructor(options: JevRouterOptions) {
     this.config = options.config;
     this.fetchImpl = options.fetchImpl ?? (typeof globalThis.fetch === "function" ? globalThis.fetch : undefined);
-    this.env = options.env ?? ((name) => process.env[name]);
     this.now = options.now ?? Date.now;
     this.idFactory = options.idFactory ?? randomUUID;
     this.limiter = options.limiter ?? sharedLimiter;
@@ -647,12 +644,11 @@ export class JevRouter {
       return this.fail("too_many_tools", `At most ${MAX_ROUTING_TOOL_QUESTIONS} eligible tools can be considered in one selection.`, call);
     }
 
-    const rawKey = this.env(this.config.apiKeyEnv);
-    const apiKey = typeof rawKey === "string" ? rawKey.trim() : "";
+    const apiKey = normalizeRoutingApiKey(this.config.apiKey);
     if (!apiKey) {
       return this.fail(
         "missing_api_key",
-        `The TypeSafe routing credential is missing: set the ${this.config.apiKeyEnv} environment variable locally, then retry the dispatch.`,
+        "The TypeSafe routing credential is missing or invalid: set jevRouting.apiKey in your private ~/.pi/subagent.json to a non-blank key without embedded whitespace or control characters, then retry the dispatch.",
         call,
       );
     }

package/src/routing-policy.ts

@@ -1,6 +1,5 @@
 import { isThinkingLevel } from "./thinking.js";
 import {
-  DEFAULT_API_KEY_ENV,
   DEFAULT_ROUTING_TIMEOUT_MS,
   DEFAULT_SELECTOR_MODEL,
   MAX_ROUTING_MODEL_ID_LENGTH,
@@ -30,22 +29,21 @@ export type {
  * - `parseJevRouting(raw, source?)` parses the `jevRouting` **subtree** (not the whole
  *   `~/.pi/subagent.json` file) and returns an immutable snapshot. It throws a plain
  *   `Error` with an actionable message on any unknown field, duplicate/blank model ID,
- *   blank description, invalid environment-variable name, non-integer/out-of-range timeout
- *   or unsupported candidate count. Callers (`src/config.ts`) catch that message and expose
- *   it as a config error; no credential or provider catalog is read.
+ *   blank description, missing/invalid credential, non-integer/out-of-range timeout
+ *   or unsupported candidate count. Callers (`src/config.ts`) expose safe error messages;
+ *   the parser never reads the environment or a provider catalog.
  * - `formatJevRoutingPrompt` renders model-facing guidance and works with **no** config, no
  *   credential and no inference, so management actions stay independent of routing setup.
  * - The candidate helpers are pure; they never contact Pi or TypeSafe.
  *
- * The credential *value* must never be stored in config: only the environment-variable name
- * is parsed and returned. The parser rejects unknown fields, so an accidental `apiKey` or
- * `apiKeyValue` field is an error rather than silently ignored.
+ * The private snapshot contains the credential from `apiKey`. Never serialize it into
+ * model-facing guidance or selector input. Credential diagnostics contain no supplied
+ * values. Legacy `apiKeyEnv` is rejected with manual migration guidance, without lookup.
  */
 
 /** Default config-file label used in prose (owned by `config.ts` for file reads). */
 export const JEV_ROUTING_CONFIG_FILE = "~/.pi/subagent.json";
 
-const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Exact provider/model ID: at least one slash, further ID slashes allowed; no whitespace, control chars or globs. */
 const MODEL_ID = /^[^\s\u0000-\u001f\u007f/*?]+(?:\/[^\s\u0000-\u001f\u007f/*?]+)+$/u;
 const MAX_GUIDANCE_MODEL_LINES = 50;
@@ -76,12 +74,19 @@ function parseSelectorModel(value: unknown, source: string): string {
   return model;
 }
 
-function parseApiKeyEnv(value: unknown, source: string): string {
-  if (value === undefined) return DEFAULT_API_KEY_ENV;
-  if (typeof value !== "string" || !ENV_VAR_NAME.test(value.trim())) {
-    invalid(source, "apiKeyEnv must be an environment-variable name such as TYPESAFE_API_KEY (the credential value must not be stored in config)");
+/** Shared credential normalization for config parsing and defensive transport validation. */
+export function normalizeRoutingApiKey(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const key = value.trim();
+  return key && !/[\s\u0000-\u001f\u007f-\u009f]/u.test(key) ? key : undefined;
+}
+
+function parseApiKey(value: unknown, source: string): string {
+  const key = normalizeRoutingApiKey(value);
+  if (key === undefined) {
+    invalid(source, "apiKey is required and must be a non-blank key without embedded whitespace or control characters; store it only in your private user config");
   }
-  return value.trim();
+  return key;
 }
 
 function parseTimeoutMs(value: unknown, source: string): number {
@@ -144,11 +149,14 @@ function parseModels(value: unknown, source: string): readonly JevRoutingModelEn
  */
 export function parseJevRouting(raw: unknown, source = JEV_ROUTING_CONFIG_FILE): JevRoutingConfig {
   const record = requireObject(raw, source, "jevRouting");
-  rejectUnknownKeys(record, ["selectorModel", "apiKeyEnv", "timeoutMs", "models"], source, "jevRouting");
+  if (Object.prototype.hasOwnProperty.call(record, "apiKeyEnv")) {
+    invalid(source, "apiKeyEnv is no longer supported; remove it and set jevRouting.apiKey to the credential in your private user config. No environment fallback or automatic migration is performed");
+  }
+  rejectUnknownKeys(record, ["selectorModel", "apiKey", "timeoutMs", "models"], source, "jevRouting");
 
   const snapshot: JevRoutingConfig = {
     selectorModel: parseSelectorModel(record.selectorModel, source),
-    apiKeyEnv: parseApiKeyEnv(record.apiKeyEnv, source),
+    apiKey: parseApiKey(record.apiKey, source),
     timeoutMs: parseTimeoutMs(record.timeoutMs, source),
     models: parseModels(record.models, source),
   };
@@ -160,7 +168,7 @@ export function jevRoutingTemplate(): string {
   return JSON.stringify({
     jevRouting: {
       selectorModel: DEFAULT_SELECTOR_MODEL,
-      apiKeyEnv: DEFAULT_API_KEY_ENV,
+      apiKey: "<your-typesafe-api-key>",
       timeoutMs: DEFAULT_ROUTING_TIMEOUT_MS,
       models: [
         {
@@ -230,7 +238,7 @@ function routingSummary(config: JevRoutingConfig): string[] {
     "Every new task/tasks[] spawn, action:\"plan\" request, /btw, resume, fork and synthesis is routed by the Jev selector against the user's candidate-model list.",
     "Do not pass model or fallback_models: those fields no longer select a route on new work and are rejected. Management actions (status/wait/cancel/steer/diff/apply/discard) never call the selector and need no credential.",
     `Selector: ${config.selectorModel} (pin an exact version instead of the moving alias to make selection reproducible).`,
-    `Credential: environment variable ${config.apiKeyEnv}, read locally at request time; the value is never stored in config, prompts, logs or results.`,
+    "Credential: jevRouting.apiKey in the private ~/.pi/subagent.json config file. Never read or copy its value into prompts, logs or results; the routing transport uses it only for the Authorization header.",
     `Logical selection deadline: ${config.timeoutMs} ms, covering all selector requests and waiting for one invocation.`,
     "Only Pi-backed new dispatch is supported; native Codex/Claude new dispatches are rejected rather than routed.",
     "Candidate models (exact IDs; the user's per-model characteristics are the matching criteria):",
@@ -259,7 +267,7 @@ export function formatJevRoutingPrompt(config: JevRoutingConfig | undefined, err
       "## Subagent routing (Jev / TypeSafe)",
       error || `No valid jevRouting configuration was found in ${JEV_ROUTING_CONFIG_FILE}.`,
       "Management actions (status/wait/cancel/steer/diff/apply/discard) remain available, but every new task/tasks[] spawn, plan, /btw, resume, fork and synthesis is rejected until jevRouting is configured.",
-      "Add jevRouting with selectorModel, apiKeyEnv and 1-255 candidate model entries (exact provider/model IDs plus user-written characteristics, including Chinese). The credential itself is read from the named environment variable at request time and is never stored in the config file.",
+      "Add jevRouting with selectorModel, apiKey and 1-255 candidate model entries (exact provider/model IDs plus user-written characteristics, including Chinese). The user must store the credential in the private config file, not in chat or source control. Do not read or display the key. Legacy apiKeyEnv is rejected; there is no environment fallback.",
       "Do not pass model or fallback_models; the selector chooses the execution model and tools.",
       "Use the package routing template; do not invent model IDs or import legacy modelPolicy entries automatically.",
     ].join("\n");

package/src/routing-types.ts

@@ -18,8 +18,6 @@ export const TYPESAFE_SYSTEMONE_ENDPOINT = "https://api.typesafe.ai/v1/systemone
 
 /** Stable alias default. An exact supported version may be pinned through config. */
 export const DEFAULT_SELECTOR_MODEL = "jev-latest";
-/** Environment variable that holds the TypeSafe credential. Never the credential value. */
-export const DEFAULT_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Default logical selection deadline in milliseconds. */
 export const DEFAULT_ROUTING_TIMEOUT_MS = 15_000;
 export const ROUTING_TIMEOUT_MIN_MS = 100;
@@ -86,11 +84,13 @@ export interface JevRoutingModelEntry {
 
 /**
  * Immutable `jevRouting` snapshot parsed from the user config subtree.
- * The credential value never appears here — only the environment-variable name.
+ * Contains a private credential. Never log this snapshot or serialize it into prompts,
+ * selector bodies, task specs, receipts or results; use explicit non-secret projections.
  */
 export interface JevRoutingConfig {
   readonly selectorModel: string;
-  readonly apiKeyEnv: string;
+  /** User-configured TypeSafe credential; transport Authorization header only. */
+  readonly apiKey: string;
   readonly timeoutMs: number;
   readonly models: readonly JevRoutingModelEntry[];
 }