@h1v35/hivex 0.2.0 → 0.2.2

package/src/model/server.ts

@@ -1,5 +1,4 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { setTimeout as delay } from 'node:timers/promises';
 import { AppServerConnection } from './connection.ts';
 import { ServerAdmissionFailure } from './failure.ts';
 import {
@@ -10,165 +9,235 @@ import {
   requestedPolicyHash,
 } from './profile.ts';
 
-function signalGroup(pid: number, signal: NodeJS.Signals | 0) {
+const signalGroup = (pid: number, signal: Parameters<typeof process.kill>[1]) => {
   try {
     process.kill(-pid, signal);
     return true;
   } catch (error) {
-    if (error instanceof Error && 'code' in error && error.code === 'ESRCH') return false;
-    if (signal === 0 && error instanceof Error && 'code' in error && error.code === 'EPERM')
+    if (Error.isError(error) && 'code' in error && error.code === 'ESRCH') {
+      return false;
+    }
+    if (signal === 0 && Error.isError(error) && 'code' in error && error.code === 'EPERM') {
       return true;
+    }
     throw error;
   }
-}
+};
 
-function onlyTerminatedMembersRemain(pid: number) {
-  if (process.platform !== 'linux') return false;
+const areOnlyTerminatedMembersRemaining = (pid: number) => {
+  if (process.platform !== 'linux') {
+    return false;
+  }
   const result = spawnSync('/bin/ps', ['-e', '-o', 'pgid=,stat='], {
-    encoding: 'utf8',
-    timeout: 1000,
+    encoding: 'utf-8',
+    env: Object.fromEntries([...Object.entries(nativeEnvironment()), ['LC_ALL', 'C']]),
     maxBuffer: 1_048_576,
-    env: { ...nativeEnvironment(), LC_ALL: 'C' },
+    timeout: 1000,
   });
-  if (result.status !== 0) return false;
+  if (result.status !== 0) {
+    return false;
+  }
   const rows = result.stdout.trim().split('\n');
-  if (rows.some((row) => !/^\s*\d+\s+\S+\s*$/.test(row))) return false;
+  if (rows.some((row) => !/^\s*\d+\s+\S+\s*$/u.test(row))) {
+    return false;
+  }
   const members = rows
-    .map((row) => row.trim().split(/\s+/))
+    .map((row) => row.trim().split(/\s+/u))
     .filter(([group]) => Number(group) === pid);
-  if (!members.length) return !signalGroup(pid, 0);
+  if (members.length === 0) {
+    return !signalGroup(pid, 0);
+  }
   // Container init may retain orphan zombies; they cannot execute or receive signals.
-  return members.every(([, state]) => state?.startsWith('Z') || state?.startsWith('X'));
-}
+  return members.every(
+    ([, state]) => state?.startsWith('Z') === true || state?.startsWith('X') === true
+  );
+};
 
-async function groupTerminated(pid: number) {
+const areGroupMembersTerminated = async (pid: number) => {
   const deadline = performance.now() + 2000;
-  while (signalGroup(pid, 0)) {
-    if (performance.now() >= deadline) return onlyTerminatedMembersRemain(pid);
-    await delay(25);
-  }
+  const result = Promise.withResolvers<boolean>();
+  const check = (): void => {
+    if (!signalGroup(pid, 0)) {
+      result.resolve(true);
+      return;
+    }
+    if (performance.now() >= deadline) {
+      result.resolve(areOnlyTerminatedMembersRemaining(pid));
+      return;
+    }
+    setTimeout(check, 25);
+  };
+  check();
+  return await result.promise;
+};
+
+const isExitComplete = async (exit: Promise<unknown>) => {
+  await exit;
   return true;
-}
+};
 
-async function settledWithin(exit: Promise<unknown>, milliseconds: number) {
+const isSettledWithin = async (exit: Promise<unknown>, milliseconds: number) => {
   const expired = Promise.withResolvers<boolean>();
-  const timer = setTimeout(() => expired.resolve(false), milliseconds);
+  const timer = setTimeout(() => {
+    expired.resolve(false);
+  }, milliseconds);
   try {
-    return await Promise.race([exit.then(() => true), expired.promise]);
+    return await Promise.race([isExitComplete(exit), expired.promise]);
   } finally {
     clearTimeout(timer);
   }
-}
+};
 
-type ServerOptions = {
+interface ServerOptions {
   binary: string;
   workspace: string;
-  notification: (method: string, params: unknown) => void;
+  notification: (method: string, parameters: unknown) => void;
   interaction: (method: string) => void;
   signal: AbortSignal;
+}
+
+const captureFailure = async <Value>(promise: Promise<Value>) => {
+  try {
+    return { value: await promise };
+  } catch (error) {
+    return { error };
+  }
+};
+
+const terminateProcessGroup = async (pid: number, exit: Promise<unknown>) => {
+  await isSettledWithin(exit, 1000);
+  const isTerminated = signalGroup(pid, 'SIGTERM');
+  if (isTerminated) {
+    const areMembersTerminated = await areGroupMembersTerminated(pid);
+    if (!areMembersTerminated) {
+      signalGroup(pid, 'SIGKILL');
+      if (!(await areGroupMembersTerminated(pid))) {
+        throw new Error('Owned Codex process group survived cleanup');
+      }
+    }
+  }
+  if (!(await isSettledWithin(exit, 1000))) {
+    throw new Error('Native Codex process was not reaped');
+  }
 };
 
-async function launchServer(options: ServerOptions, disabledServers: string[]) {
+const launchServer = async (options: ServerOptions, disabledServers: string[]) => {
   const version = spawnSync(options.binary, ['--version'], {
+    encoding: 'utf-8',
     env: nativeEnvironment(),
-    encoding: 'utf8',
-    timeout: 10_000,
     maxBuffer: 65_536,
+    timeout: 10_000,
   });
-  if (version.status !== 0 || version.stdout.trim() !== nativeVersion)
+  if (version.status !== 0 || version.stdout.trim() !== nativeVersion) {
     throw new Error('Knowledge execution requires verified codex-cli 0.153.2');
+  }
   const child = spawn(options.binary, launchArguments(disabledServers), {
-    env: nativeEnvironment(),
     cwd: options.workspace,
-    stdio: 'pipe',
     detached: true,
+    env: nativeEnvironment(),
+    stdio: 'pipe',
+  });
+  const exit = Promise.withResolvers<boolean>();
+  child.once('exit', () => {
+    exit.resolve(true);
+  });
+  child.once('error', () => {
+    exit.resolve(true);
   });
-  const exit = Promise.withResolvers<void>();
-  child.once('exit', () => exit.resolve());
-  child.once('error', () => exit.resolve());
   child.stderr.resume();
-  if (child.pid === undefined) throw new Error('Native Codex could not start');
-  const pid = child.pid;
+  const { pid } = child;
+  if (pid === undefined) {
+    throw new Error('Native Codex could not start');
+  }
   const rpc = new AppServerConnection({
     input: child.stdin,
-    output: child.stdout,
-    onNotification: options.notification,
     onInteractiveRequest: options.interaction,
+    onNotification: options.notification,
+    output: child.stdout,
   });
   const stop = async () => {
     child.stdin.end();
-    try {
-      await settledWithin(exit.promise, 1000);
-      if (signalGroup(pid, 'SIGTERM') && !(await groupTerminated(pid))) {
-        signalGroup(pid, 'SIGKILL');
-        if (!(await groupTerminated(pid)))
-          throw new Error('Owned Codex process group survived cleanup');
-      }
-      if (!(await settledWithin(exit.promise, 1000)))
-        throw new Error('Native Codex process was not reaped');
-    } finally {
-      rpc.dispose();
-      child.stdin.destroy();
-      child.stdout.destroy();
-      child.stderr.destroy();
+    const result = await captureFailure(terminateProcessGroup(pid, exit.promise));
+    rpc.dispose();
+    child.stdin.destroy();
+    child.stdout.destroy();
+    child.stderr.destroy();
+    if ('error' in result) {
+      throw result.error;
     }
   };
   try {
     await rpc.request(
       'initialize',
       { clientInfo: { name: 'hivex', version: '0.1.0' } },
-      { signal: options.signal },
+      { signal: options.signal }
     );
     rpc.notify('initialized');
     const profile = await admitProfile({ rpc, signal: options.signal });
     return {
+      activeServers: profile.activeServers,
+      admission: {
+        ...profile.evidence,
+        launchPolicyHash: requestedPolicyHash(disabledServers),
+      },
+      pid,
       rpc,
       stop,
-      pid,
-      activeServers: profile.activeServers,
-      admission: { ...profile.evidence, launchPolicyHash: requestedPolicyHash(disabledServers) },
     };
   } catch (error) {
     try {
       await stop();
     } catch {
-      throw new ServerAdmissionFailure({ cause: error, cleanup: 'failed', processId: pid });
+      throw new ServerAdmissionFailure({
+        cause: error,
+        cleanup: 'failed',
+        processId: pid,
+      });
     }
-    throw new ServerAdmissionFailure({ cause: error, cleanup: 'confirmed', processId: pid });
+    throw new ServerAdmissionFailure({
+      cause: error,
+      cleanup: 'confirmed',
+      processId: pid,
+    });
   }
-}
+};
+
+const stopForAdmission = async (server: Awaited<ReturnType<typeof launchServer>>) => {
+  try {
+    await server.stop();
+  } catch (error) {
+    throw new ServerAdmissionFailure({
+      admission: server.admission,
+      cause: error,
+      cleanup: 'failed',
+      processId: server.pid,
+    });
+  }
+};
 
-export async function startServer(options: ServerOptions) {
+export const startServer = async (options: ServerOptions) => {
   const initial = await launchServer(options, []);
-  if (!initial.activeServers.length) return initial;
+  if (initial.activeServers.length === 0) {
+    return initial;
+  }
   await stopForAdmission(initial);
-  if (options.signal.aborted)
+  if (options.signal.aborted) {
     throw new ServerAdmissionFailure({
+      admission: initial.admission,
       cause: options.signal.reason,
       cleanup: 'confirmed',
       processId: initial.pid,
-      admission: initial.admission,
     });
+  }
   const isolated = await launchServer(options, initial.activeServers);
-  if (!isolated.activeServers.length) return isolated;
+  if (isolated.activeServers.length === 0) {
+    return isolated;
+  }
   await stopForAdmission(isolated);
   throw new ServerAdmissionFailure({
+    admission: isolated.admission,
     cause: new Error('MCP configuration changed or did not honor process-local overrides'),
     cleanup: 'confirmed',
     processId: isolated.pid,
-    admission: isolated.admission,
   });
-}
-
-async function stopForAdmission(server: Awaited<ReturnType<typeof launchServer>>) {
-  try {
-    await server.stop();
-  } catch (error) {
-    throw new ServerAdmissionFailure({
-      cause: error,
-      cleanup: 'failed',
-      processId: server.pid,
-      admission: server.admission,
-    });
-  }
-}
+};

package/src/model/thread.ts

@@ -1,35 +1,35 @@
 import { z } from 'zod';
-import { AppServerConnection } from './connection.ts';
 import { knowledgeModel, knowledgeThread } from './profile.ts';
+import type { AppServerConnection } from './connection.ts';
 
 const startedThread = z.looseObject({
-  thread: z.looseObject({ id: z.string(), ephemeral: z.literal(true) }),
+  cwd: z.string(),
+  instructionSources: z.array(z.string()),
   model: z.literal(knowledgeModel.name),
   modelProvider: z.literal('openai'),
   reasoningEffort: z.literal('max'),
-  cwd: z.string(),
   sandbox: z.looseObject({ type: z.literal('readOnly') }),
+  thread: z.looseObject({ ephemeral: z.literal(true), id: z.string() }),
   // Discovery paths can be reported even with project_doc_max_bytes=0, verified at admission.
-  instructionSources: z.array(z.string()),
 });
 const mcpInventory = z.looseObject({
   data: z.array(
     z.looseObject({
+      resourceTemplates: z.array(z.unknown()).length(0),
+      resources: z.array(z.unknown()).length(0),
       runtimeStatus: z.literal('disabled'),
       tools: z.record(z.string(), z.unknown()).refine((value) => !Object.keys(value).length),
-      resources: z.array(z.unknown()).length(0),
-      resourceTemplates: z.array(z.unknown()).length(0),
-    }),
+    })
   ),
   nextCursor: z.null().optional(),
 });
 const threadStartTimeoutMilliseconds = 90_000;
 
-export async function startKnowledgeThread(options: {
+export const startKnowledgeThread = async (options: {
   rpc: AppServerConnection;
   workspace: string;
   signal: AbortSignal;
-}) {
+}) => {
   const { rpc, workspace, signal } = options;
   const started = startedThread.parse(
     await rpc.request(
@@ -38,13 +38,23 @@ export async function startKnowledgeThread(options: {
         ...knowledgeThread,
         cwd: workspace,
       },
-      { signal, timeoutMilliseconds: threadStartTimeoutMilliseconds },
-    ),
+      { signal, timeoutMilliseconds: threadStartTimeoutMilliseconds }
+    )
   );
-  if (started.cwd !== workspace) throw new Error('Native Codex workspace changed');
+  if (started.cwd !== workspace) {
+    throw new Error('Native Codex workspace changed');
+  }
   const threadId = started.thread.id;
+  const threadStatusThreadId = { threadId };
+  const threadStatusLimit = { limit: 100 };
+  const threadStatusParameters = {
+    ...threadStatusThreadId,
+    ...threadStatusLimit,
+  };
   mcpInventory.parse(
-    await rpc.request('mcpServerStatus/list', { threadId, limit: 100 }, { signal }),
+    await rpc.request('mcpServerStatus/list', threadStatusParameters, {
+      signal,
+    })
   );
   return threadId;
-}
+};

package/src/model/transcript.ts

@@ -3,43 +3,66 @@ import { z } from 'zod';
 const identity = z.looseObject({ threadId: z.string(), turnId: z.string() });
 const terminal = z.looseObject({
   threadId: z.string(),
-  turn: z.looseObject({ id: z.string(), status: z.enum(['completed', 'failed', 'interrupted']) }),
+  turn: z.looseObject({
+    id: z.string(),
+    status: z.enum(['completed', 'failed', 'interrupted']),
+  }),
 });
 const itemEvent = identity.extend({
-  item: z.looseObject({ id: z.string(), type: z.string(), text: z.string().optional() }),
+  item: z.looseObject({
+    id: z.string(),
+    text: z.string().optional(),
+    type: z.string(),
+  }),
 });
 export const usageSchema = z.object({
-  inputTokens: z.number().int().nonnegative(),
+  cacheWriteInputTokens: z.number().int().nonnegative().optional(),
   cachedInputTokens: z.number().int().nonnegative(),
+  inputTokens: z.number().int().nonnegative(),
   outputTokens: z.number().int().nonnegative(),
   reasoningOutputTokens: z.number().int().nonnegative(),
   totalTokens: z.number().int().nonnegative(),
-  cacheWriteInputTokens: z.number().int().nonnegative().optional(),
 });
-const usageEvent = identity.extend({ tokenUsage: z.looseObject({ total: usageSchema }) });
+const usageEvent = identity.extend({
+  tokenUsage: z.looseObject({ total: usageSchema }),
+});
 export type Usage = z.infer<typeof usageSchema>;
 
-function consistentUsage(current: Usage, previous: Usage | undefined) {
-  if (current.totalTokens !== current.inputTokens + current.outputTokens) return false;
+const consistentUsage = (current: Usage, previous: Usage | undefined) => {
+  if (current.totalTokens !== current.inputTokens + current.outputTokens) {
+    return false;
+  }
   if (
     current.cachedInputTokens > current.inputTokens ||
     current.reasoningOutputTokens > current.outputTokens
-  )
+  ) {
     return false;
+  }
   if (
     current.cacheWriteInputTokens !== undefined &&
     current.cacheWriteInputTokens > current.inputTokens
-  )
+  ) {
     return false;
-  if (!previous) return true;
+  }
+  if (previous === undefined) {
+    return true;
+  }
   return (
     current.inputTokens >= previous.inputTokens &&
     current.outputTokens >= previous.outputTokens &&
     current.totalTokens >= previous.totalTokens
   );
-}
+};
 
