ei-tui 1.6.8 → 1.7.0

package/src/cli.ts

@@ -17,6 +17,9 @@ import type { StorageState } from "./core/types";
 import { resolvePersonaId, filterByPersona, filterTypeSpecificByPersona, filterBySource, filterTypeSpecificBySource } from "./cli/persona-filter.js";
 import { installMcpClients } from "./cli/install.js";
 import { getRecentSessionMessages } from "./cli/session-context.js";
+import { createEntity, updateEntity, removeEntity, CorrectionValidationError, CORRECTABLE_TYPES, UPDATABLE_TYPES } from "./cli/corrections-endpoints.js";
+import { createPersonaEntity, updatePersonaEntity, removePersonaEntity } from "./cli/persona-corrections.js";
+import type { CorrectableType } from "./core/corrections.js";
 import pkg from "../package.json" assert { type: "json" };
 
 const rawArgs = process.argv.slice(2);
@@ -38,6 +41,39 @@ const TYPE_ALIASES: Record<string, string> = {
   personas: "personas",
 };
 
+// Wider set accepted by `ei create/update/remove persona` — corrections-endpoints.ts's
+// CORRECTABLE_TYPES/UPDATABLE_TYPES intentionally stay persona-free (personas bypass
+// that module's shared SCHEMAS dispatch entirely, see persona-corrections.ts), so this
+// CLI-only layer is what actually widens the accepted type set.
+const CLI_CORRECTABLE_TYPES = [...CORRECTABLE_TYPES, "persona"] as const;
+const CLI_UPDATABLE_TYPES = [...UPDATABLE_TYPES, "persona"] as const;
+
+// Singular CorrectableType resolution for `ei create/update/remove` — derived
+// from TYPE_ALIASES + CLI_CORRECTABLE_TYPES so the two alias systems can never
+// silently diverge on which strings are accepted (e.g. "person"/"people"
+// stay synonymous here too, since both funnel through TYPE_ALIASES first).
+const PLURAL_TO_CORRECTABLE: Record<string, CorrectableType> = Object.fromEntries(
+  CLI_CORRECTABLE_TYPES.map((t) => [TYPE_ALIASES[t], t])
+);
+
+function resolveCorrectableType(raw: string): CorrectableType | null {
+  const plural = TYPE_ALIASES[raw];
+  return plural ? PLURAL_TO_CORRECTABLE[plural] ?? null : null;
+}
+
+// Plural CorrectableType resolution for `ei update` — same TYPE_ALIASES
+// lookup as resolveCorrectableType above, but sourced from CLI_UPDATABLE_TYPES
+// instead of CLI_CORRECTABLE_TYPES since quotes are correctable via update
+// (repointing data_item_ids after a split/merge, fixing mistranscribed
+// text) but never created or removed.
+const PLURAL_TO_UPDATABLE: Record<string, CorrectableType> = Object.fromEntries(
+  CLI_UPDATABLE_TYPES.map((t) => [TYPE_ALIASES[t], t])
+);
+function resolveUpdatableType(raw: string): CorrectableType | null {
+  const plural = TYPE_ALIASES[raw];
+  return plural ? PLURAL_TO_UPDATABLE[plural] ?? null : null;
+}
+
 function printHelp(): void {
   console.log(`
 Ei
@@ -55,6 +91,9 @@ Usage:
   ei --id <id>                  Look up a specific entity by ID
   echo <id> | ei --id           Look up entity by ID from stdin
   ei mcp                        Start the Ei MCP stdio server (for Claude Code/Cursor/Codex)
+  ei create <type> --json '<json>'  Create a new entity (fact/topic/person/persona)
+  ei update <type> <id> --json '<json>'  Replace an entity by ID (full record, not a patch; fact/topic/person/quote/persona)
+  ei remove <type> <id>         Remove an entity by ID (fact/topic/person/persona; not quotes)
 
 Types:
   quote / quotes      Quotes from conversation history
@@ -69,12 +108,13 @@ Options:
   --persona, -p       Filter to entities a specific persona has learned about
   --source, -s        Filter to entities from a specific source (prefix match, e.g. "cursor", "codex:my-machine", "opencode:my-machine:ses_abc123")
   --id                Look up entity by ID (accepts value or stdin)
-  --install           Register Ei with Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks where supported)
+  --install           Register Ei with Claude Code, Cursor, Codex, and OpenCode (MCP + context hooks + skills where supported)
   --sync              Pull latest state from remote sync server into state.backup.json (no TUI required)
   --session <id>      Session ID to enrich the query with recent context (use with --hook-source)
   --hook-source <src> Source of the hook: "opencode-plugin" (OpenCode SQLite), "cursor", or "codex"
   --transcript <path> Path to a Claude Code JSONL transcript file for context enrichment
   --help, -h          Show this help message
+  --json <json>       JSON body for create/update (full record for update, not a patch)
 
 Examples:
   ei "debugging"                         # Search everything
@@ -86,6 +126,13 @@ Examples:
   ei topics --source cursor "X"          # Topics learned from Cursor sessions
   ei --id abc-123                        # Look up entity by ID
   ei "memory leak" | jq .[0].id | ei --id  # Pipe ID from search
+  ei create fact --json '{"name":"Field of Study","description":"CS","sentiment":0,"validated_date":""}'
+  ei update fact abc-123 --json '{"name":"Field of Study","description":"Updated","sentiment":0,"validated_date":""}'
+  ei update quote <id> --json '{"data_item_ids":["person-b-id"], ...}'  # Repoint a quote after splitting a bad merge (fetch the full record via 'ei --id <id>' first)
+  ei create persona --json '{"display_name":"Yoda","long_description":"Speaks in inverted syntax, wise and patient.","traits":[{"name":"Inverted speech","description":"Talks like Yoda","sentiment":0.7}],"topics":[]}'
+  ei update persona <id> --json '<full persona record from ei --id <id>, edited>'
+  ei remove persona abc-123              # Remove a persona (reserved personas like "ei"/"emmet" must be archived instead)
+  ei remove fact abc-123                 # Remove a fact by ID
 `);
 }
 
