fuli-context 0.9.0 → 0.11.0

package/src/agents/codex/lifecycle-hook.js

@@ -26,20 +26,9 @@ export async function codexStopLifecycleOutput(input, invoke) {
   if (check?.decision !== 'block' || typeof check.reason !== 'string' || !check.reason.trim()) {
     return {};
   }
-  if (input.stop_hook_active === true) {
-    if (typeof check.task_context_token === 'string' && check.task_context_token.trim()) {
-      await invoke('checkpoint_task_knowledge', {
-        taskContextToken: check.task_context_token,
-        disposition: 'retain_nothing',
-        reason: 'Codex Stop hook fallback after one checkpoint continuation.',
-        workLog: { status: 'incomplete', summary: 'The host stopped before the employee submitted a work summary. Review the prior task before resuming.' },
-        sourceApplication: 'codex',
-        sourceSessionId: sessionId
-      });
-    }
-    return {};
-  }
-  return { decision: 'block', reason: boundedHookMessage(check.reason) };
+  // Checkpoints are advisory to the host. Never force another model turn or
+  // fabricate a work log merely because the user is ending the conversation.
+  return { systemMessage: boundedHookMessage(check.reason) };
 }
 
 export async function codexLifecycleOutput(event, input, invoke) {
@@ -73,6 +62,9 @@ export async function runCodexLifecycleHook(args, dependencies = {}) {
   );
   let app;
   let leases;
+  let closing;
+  const cleanup = () => closing ??= Promise.allSettled([closeQuietly(leases), closeQuietly(app)]);
+  dependencies.onCleanup?.(cleanup);
   try {
     app = (dependencies.openApplication ?? openFederatedGraphApplication)({
       runtimeConfigPath
@@ -94,32 +86,31 @@ export async function runCodexLifecycleHook(args, dependencies = {}) {
             // Existing guards and all later failures remain fail-closed.
             return { systemMessage: `Fuli: ${sync.reason}. Message submission is allowed; no saved Agent context was loaded or changed.` };
           }
-          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { systemMessage: boundedHookMessage(sync.reason) };
           const entryGuard = sync.status === 'capture_disabled' ? null : guard;
           if (event === 'UserPromptSubmit' && entryGuard?.value) await entryGuard.write({ ...entryGuard.value, phase: 'beginning' });
           const result = await codexLifecycleOutput(event, input, async (name, parameters) => {
-            const context = await invokeTool(app, name, parameters);
+            const context = await invokeTool(app, name, parameters, { signal: dependencies.signal });
             if (name === 'begin_task_context') await recordTranscriptTaskEntry(entryGuard, context);
             return context;
           });
           if (event === 'UserPromptSubmit') sync = await claimTranscriptBoundary(app, input, 'codex', sync, {
             normalize: normalizeCodexRecord, verify: verifyCodexTranscript
           }, entryGuard);
-          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { systemMessage: boundedHookMessage(sync.reason) };
           return withTranscriptNotice(result, sync);
         });
       } catch (error) {
         if (event !== 'UserPromptSubmit' || !app.getCapturePolicy?.().enabled || !input.transcript_path) throw error;
-        return { decision: 'block', reason: error.code === 'EADDRINUSE'
+        return { systemMessage: error.code === 'EADDRINUSE'
           ? 'The session handoff lock is occupied. Retry after the current hook finishes; if it persists, start a new host session and resume the intended Agent.'
           : 'Fuli transcript handoff could not be completed safely. Retry task entry; no previous Agent context was supplied.' };
       }
-    });
+    }, { signal: dependencies.signal });
     write(`${JSON.stringify(output)}\n`);
     return output;
   } finally {
-    await closeQuietly(leases);
-    await closeQuietly(app);
+    await cleanup();
   }
 }
 
@@ -142,13 +133,46 @@ async function readHookInput() {
   return JSON.parse(Buffer.concat(chunks).toString('utf8'));
 }
 
