u-foo 2.2.4 → 2.3.1

package/SKILLS/ufoo/SKILL.md

@@ -8,11 +8,12 @@ description: |
 
 # ufoo — Unified Agent Protocol
 
-ufoo is the multi-agent coordination layer. It provides three capabilities:
+ufoo is the multi-agent coordination layer. It provides four capabilities:
 
-1. **Context Decisions** — Persistent knowledge log shared across agents
-2. **Event Bus** — Inter-agent messaging
-3. **Initialization** — Project setup for ufoo modules
+1. **Context Decisions** — Sparse log of major plan-level choices shared across agents
+2. **Shared Memory** — Durable, low-noise project facts shared across agents
+3. **Event Bus** — Inter-agent messaging
+4. **Initialization** — Project setup for ufoo modules
 
 ## Session Marker
 
@@ -26,13 +27,14 @@ When you see a probe marker command like `/ufoo <marker>` (Claude) or `$ufoo <ma
 
 **"Only record decisions that matter beyond this session."**
 
-Record a decision for important, plan-level knowledge that other agents or your future self need. The threshold is HIGH — most tasks do NOT need a decision.
+The default is **no new decision**. Record one only for important, plan-level knowledge that other agents or your future self will need.
 
 - **Always record**: architectural choices, plan-level decisions with multiple options, cross-agent coordination decisions, trade-off analysis where alternatives were considered and rejected
 - **Also record**: design patterns that set precedent, integration contracts between systems, decisions that constrain future work
-- **Do NOT record**: routine bug fixes, simple implementation details, trivial observations, findings that only matter within the current task
-- **Write the decision BEFORE acting on it** — if your session dies, the knowledge survives
-- **Rule of thumb**: if another agent wouldn't need to know about it, don't write a decision
+- **Do NOT record**: routine bug fixes, simple implementation details, trivial observations, generic planning/evaluation/recommendation requests, or findings that only matter within the current task
+- **Prefer shared memory**: durable project facts and long-lived factual constraints belong in shared memory, not decisions
+- **Write the decision BEFORE acting on it** — but only after the high bar above is clearly met
+- **Rule of thumb**: if another agent would not need this as a future constraint, do not write a decision
 
 ### Commands
 
@@ -75,9 +77,51 @@ What must follow from this?
 
 **NEVER resolve blindly.** Reading the title is not enough.
 
+### Read-First Rule
+
+Shared context is **read-first**, not write-only:
+
+1. At session start or before related work, read open decisions first.
+2. Do not create a new decision just to persist ordinary work state.
+3. Consume shared memory via prompt prefix / `recall` / `search_memory` before writing new memory.
+
+---
+
+## 2. Shared Memory
+
+Shared memory records durable project facts only. It is not a scratchpad, progress log, user-preference store, or replacement for decisions.
+
+### When to Record
+
+- **Record**: permanent project invariants, external ownership facts, integration contracts, long-lived process constraints
+- **Do NOT record**: current task status, transient observations, "today/current/recent" facts, agent feedback, routine findings, or anything likely to expire
+- **Read first**: if memory may already exist, use `recall` / `search_memory` before `remember` or `edit_memory`
+- **Prefer edit over duplicate**: update an existing memory when the fact already exists but wording changed
+
+### Commands
+
+```bash
+ufoo memory add "Title" --body "Durable fact body" --tags infra,billing
+ufoo memory list [--tag infra] [--all]
+ufoo memory show mem-0001
+ufoo memory edit mem-0001
+ufoo memory forget mem-0001
+ufoo memory rebuild-index
+ufoo memory audit mem-0001
+```
+
+### Agent Tools
+
+- `remember` — write a new durable memory fact
+- `recall` — read memory by id or tags
+- `search_memory` — search memory before writing or when more context is needed
+- `search_history` — search local Claude/Codex session history as redacted evidence
+- `edit_memory` — directly update any existing memory, with optional `expected_updated_at`
+- `forget` — archive an obsolete or polluted memory entry
+
 ---
 
-## 2. Event Bus (ubus)
+## 3. Event Bus (ubus)
 
 ### Commands
 
@@ -122,7 +166,7 @@ Notes:
 
 ---
 
-## 3. Message Format
+## 4. Message Format
 
 Bus messages use a unified prefix format to distinguish sources:
 
@@ -134,7 +178,7 @@ When you see `[manual]<to:xxx>`, it's a direct user instruction to an agent —
 
 ---
 
-## 4. Team Activity (Input History)
+## 5. Team Activity (Input History)
 
 Your bootstrap prompt may include a `## Team Activity` section showing recent prompts sent to all agents. Use this to understand:
 - What each agent is currently working on
@@ -150,7 +194,7 @@ ufoo history prompt [limit]     # Render as injectable prompt block
 
 ---
 
