fuli-context 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fuli-context",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Local-first collaboration relationship graph for AI agents.",
   "type": "module",
   "files": [
@@ -14,9 +14,7 @@
     "docs/agent-conversations-and-collaboration.md",
     "docs/employee-agents.md",
     "docs/agent-interface-architecture.md",
-    "docs/roundtable-beta-testing.md",
-    "docs/roundtable-beta-validation.md",
-    "docs/roundtable-research.md",
+    "docs/roundtable.md",
     "examples/external-knowledge/markdown-folder.mjs",
     "graph-provider/Dockerfile",
     "graph-provider/pyproject.toml",

package/skills/capturing-session-knowledge/SKILL.md

@@ -288,7 +288,7 @@ worker session (`workerRuntime.sessionId`, or a worker session link only when su
 Label `sourceApplication` and `sourceSessionId` separately as the reporting host. They do not
 identify an external worker; do not substitute them for missing worker evidence.
 Use only the source-labelled cumulative `tokenUsage` reported for that worker. If it is absent,
-show `not reported`; never estimate it or copy a conversation-wide total into a worker row. If no
+show `-`; never estimate it or copy a conversation-wide total into a worker row. If no
 worker session link exists, show `workerRuntime.sessionId` or `not reported`; never invent a link. This applies only
 to Provider-reported actual workers. When empty `executionSummary` is returned, omit rows; an absent
 `executionSummary` also omits rows. Configured, allowed, or available clients/executors are not evidence

package/src/agents/claude-code/lifecycle-hook.js

@@ -37,19 +37,7 @@ export async function claudeLifecycleOutput(event, input, invoke) {
   const check = await invoke('verify_task_checkpoint', { sessionId, ...source });
   const reason = boundedHookMessage(check?.reason);
   if (check?.decision !== 'block' || !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: 'Claude Code 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.' },
-        ...source
-      });
-    }
-    return {};
-  }
-  return { decision: 'block', reason };
+  return { systemMessage: reason };
 }
 
 export function claudeLifecycleUnavailable(event) {
@@ -80,7 +68,7 @@ export async function runClaudeLifecycleHook(args, dependencies = {}) {
           let sync = await syncConversationTranscript(app, input, 'claude_code', {
             normalize: normalizeClaudeRecord, verify: verifyClaudeTranscript
           }, guard);
-          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 output = await claudeLifecycleOutput(event, input, async (name, parameters) => {
@@ -91,12 +79,12 @@ export async function runClaudeLifecycleHook(args, dependencies = {}) {
           if (event === 'UserPromptSubmit') sync = await claimTranscriptBoundary(app, input, 'claude_code', sync, {
             normalize: normalizeClaudeRecord, verify: verifyClaudeTranscript
           }, entryGuard);
-          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { systemMessage: boundedHookMessage(sync.reason) };
           return withTranscriptNotice(output, 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.' };
       }
@@ -127,7 +115,6 @@ async function main() {
     ? configured : 28000;
   const controller = new AbortController();
   let emitted = false;
-  let guarded = false;
   const emit = (output, callback) => {
     if (emitted) return;
     emitted = true;
@@ -137,11 +124,11 @@ async function main() {
   // No prompt, transcript, path or raw exception is written to diagnostics.
   const deadline = setTimeout(() => {
     controller.abort();
-    emit(guarded && event === 'UserPromptSubmit' ? { decision: 'block', reason: 'Fuli transcript handoff timed out. Retry task entry; the previous Agent context was not supplied.' } : claudeLifecycleUnavailable(event), () => process.exit(0));
+    emit(claudeLifecycleUnavailable(event), () => process.exit(0));
   }, timeoutMs);
   const abort = setTimeout(() => controller.abort(), Math.max(1, timeoutMs - 1500));
   try {
-    const output = await runClaudeLifecycleHook(args, { signal: controller.signal, onTranscriptGuard: () => { guarded = true; } });
+    const output = await runClaudeLifecycleHook(args, { signal: controller.signal });
     emit(output);
   } catch {
     emit(claudeLifecycleUnavailable(event));

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/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/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/graphiti/federated-application.js

@@ -92,6 +92,7 @@ export function openFederatedGraphApplication({
   config,
   capturePolicyStore,
   agentAccessPolicyStore,
+  tokenUsageResolver,
   fetchImpl = globalThis.fetch,
   env = process.env
 }) {
@@ -105,6 +106,7 @@ export function openFederatedGraphApplication({
     agentAccessPolicyStore: agentAccessPolicyStore ?? new AgentAccessPolicyStore(
       agentAccessPolicyPathForRuntime(runtimeConfigPath)
     ),
+    tokenUsageResolver,
     consoleUrl: sourceConsoleUrl(runtimeConfigPath),
     providerRequestTimeoutMs: providerRequestTimeoutFromEnv(env)
   });
@@ -140,7 +142,8 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     consoleUrl = sourceConsoleUrl(null),
     projectPathResolver = resolvePersonalProjectPath,
     taskContextRegistry = null,
-    providerRequestTimeoutMs = undefined
+    providerRequestTimeoutMs = undefined,
+    tokenUsageResolver = undefined
   } = {}) {
     super();
     this.graphiti = true;
@@ -149,6 +152,7 @@ export class FederatedGraphApplication extends ProjectAgentControlPlaneApplicati
     this.agentAccessPolicyStore = agentAccessPolicyStore;
     this.consoleUrl = consoleUrl;
     this.projectPathResolver = projectPathResolver;
+    this.tokenUsageResolver = tokenUsageResolver;
     this.personal = new GraphitiProviderClient({
       baseUrl: config.personal.providerUrl,
       accessToken: config.personal.accessToken,

package/src/graphiti/project-agent-mapping.js

@@ -380,7 +380,7 @@ export function providerProjectAgentTaskActivity(input) {
   }
   if (hasAny(input, ['tokenUsage', 'token_usage'])) {
     result.token_usage = providerProjectAgentTokenUsage(
-      input.tokenUsage ?? input.token_usage
+      input.tokenUsage !== undefined ? input.tokenUsage : input.token_usage
     );
   }
   if (hasAny(input, ['workerRuntime', 'worker_runtime'])) {