@holoscript/holoscript-agent 2.0.2 → 2.0.4

package/dist/index.js

@@ -4,7 +4,7 @@
 import { homedir as homedir3, hostname as hostname2 } from "os";
 import { join as join4 } from "path";
 import { createHash as createHash4, createDecipheriv, randomBytes as randomBytes2 } from "crypto";
-import { Wallet as Wallet2 } from "ethers";
+import { Wallet as Wallet3 } from "ethers";
 import {
   createAnthropicProvider,
   createOpenAIProvider,
@@ -35,7 +35,7 @@ function loadIdentity(env = process.env) {
       `HOLOSCRIPT_AGENT_PROVIDER=${provider} not in [${[...VALID_PROVIDERS].join(", ")}]`
     );
   }
-  const x402Bearer = required(env, "HOLOSCRIPT_AGENT_X402_BEARER");
+  const x402Bearer = (env.HOLOSCRIPT_AGENT_X402_BEARER ?? "").trim();
   const wallet = required(env, "HOLOSCRIPT_AGENT_WALLET");
   if (!/^0x[0-9a-fA-F]{40}$/.test(wallet)) {
     throw new Error(`HOLOSCRIPT_AGENT_WALLET is not a 0x-prefixed 40-hex address: ${wallet}`);
@@ -72,7 +72,7 @@ function identityForLog(id) {
     handle: id.handle,
     surface: id.surface,
     wallet: `${id.wallet.slice(0, 6)}\u2026${id.wallet.slice(-4)}`,
-    bearer: `${id.x402Bearer.slice(0, 6)}\u2026`,
+    bearer: id.x402Bearer ? `${id.x402Bearer.slice(0, 6)}\u2026` : "(broker-resolved)",
     provider: id.llmProvider,
     model: id.llmModel,
     brain: id.brainPath,
@@ -95,7 +95,8 @@ async function loadBrain(brainPath, scopeTier = "warm") {
     requires,
     prefers,
     avoids,
-    reflect: extractReflect(raw)
+    reflect: extractReflect(raw),
+    onTaskActions: extractOnTaskActions(raw)
   };
 }
 function extractReflect(brain) {
@@ -130,6 +131,53 @@ function extractIdentity(brain) {
   const avoids = listField(identityBlock, "avoids") ?? [];
   return { domain, capabilityTags, requires, prefers, avoids };
 }
+function extractOnTaskActions(brain) {
+  const block = sliceNamedBlock(brain, "on_task");
+  if (!block) return [];
+  const VERBS = ["recall", "rag_query", "llm_call", "plan", "reflect"];
+  const entries = [];
+  for (const verb of VERBS) {
+    const re = new RegExp(`\\b${verb}\\s*\\{`, "g");
+    let m;
+    while ((m = re.exec(block)) !== null) {
+      const start = m.index + m[0].length;
+      let depth = 1;
+      let end = -1;
+      for (let i = start; i < block.length; i++) {
+        if (block[i] === "{") depth++;
+        else if (block[i] === "}") {
+          depth--;
+          if (depth === 0) {
+            end = i;
+            break;
+          }
+        }
+      }
+      if (end < 0) continue;
+      entries.push({ verb, config: parseKVBlock(block.slice(start, end)), _pos: m.index });
+    }
+  }
+  return entries.sort((a, b) => a._pos - b._pos).map(({ _pos: _ignored, ...rest }) => rest);
+}
+function parseKVBlock(block) {
+  const out = {};
+  const strRe = /\b(\w+)\s*:\s*"([^"]*)"/g;
+  let m;
+  while ((m = strRe.exec(block)) !== null) out[m[1]] = m[2];
+  const arrRe = /\b(\w+)\s*:\s*\[([^\]]*)\]/g;
+  while ((m = arrRe.exec(block)) !== null) {
+    out[m[1]] = m[2].split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter((s) => s.length > 0);
+  }
+  const boolRe = /\b(\w+)\s*:\s*(true|false)\b/g;
+  while ((m = boolRe.exec(block)) !== null) {
+    if (!(m[1] in out)) out[m[1]] = m[2] === "true";
+  }
+  const numRe = /\b(\w+)\s*:\s*(-?\d+(?:\.\d+)?)\b/g;
+  while ((m = numRe.exec(block)) !== null) {
+    if (!(m[1] in out)) out[m[1]] = parseFloat(m[2]);
+  }
+  return out;
+}
 function sliceNamedBlock(src, name) {
   const re = new RegExp(`\\b${name}\\s*:?\\s*\\{`, "g");
   const match = re.exec(src);
@@ -570,6 +618,37 @@ var HolomeshClient = class {
   async delegateTask(taskId, toAgentId) {
     return this.req("PATCH", `/team/${this.teamId}/board/${taskId}`, await this.signBody({ action: "delegate", toAgentId }));
   }
+  // ── Cognitive-verb knowledge surface (Phase 2.2 — recall / rag_query) ────────
+  /**
+   * Query the TEAM knowledge base (the `rag_query` cognitive verb). Bearer-only
+   * GET; `q` is the server-side search filter. Returns [] on any failure so a
+   * retrieval miss never breaks a tick.
+   */
+  async queryTeamKnowledge(query, limit = 5) {
+    const qs = new URLSearchParams({ q: query, limit: String(limit) }).toString();
+    try {
+      const data = await this.req(
+        "GET",
+        `/team/${this.teamId}/knowledge?${qs}`
+      );
+      return data.entries ?? [];
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Query this agent's PRIVATE workspace knowledge (the `recall` cognitive verb).
+   * The endpoint has no server-side search param, so the caller filters by query
+   * client-side. Returns [] on any failure.
+   */
+  async queryPrivateKnowledge() {
+    try {
+      const data = await this.req("GET", `/knowledge/private`);
+      return data.entries ?? [];
+    } catch {
+      return [];
+    }
+  }
   async req(method, path, body) {
     const url = `${this.apiBase}${path}`;
     const res = await this.fetchImpl(url, {
@@ -619,6 +698,44 @@ function priority(t) {
   return map[String(t.priority).toLowerCase()] ?? 5;
 }
 
+// src/bearer-broker.ts
+import { Wallet } from "ethers";
+var RECOVERY_DOMAIN = { name: "HoloMesh", version: "1" };
+var RECOVERY_TYPES = {
+  Recovery: [{ name: "nonce", type: "string" }]
+};
+async function resolveBearerViaBroker(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const wallet = new Wallet(opts.privateKey);
+  const address = wallet.address;
+  const base = opts.meshApiBase.replace(/\/+$/, "");
+  const chalRes = await doFetch(`${base}/key/challenge`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ wallet_address: address })
+  });
+  if (!chalRes.ok) {
+    throw new Error(`bearer-broker: /key/challenge returned ${chalRes.status} for ${address}`);
+  }
+  const chal = await chalRes.json();
+  if (!chal.nonce) throw new Error("bearer-broker: /key/challenge returned no nonce");
+  const signature = await wallet.signTypedData(RECOVERY_DOMAIN, RECOVERY_TYPES, {
+    nonce: chal.nonce
+  });
+  const recRes = await doFetch(`${base}/key/recover`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ wallet_address: address, nonce: chal.nonce, signature })
+  });
+  if (!recRes.ok) {
+    throw new Error(`bearer-broker: /key/recover returned ${recRes.status} for ${address}`);
+  }
+  const rec = await recRes.json();
+  const bearer = rec.agent?.api_key;
+  if (!bearer) throw new Error("bearer-broker: /key/recover returned no api_key");
+  return bearer;
+}
+
 // src/cael-builder.ts
 import { createHash } from "crypto";
 function sha(input) {
@@ -1030,6 +1147,109 @@ function errResult(id, message) {
   return { type: "tool_result", tool_use_id: id, content: message, is_error: true };
 }
 
+// src/cognitive-verbs.ts
+var DEFAULT_LIMIT = 5;
+var MAX_ENTRY_CHARS = 320;
+var MAX_INJECTED_CHARS = 2400;
+function strField(config, ...keys) {
+  for (const k of keys) {
+    const v = config[k];
+    if (typeof v === "string" && v.trim()) return v.trim();
+  }
+  return "";
+}
+function numField(config, key, fallback) {
+  const v = config[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+function formatEntries(entries) {
+  let out = "";
+  for (const e of entries) {
+    const line = `- ${(e.content ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_ENTRY_CHARS)}`;
+    if (out.length + line.length > MAX_INJECTED_CHARS) break;
+    out += (out ? "\n" : "") + line;
+  }
+  return out;
+}
+async function augmentWithOnTaskCognition(deps) {
+  let content = deps.systemPrompt;
+  if (!deps.onTaskActions || deps.onTaskActions.length === 0) return content;
+  for (const action of deps.onTaskActions) {
+    try {
+      switch (action.verb) {
+        case "llm_call": {
+          const prompt = strField(action.config, "prompt");
+          if (prompt) {
+            content += `
+
+[Brain on_task directive]
+${prompt}`;
+            deps.log({ ev: "on-task-llm-call", taskId: deps.task.id, promptLen: prompt.length });
+          }
+          break;
+        }
+        case "rag_query": {
+          const query = strField(action.config, "query", "q") || deps.task.title;
+          const limit = numField(action.config, "limit", DEFAULT_LIMIT);
+          const entries = await deps.queryTeamKnowledge(query, limit);
+          if (entries.length > 0) {
+            content += `
+
+[Retrieved knowledge for "${query}"]
+${formatEntries(entries)}`;
+          }
+          deps.log({ ev: "on-task-rag-query", taskId: deps.task.id, query, retrieved: entries.length });
+          break;
+        }
+        case "recall": {
+          const query = strField(action.config, "query", "q");
+          const limit = numField(action.config, "limit", DEFAULT_LIMIT);
+          const all = await deps.queryPrivateKnowledge();
+          const needle = query.toLowerCase();
+          const matched = (needle ? all.filter((e) => `${e.id ?? ""} ${e.content ?? ""}`.toLowerCase().includes(needle)) : all).slice(0, limit);
+          if (matched.length > 0) {
+            content += `
+
+[Recalled memory${query ? ` for "${query}"` : ""}]
+${formatEntries(matched)}`;
+          }
+          deps.log({ ev: "on-task-recall", taskId: deps.task.id, query, recalled: matched.length });
+          break;
+        }
+        case "plan": {
+          if (!deps.plan) break;
+          const goal = strField(action.config, "goal", "prompt", "of") || deps.task.title;
+          const planText = await deps.plan(
+            `Produce a short numbered plan (max 6 steps) to accomplish this task. Be concrete and specific to the goal; do not execute it.
+
+Goal: ${goal}`
+          );
+          const trimmed = planText.trim().slice(0, MAX_INJECTED_CHARS);
+          if (trimmed) {
+            content += `
+
+[Plan]
+${trimmed}`;
+            deps.log({ ev: "on-task-plan", taskId: deps.task.id, planLen: trimmed.length });
+          }
+          break;
+        }
+        // `reflect` is handled post-artifact in runner.ts, not here.
+        default:
+          break;
+      }
+    } catch (err) {
+      deps.log({
+        ev: "on-task-verb-error",
+        taskId: deps.task.id,
+        verb: action.verb,
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return content;
+}
+
 // src/runner.ts
 var RUNTIME_VERSION = "1.0.0";
 var AgentRunner = class {
@@ -1112,8 +1332,23 @@ var AgentRunner = class {
     log({ ev: "claim", taskId: target.id, title: target.title });
     await mesh.claim(target.id);
     const start = Date.now();
+    const systemContent = await augmentWithOnTaskCognition({
+      systemPrompt: brain.systemPrompt,
+      onTaskActions: brain.onTaskActions ?? [],
+      task: { id: target.id, title: target.title },
+      queryTeamKnowledge: (q, limit) => mesh.queryTeamKnowledge(q, limit),
+      queryPrivateKnowledge: () => mesh.queryPrivateKnowledge(),
+      plan: async (prompt) => {
+        const resp = await provider.complete(
+          { messages: [{ role: "user", content: prompt }], maxTokens: 512, temperature: 0.3 },
+          identity.llmModel
+        );
+        return resp.content;
+      },
+      log
+    });
     const messages = [
-      { role: "system", content: brain.systemPrompt },
+      { role: "system", content: systemContent },
       { role: "user", content: buildTaskPrompt(target) }
     ];
     let aggUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
@@ -2173,7 +2408,7 @@ import { mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync a
 import { join as join3 } from "path";
 import { homedir as homedir2, hostname } from "os";
 import { randomBytes, createCipheriv, createHash as createHash3 } from "crypto";
-import { Wallet } from "ethers";
+import { Wallet as Wallet2 } from "ethers";
 var HANDLE_PATTERN2 = /^[a-z0-9_-]{1,64}$/i;
 var EIP712_DOMAIN = { name: "HoloMesh", version: "1" };
 var EIP712_TYPES = {
@@ -2222,7 +2457,7 @@ async function provisionAgent(req, opts = { execute: false }) {
     };
     return reused;
   }
-  const wallet = Wallet.createRandom();
+  const wallet = Wallet2.createRandom();
   mkdirSync4(seatDir, { recursive: true });
   const masterKey = ensureMasterKey(seatsRoot);
   const encryptedBlob = {
@@ -2445,11 +2680,31 @@ async function cmdRun(opts) {
     dailyBudgetUsd: identity.budgetUsdPerDay,
     pricer: defaultPricerForProvider(effectiveIdentity.llmProvider)
   });
+  const seat = loadSeatWallet(identity.handle);
+  let bearer = identity.x402Bearer;
+  if (!bearer) {
+    if (!seat) {
+      throw new Error(
+        "No HOLOSCRIPT_AGENT_X402_BEARER set and no seat wallet found to resolve it from the HoloKey broker. Provide a bearer, or point at the seat wallet via HOLOSCRIPT_AGENT_SEATS_ROOT + HOLOSCRIPT_AGENT_SEAT_ID (+ HOLOSCRIPT_AGENT_SEAT_MASTER_KEY)."
+      );
+    }
+    bearer = await resolveBearerViaBroker({
+      privateKey: seat.wallet.privateKey,
+      meshApiBase: identity.meshApiBase
+    });
+    console.log(
+      JSON.stringify({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        ev: "bearer-resolved-via-broker",
+        wallet: `${seat.address.slice(0, 6)}\u2026${seat.address.slice(-4)}`
+      })
+    );
+  }
   const mesh = new HolomeshClient({
     apiBase: identity.meshApiBase,
-    bearer: identity.x402Bearer,
+    bearer,
     teamId: identity.teamId,
-    signer: buildRequestSigner(identity.handle)
+    signer: buildRequestSigner(seat)
   });
   const commitHook = buildCommitHook(identity, mesh);
   const auditLog = buildAuditLog();
@@ -2701,10 +2956,19 @@ async function cmdAblate(rest) {
 }
 async function cmdWhoami() {
   const identity = loadIdentity();
+  const seat = loadSeatWallet(identity.handle);
+  let bearer = identity.x402Bearer;
+  if (!bearer && seat) {
+    bearer = await resolveBearerViaBroker({
+      privateKey: seat.wallet.privateKey,
+      meshApiBase: identity.meshApiBase
+    });
+  }
   const mesh = new HolomeshClient({
     apiBase: identity.meshApiBase,
-    bearer: identity.x402Bearer,
-    teamId: identity.teamId
+    bearer,
+    teamId: identity.teamId,
+    signer: buildRequestSigner(seat)
   });
   const me = await mesh.whoAmI();
   console.log(JSON.stringify({ identity: identityForLog(identity), me }, null, 2));
@@ -2763,12 +3027,12 @@ function canonicalizeSigning(value) {
   const obj = value;
   return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonicalizeSigning(obj[k])}`).join(",")}}`;
 }
-function buildRequestSigner(handle) {
+function loadSeatWallet(handle) {
   const seatsRoot = process.env.HOLOSCRIPT_AGENT_SEATS_ROOT ?? join4(homedir3(), ".holoscript-agent", "seats");
   const fp = createHash4("sha256").update(hostname2() + homedir3()).digest("hex").slice(0, 8);
-  const seatId = `holoscript-${handle}-${fp}-x402`;
+  const seatId = process.env.HOLOSCRIPT_AGENT_SEAT_ID ?? `holoscript-${handle}-${fp}-x402`;
   const walletPath = join4(seatsRoot, seatId, "wallet.enc");
-  const masterKeyPath = join4(seatsRoot, ".master-key");
+  const masterKeyPath = process.env.HOLOSCRIPT_AGENT_SEAT_MASTER_KEY ?? join4(seatsRoot, ".master-key");
   if (!existsSync4(walletPath) || !existsSync4(masterKeyPath)) return void 0;
   try {
     const blob = JSON.parse(readFileSync5(walletPath, "utf8"));
@@ -2776,21 +3040,28 @@ function buildRequestSigner(handle) {
     const iv = Buffer.from(blob.encrypted_privkey.iv, "base64");
     const ct = Buffer.from(blob.encrypted_privkey.ct, "base64");
     const tag = Buffer.from(blob.encrypted_privkey.tag, "base64");
-    const decipher = createDecipheriv(blob.encrypted_privkey.alg ?? "aes-256-gcm", masterKey, iv);
+    const decipher = createDecipheriv(
+      blob.encrypted_privkey.alg ?? "aes-256-gcm",
+      masterKey,
+      iv
+    );
     decipher.setAuthTag(tag);
     const privateKey = Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
-    const wallet = new Wallet2(privateKey);
-    return async (body) => {
-      const nonce = randomBytes2(16).toString("hex");
-      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-      const payload = canonicalizeSigning({ body, nonce, timestamp });
-      const signature = await wallet.signMessage(payload);
-      return { body, signature, signer_address: blob.address, nonce, timestamp };
-    };
+    return { wallet: new Wallet3(privateKey), address: blob.address };
   } catch {
     return void 0;
   }
 }
+function buildRequestSigner(seat) {
+  if (!seat) return void 0;
+  return async (body) => {
+    const nonce = randomBytes2(16).toString("hex");
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const payload = canonicalizeSigning({ body, nonce, timestamp });
+    const signature = await seat.wallet.signMessage(payload);
+    return { body, signature, signer_address: seat.address, nonce, timestamp };
+  };
+}
 function scopeTierFromEnv() {
   const t = (process.env.HOLOSCRIPT_AGENT_SCOPE_TIER ?? "warm").toLowerCase();
   if (t === "cold" || t === "warm" || t === "hot") return t;
@@ -2838,11 +3109,17 @@ REQUIRED ENV
   HOLOSCRIPT_AGENT_MODEL             model id (e.g. "claude-opus-4-8")
   HOLOSCRIPT_AGENT_BRAIN             path to .hsplus brain composition
   HOLOSCRIPT_AGENT_WALLET            0x\u2026 wallet address
-  HOLOSCRIPT_AGENT_X402_BEARER       per-surface mesh bearer (W.087 vertex B)
   HOLOMESH_TEAM_ID                   target team id
   ANTHROPIC_API_KEY | OPENAI_API_KEY | GEMINI_API_KEY  per provider
 
 OPTIONAL ENV
+  HOLOSCRIPT_AGENT_X402_BEARER       per-surface mesh bearer. OPTIONAL: when absent, the runner
+                                     resolves it from the HoloKey broker by proving wallet
+                                     ownership (POST /key/challenge \u2192 sign \u2192 /key/recover), so the
+                                     bearer is never stored in plaintext .env. Requires a seat wallet.
+  HOLOSCRIPT_AGENT_SEAT_ID           override the computed seat-dir name (e.g. a sovereign x402 seat
+                                     "sovereign-<surface>-<fp>-default-x402"); pairs with SEATS_ROOT
+  HOLOSCRIPT_AGENT_SEAT_MASTER_KEY   override the master-key path used to decrypt the seat wallet.enc
   HOLOSCRIPT_AGENT_BUDGET_USD_DAY    default 5
   HOLOSCRIPT_AGENT_SCOPE_TIER        cold | warm | hot (default warm)
   HOLOSCRIPT_AGENT_TICK_MS           daemon tick interval, default 60000