-## 5. Initialization (uinit)
+## 6. Initialization (uinit)
 
 Trigger: `/uinit` or `/ufoo init`
 

package/SKILLS/uinit/SKILL.md

@@ -29,7 +29,7 @@ Please select modules to enable:
 ```
 
 Options:
-- `context` (recommended) - Shared context, decision recording, knowledge persistence
+- `context` (recommended) - Shared context, sparse decision log for major plan-level choices
 - `bus` (recommended) - Multi-agent communication, task delegation, message passing
 - `resources` (optional) - UI tone guide, icon library
 
@@ -61,6 +61,7 @@ fi
 === ufoo initialization complete ===
 
 Enabled modules:
+  ✓ core memory → .ufoo/memory/
   ✓ context → .ufoo/context/
   ✓ bus → .ufoo/bus/ + .ufoo/agent/
 
@@ -73,6 +74,6 @@ Next steps:
 
 ## Notes
 
-- If .ufoo/context, .ufoo/bus, or .ufoo/agent already exists, skip creation
+- If .ufoo/memory, .ufoo/context, .ufoo/bus, or .ufoo/agent already exists, skip creation
 - After initialization, reuse existing subscriber ID first, join only as fallback (if bus enabled)
 - AGENTS.md will have protocol description block injected

package/modules/AGENTS.template.md

@@ -1,7 +1,8 @@
 <!-- ufoo -->
 ## ufoo Agent Protocol
 
-> **Record decisions before acting.** Any knowledge with information value → `ufoo ctx decisions new "Title"` BEFORE you act on it.
+> **Default: do not write a decision.** Record one only for important, plan-level knowledge that should constrain future work: architectural choices, trade-off analysis, cross-agent coordination, or precedent-setting integration contracts. NOT for routine findings, simple fixes, or because the user asked for a plan/evaluation/recommendation. Durable project facts belong in shared memory, not decisions. → `ufoo ctx decisions new "Title"` BEFORE acting only when that high bar is met.
+> **Read shared memory before writing it.** Durable facts live in `.ufoo/memory/`; use `ufoo memory list/show`, `recall`, `search_memory`, or redacted `search_history` evidence before `remember` / `edit_memory`.
 > **Auto-execute bus messages.** On `ubus`: execute tasks immediately, reply to sender, then `ufoo bus ack`. Never ask the user.
 > **Full protocol**: `/ufoo` skill (auto-loaded on session start). Docs: `.ufoo/docs/`
 <!-- /ufoo -->

package/modules/bus/README.md

@@ -134,7 +134,7 @@ Examples:
 
 | Module | Problem Solved |
 |--------|----------------|
-| context | Shared context, decision recording, knowledge persistence |
+| context | Shared context, sparse decision log for major plan-level choices |
 | bus | Real-time communication, task delegation, message passing |
 
 Both are independent peer modules that can be used separately or together.

package/modules/context/SKILLS/uctx/SKILL.md

@@ -13,13 +13,15 @@ description: |
 Fast context check for daily use. Run at session start or anytime.
 
 Pre-flight reminder:
-- If the user is asking for an important architectural decision, a plan with multiple options, or a cross-agent coordination choice, write a decision before replying.
-  Do NOT write decisions for routine tasks, simple bug fixes, or trivial findings.
+- Default is no new decision.
+- Write a decision only for important architectural choices, trade-off outcomes, cross-agent coordination, or precedent-setting integration contracts.
+- Do NOT write decisions for routine tasks, simple bug fixes, trivial findings, or generic plan/evaluation/recommendation requests.
+- Durable project facts belong in shared memory, not decisions.
   Use: `ufoo ctx decisions new "<Title>"`
 
 ## Decision format (canonical)
 
-Project context is decision-only. Decisions live at:
+The context module tracks decisions only. Durable shared facts belong in shared memory. Decisions live at:
 `<project>/.ufoo/context/decisions/`
 
 Decision index (JSONL):
@@ -36,7 +38,7 @@ Each JSONL row includes:
 - `file` (decision filename)
 - `author` (decision author or resolver)
 
-Create a new decision (recommended before replying when required):
+Create a new decision (only when the high-threshold rule above requires it):
 ```bash
 ufoo ctx decisions new "Short Title"
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "2.2.4",
+  "version": "2.3.1",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/agent/activityStatePublisher.js

@@ -12,6 +12,7 @@ const { writeActivityState } = require("./activityStateWriter");
  * @param {string} options.subscriber  - Subscriber ID (e.g. "claude-code:abc123")
  * @param {string} options.projectRoot - Project root (unused, kept for API compat)
  * @param {boolean} [options.force=true] - Force overwrite priority-protected states