-async function main() {
+export async function runCodexLifecycleCommand(args, dependencies = {}) {
+  const configured = Number(args[args.indexOf('--timeout-ms') + 1]);
+  const timeoutMs = args.includes('--timeout-ms') && Number.isSafeInteger(configured) && configured > 0
+    ? Math.min(configured, 5000) : 5000;
+  const controller = new AbortController();
+  let emitted = false;
+  const write = value => {
+    if (emitted) return;
+    emitted = true;
+    (dependencies.write ?? (value => process.stdout.write(value)))(value);
+  };
+  const unavailable = JSON.stringify({ systemMessage: 'Fuli context is unavailable. Continue with the user request; saved context and checkpoint were not verified.' }) + '\n';
+  let cleanup = async () => {};
+  let deadline;
+  const expired = new Promise(resolve => {
+    deadline = setTimeout(async () => {
+      controller.abort();
+      write(unavailable);
+      // A broken dependency must not hold the host open. Give opened leases
+      // and connections a bounded chance to close before the process exits.
+      let grace;
+      await Promise.race([cleanup(), new Promise(done => { grace = setTimeout(done, 250); })]);
+      clearTimeout(grace);
+      resolve({ timedOut: true });
+    }, timeoutMs);
+  });
   try {
-    await runCodexLifecycleHook(process.argv.slice(2));
-  } catch {
-    // Fail open without printing prompts, transcripts, paths or credentials.
-    process.stdout.write('{}\n');
+    const running = runCodexLifecycleHook(args, { ...dependencies, signal: controller.signal, write,
+      onCleanup: close => { cleanup = close; } }).then(() => ({ timedOut: false }), () => {
+      // Never print prompts, transcripts, paths or credentials.
+      write(unavailable);
+      return { timedOut: false };
+    });
+    return await Promise.race([running, expired]);
+  } finally {
+    clearTimeout(deadline);
   }
 }
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const result = await runCodexLifecycleCommand(process.argv.slice(2));
+  if (result.timedOut) process.exit(0);
+}

package/src/agents/codex/token-usage.js

