@humwick/runner 0.0.0-stage → 0.130.1

package/src/context-command.ts

@@ -0,0 +1,151 @@
+import { isRecord } from "@humwick/sdk";
+import type { ManagedProcess, ProviderAdapter } from "./adapter";
+import type { NativeSelfResumeHandoff, NativeSelfResumeTracker } from "./native-self-resume";
+
+export const LATE_CLEAR_GRACE_MS = 120_000;
+// Claude caps each hook context string at 10k; leave room for the review reminder.
+// https://code.claude.com/docs/en/hooks#json-output
+export const LATE_CLEAR_HOOK_MAX_CHARS = 8_000;
+
+/** Hold pre-clear inbox work until its continuation arrives or the settled clear's deadline. */
+export class ClearInjectInboxFence {
+  private pending?: { commandId: string; heldMessageIds: Set<number>; clearing: boolean; continuationAccepted?: boolean; timer?: ReturnType<typeof setTimeout> };
+
+  constructor(private readonly onRelease: () => void) {}
+
+  get active(): boolean { return this.pending !== undefined; }
+
+  begin(type: string, params: Record<string, unknown>, commandId: string, messageIds: Iterable<number>): void {
+    const resume = isRecord(params.selfResume) ? params.selfResume : undefined;
+    if (type !== "agent.clearContext" || resume?.mode !== "clear-inject" || typeof resume.continuation !== "string" || !resume.continuation.trim()) return;
+    this.reset();
+    this.pending = { commandId, heldMessageIds: new Set(messageIds), clearing: true };
+  }
+
+  finish(commandId: string, awaitingLateClear: boolean): void {
+    const pending = this.pending;
+    if (pending?.commandId !== commandId) return;
+    pending.clearing = awaitingLateClear;
+    // #2854: the continuation backstop may never arrive; wake the inbox independently.
+    pending.timer = setTimeout(() => {
+      if (this.pending !== pending) return;
+      this.reset();
+      this.onRelease();
+    }, LATE_CLEAR_GRACE_MS);
+    pending.timer.unref?.();
+    if (!awaitingLateClear) this.onRelease();
+  }
+
+  accept(commandId: string, awaitingLateClear: boolean): void {
+    if (this.pending?.commandId !== commandId) return;
+    this.pending.continuationAccepted = true;
+    if (awaitingLateClear) return;
+    this.reset();
+    this.onRelease();
+  }
+
+  endLateClearGrace(commandId: string): void {
+    const pending = this.pending;
+    if (pending?.commandId !== commandId) return;
+    pending.clearing = false;
+    if (pending.continuationAccepted) this.reset();
+    this.onRelease();
+  }
+
+  holds(messageId: number): boolean { return Boolean(this.pending && (this.pending.clearing || this.pending.heldMessageIds.has(messageId))); }
+
+  reset(): void {
+    if (this.pending?.timer) clearTimeout(this.pending.timer);
+    this.pending = undefined;
+  }
+}
+
+interface LateClearContinuation {
+  clearCommandId: string;
+  content: string;
+  fullContextMessageId?: number;
+}
+
+export function lateClearHookContent(recovery: LateClearContinuation): string {
+  if (recovery.content.length <= LATE_CLEAR_HOOK_MAX_CHARS) return recovery.content;
+  const fetch = recovery.fullContextMessageId
+    ? `relay_get_message #${recovery.fullContextMessageId} (CLI: agent-relay get-message ${recovery.fullContextMessageId})`
+    : 'relay_recall with query "latest working state"';
+  return `A delayed /clear committed after its confirmation timed out. Your saved continuation exceeds the hook context limit. Retrieve it with ${fetch} before resuming work; the full continuation was not injected here.`;
+}
+
+/** Own the uncertainty window between submitting /clear and its actual SessionStart. */
+export class LateClearRecovery {
+  private pending?: LateClearContinuation & { observed: boolean; failed: boolean; settled: Promise<void>; resolve(): void; cancel?: () => void };
+
+  constructor(private readonly onGraceEnd: (commandId: string) => void, private readonly schedule = (fn: () => void, ms: number): (() => void) => {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+  }) {}
+
+  begin(commandId: string, params: Record<string, unknown>, couples: boolean | undefined): void {
+    this.reset();
+    const resume = isRecord(params.selfResume) ? params.selfResume : undefined;
+    if (!couples || resume?.mode !== "clear-inject" || typeof resume.continuation !== "string" || !resume.continuation.trim()) return;
+    let resolve!: () => void;
+    const settled = new Promise<void>((done) => { resolve = done; });
+    this.pending = { clearCommandId: commandId, content: resume.continuation.trim(), observed: false, failed: false, settled, resolve,
+      ...(Number.isSafeInteger(resume.fullContextMessageId) && Number(resume.fullContextMessageId) > 0 ? { fullContextMessageId: Number(resume.fullContextMessageId) } : {}) };
+  }
+
+  finish(commandId: string, confirmed: boolean): void {
+    const pending = this.pending;
+    if (pending?.clearCommandId !== commandId) return;
+    if (confirmed || pending.observed) { this.reset(); return; }
+    pending.failed = true;
+    pending.cancel = this.schedule(() => {
+      if (this.pending !== pending) return;
+      this.endGrace();
+    }, LATE_CLEAR_GRACE_MS);
+  }
+
+  observe(): LateClearContinuation | undefined {
+    const pending = this.pending;
+    if (!pending) return;
+    if (!pending.failed) { pending.observed = true; return; }
+    this.reset();
+    return pending;
+  }
+
+  holds(commandId: string): boolean { return this.pending?.clearCommandId === commandId; }
+  ready(): Promise<void> { return this.pending?.settled ?? Promise.resolve(); }
+
+  endGrace(): void {
+    const pending = this.pending;
+    this.reset();
+    if (pending?.failed) this.onGraceEnd(pending.clearCommandId);
+  }
+
+  reset(): void {
+    this.pending?.cancel?.();
+    this.pending?.resolve();
+    this.pending = undefined;
+  }
+}
+
+export async function executeCompactCommand(adapter: ProviderAdapter, process: ManagedProcess | undefined, params: Record<string, unknown>, tracker: NativeSelfResumeTracker, handoff: NativeSelfResumeHandoff | undefined, awaitIdle: () => Promise<void>, resetContext: () => void): Promise<Record<string, unknown> | void> {
+  if (!adapter.compact || !process) throw new Error("provider does not support compact");
+  await tracker.run(handoff, awaitIdle);
+  resetContext();
+  if (handoff && !adapter.compactReportsSubmission) handoff.submittedAt = Date.now();
+  const compact = () => adapter.compact!(process, {
+    instructions: typeof params.instructions === "string" ? params.instructions : undefined,
+    signal: handoff?.abort.signal,
+    onSubmitted: () => { if (handoff) handoff.submittedAt = Date.now(); },
+  });
+  const result = handoff ? await tracker.run(handoff, compact) : await compact();
+  return handoff ? { ...(result ?? {}), nativeSelfResume: await handoff.promise } : result;
+}
+
+export function assertClearInjectCommitted(couples: boolean | undefined, params: Record<string, unknown>, result: Record<string, unknown> | undefined, log: (message: string) => void): void {
+  const resume = isRecord(params.selfResume) ? params.selfResume : undefined;
+  if (!couples || resume?.mode !== "clear-inject" || typeof resume.continuation !== "string" || !resume.continuation.trim() || result?.clearConfirmed === true) return;
+  log("self-resume clear-inject commit was NOT confirmed; failing the command so the relay re-injects the continuation instead of silently no-oping");
+  throw new Error("clear-inject clear commit not confirmed (possible no-op); failing so the continuation is re-injected rather than silently lost");
+}