+ * publish(state, extra, { force }) can override this default for one transition.
  */
 function createActivityStatePublisher(options = {}) {
   const {
@@ -22,10 +23,13 @@ function createActivityStatePublisher(options = {}) {
 
   let lastState = "";
 
-  function publish(state, extra = {}) {
+  function publish(state, extra = {}, publishOptions = {}) {
     if (state === lastState) return false;
     const since = extra.since || undefined;
-    const changed = writeActivityState(agentsFile, subscriber, state, { since, force });
+    const effectiveForce = typeof publishOptions.force === "boolean"
+      ? publishOptions.force
+      : force;
+    const changed = writeActivityState(agentsFile, subscriber, state, { since, force: effectiveForce });
     if (!changed) return false;
     lastState = state;
     // Write to bus events directory for daemon bridge to pick up.

package/src/agent/codexThreadProvider.js

@@ -61,7 +61,7 @@ async function* defaultCodexTransportStreamFactory({
   });
   if (!result.ok) {
     const err = new Error(result.error || "Codex upstream request failed");
-    err.code = "CODEX_UPSTREAM_FAILED";
+    err.code = result.errorCode || "CODEX_UPSTREAM_FAILED";
     throw err;
   }
 
@@ -145,7 +145,7 @@ class CodexThreadProvider {
     this.cwd = cwd;
     this.extraArgs = Array.isArray(extraArgs) ? extraArgs.slice() : [];
     this.streamFactory = streamFactory;
-    this.sdk = sdk || resolveCodexSdk();
+    this.sdk = sdk || (streamFactory === defaultCodexStreamFactory ? resolveCodexSdk() : null);
     this.tools = Array.isArray(tools) ? tools.slice() : [];
   }
 

package/src/agent/controllerToolExecutor.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const EventBus = require("../bus");
+const { getToolDefinition, CALLER_TIERS } = require("../tools");
 const { dispatchMessageHandler } = require("../tools/handlers/dispatchMessage");
 const { ackBusHandler } = require("../tools/handlers/ackBus");
 
@@ -145,6 +146,25 @@ async function handleLaunchAgent(ctx, args) {
   };
 }
 
+async function handleSharedRegistryTool(ctx, name, args, audit = {}) {
+  const definition = getToolDefinition(name);
+  if (!definition || typeof definition.handler !== "function") {
+    throw buildStructuredError("unsupported_tool", `unsupported controller tool: ${name}`);
+  }
+  if (!definition.allowed_tiers.includes(CALLER_TIERS.CONTROLLER)) {
+    throw buildStructuredError("forbidden_caller_tier", `controller is not allowed to invoke tool: ${name}`);
+  }
+  const eventBus = ctx.eventBus || new EventBus(ctx.projectRoot);
+  return definition.handler({
+    projectRoot: ctx.projectRoot,
+    subscriber: ctx.subscriber || "ufoo-agent",
+    caller_tier: CALLER_TIERS.CONTROLLER,
+    eventBus,
+    turn_id: audit.turn_id || "",
+    tool_call_id: audit.tool_call_id || "",
+  }, args);
+}
+
 async function executeControllerTool(ctx, toolCall = {}) {
   const observer = ctx.observer || { emit: () => {}, audit: () => {} };
   const name = String(toolCall.name || "").trim();
@@ -169,7 +189,10 @@ async function executeControllerTool(ctx, toolCall = {}) {
     } else if (name === "launch_agent") {
       result = await handleLaunchAgent(ctx, args);
     } else {
-      throw buildStructuredError("unsupported_tool", `unsupported controller tool: ${name}`);
+      result = await handleSharedRegistryTool(ctx, name, args, {
+        turn_id: turnId,
+        tool_call_id: toolCallId,
+      });
     }
 
     observer.emit("tool_call_finished", {

package/src/agent/credentials/claude.js

@@ -25,6 +25,7 @@ function resolveClaudeOauthPaths(options = {}) {
   const configDir = String(options.configDir || defaultClaudeConfigDir()).trim() || defaultClaudeConfigDir();
   const profile = String(options.profile || "").trim();
   const explicitTokenPath = String(options.tokenPath || "").trim();
+  const explicitSettingsPath = String(options.settingsPath || "").trim();
   const profileDir = profile ? path.join(configDir, "profiles", profile) : configDir;
   const tokenPath = explicitTokenPath || path.join(profileDir, "oauth.json");
   return {
@@ -33,9 +34,17 @@ function resolveClaudeOauthPaths(options = {}) {
     profileDir,
     tokenPath,
     lockPath: `${tokenPath}.lock`,
+    settingsPath: explicitSettingsPath || path.join(configDir, "settings.json"),
   };
 }
 
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
 function classifyTokenState(expiresAtMs, nowMs, refreshWindowMs) {
   if (!Number.isFinite(expiresAtMs)) return "invalid";
   if (expiresAtMs <= nowMs) return "expired";
@@ -208,6 +217,61 @@ class ClaudeUpstreamCredentialResolver {
     };
   }
 
+  readSettingsEnv() {
+    let raw;
+    try {
+      raw = JSON.parse(this.fs.readFileSync(this.paths.settingsPath, "utf8"));
+    } catch {
+      return {};
+    }
+    const env = raw && raw.env && typeof raw.env === "object" && !Array.isArray(raw.env)
+      ? raw.env
+      : {};
+    const apiKeySource = firstString(env.ANTHROPIC_API_KEY)
+      ? "settings:ANTHROPIC_API_KEY"
+      : (firstString(env.CLAUDE_API_KEY) ? "settings:CLAUDE_API_KEY" : "");
+    return {
+      apiKey: firstString(env.ANTHROPIC_API_KEY, env.CLAUDE_API_KEY),
+      apiKeySource,
+      authToken: firstString(env.ANTHROPIC_AUTH_TOKEN),
+    };
+  }
+
+  buildApiKeyCredential(apiKey, source, credentialPath = "") {
+    return buildCredentialDescriptor({
+      provider: "claude",
+      credentialKind: "api-key",
+      source,
+      apiKey,
+      tokenType: "Bearer",
+      state: "fresh",
+      refreshable: false,
+      profile: this.paths.profile,
+      credentialPath,
+      nowMs: this.now(),
+      refreshWindowMs: this.refreshWindowMs,
+    });
+  }
+
+  buildAuthTokenCredential(accessToken, source, credentialPath = "") {
+    return buildCredentialDescriptor({
+      provider: "claude",
+      credentialKind: "oauth",
+      source,
+      accessToken,
+      tokenType: "Bearer",
+      state: "fresh",
+      refreshable: false,
+      profile: this.paths.profile,
+      credentialPath,
+      nowMs: this.now(),
+      refreshWindowMs: this.refreshWindowMs,
+      metadata: {
+        tokenPath: credentialPath,
+      },
+    });
+  }
+
   buildResolvedCredential(tokenRecord) {
     return buildCredentialDescriptor({
       provider: "claude",
@@ -269,21 +333,26 @@ class ClaudeUpstreamCredentialResolver {
   }
 
   async resolveCredentials() {
-    const apiKey = typeof this.env.ANTHROPIC_API_KEY === "string" ? this.env.ANTHROPIC_API_KEY.trim() : "";
-    if (apiKey) {
-      return buildCredentialDescriptor({
-        provider: "claude",
-        credentialKind: "api-key",
-        source: "api-key",
-        apiKey,
-        tokenType: "Bearer",
-        state: "fresh",
-        refreshable: false,
-        profile: this.paths.profile,
-        credentialPath: "",
-        nowMs: this.now(),
-        refreshWindowMs: this.refreshWindowMs,
-      });
+    const anthropicApiKey = firstString(this.env.ANTHROPIC_API_KEY);
+    const claudeApiKey = firstString(this.env.CLAUDE_API_KEY);
+    if (anthropicApiKey || claudeApiKey) {
+      return this.buildApiKeyCredential(
+        anthropicApiKey || claudeApiKey,
+        anthropicApiKey ? "env:ANTHROPIC_API_KEY" : "env:CLAUDE_API_KEY",
+      );
+    }
+
+    const authToken = firstString(this.env.ANTHROPIC_AUTH_TOKEN);
+    if (authToken) {
+      return this.buildAuthTokenCredential(authToken, "env:ANTHROPIC_AUTH_TOKEN");
+    }
+
+    const settingsEnv = this.readSettingsEnv();
+    if (settingsEnv.apiKey) {
+      return this.buildApiKeyCredential(settingsEnv.apiKey, settingsEnv.apiKeySource || "settings:ANTHROPIC_API_KEY", this.paths.settingsPath);
+    }
+    if (settingsEnv.authToken) {
+      return this.buildAuthTokenCredential(settingsEnv.authToken, "settings:ANTHROPIC_AUTH_TOKEN", this.paths.settingsPath);
     }
 
     let tokenRecord;
@@ -291,7 +360,7 @@ class ClaudeUpstreamCredentialResolver {
       tokenRecord = this.readTokenFile();
     } catch (err) {
       if (err && err.code === "ENOENT") {
-        const missing = new Error("Claude OAuth token not found and ANTHROPIC_API_KEY is unset");
+        const missing = new Error("Claude credentials not found in environment, Claude settings, or OAuth token file");
         missing.code = "CLAUDE_AUTH_UNAVAILABLE";
         throw missing;
       }