-export function captureTranscript() {
+const observeRejection = async (promise: Promise<unknown>): Promise<void> => {
+  try {
+    await promise;
+  } catch {
+    // The rejection is handled by the caller through the public promise.
+  }
+};
+
+export const captureTranscript = () => {
   const done = Promise.withResolvers<z.infer<typeof terminal>>();
   const items: z.infer<typeof itemEvent>[] = [];
   const state: {
@@ -51,36 +74,53 @@ export function captureTranscript() {
   const identities = new Set<string>();
   const trackIdentity = (value: { threadId: string; turnId: string }) => {
     identities.add(JSON.stringify([value.threadId, value.turnId]));
-    if (identities.size > 1) throw new Error('Native evidence mixed thread or turn identities');
-  };
-  void done.promise.catch(() => undefined);
-  const receive = (method: string, params: unknown) => {
-    if (method === 'turn/completed') {
-      const event = terminal.parse(params);
-      trackIdentity({ threadId: event.threadId, turnId: event.turn.id });
-      if (state.terminalSeen) throw new Error('Duplicate native terminal event');
-      state.terminalSeen = true;
-      done.resolve(event);
+    if (identities.size > 1) {
+      throw new Error('Native evidence mixed thread or turn identities');
     }
-    if (method === 'thread/tokenUsage/updated') {
-      const event = usageEvent.parse(params);
-      trackIdentity(event);
-      if (!consistentUsage(event.tokenUsage.total, state.counter?.tokenUsage.total)) {
-        state.usageInvalid = true;
-        throw new Error('Native usage is inconsistent or regressed');
+  };
+  void observeRejection(done.promise);
+  const receive = (method: string, parameters: unknown) => {
+    switch (method) {
+      case 'turn/completed': {
+        const event = terminal.parse(parameters);
+        trackIdentity({ threadId: event.threadId, turnId: event.turn.id });
+        if (state.terminalSeen) {
+          throw new Error('Duplicate native terminal event');
+        }
+        state.terminalSeen = true;
+        done.resolve(event);
+        break;
+      }
+      case 'thread/tokenUsage/updated': {
+        const event = usageEvent.parse(parameters);
+        trackIdentity(event);
+        if (!consistentUsage(event.tokenUsage.total, state.counter?.tokenUsage.total)) {
+          state.usageInvalid = true;
+          throw new Error('Native usage is inconsistent or regressed');
+        }
+        state.counter = event;
+        break;
+      }
+      case 'item/completed':
+      case 'item/started': {
+        const entry = itemEvent.parse(parameters);
+        trackIdentity(entry);
+        if (!['userMessage', 'reasoning', 'agentMessage'].includes(entry.item.type)) {
+          throw new Error('Unexpected knowledge-model tool activity');
+        }
+        if (method === 'item/completed' && entry.item.type === 'agentMessage') {
+          items.push(entry);
+        }
+        break;
+      }
+      default: {
+        break;
       }
-      state.counter = event;
     }
-    if (method !== 'item/started' && method !== 'item/completed') return;
-    const entry = itemEvent.parse(params);
-    trackIdentity(entry);
-    if (!['userMessage', 'reasoning', 'agentMessage'].includes(entry.item.type))
-      throw new Error('Unexpected knowledge-model tool activity');
-    if (method === 'item/completed' && entry.item.type === 'agentMessage') items.push(entry);
   };
-  const notification = (method: string, params: unknown) => {
+  const notification = (method: string, parameters: unknown) => {
     try {
-      receive(method, params);
+      receive(method, parameters);
     } catch (error) {
       state.invalid = true;
       throw error;
@@ -90,25 +130,26 @@ export function captureTranscript() {
     const current = state.counter;
     if (
       state.usageInvalid ||
-      !current ||
-      current.threadId !== expected.threadId ||
+      current?.threadId !== expected.threadId ||
       current.turnId !== expected.turnId
-    )
+    ) {
       return null;
+    }
     return current.tokenUsage.total;
   };
   const assertValid = (expected: { threadId: string; turnId: string }) => {
-    if (state.invalid || !identities.has(JSON.stringify([expected.threadId, expected.turnId])))
+    if (state.invalid || !identities.has(JSON.stringify([expected.threadId, expected.turnId]))) {
       throw new Error('Native evidence did not retain one consistent invocation identity');
+    }
   };
   return {
-    done,
-    items,
-    notification,
-    measured,
     assertValid,
+    done,
     get invalid() {
       return state.invalid;
     },
+    items,
+    measured,
+    notification,
   };
-}
+};

package/src/ordering.ts

@@ -0,0 +1,9 @@
+// Existing snapshots and work keys use JavaScript's UTF-16 string order.
+export const compareSerializedStrings = function compareSerializedStrings(
+  left: string,
+  right: string
+) {
+  const leftUnits = Buffer.from(left, 'utf-16le').swap16();
+  const rightUnits = Buffer.from(right, 'utf-16le').swap16();
+  return leftUnits.compare(rightUnits);
+};