package/src/context-probe-state.ts

@@ -0,0 +1,6 @@
+import { readContextProbeState } from "@humwick/sdk/context-probe";
+import { contextStateDirFromEnv } from "./config";
+
+export function readRunnerContextProbeState(agentId: string) {
+  return readContextProbeState(agentId, contextStateDirFromEnv());
+}

package/src/continuation-archive.ts

@@ -0,0 +1,179 @@
+import type { HumwickHttpClient } from "@humwick/sdk";
+import type { OutboxRecord } from "./outbox";
+
+const CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES = 64 * 1024;
+const CONTINUATION_ARCHIVE_CHUNK_TARGET_BYTES = 56 * 1024;
+const CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES = 8 * 1024 * 1024;
+const encoder = new TextEncoder();
+const fatalUtf8Decoder = new TextDecoder("utf-8", { fatal: true });
+
+interface ContinuationArchiveOutboxPayload {
+  agentId: string;
+  segment: string;
+  generation?: number;
+  deliveredChunks?: number;
+  totalChunks?: number;
+}
+
+interface ContinuationArchiveResponse {
+  archive?: { generation?: unknown };
+}
+
+export function boundContinuationArchiveSegment(segment: string): { segment: string; keptBytes: number; droppedBytes: number } {
+  const encoded = encoder.encode(segment);
+  const bytes = encoded.byteLength;
+  if (bytes <= CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES) {
+    return { segment, keptBytes: bytes, droppedBytes: 0 };
+  }
+  const bounded = decodeUtf8Prefix(encoded, CONTINUATION_ARCHIVE_MAX_GENERATION_BYTES);
+  const keptBytes = utf8Bytes(bounded);
+  return { segment: bounded.trimEnd(), keptBytes, droppedBytes: bytes - keptBytes };
+}
+
+export async function deliverContinuationArchiveRecord(input: {
+  record: OutboxRecord;
+  http: Pick<HumwickHttpClient, "recordContinuationArchive">;
+  updatePayload: (seq: number, payload: unknown) => void;
+  sessionLog: (message: string) => void;
+}): Promise<void> {
+  const payload = input.record.payload as ContinuationArchiveOutboxPayload;
+  let segment = payload.segment;
+  if (!payload.agentId || typeof segment !== "string") throw new Error("invalid continuation archive outbox payload");
+
+  const bounded = boundContinuationArchiveSegment(segment);
+  if (bounded.droppedBytes > 0) {
+    segment = bounded.segment;
+    input.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes before delivery`);
+    input.updatePayload(input.record.seq, { ...payload, segment, deliveredChunks: 0, totalChunks: undefined, generation: undefined });
+  }
+
+  const chunks = splitContinuationArchiveSegment({
+    agentId: payload.agentId,
+    segment,
+    occurredAt: input.record.occurredAt,
+  });
+  const knownGeneration = Number.isSafeInteger(payload.generation) ? payload.generation : undefined;
+  const deliveredChunks = knownGeneration === undefined ? 0 : Math.max(0, Math.min(payload.deliveredChunks ?? 0, chunks.length));
+  let generation = knownGeneration;
+
+  for (let index = deliveredChunks; index < chunks.length; index += 1) {
+    const request = {
+      agentId: payload.agentId,
+      segment: chunks[index]!,
+      occurredAt: input.record.occurredAt,
+      ...(generation !== undefined ? { generation } : {}),
+    };
+    assertContinuationArchivePostFits(request);
+    const response = await input.http.recordContinuationArchive(request) as ContinuationArchiveResponse;
+    const returnedGeneration = archiveGeneration(response);
+    if (generation === undefined) {
+      if (returnedGeneration === undefined) throw new Error("continuation archive response missing generation");
+      generation = returnedGeneration;
+    } else if (returnedGeneration !== undefined && returnedGeneration !== generation) {
+      throw new Error(`continuation archive generation mismatch: expected ${generation}, got ${returnedGeneration}`);
+    }
+    input.updatePayload(input.record.seq, {
+      ...payload,
+      segment,
+      generation,
+      deliveredChunks: index + 1,
+      totalChunks: chunks.length,
+    } satisfies ContinuationArchiveOutboxPayload);
+  }
+}
+
+function splitContinuationArchiveSegment(input: { agentId: string; segment: string; occurredAt: number }): string[] {
+  const chunks: string[] = [];
+  let current = "";
+  for (const line of transcriptLines(input.segment)) {
+    if (!line) continue;
+    if (fitsContinuationArchiveChunk(input.agentId, line, input.occurredAt)) {
+      const next = current ? current + line : line;
+      if (utf8Bytes(next) <= CONTINUATION_ARCHIVE_CHUNK_TARGET_BYTES && fitsContinuationArchiveChunk(input.agentId, next, input.occurredAt)) {
+        current = next;
+        continue;
+      }
+      if (current) chunks.push(current.trimEnd());
+      current = line;
+      continue;
+    }
+    if (current) {
+      chunks.push(current.trimEnd());
+      current = "";
+    }
+    chunks.push(...splitLongContinuationArchiveLine(input.agentId, line, input.occurredAt));
+  }
+  if (current) chunks.push(current.trimEnd());
+  return chunks.filter((chunk) => chunk.length > 0);
+}
+
+function transcriptLines(segment: string): string[] {
+  const lines = segment.match(/[^\n]*(?:\n|$)/g) ?? [segment];
+  return lines.filter((line) => line.length > 0);
+}
+
+function splitLongContinuationArchiveLine(agentId: string, line: string, occurredAt: number): string[] {
+  const chars = Array.from(line);
+  const chunks: string[] = [];
+  let offset = 0;
+  while (offset < chars.length) {
+    let low = 1;
+    let high = chars.length - offset;
+    let best = 0;
+    while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      const candidate = chars.slice(offset, offset + mid).join("");
+      if (utf8Bytes(candidate) <= CONTINUATION_ARCHIVE_CHUNK_TARGET_BYTES && fitsContinuationArchiveChunk(agentId, candidate, occurredAt)) {
+        best = mid;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    if (best === 0) throw new Error("continuation archive chunk budget cannot fit one character");
+    chunks.push(chars.slice(offset, offset + best).join(""));
+    offset += best;
+  }
+  return chunks;
+}
+
+function fitsContinuationArchiveChunk(agentId: string, segment: string, occurredAt: number): boolean {
+  return continuationArchivePostBytes({
+    agentId,
+    segment,
+    occurredAt,
+    generation: Number.MAX_SAFE_INTEGER,
+  }) < CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES;
+}
+
+function assertContinuationArchivePostFits(input: { agentId: string; segment: string; occurredAt: number; generation?: number }): void {
+  const bytes = continuationArchivePostBytes(input);
+  if (bytes >= CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES) {
+    throw new Error(`continuation archive chunk JSON body is ${bytes} bytes; max is ${CONTINUATION_ARCHIVE_MAX_POST_BODY_BYTES - 1}`);
+  }
+}
+
+function continuationArchivePostBytes(input: { agentId: string; segment: string; occurredAt: number; generation?: number }): number {
+  return utf8Bytes(JSON.stringify(input));
+}
+
+function archiveGeneration(response: ContinuationArchiveResponse): number | undefined {
+  const generation = response.archive?.generation;
+  return typeof generation === "number" && Number.isSafeInteger(generation) && generation >= 0 ? generation : undefined;
+}
+
+function decodeUtf8Prefix(bytes: Uint8Array, maxBytes: number): string {
+  let end = Math.min(maxBytes, bytes.byteLength);
+  while (end > 0) {
+    try {
+      return fatalUtf8Decoder.decode(bytes.subarray(0, end));
+    } catch {
+      end -= 1;
+    }
+  }
+  return "";
+}
+
+function utf8Bytes(value: string): number {
+  return encoder.encode(value).byteLength;
+}