@halofy/agent-connect 0.5.1 → 0.7.0

package/README.md

@@ -25,7 +25,7 @@ bounded recall block formats stay in place and tested for when it returns.
 There is one setup path for every packaged client:
 
 ```bash
-npx --yes @halofy/agent-connect@0.5.1 install <client-kind> \
+npx --yes @halofy/agent-connect@0.6.0 install <client-kind> \
   --server https://app.halofy.ai \
   --claim '<one-time-claim>'
 ```
@@ -81,6 +81,20 @@ represented by digest-only placeholders and make coverage partial;
 encrypted retry queue, and real-host fixtures are verified. The adapter never
 opens an arbitrary transcript-referenced local file to fill that gap.
 
+Since 0.6.0, reviewed transcript drivers extend host-reported token usage and
+content-free session metadata to Codex CLI (rollout files) and Kimi Code CLI
+(session wire files). The same containment commitment applies: a driver never
+opens a hook-supplied path. It derives the session file from a validated
+session id (`[A-Za-z0-9_-]{1,128}`) under the host's own root
+(`CODEX_HOME`/`~/.codex`, `KIMI_CODE_HOME`/`~/.kimi-code`), and every
+index-supplied or cached path must realpath-resolve inside that root or the
+read is skipped. Capture additionally requires the installation's frozen
+`tokenUsage` capability — installations consented before 0.6.0 never have
+their transcripts read until reinstalled under the current disclosure. A
+single `install all --claims <kind>=<claim>,…` invocation sweeps the claimed,
+detected hosts with one CONNECT covering the explicitly listed set; each host
+keeps its own installation, capabilities, and status.
+
 Run focused checks from this directory:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halofy/agent-connect",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Halofy lifecycle installer and runtime for supported agents; runtime requests are signed with a per-installation Ed25519 key",
   "bin": {
@@ -24,7 +24,7 @@
   },
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "check": "node --check src/*.mjs && node --check bin/*.mjs",
+    "check": "node --check src/*.mjs && node --check src/transcript-drivers/*.mjs && node --check bin/*.mjs",
     "prepack": "npm run check && npm test"
   },
   "engines": {

package/src/claude-hook.mjs

@@ -3,6 +3,25 @@ import { basename } from "node:path";
 import { LifecycleRuntime } from "./runtime.mjs";
 import { normalizeClaudeHookEvent, RECALL_INJECTION_ENABLED, rankedRecallBlocks } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
+import { describeSkillSync, syncManagedSkills } from "./skills-sync.mjs";
+
+/**
+ * Badge skills ride the SessionStart heartbeat (D37): check in, repair, and
+ * quarantine, but never let a skills problem degrade memory recall.
+ */
+export async function syncSkillsAtSessionStart(runtime, connection, root, stderr) {
+  try {
+    const summary = await syncManagedSkills({ connection, transport: runtime.transport, root });
+    if (summary.supported && (summary.installed.length || summary.updated.length ||
+        summary.quarantined.length || summary.errors.length)) {
+      stderr.write(`[halofy] ${describeSkillSync(summary)}\n`);
+    }
+    return summary;
+  } catch (error) {
+    stderr.write(`[halofy] skill sync degraded: ${error?.code || "runtime_unavailable"}\n`);
+    return null;
+  }
+}
 
 function id(value) {
   return createHash("sha256").update(String(value)).digest("hex");
@@ -86,6 +105,7 @@ export async function runClaudeLifecycleHook(connection, eventName, {
     if (eventName === "SessionStart") {
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
+      await syncSkillsAtSessionStart(runtime, connection, root, stderr);
       if (RECALL_INJECTION_ENABLED) {
         const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
         const recalled = await runtime.recall(

package/src/client-registry.mjs

@@ -58,8 +58,9 @@ export const CLIENT_REGISTRY = Object.freeze({
       subagents: true, compactionCheckpoints: true, contextRecalled: true,
       // 0.5.0: host-reported model token usage, thinking blocks, structured
       // tool outcomes, and content-free session metadata from the native
-      // transcript. Claude Code is the only host whose reviewed adapter
-      // reads these today.
+      // transcript. Since 0.6.0 codex and kimi-cli also report usage and
+      // metadata via their reviewed transcript drivers; thinking blocks and
+      // structured tool outcomes remain Claude Code-only.
       tokenUsage: true, sessionMetadata: true, toolOutcomes: true,
       thinking: true,
     }),
@@ -104,6 +105,9 @@ export const CLIENT_REGISTRY = Object.freeze({
       toolInputs: true, toolOutputs: true, toolFailures: true,
       artifactReferences: true, subagents: true, compactionCheckpoints: true,
       contextRecalled: true,
+      // 0.6.0: host-reported usage and content-free session metadata read
+      // from the session wire by the reviewed kimi transcript driver.
+      tokenUsage: true, sessionMetadata: true,
     }),
   }),
   vscode: Object.freeze({
@@ -131,6 +135,9 @@ export const CLIENT_REGISTRY = Object.freeze({
       subagentStart: true, subagentStop: true, postToolUse: true,
       userMessages: true, toolInputs: true, toolOutputs: true, subagents: true,
       compactionCheckpoints: true, contextRecalled: true,
+      // 0.6.0: host-reported usage and content-free session metadata read
+      // from the native rollout by the reviewed codex transcript driver.
+      tokenUsage: true, sessionMetadata: true,
     }),
   }),
   cline: Object.freeze({

package/src/host-config.mjs

@@ -2,6 +2,7 @@ import { chmod, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { readJson, writeHostConfigFile } from "./storage.mjs";
+import { codexHome, kimiHome } from "./host-roots.mjs";
 
 function commandArg(value) {
   const text = String(value);
@@ -172,7 +173,7 @@ export async function configureKimi({
   installationId,
   nodePath = process.execPath,
   runtimePath,
-  kimiRoot = process.env.KIMI_CODE_HOME || join(homedir(), ".kimi-code"),
+  kimiRoot = kimiHome(),
 }) {
   validateInputs({ installationId, runtimePath });
   const configPath = join(kimiRoot, "config.toml");
@@ -292,7 +293,7 @@ export async function configureCodex({
   installationId,
   nodePath = process.execPath,
   runtimePath,
-  codexRoot = process.env.CODEX_HOME || join(homedir(), ".codex"),
+  codexRoot = codexHome(),
 }) {
   validateInputs({ installationId, runtimePath });
   const hooksPath = join(codexRoot, "hooks.json");

package/src/host-hook.mjs

@@ -8,7 +8,8 @@ import {
   rankedRecallBlocks,
 } from "./session.mjs";
 import { defaultRuntimeDirectory } from "./storage.mjs";
-import { readHookInput } from "./claude-hook.mjs";
+import { readHookInput, syncSkillsAtSessionStart } from "./claude-hook.mjs";
+import { transcriptDriverFor } from "./transcript-drivers/index.mjs";
 
 const USER_EVENTS = new Set(["UserPromptSubmit", "beforeSubmitPrompt", "BeforeAgent", "pre_llm_call"]);
 const ASSISTANT_EVENTS = new Set(["afterAgentResponse", "AfterAgent", "post_llm_call", "transform_llm_output"]);
@@ -116,6 +117,29 @@ async function enqueueTool(runtime, session, eventName, input) {
   ]);
 }
 
+/**
+ * Best-effort transcript catch-up for hosts with a reviewed driver. Consent
+ * is double-gated: the driver must exist for this client kind AND the
+ * install-time frozen capability snapshot must declare tokenUsage — an older
+ * installation never has its transcript read, even under an upgraded runtime.
+ * Failures are swallowed: capture evidence must never degrade the hook path.
+ */
+async function catchUpHost(runtime, connection, session, sessionFacts = {}) {
+  try {
+    if (connection.capabilities?.tokenUsage !== true) return;
+    const driver = transcriptDriverFor(connection.clientKind);
+    if (driver === null) return;
+    const located = await driver.locate(session, {});
+    if (located === null) return;
+    await runtime.captureHostTranscript(session, driver, located.path, {
+      ...(located.sessionFacts ?? {}),
+      ...sessionFacts,
+    });
+  } catch {
+    // Transcript evidence is additive; the hook result stands without it.
+  }
+}
+
 /** Runs one reviewed host hook without blocking the host when Halofy browns out. */
 export async function runHostLifecycleHook(connection, eventName, {
   input,
@@ -134,6 +158,7 @@ export async function runHostLifecycleHook(connection, eventName, {
     if (START_EVENTS.has(eventName)) {
       await runtime.replay();
       await runtime.heartbeat(connection.capabilities || {});
+      await syncSkillsAtSessionStart(runtime, connection, root, stderr);
       if (RECALL_INJECTION_ENABLED) {
         const project = hookInput.cwd ? basename(String(hookInput.cwd)) : "";
         const recalled = await runtime.recall(session,
@@ -142,8 +167,10 @@ export async function runHostLifecycleHook(connection, eventName, {
         if (output) stdout.write(output);
       }
     } else if (USER_EVENTS.has(eventName)) {
-      // Prompt capture is independent of recall: non-Claude hosts have no
-      // transcript, so this enqueue is how user messages reach the archive.
+      // Prompt capture is independent of recall: hosts without a reviewed
+      // transcript driver rely on this enqueue to reach the archive, and
+      // hook-sourced events stay authoritative for messages even where a
+      // driver adds usage/metadata evidence.
       const prompt = promptText(hookInput);
       await enqueueMessage(runtime, connection, session, "user", prompt, eventName, hookInput);
       if (RECALL_INJECTION_ENABLED && connection.clientKind !== "cursor" &&
@@ -157,6 +184,7 @@ export async function runHostLifecycleHook(connection, eventName, {
       await runtime.commitIfThreshold(session);
     } else if (TOOL_EVENTS.has(eventName)) {
       await enqueueTool(runtime, session, eventName, hookInput);
+      await catchUpHost(runtime, connection, session);
     } else if (COMPACT_EVENTS.has(eventName)) {
       await runtime.enqueueSequencedEvents(session, ({ sessionHash, nextSequence }) => [
         normalizeClaudeHookEvent("compaction", {
@@ -164,14 +192,20 @@ export async function runHostLifecycleHook(connection, eventName, {
           event_id: eventEvidenceId(eventName, hookInput),
         }, { sessionHash, sequence: nextSequence }),
       ]);
+      await catchUpHost(runtime, connection, session);
       await runtime.commit(session, "pre_compaction");
     } else if (SUBAGENT_START_EVENTS.has(eventName)) {
       await runtime.resolveSession(childSession(hookInput, session), session);
     } else if (SUBAGENT_STOP_EVENTS.has(eventName)) {
+      // Subagent transcript files are a documented per-host limitation; the
+      // parent session still catches up so its usage stays current.
+      await within(10_000, () => catchUpHost(runtime, connection, session));
       await within(10_000, () => runtime.close(childSession(hookInput, session), "session_end"));
     } else if (END_EVENTS.has(eventName)) {
+      await within(10_000, () => catchUpHost(runtime, connection, session, { closeReason: "session_end" }));
       await within(15_000, () => runtime.close(session));
     } else if (STOP_EVENTS.has(eventName)) {
+      await within(10_000, () => catchUpHost(runtime, connection, session));
       if (connection.clientKind === "vscode" || connection.clientKind === "cline") {
         await within(15_000, () => runtime.close(session));
       } else {

package/src/host-roots.mjs

@@ -0,0 +1,13 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Single authority for each host's on-disk root. host-config.mjs (hook/MCP
+// installation) and transcript-drivers/ (session-file location) must agree on
+// these paths or capture silently reads the wrong tree.
+export function codexHome(env = process.env) {
+  return env.CODEX_HOME || join(homedir(), ".codex");
+}
+
+export function kimiHome(env = process.env) {
+  return env.KIMI_CODE_HOME || join(homedir(), ".kimi-code");
+}

package/src/install.mjs

@@ -7,6 +7,7 @@ import { ConnectionStore, defaultRuntimeDirectory, ensurePrivateDirectory, readJ
 import { SignedRuntimeTransport } from "./transport.mjs";
 import { INSTALLER_VERSION, RUNTIME_VERSION } from "./version.mjs";
 import { CLIENT_KINDS, CLIENT_REGISTRY, lifecycleClient } from "./client-registry.mjs";
+import { syncManagedSkills } from "./skills-sync.mjs";
 
 export const CLAUDE_CAPABILITIES = CLIENT_REGISTRY["claude-code"].capabilities;
 
@@ -61,6 +62,54 @@ export async function fetchClaimDisclosure({
   }
 }
 
+/**
+ * Batch pre-consumption disclosure for the install-all sweep. One POST — and
+ * therefore one throttle token — covers every claim in the command, so a full
+ * sweep (1 disclosure + N consumes) fits the per-address budget. Entries come
+ * back positionally; an unusable claim is null. Any failure yields null for
+ * the whole batch (older server), never an error.
+ */
+export async function fetchClaimDisclosures({
+  serverUrl,
+  claims,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 5_000,
+}) {
+  try {
+    const normalizedServerUrl = normalizeLifecycleServerUrl(serverUrl);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+      response = await fetchImpl(`${normalizedServerUrl}/v1/agent-installations/claim-info`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ claims }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (!response.ok) return null;
+    const body = await response.json();
+    if (!Array.isArray(body?.disclosures)) return null;
+    return claims.map((_, index) => {
+      const entry = body.disclosures[index];
+      if (entry === null || typeof entry !== "object") return null;
+      // Server-supplied text is printed to a terminal: strip control
+      // characters (including ANSI escape introducers) and bound the length.
+      const organization = typeof entry.organization === "string"
+        ? entry.organization.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, 100)
+        : "";
+      const clientKind = typeof entry.clientKind === "string" &&
+        /^[a-z0-9][a-z0-9-]{0,63}$/.test(entry.clientKind) ? entry.clientKind : null;
+      return organization ? { organization, clientKind } : null;
+    });
+  } catch {
+    return null;
+  }
+}
+
 export async function consumeInstallationClaim({
   serverUrl,
   claim,
@@ -211,6 +260,28 @@ export async function heartbeatInstalledConnection({
   return true;
 }
 
+/**
+ * Install-time skill delivery: the moment the badge is bound, the approved
+ * team + org skills land in the host's skills folder (D37/D38). Returns the
+ * content-free sync summary; never throws for a server or skill problem.
+ */
+export async function syncInstalledSkills({
+  installationId,
+  root = defaultRuntimeDirectory(),
+  fetchImpl = globalThis.fetch,
+  home,
+  env,
+}) {
+  const connection = await new ConnectionStore(root).load(installationId);
+  return syncManagedSkills({
+    connection,
+    transport: new SignedRuntimeTransport(connection, { fetchImpl }),
+    root,
+    ...(home ? { home } : {}),
+    ...(env ? { env } : {}),
+  });
+}
+
 export function localMcpSnippet({ nodePath = process.execPath, proxyPath, installationId }) {
   return {
     mcpServers: {