@@ -0,0 +1,235 @@
+import { constants } from 'node:fs';
+import { lstat, opendir, open } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+
+const MAX_HEADER_BYTES = 64 * 1024;
+const MAX_USAGE_TAIL_BYTES = 4 * 1024 * 1024;
+const MAX_CANDIDATE_FILES = 128;
+const MAX_DIRECTORY_ENTRIES = 2048;
+const MAX_DIRECTORY_DEPTH = 8;
+
+/**
+ * Codex's native JSONL session adapter. It returns only the latest cumulative
+ * token_count snapshot and never returns transcript records or text.
+ */
+export function createCodexTokenUsageResolver({
+  sessionsDirectory = undefined,
+  archivedSessionsDirectory = undefined,
+  codexSessionsDirectory = undefined,
+  codexArchivedSessionsDirectory = undefined,
+  codexHomeDirectory = undefined,
+  homeDirectory = undefined
+} = {}) {
+  const explicitSessionsDirectory = sessionsDirectory ?? codexSessionsDirectory;
+  const explicitArchivedSessionsDirectory =
+    archivedSessionsDirectory ?? codexArchivedSessionsDirectory;
+  const home = typeof homeDirectory === 'string' && homeDirectory
+    ? homeDirectory : defaultHomeDirectory();
+  const codexHome = typeof codexHomeDirectory === 'string' && codexHomeDirectory
+    ? codexHomeDirectory
+    : homeDirectory === undefined ? (defaultCodexHomeDirectory() ?? (home ? join(home, '.codex') : null))
+      : (home ? join(home, '.codex') : null);
+  const useDefaultRoots = explicitSessionsDirectory === undefined &&
+    explicitArchivedSessionsDirectory === undefined;
+  const roots = [
+    explicitSessionsDirectory ?? (useDefaultRoots && codexHome ? join(codexHome, 'sessions') : null),
+    explicitArchivedSessionsDirectory ??
+      (useDefaultRoots && codexHome ? join(codexHome, 'archived_sessions') : null)
+  ]
+    .filter((root, index, values) => typeof root === 'string' && root && values.indexOf(root) === index);
+  return {
+    resolve: (request) => resolveCodexTokenUsage(request, { roots })
+  };
+}
+
+export async function resolveCodexTokenUsage(request = {}, { roots } = {}) {
+  const sessionId = safeSessionId(request.sessionId ?? request.session_id);
+  if (!sessionId) return null;
+  const configuredRoots = Array.isArray(roots) ? roots : roots ? [roots] : null;
+  const directories = (configuredRoots ?? [
+    defaultCodexSessionsDirectory(),
+    defaultCodexArchivedSessionsDirectory()
+  ]).filter((root, index, values) => typeof root === 'string' && root && values.indexOf(root) === index);
+
+  let inspectedEntries = 0;
+  let candidates = 0;
+  for (const root of directories) {
+    const files = await matchingSessionFiles(root, sessionId, {
+      onEntry: () => { inspectedEntries += 1; },
+      get entriesInspected() { return inspectedEntries; },
+      get candidatesFound() { return candidates; },
+      addCandidate: () => { candidates += 1; }
+    });
+    for (const file of files) {
+      const usage = await readSessionUsage(file, sessionId);
+      if (usage) return usage;
+    }
+    if (inspectedEntries >= MAX_DIRECTORY_ENTRIES || candidates >= MAX_CANDIDATE_FILES) break;
+  }
+  return null;
+}
+
+async function matchingSessionFiles(root, sessionId, counters, depth = 0) {
+  if (depth > MAX_DIRECTORY_DEPTH || counters.entriesInspected >= MAX_DIRECTORY_ENTRIES ||
+      counters.candidatesFound >= MAX_CANDIDATE_FILES) return [];
+  let directory;
+  try {
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory()) return [];
+    directory = await opendir(root);
+  } catch {
+    return [];
+  }
+
+  const files = [];
+  try {
+    for await (const entry of directory) {
+      counters.onEntry();
+      if (counters.entriesInspected > MAX_DIRECTORY_ENTRIES ||
+          counters.candidatesFound >= MAX_CANDIDATE_FILES) break;
+      const path = join(root, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...await matchingSessionFiles(path, sessionId, counters, depth + 1));
+        continue;
+      }
+      if (!entry.isFile() || extname(entry.name) !== '.jsonl' ||
+          !basename(entry.name).includes(sessionId)) continue;
+      counters.addCandidate();
+      files.push(path);
+    }
+  } catch {
+    // A session directory can rotate while the host is running. An incomplete
+    // scan is an unavailable snapshot, never a reason to guess another file.
+  } finally {
+    await directory.close().catch(() => {});
+  }
+  return files;
+}
+
+async function readSessionUsage(filePath, sessionId) {
+  let file;
+  try {
+    file = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size <= 0) return null;
+
+    const header = await readBytes(file, Math.min(MAX_HEADER_BYTES, stat.size), 0);
+    const firstLineEnd = header.indexOf(10);
+    if (firstLineEnd < 0 || !isSessionHeader(header.subarray(0, firstLineEnd), sessionId)) {
+      return null;
+    }
+
+    const start = Math.max(0, stat.size - MAX_USAGE_TAIL_BYTES);
+    const tail = await readBytes(file, stat.size - start, start);
+    let firstLine = 0;
+    if (start > 0) {
+      const previous = await readBytes(file, 1, start - 1);
+      if (previous[0] !== 10) {
+        firstLine = tail.indexOf(10) + 1;
+        if (firstLine <= 0) return null;
+      }
+    }
+    return latestTokenUsage(tail.subarray(firstLine));
+  } catch {
+    return null;
+  } finally {
+    await file?.close().catch(() => {});
+  }
+}
+
+async function readBytes(file, length, position) {
+  const buffer = Buffer.allocUnsafe(length);
+  let offset = 0;
+  while (offset < length) {
+    const result = await file.read(buffer, offset, length - offset, position + offset);
+    if (!result.bytesRead) break;
+    offset += result.bytesRead;
+  }
+  return offset === length ? buffer : buffer.subarray(0, offset);
+}
+
+function isSessionHeader(bytes, sessionId) {
+  try {
+    const record = JSON.parse(bytes.toString('utf8'));
+    return record?.type === 'session_meta' && record.payload?.id === sessionId;
+  } catch {
+    return false;
+  }
+}
+
+function latestTokenUsage(bytes) {
+  let latest = null;
+  const text = bytes.toString('utf8');
+  let offset = 0;
+  while (offset < text.length) {
+    const end = text.indexOf('\n', offset);
+    const line = text.slice(offset, end < 0 ? text.length : end).trim();
+    if (line.includes('"token_count"') && line.includes('"total_token_usage"')) {
+      try {
+        const record = JSON.parse(line);
+        const total = record?.payload?.info?.total_token_usage;
+        if (record?.type === 'event_msg' && record.payload?.type === 'token_count') {
+          const totalTokens = nonNegativeInteger(total?.total_tokens);
+          if (totalTokens !== null) {
+            latest = {
+              source: 'host',
+              totalTokens,
+              inputTokens: optionalNonNegativeInteger(total?.input_tokens),
+              outputTokens: optionalNonNegativeInteger(total?.output_tokens),
+              cachedInputTokens: optionalNonNegativeInteger(total?.cached_input_tokens),
+              cacheWriteInputTokens: optionalNonNegativeInteger(total?.cache_write_input_tokens),
+              reasoningOutputTokens: optionalNonNegativeInteger(total?.reasoning_output_tokens)
+            };
+          }
+        }
+      } catch {
+        // Ignore malformed native records and continue to later snapshots.
+      }
+    }
+    if (end < 0) break;
+    offset = end + 1;
+  }
+  return latest;
+}
+
+function optionalNonNegativeInteger(value) {
+  return value === null || value === undefined ? null : nonNegativeInteger(value);
+}
+
+function nonNegativeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function safeSessionId(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  if (!normalized || normalized.length > 256 || normalized.includes('..') ||
+      !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) return null;
+  return normalized;
+}
+
+function defaultCodexSessionsDirectory() {
+  const codexHome = defaultCodexRootDirectory();
+  return codexHome ? join(codexHome, 'sessions') : null;
+}
+
+function defaultCodexArchivedSessionsDirectory() {
+  const codexHome = defaultCodexRootDirectory();
+  return codexHome ? join(codexHome, 'archived_sessions') : null;
+}
+
+function defaultCodexRootDirectory() {
+  const configured = defaultCodexHomeDirectory();
+  if (configured) return configured;
+  const home = defaultHomeDirectory();
+  return home ? join(home, '.codex') : null;
+}
+
+function defaultCodexHomeDirectory() {
+  const value = process.env.CODEX_HOME;
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function defaultHomeDirectory() {
+  return process.env.HOME ?? process.env.USERPROFILE ?? null;
+}

package/src/agents/codex/wake.js

@@ -0,0 +1,47 @@
+import { existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { findFile, firstField, listDirectory } from '../session-log.js';
+
+// Wakes Codex headlessly with a read-only sandbox. Resuming records the exchange in
+// that conversation; Codex refuses while the conversation is open in the app.
+export const codexWake = Object.freeze({
+  id: 'codex',
+
+  resolveCommand({ env, which, platform, fileExists = existsSync }) {
+    if (env.FULI_CODEX_BIN) return env.FULI_CODEX_BIN;
+    const found = which('codex', platform);
+    if (found) return found;
+    if (platform === 'win32') return newestBundledCodex(join(env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'OpenAI', 'Codex', 'bin'));
+    const bundled = platform === 'darwin' ? '/Applications/Codex.app/Contents/Resources/codex' : null;
+    return bundled && fileExists(bundled) ? bundled : null;
+  },
+
+  args({ sessionId, cwd }) {
+    return sessionId
+      ? ['exec', 'resume', '--json', '--skip-git-repo-check', '-c', 'sandbox_mode="read-only"', sessionId, '-']
+      : ['exec', '--json', '--skip-git-repo-check', '--sandbox', 'read-only', '-C', cwd, '-'];
+  },
+
+  // A session resumes only from the directory it started in.
+  sessionDirectory(sessionId, { home, env }) {
+    const file = findFile(join(env.CODEX_HOME || join(home, '.codex'), 'sessions'), `${sessionId}.jsonl`, 4);
+    return file ? firstField(file, (line) => line.type === 'session_meta' ? line.payload?.cwd : null) : null;
+  },
+
+  // `codex exec --json` streams items; the last agent message before turn.completed is the answer.
+  initialState: () => ({ body: '', completed: false, failed: false }),
+  readEvent(event, state) {
+    if (event.type === 'item.completed' && event.item?.type === 'agent_message') state.body = event.item.text ?? '';
+    if (event.type === 'turn.completed') state.completed = true;
+    if (event.type === 'turn.failed' || event.type === 'error') state.failed = true;
+  },
+});
+
+// The Codex app keeps each CLI version in its own folder; the newest is current.
+function newestBundledCodex(root) {
+  const candidates = [join(root, 'codex.exe'), ...listDirectory(root).map((entry) => join(root, entry, 'codex.exe'))]
+    .filter((path) => existsSync(path));
+  return candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0] ?? null;
+}

package/src/agents/cursor/lifecycle-hook.js

@@ -6,7 +6,6 @@ import { callAgentTool } from '../../agent-tools.js';
 import { createRuntimeLeaseClient } from '../../adaptive-runtime/lease-client.js';
 import { openFederatedGraphApplication } from '../../graphiti/federated-application.js';
 import { resolveGraphRuntimeOptions } from '../../graphiti/runtime-config.js';
-import { boundedHookMessage } from '../lifecycle-message.js';
 
 const EVENTS = new Set(['sessionStart', 'beforeSubmitPrompt', 'stop']);
 
@@ -18,14 +17,9 @@ export async function cursorLifecycleOutput(event, input, invoke) {
   }
   const source = { sourceApplication: 'cursor', sourceSessionId: sessionId };
   if (event === 'stop') {
-    // One host-counted continuation at most; never restart cancelled/error turns.
-    if (input.status !== 'completed' || (input.loop_count ?? 0) >= 1) return {};
-    const check = await invoke('verify_task_checkpoint', { sessionId, ...source });
-    const notice = '\nIf this mode is read-only or checkpoint writes are denied, state that the checkpoint was not saved and do not retry. This is the only checkpoint continuation.';
-    const reason = boundedHookMessage(check.reason, { maxBytes: 8_000 - Buffer.byteLength(notice, 'utf8') });
-    return check.status === 'checkpoint_required' && reason.trim()
-      ? { followup_message: reason + notice }
-      : {};
+    // Cursor has no advisory Stop output. A followup_message would start
+    // another model turn, so pending checkpoints remain available through MCP.
+    return {};
   }
   const roots = input.workspace_roots;
   if (!Array.isArray(roots) || roots.length !== 1 || typeof roots[0] !== 'string') {

package/src/agents/identity-receipt.js

@@ -12,20 +12,30 @@ export function agentContinuation(projectId, agentId, conversationId = null) {
     guidance: 'Use a connected client and the same authorized project/Agent. Obtain a fresh task context; never reuse the previous client’s token. This is a FULI prompt, not a native client @ picker registration.' };
 }
 
-export function taskAgentReceipt(application, { projectId, agentId, name = null,
-  sourceApplication = null, workStatus = null, conversationId = null, persistence = null }) {
-  const owner = agentId ? { agent_id: agentId, name,
-    profile_url: agentProfileUrl(application, agentId), source_application: sourceApplication } : null;
+function agentLink(application, agentId, name) {
   const label = String(name?.trim() || agentId).replace(/[\r\n\t]+/g, ' ')
     .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
     .replace(/[\\`*_{}\[\]()!|]/g, '\\$&');
+  return `[${label}](<${agentProfileUrl(application, agentId).replace(/[<>\s]/g, encodeURIComponent)}>)`;
+}
+
+// The reply's attribution line: who led the task and who actually helped.
+export function taskAgentReceipt(application, { projectId, agentId, name = null,
+  sourceApplication = null, workStatus = null, conversationId = null, persistence = null,
+  collaborators = [] }) {
+  const owner = agentId ? { agent_id: agentId, name,
+    profile_url: agentProfileUrl(application, agentId), source_application: sourceApplication } : null;
+  const helpers = owner ? collaborators.filter(item => item.agentId !== agentId) : [];
   const markdown = owner
-    ? `FULI Agent：[${label}](<${owner.profile_url.replace(/[<>\s]/g, encodeURIComponent)}>)`
+    ? `FULI Agent：负责人 ${agentLink(application, agentId, name)}`
+      + (helpers.length ? ` · 协作 ${helpers.map(item => agentLink(application, item.agentId, item.name)).join('、')}` : '')
     : 'FULI Agent：未选定';
   return { required: true, markdown, owner,
+    collaborators: helpers.map(item => ({ agent_id: item.agentId, name: item.name,
+      profile_url: agentProfileUrl(application, item.agentId) })),
     personal_project_id: projectId, work_status: workStatus, persistence,
     continuation: owner ? agentContinuation(projectId, agentId, conversationId) : null,
-    guidance: 'MUST include agent_receipt.markdown unchanged exactly once in every final user-visible reply, including greetings, status and errors, even when capture is disabled or nothing is retained. Use this task’s receipt; never invent an owner. Report only truthful work/memory status and actually used collaboration_receipt participants; tools and configured peers are not independent model workers.' };
+    guidance: 'MUST end every final user-visible reply with agent_receipt.markdown unchanged, exactly once, including greetings, status and errors, even when capture is disabled or nothing is retained. The receipt returned by checkpoint_task_knowledge supersedes the entry receipt because it names actual collaborators. Never invent an owner or a collaborator.' };
 }
 
 export function employeeCollaborationReceipt(application, context, { tool, permission, sourceApplication }) {

package/src/agents/session-log.js

@@ -0,0 +1,34 @@
+import { closeSync, openSync, readSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Read-only helpers for locating a client's JSONL session log on disk.
+
+export function listDirectory(directory) {
+  try { return readdirSync(directory); } catch { return []; }
+}
+
+// Newest-first search for a file ending in `suffix`, at most `depth` levels down.
+export function findFile(directory, suffix, depth) {
+  for (const entry of listDirectory(directory).sort().reverse()) {
+    const path = join(directory, entry);
+    if (entry.endsWith(suffix)) return path;
+    if (depth > 0 && !entry.includes('.')) {
+      const found = findFile(path, suffix, depth - 1);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+// The first non-empty string `pick` returns for a JSON line near the start of the log.
+export function firstField(file, pick) {
+  const handle = openSync(file, 'r');
+  try {
+    const buffer = Buffer.alloc(256 * 1024);
+    const length = readSync(handle, buffer, 0, buffer.length, 0);
+    for (const line of buffer.subarray(0, length).toString('utf8').split('\n')) {
+      try { const value = pick(JSON.parse(line)); if (typeof value === 'string' && value) return value; } catch { /* partial line */ }
+    }
+    return null;
+  } finally { closeSync(handle); }
+}

package/src/agents/token-usage-resolver.js

@@ -0,0 +1,147 @@
+import { createCodexTokenUsageResolver } from './codex/token-usage.js';
+
+const TOKEN_USAGE_SOURCES = new Set(['executor', 'host', 'dingdong']);
+const DEFAULT_RESOLVER = createAgentTokenUsageResolver();
+
+/**
+ * Resolve one exact worker/session identity through the runtime adapter port.
+ *
+ * A worker runtime is authoritative when present. Its session is never
+ * replaced with the reporting host session. A reporting host session is used
+ * only when no worker runtime was supplied, which covers direct host activity.
+ */
+export function resolveAgentSession(input = {}) {
+  const workerRuntime = input.workerRuntime ?? input.worker_runtime;
+  if (workerRuntime !== undefined && workerRuntime !== null) {
+    if (!workerRuntime || typeof workerRuntime !== 'object' || Array.isArray(workerRuntime)) {
+      return null;
+    }
+    const application = workerRuntime.application;
+    const sessionId = safeSessionId(workerRuntime.sessionId ?? workerRuntime.session_id);
+    if (!validApplication(application) || !sessionId) return null;
+    return {
+      application,
+      sessionId,
+      sourceApplication: input.sourceApplication ?? input.source_application ?? null,
+      sourceSessionId: input.sourceSessionId ?? input.source_session_id ?? null,
+      scope: 'worker'
+    };
+  }
+
+  if (hasWorkerMetadata(input)) return null;
+  const application = input.sourceApplication ?? input.source_application;
+  const sessionId = safeSessionId(input.sourceSessionId ?? input.source_session_id);
+  if (!validApplication(application) || !sessionId) return null;
+  return {
+    application,
+    sessionId,
+    sourceApplication: application,
+    sourceSessionId: sessionId,
+    scope: 'host'
+  };
+}
+
+/**
+ * Shared adapter port for exact session token usage.
+ *
+ * Adapters receive only the selected session identity and return a cumulative
+ * snapshot or null. They must not return transcript content.
+ */
+export function createAgentTokenUsageResolver({ adapters } = {}) {
+  const registry = adapters instanceof Map
+    ? adapters
+    : new Map(Object.entries(adapters ?? {
+      codex: createCodexTokenUsageResolver()
+    }));
+  return {
+    async resolve(input = {}) {
+      const session = resolveAgentSession(input);
+      if (!session) return null;
+      const adapter = registry.get(session.application);
+      const resolve = typeof adapter === 'function' ? adapter : adapter?.resolve;
+      if (typeof resolve !== 'function') return null;
+      try {
+        return normalizeTokenUsage(await resolve.call(adapter, session));
+      } catch {
+        // Usage collection is best-effort. It must not prevent the host from
+        // recording otherwise valid worker activity.
+        return null;
+      }
+    }
+  };
+}
+
+export async function enrichProjectAgentTaskActivity(input = {}, resolver = DEFAULT_RESOLVER) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return input;
+  const actorKind = input.actorKind ?? input.actor_kind;
+  if (actorKind === 'human') return input;
+  // Null is an explicit report (including an explicit zero inside the object),
+  // so only an omitted value is eligible for automatic collection.
+  const explicitTokenUsage = (Object.hasOwn(input, 'tokenUsage') && input.tokenUsage !== undefined) ||
+    (Object.hasOwn(input, 'token_usage') && input.token_usage !== undefined);
+  if (explicitTokenUsage) return input;
+
+  const resolve = typeof resolver === 'function' ? resolver : resolver?.resolve;
+  if (typeof resolve !== 'function') return input;
+  try {
+    const tokenUsage = normalizeTokenUsage(await resolve.call(resolver, input));
+    return tokenUsage ? { ...input, tokenUsage } : input;
+  } catch {
+    return input;
+  }
+}
+
+export async function resolveProjectAgentTaskActivityTokenUsage(input, resolver = DEFAULT_RESOLVER) {
+  const enriched = await enrichProjectAgentTaskActivity(input, resolver);
+  if (!enriched || typeof enriched !== 'object') return null;
+  return enriched.tokenUsage !== undefined ? enriched.tokenUsage : enriched.token_usage ?? null;
+}
+
+function normalizeTokenUsage(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const source = value.source;
+  const totalTokens = nonNegativeInteger(value.totalTokens ?? value.total_tokens);
+  if (!TOKEN_USAGE_SOURCES.has(source) || totalTokens === null) return null;
+  return {
+    source,
+    totalTokens,
+    inputTokens: optionalNonNegativeInteger(value.inputTokens ?? value.input_tokens),
+    outputTokens: optionalNonNegativeInteger(value.outputTokens ?? value.output_tokens),
+    cachedInputTokens: optionalNonNegativeInteger(value.cachedInputTokens ?? value.cached_input_tokens),
+    cacheWriteInputTokens: optionalNonNegativeInteger(
+      value.cacheWriteInputTokens ?? value.cache_write_input_tokens
+    ),
+    reasoningOutputTokens: optionalNonNegativeInteger(
+      value.reasoningOutputTokens ?? value.reasoning_output_tokens
+    )
+  };
+}
+
+function optionalNonNegativeInteger(value) {
+  return value === null || value === undefined ? null : nonNegativeInteger(value);
+}
+
+function nonNegativeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function validApplication(value) {
+  return typeof value === 'string' && value.length > 0 && value.length <= 64;
+}
+
+function hasWorkerMetadata(input) {
+  return [
+    input.workerId ?? input.worker_id,
+    input.workerLabel ?? input.worker_label,
+    input.workerStatus ?? input.worker_status,
+    input.workerOccupationEmoji ?? input.worker_occupation_emoji
+  ].some((value) => value !== undefined && value !== null && value !== '');
+}
+
+function safeSessionId(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim();
+  if (!normalized || normalized.length > 256 || normalized.includes('..') ||
+      !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(normalized)) return null;
+  return normalized;
+}

package/src/agents/wake-registry.js

@@ -0,0 +1,14 @@
+import { claudeCodeWake } from './claude-code/wake.js';
+import { codexWake } from './codex/wake.js';
+
+// Clients that can be woken headlessly to answer another Agent, in preference order.
+export const WAKE_ADAPTERS = Object.freeze({
+  [claudeCodeWake.id]: claudeCodeWake,
+  [codexWake.id]: codexWake,
+});
+
+export const WAKE_CLIENTS = Object.freeze(Object.keys(WAKE_ADAPTERS));
+
+export function wakeAdapter(client) {
+  return Object.hasOwn(WAKE_ADAPTERS, client) ? WAKE_ADAPTERS[client] : null;
+}