@@ -146,6 +193,89 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
+  if (args[0] === "create") {
+    const rawType = args[1];
+    const entityType = rawType ? resolveCorrectableType(rawType) : null;
+    if (!entityType) {
+      console.error(`ei create requires a valid type (${CLI_CORRECTABLE_TYPES.join(", ")}). Got: ${rawType ?? "(none)"}`);
+      process.exit(1);
+    }
+    const jsonIdx = args.indexOf("--json");
+    const jsonStr = jsonIdx !== -1 ? args[jsonIdx + 1] : undefined;
+    if (!jsonStr) {
+      console.error("ei create requires --json '<json>'");
+      process.exit(1);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`Invalid JSON: ${(e as Error).message}`);
+      process.exit(1);
+    }
+    try {
+      const result = entityType === "persona" ? await createPersonaEntity(body) : await createEntity(entityType, body);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(e instanceof CorrectionValidationError ? e.message : (e as Error).message);
+      process.exit(1);
+    }
+  }
+
+  if (args[0] === "update") {
+    const rawType = args[1];
+    const id = args[2];
+    const entityType = rawType ? resolveUpdatableType(rawType) : null;
+    if (!entityType || !id) {
+      console.error(`Usage: ei update <type> <id> --json '<json>' (types: ${CLI_UPDATABLE_TYPES.join(", ")})`);
+      process.exit(1);
+    }
+    const jsonIdx = args.indexOf("--json");
+    const jsonStr = jsonIdx !== -1 ? args[jsonIdx + 1] : undefined;
+    if (!jsonStr) {
+      console.error("ei update requires --json '<json>'");
+      process.exit(1);
+    }
+    let body: unknown;
+    try {
+      body = JSON.parse(jsonStr);
+    } catch (e) {
+      console.error(`Invalid JSON: ${(e as Error).message}`);
+      process.exit(1);
+    }
+    try {
+      const record = entityType === "persona" ? await updatePersonaEntity(id, body) : await updateEntity(entityType, id, body);
+      console.log(JSON.stringify(record, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error(e instanceof CorrectionValidationError ? e.message : (e as Error).message);
+      process.exit(1);
+    }
+  }
+
+  if (args[0] === "remove") {
+    const rawType = args[1];
+    const id = args[2];
+    const entityType = rawType ? resolveCorrectableType(rawType) : null;
+    if (!entityType || !id) {
+      console.error(`Usage: ei remove <type> <id> (types: ${CLI_CORRECTABLE_TYPES.join(", ")})`);
+      process.exit(1);
+    }
+    try {
+      if (entityType === "persona") {
+        await removePersonaEntity(id);
+      } else {
+        await removeEntity(entityType, id);
+      }
+      console.log(JSON.stringify({ removed: true, id }, null, 2));
+      process.exit(0);
+    } catch (e) {
+      console.error((e as Error).message);
+      process.exit(1);
+    }
+  }
+
   if (args[0] === "--sync") {
     const { getDataPath } = await import("./cli/retrieval.js");
     const { RemoteSync } = await import("./storage/remote.js");
@@ -283,6 +413,7 @@ async function main(): Promise<void> {
         session: { type: "string" },
         "hook-source": { type: "string" },
         transcript: { type: "string" },
+        format: { type: "string", short: "f" },
       },
       allowPositionals: true,
       strict: true,
@@ -336,6 +467,8 @@ async function main(): Promise<void> {
     ? [...recentMessages, query].join(" ").trim()
     : query;
 
+  const format = parsed.values.format?.trim();
+
   let result;
   if (targetType) {
     const module = await import(`./cli/commands/${targetType}.js`);
@@ -346,6 +479,20 @@ async function main(): Promise<void> {
     if (sourcePrefix && state) {
       result = filterTypeSpecificBySource(result, state, sourcePrefix, targetType);
     }
+
+    // --format prompt: output a formatted text block instead of JSON.
+    // Currently supported for personas only; other types tracked in GitHub issue #77.
+    if (format === "prompt" && targetType === "personas") {
+      // BUG-1 fix: when no persona matches, emit nothing and exit clean.
+      // Do NOT fall through to JSON — callers check block.trim() truthiness
+      // and "[]".trim() is truthy, corrupting system prompts.
+      if (!Array.isArray(result) || result.length === 0) {
+        process.exit(0);
+      }
+      const { buildEiRelationshipBlock } = await import("./cli/commands/personas.js");
+      process.stdout.write(buildEiRelationshipBlock(result[0]) + "\n");
+      process.exit(0);
+    }
   } else {
     result = await retrieveBalanced(enrichedQuery, limit, options);
     if (personaId && state) {

package/src/core/corrections.ts

@@ -0,0 +1,233 @@
+/**
+ * Corrections Queue — external write path for CLI/MCP tools.
+ *
+ * Ei's CLI and MCP server are read-only against a snapshot of state.json —
+ * they never hold the live StateManager the running TUI/daemon owns, so
+ * they can't safely mutate state.json directly (the running instance's
+ * next debounced save would silently clobber the write with its stale
+ * in-memory copy).
+ *
+ * corrections.json is the queue that closes this gap. External writers
+ * (ei_update / ei_create / ei_remove) append fully-formed CorrectionRecords
+ * here under an advisory lock. Two consumers drain it:
+ *   - The running Processor, once per runLoop tick (near-instant, ~100ms).
+ *   - The CLI itself, self-draining directly into state.json when it
+ *     detects no live instance is running (see src/cli/corrections-io.ts).
+ *
+ * Every CorrectionRecord is a complete, ready-to-apply entity — including
+ * a pre-computed embedding and (for creates) a pre-assigned id — so
+ * draining is a pure apply, never a fetch-then-merge.
+ */
+
+import type { HumanEntity, Fact, Topic, Person, Quote, PersonaEntity, StorageState } from "./types.js";
+import { isReservedPersonaId } from "./types.js";
+import { withLock, atomicWrite } from "../storage/file-lock.js";
+
+export type CorrectableType = "fact" | "topic" | "person" | "quote" | "persona";
+export type CorrectableEntity = Fact | Topic | Person | Quote | PersonaEntity;
+export const CORRECTABLE_TYPES: CorrectableType[] = ["fact", "topic", "person", "quote", "persona"];
+
+export interface CorrectionUpsert {
+  op: "upsert";
+  entity_type: CorrectableType;
+  id: string;
+  record: CorrectableEntity;
+  timestamp: string;
+}
+
+export interface CorrectionRemove {
+  op: "remove";
+  entity_type: CorrectableType;
+  id: string;
+  timestamp: string;
+}
+
+export type CorrectionRecord = CorrectionUpsert | CorrectionRemove;
+
+/**
+ * Runtime shape validation for a CorrectionRecord read back from
+ * corrections.json. The TypeScript union is compile-time only — every
+ * record actually enters the system via `JSON.parse(...) as CorrectionRecord`
+ * in readCorrections(), so a malformed-but-valid-JSON record (bad `op`,
+ * mismatched `record.id`, missing `record` on an upsert) is otherwise
+ * silently trusted. Both consumers (CLI read-merge/self-drain via
+ * applyCorrectionToHuman, and Processor.applyCorrectionRecord) call this
+ * before mutating anything — it throws, never coerces, so a malformed `op`
+ * can never be silently treated as its sibling operation.
+ */
+export function assertValidCorrection(value: unknown): asserts value is CorrectionRecord {
+  if (!value || typeof value !== "object") {
+    throw new Error(`Malformed correction record: expected an object, got ${JSON.stringify(value)}`);
+  }
+  if (!("op" in value) || (value.op !== "upsert" && value.op !== "remove")) {
+    throw new Error(`Malformed correction record: op must be "upsert" or "remove", got ${JSON.stringify("op" in value ? value.op : undefined)}`);
+  }
+  if (!("entity_type" in value) || !CORRECTABLE_TYPES.includes(value.entity_type as CorrectableType)) {
+    throw new Error(`Malformed correction record: entity_type must be one of ${CORRECTABLE_TYPES.join(", ")}, got ${JSON.stringify("entity_type" in value ? value.entity_type : undefined)}`);
+  }
+  if (!("id" in value) || typeof value.id !== "string" || value.id.length === 0) {
+    throw new Error(`Malformed correction record: id must be a non-empty string, got ${JSON.stringify("id" in value ? value.id : undefined)}`);
+  }
+  if (value.op === "upsert") {
+    if (!("record" in value) || !value.record || typeof value.record !== "object") {
+      throw new Error(`Malformed correction record: upsert requires a record object`);
+    }
+    if (!("id" in value.record) || value.record.id !== value.id) {
+      throw new Error(`Malformed correction record: record.id (${JSON.stringify("id" in value.record ? value.record.id : undefined)}) must equal wrapper id (${JSON.stringify(value.id)})`);
+    }
+  }
+}
+
+/**
+ * Read pending corrections without a lock. Returns [] if the file doesn't
+ * exist or is empty. fs/promises is imported dynamically, not statically —
+ * this module is transitively bundled into Web's browser build via
+ * src/core/processor.ts, and a static `import { readFile } from "fs/promises"`
+ * fails Vite's rollup build (no named exports on the browser-externalized
+ * stub), not just at runtime.
+ */
+export async function readCorrections(correctionsPath: string): Promise<CorrectionRecord[]> {
+  const { readFile } = await import(/* @vite-ignore */ "fs/promises");
+  let text: string;
+  try {
+    text = await readFile(correctionsPath, "utf-8");
+  } catch {
+    return [];
+  }
+  if (!text) return [];
+  return JSON.parse(text) as CorrectionRecord[];
+}
+
+/**
+ * Append one correction under lock (read-modify-write — corrections.json
+ * is a JSON array, not an append-only log, so concurrent writers must
+ * serialize through the same lock rather than racing on a blind append).
+ */
+export async function appendCorrection(
+  correctionsPath: string,
+  record: CorrectionRecord
+): Promise<void> {
+  await withLock(correctionsPath, async () => {
+    const existing = await readCorrections(correctionsPath);
+    existing.push(record);
+    await atomicWrite(correctionsPath, JSON.stringify(existing, null, 2));
+  });
+}
+
+/**
+ * Merge a person's `name` from its primary identifier, replicating the
+ * invariant HumanState.person_upsert enforces on the live-write path
+ * (CONTRACTS.md "Person Identifiers — name Sync Rule"). Both consumers of
+ * this module (Live's StateManager and the CLI's self-drain) must produce
+ * an identical HumanEntity for a given corrections.json, so the formula
+ * is centralized here rather than re-derived at each call site.
+ */
+function syncPersonName(person: Person): Person {
+  const identifiers = person.identifiers ?? [];
+  const primary = identifiers.find((i) => i.is_primary) ?? identifiers[0];
+  return primary ? { ...person, name: primary.value } : person;
+}
+
+/**
+ * Resolve the target array for a CorrectableType. Throws on anything
+ * other than the 4 known types — corrections.json is external input from
+ * CLI/MCP tools (potentially LLM-driven), and a malformed entity_type must
+ * never silently fall through to the people array. Live's Processor
+ * already enforces this (applyCorrectionRecord); this is the equivalent
+ * guard for the CLI read-merge and self-drain paths.
+ */
+function getCorrectableArray(human: HumanEntity, entityType: string): Array<{ id: string }> {
+  if (entityType === "fact") return human.facts;
+  if (entityType === "topic") return human.topics;
+  if (entityType === "person") return human.people;
+  if (entityType === "quote") return human.quotes;
+  throw new Error(`Unrecognized correction entity_type: ${entityType}`);
+}
+
+/**
+ * Apply one correction to a HumanEntity in place, mirroring the exact
+ * upsert/remove semantics of HumanState (src/core/state/human.ts) —
+ * replace-by-id for upsert, splice + orphaned quote-reference cleanup for
+ * remove (for all 3 types, matching fact_remove/topic_remove/person_remove
+ * in HumanState — not just person). Used by both the CLI's read-merge
+ * (materializing a corrected view without a StateManager) and its
+ * self-drain (writing corrections straight into state.json when no live
+ * instance is running).
+ */
+export function applyCorrectionToHuman(human: HumanEntity, correction: CorrectionRecord): void {
+  assertValidCorrection(correction);
+  const array = getCorrectableArray(human, correction.entity_type);
+
+  if (correction.op === "remove") {
+    const idx = array.findIndex((item) => item.id === correction.id);
+    if (idx < 0) return;
+    array.splice(idx, 1);
+    human.quotes.forEach((q) => {
+      q.data_item_ids = q.data_item_ids.filter((itemId) => itemId !== correction.id);
+    });
+    human.last_updated = new Date().toISOString();
+    return;
+  }
+
+  const record = correction.entity_type === "person"
+    ? syncPersonName(correction.record as Person)
+    : correction.record;
+  const idx = array.findIndex((item) => item.id === correction.id);
+  if (idx >= 0) {
+    array[idx] = record;
+  } else {
+    array.push(record);
+  }
+  human.last_updated = new Date().toISOString();
+}
+
+/** Apply every pending correction to a HumanEntity, in file order (later records for the same id win). */
+export function applyCorrectionsToHuman(human: HumanEntity, corrections: CorrectionRecord[]): void {
+  for (const correction of corrections) {
+    applyCorrectionToHuman(human, correction);
+  }
+}
+
+/**
+ * Apply one correction to a StorageState's personas map in place. Personas
+ * live outside HumanEntity — src/core/types/integrations.ts's StorageState.personas
+ * is a top-level `Record<id, {entity, messages}>` — so they need their own
+ * apply function rather than routing through getCorrectableArray/
+ * applyCorrectionToHuman, which only ever resolve arrays on HumanEntity.
+ *
+ * The reserved-persona delete guard here is defense-in-depth for a
+ * hand-edited corrections.json: the primary guard is the SYNCHRONOUS check
+ * in src/cli/persona-corrections.ts's removePersonaEntity, which runs
+ * before a correction is ever queued (so a live-drained rejection here can
+ * never surface as a silent no-op after an apparent CLI success).
+ */
+export function applyCorrectionToPersonas(personas: StorageState["personas"], correction: CorrectionRecord): void {
+  assertValidCorrection(correction);
+  if (correction.op === "remove") {
+    if (isReservedPersonaId(correction.id)) {
+      throw new Error(`Cannot delete reserved persona "${correction.id}". Use archive instead.`);
+    }
+    delete personas[correction.id];
+    return;
+  }
+  personas[correction.id] = {
+    entity: correction.record as PersonaEntity,
+    messages: personas[correction.id]?.messages ?? [],
+  };
+}
+
+/** Route one correction to its target: the personas map for entity_type "persona", the HumanEntity for everything else. */
+export function applyCorrectionToState(state: StorageState, correction: CorrectionRecord): void {
+  if (correction.entity_type === "persona") {
+    applyCorrectionToPersonas(state.personas, correction);
+  } else {
+    applyCorrectionToHuman(state.human, correction);
+  }
+}
+
+/** Apply every pending correction to a StorageState, in file order (later records for the same id win). */
+export function applyCorrectionsToState(state: StorageState, corrections: CorrectionRecord[]): void {
+  for (const correction of corrections) {
+    applyCorrectionToState(state, correction);
+  }
+}

package/src/core/handlers/human-extraction.ts

@@ -169,7 +169,10 @@ export async function handleHumanTopicScan(response: LLMResponse, state: StateMa
     return;
   }
 
-  const context = response.request.data as unknown as ExtractionContext;
+  const context = {
+    ...(response.request.data as unknown as ExtractionContext),
+    channelDisplayName: (response.request.data as Record<string, unknown>).personaDisplayName as string,
+  };
   if (!context?.personaId) return;
 
   const extractionModel = (response.request.data as Record<string, unknown>).extraction_model as string | undefined;
@@ -347,7 +350,10 @@ export async function handleEventScan(response: LLMResponse, state: StateManager
     return;
   }
 
-  const context = response.request.data as unknown as ExtractionContext;
+  const context = {
+    ...(response.request.data as unknown as ExtractionContext),
+    channelDisplayName: (response.request.data as Record<string, unknown>).personaDisplayName as string,
+  };
   if (!context?.personaId) return;
 
   const extractionModel = (response.request.data as Record<string, unknown>).extraction_model as string | undefined;

package/src/core/handlers/human-matching.ts

@@ -282,7 +282,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
         value: i.value,
         ...(i.is_primary ? { is_primary: i.is_primary } : {}),
       })),
-      state
+      state.persona_getAll()
     );
     const allCandidateIds = [...llmIdentifiers, ...candidateIdentifiers];
     if (allCandidateIds.length === 0) {
@@ -303,7 +303,7 @@ export async function handlePersonUpdate(response: LLMResponse, state: StateMana
         ...i,
         type: normalizeIdentifierType(i.type, state),
       })),
-      state
+      state.persona_getAll()
     );
     for (const id of sanitizedToAdd) {
       if (!base.some(e => e.value === id.value)) {

package/src/core/llm-client.ts

@@ -310,10 +310,16 @@ export async function callLLMRaw(
     headers["anthropic-dangerous-direct-browser-access"] = "true";
   }
   
+  // Omit temperature for models that don't accept it (e.g. Anthropic extended-thinking models).
+  // Also omit when thinking_budget > 0: Anthropic rejects temperature alongside thinking params.
+  const sendTemperature =
+    !modelConfig?.temperature_disabled &&
+    !(modelConfig?.thinking_budget !== undefined && modelConfig.thinking_budget > 0);
+
   const requestBody: Record<string, unknown> = {
     ...(model !== undefined && { model }),
     messages: finalMessages,
-    temperature,
+    ...(sendTemperature && { temperature }),
     max_tokens: modelConfig?.max_output_tokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
   };
 

package/src/core/orchestrators/human-extraction.ts

@@ -479,6 +479,7 @@ export function queueTopicUpdate(
       next_step: LLMNextStep.HandleTopicUpdate,
       data: {
         ...context,
+        personaDisplayName: context.channelDisplayName,
         isNewItem,
         existingItemId: existingItem?.id,
         candidateName: isNewItem ? context.candidateName : undefined,

package/src/core/persona-tools.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared boolean-map <-> flat-id-array conversion for PersonaEntity.tools.
+ *
+ * PersonaEntity.tools is persisted (and written by external CRUD callers)
+ * as a flat array of ToolDefinition ids. That's opaque to a human or an
+ * external agent — nothing about a bare UUID says which provider it
+ * belongs to, what it's called, or whether it's even grantable right now
+ * (a tool under a disabled provider is unusable regardless of whether its
+ * id sits in this array). buildPersonaToolsMap/resolvePersonaToolsFromMap
+ * convert between that flat storage shape and a self-documenting
+ * `{ [providerDisplayName]: { [toolDisplayName]: boolean } }` map — the
+ * same shape the TUI's $EDITOR/YAML persona editor has used since before
+ * this module existed (originally defined in
+ * tui/src/util/yaml-persona.ts, relocated here so the external CRUD
+ * surface — src/cli/retrieval.ts's lookupById and
+ * src/cli/persona-corrections.ts's create/update — can present and accept
+ * the identical shape instead of a raw UUID array).
+ *
+ * Relocation is verbatim: same names, same signatures, same bodies as the
+ * TUI originals. The TUI now imports both functions from here rather than
+ * defining its own copies.
+ */
+import type { ToolDefinition, ToolProvider } from "./types.js";
+
+export function buildPersonaToolsMap(
+  enabledToolIds: string[],
+  allTools: ToolDefinition[],
+  allProviders: ToolProvider[]
+): Record<string, Record<string, boolean>> | undefined {
+  if (allTools.length === 0) return undefined;
+  const enabledSet = new Set(enabledToolIds);
+  const result: Record<string, Record<string, boolean>> = {};
+  for (const provider of allProviders.filter(p => p.enabled)) {
+    const providerTools = allTools.filter(t => t.provider_id === provider.id);
+    if (providerTools.length === 0) continue;
+    result[provider.display_name] = Object.fromEntries(
+      providerTools.map(t => [t.display_name, enabledSet.has(t.id)])
+    );
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+export function resolvePersonaToolsFromMap(
+  toolsMap: Record<string, Record<string, boolean>> | undefined,
+  allTools: ToolDefinition[],
+  allProviders: ToolProvider[]
+): string[] | undefined {
+  if (!toolsMap) return undefined;
+  const enabledIds: string[] = [];
+  for (const [providerDisplayName, toolToggles] of Object.entries(toolsMap)) {
+    const provider = allProviders.find(p => p.display_name === providerDisplayName);
+    if (!provider) continue;
+    for (const [toolDisplayName, enabled] of Object.entries(toolToggles)) {
+      if (!enabled) continue;
+      const tool = allTools.find(t => t.provider_id === provider.id && t.display_name === toolDisplayName);
+      if (tool) enabledIds.push(tool.id);
+    }
+  }
+  return enabledIds.length > 0 ? enabledIds : [];
+}
+
+/**
+ * A tool id belonging to a currently-disabled provider is invisible to
+ * buildPersonaToolsMap and therefore can never appear in a caller's
+ * submitted map -- not because the caller chose to omit it, but because
+ * they had no way to see it. Full-record-replace semantics only apply to
+ * the portion of tools[] a caller could actually read and edit; anything
+ * outside that boundary must survive an edit unconditionally, or a normal
+ * read-edit-write cycle silently destroys stored state the caller never
+ * had a chance to preserve correctly. This is intentionally NOT a general
+ * merge -- resolvedVisibleIds still fully governs every id whose provider
+ * IS enabled; only ids that are structurally unaddressable right now get
+ * carried forward.
+ */
+export function preserveHiddenToolGrants(
+  resolvedVisibleIds: string[] | undefined,
+  existingIds: string[] | undefined,
+  allTools: ToolDefinition[],
+  allProviders: ToolProvider[]
+): string[] | undefined {
+  const providerById = new Map(allProviders.map(p => [p.id, p]));
+  const toolById = new Map(allTools.map(t => [t.id, t]));
+  const hidden = (existingIds ?? []).filter(id => {
+    const tool = toolById.get(id);
+    if (!tool) return false;
+    const provider = providerById.get(tool.provider_id);
+    return provider ? !provider.enabled : false;
+  });
+  if (hidden.length === 0) return resolvedVisibleIds;
+  const merged = new Set([...(resolvedVisibleIds ?? []), ...hidden]);
+  return merged.size > 0 ? Array.from(merged) : undefined;
+}

package/src/core/personas/opencode-agent.ts

@@ -3,7 +3,6 @@ import type { PersonaTrait } from "../types.js";
 import type { StateManager } from "../state-manager.js";
 import type { IOpenCodeReader } from "../../integrations/opencode/types.js";
 import { AGENT_ALIASES } from "../../integrations/opencode/types.js";
-import { createOpenCodeReader } from "../../integrations/opencode/reader-factory.js";
 import { DEFAULT_SEED_TRAITS } from "../constants/seed-traits.js";
 
 const OPENCODE_GROUP = "OpenCode";
@@ -52,8 +51,7 @@ export async function ensureAgentPersona(
     return existing;
   }
 
-  const agentReader = reader ?? await createOpenCodeReader();
-  const agentInfo = await agentReader.getAgentInfo(canonical);
+  const agentInfo = reader ? await reader.getAgentInfo(canonical) : null;
 
   const now = new Date().toISOString();
   const personaId = crypto.randomUUID();