harnery 0.35.0 → 0.36.0

package/src/core/hooks/resolve/transcript.ts

@@ -3,6 +3,8 @@ import { basename, dirname, join } from "node:path";
 
 import { toolResponseMintedSessionName } from "../../agents/session-name-display.ts";
 
+export const ASSISTANT_STATUS_BOX_PREFIX = "┌─ agent-";
+
 /**
  * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
  * the most-recent assistant turn. Used by `turn.completed` events to populate
@@ -76,6 +78,22 @@ export function scanAssistantTextIncludes(
   return false;
 }
 
+/**
+ * Strict status-box evidence shared by turn telemetry and the Stop-time
+ * continuation fallback. Both inputs are assistant-only surfaces: the JSONL
+ * scanner rejects tool_result rows, while lastAssistantMessage comes directly
+ * from the adapter's completed assistant response.
+ */
+export function scanAssistantStatusBoxPresent(
+  transcriptPath: string | undefined,
+  lastAssistantMessage: string | undefined,
+): boolean {
+  return (
+    scanAssistantTextIncludes(transcriptPath, ASSISTANT_STATUS_BOX_PREFIX) ||
+    lastAssistantMessage?.includes(ASSISTANT_STATUS_BOX_PREFIX) === true
+  );
+}
+
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);

package/src/core/inbox/contract.ts

@@ -0,0 +1,81 @@
+export const HARNERY_INBOX_RECORD_SCHEMA = "harnery.inbox-record/v1" as const;
+export const HARNERY_INBOX_STATUS_SCHEMA = "harnery.inbox-status/v1" as const;
+
+export interface HarneryInboxLimits {
+  max_message_body_bytes: number;
+  max_pending_count: number;
+  max_pending_bytes: number;
+  max_history_bytes: number;
+  max_history_records: number;
+  warning_pressure_ratio: number;
+  max_surface_count: number;
+  max_surface_bytes: number;
+  max_surface_tokens: number;
+  surfaced_grace_ms: number;
+  terminal_grace_ms: number;
+}
+
+export interface HarneryInboxMessageRecordV1 {
+  schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
+  kind: "message";
+  message_id: string;
+  sender_instance_id: string;
+  sender_display_name: string;
+  recipient_instance_id: string;
+  recipient_display_name: string;
+  created_at: string;
+  body: string;
+  body_bytes: number;
+}
+
+export interface HarneryInboxSurfacedRecordV1 {
+  schema: typeof HARNERY_INBOX_RECORD_SCHEMA;
+  kind: "surfaced";
+  message_id: string;
+  surfaced_at: string;
+}
+
+export type HarneryInboxRecordV1 = HarneryInboxMessageRecordV1 | HarneryInboxSurfacedRecordV1;
+
+export interface HarneryInboxStatusV1 {
+  schema: typeof HARNERY_INBOX_STATUS_SCHEMA;
+  recipient_instance_id: string;
+  pending_count: number;
+  pending_bytes: number;
+  total_history_bytes: number;
+  oldest_pending_at?: string;
+  pressure: "normal" | "warning" | "exhausted";
+  last_surface_at?: string;
+  last_compaction_at?: string;
+}
+
+export type HarneryInboxCapacityReason =
+  | "message_body_limit"
+  | "pending_count_limit"
+  | "pending_bytes_limit"
+  | "history_bytes_limit";
+
+export class HarneryInboxCapacityError extends Error {
+  constructor(
+    readonly reason_code: HarneryInboxCapacityReason,
+    readonly current: number,
+    readonly limit: number,
+  ) {
+    super(
+      `inbox capacity ${reason_code}: ${current}/${limit}; use a managed artifact for larger payloads`,
+    );
+  }
+}
+
+export interface HarneryInboxSurfaceBudget {
+  max_count: number;
+  max_bytes: number;
+  max_tokens: number;
+}
+
+export interface HarneryInboxSurfaceResult {
+  emitted: readonly HarneryInboxMessageRecordV1[];
+  remaining_pending_count: number;
+  remaining_pending_bytes: number;
+  repeated_after_crash_possible: true;
+}

package/src/core/inbox/index.ts

@@ -0,0 +1,4 @@
+export * from "./contract.ts";
+export * from "./lifecycle.ts";
+export * from "./service.ts";
+export * from "./watcher.ts";

package/src/core/inbox/lifecycle.ts

@@ -0,0 +1,104 @@
+import type { HarneryInboxLimits, HarneryInboxRecordV1 } from "./contract.ts";
+import { project } from "./service.ts";
+
+export const HARNERY_INBOX_COMPACTION_PLAN_SCHEMA = "harnery.inbox-compaction-plan/v1" as const;
+
+export type HarneryRecipientLifecycle = "active" | "resumable" | "terminal";
+
+export interface HarneryInboxCompactionPlan {
+  schema: typeof HARNERY_INBOX_COMPACTION_PLAN_SCHEMA;
+  recipient_instance_id: string;
+  action: "none" | "compact-surfaced" | "prune-terminal";
+  reason_code:
+    | "pending_protected"
+    | "active_recipient"
+    | "surfaced_grace"
+    | "terminal_grace"
+    | "eligible";
+  remove_record_count: number;
+  retained_record_count: number;
+  protected_pending_count: number;
+  dry_run: true;
+}
+
+export function planInboxCompaction(input: {
+  recipient_instance_id: string;
+  records: readonly HarneryInboxRecordV1[];
+  lifecycle: HarneryRecipientLifecycle;
+  terminal_at?: string;
+  now: Date;
+  limits: HarneryInboxLimits;
+}): HarneryInboxCompactionPlan {
+  const projection = project(input.records);
+  const surfacedAt = new Map<string, number>();
+  for (const record of input.records) {
+    if (record.kind === "surfaced")
+      surfacedAt.set(record.message_id, Date.parse(record.surfaced_at));
+  }
+  const compactableIds = new Set(
+    [...surfacedAt]
+      .filter(([, timestamp]) => input.now.getTime() - timestamp >= input.limits.surfaced_grace_ms)
+      .map(([id]) => id),
+  );
+  const compactableRecords = input.records.filter((record) =>
+    compactableIds.has(record.message_id),
+  ).length;
+  if (input.lifecycle === "terminal") {
+    if (projection.pending.length > 0) {
+      return plan(
+        input,
+        "none",
+        "pending_protected",
+        0,
+        input.records.length,
+        projection.pending.length,
+      );
+    }
+    const terminalAt = input.terminal_at ? Date.parse(input.terminal_at) : Number.NaN;
+    if (
+      !Number.isFinite(terminalAt) ||
+      input.now.getTime() - terminalAt < input.limits.terminal_grace_ms
+    ) {
+      return plan(input, "none", "terminal_grace", 0, input.records.length, 0);
+    }
+    return plan(input, "prune-terminal", "eligible", input.records.length, 0, 0);
+  }
+  if (compactableRecords === 0) {
+    return plan(
+      input,
+      "none",
+      surfacedAt.size > 0 ? "surfaced_grace" : "active_recipient",
+      0,
+      input.records.length,
+      projection.pending.length,
+    );
+  }
+  return plan(
+    input,
+    "compact-surfaced",
+    "eligible",
+    compactableRecords,
+    input.records.length - compactableRecords,
+    projection.pending.length,
+  );
+}
+
+function plan(
+  input: { recipient_instance_id: string },
+  action: HarneryInboxCompactionPlan["action"],
+  reason_code: HarneryInboxCompactionPlan["reason_code"],
+  remove_record_count: number,
+  retained_record_count: number,
+  protected_pending_count: number,
+): HarneryInboxCompactionPlan {
+  return {
+    schema: HARNERY_INBOX_COMPACTION_PLAN_SCHEMA,
+    recipient_instance_id: input.recipient_instance_id,
+    action,
+    reason_code,
+    remove_record_count,
+    retained_record_count,
+    protected_pending_count,
+    dry_run: true,
+  };
+}

package/src/core/inbox/service.ts

@@ -0,0 +1,305 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { readCrashSafeJsonlFile, updateCrashSafeJsonlFile } from "../storage/durable-history.ts";
+import {
+  HARNERY_INBOX_RECORD_SCHEMA,
+  HARNERY_INBOX_STATUS_SCHEMA,
+  HarneryInboxCapacityError,
+  type HarneryInboxLimits,
+  type HarneryInboxMessageRecordV1,
+  type HarneryInboxRecordV1,
+  type HarneryInboxStatusV1,
+  type HarneryInboxSurfaceBudget,
+  type HarneryInboxSurfaceResult,
+} from "./contract.ts";
+
+export interface HarneryInboxServiceOptions {
+  coord_root: string;
+  limits: HarneryInboxLimits;
+  now?: () => Date;
+  id?: () => string;
+}
+
+export interface HarneryInboxSendInput {
+  sender_instance_id: string;
+  sender_display_name: string;
+  recipient_instance_id: string;
+  recipient_display_name: string;
+  body: string;
+}
+
+export interface HarneryInboxSendReceipt {
+  state: "queued";
+  message_id: string;
+  body_bytes: number;
+  synced: true;
+}
+
+export class HarneryInboxService {
+  readonly #options: HarneryInboxServiceOptions;
+
+  constructor(options: HarneryInboxServiceOptions) {
+    validateLimits(options.limits);
+    this.#options = options;
+  }
+
+  send(input: HarneryInboxSendInput): HarneryInboxSendReceipt {
+    const recipient = opaqueId(input.recipient_instance_id, "recipient instance");
+    const bodyBytes = Buffer.byteLength(input.body);
+    const limits = this.#options.limits;
+    if (bodyBytes === 0 || bodyBytes > limits.max_message_body_bytes) {
+      throw new HarneryInboxCapacityError(
+        "message_body_limit",
+        bodyBytes,
+        limits.max_message_body_bytes,
+      );
+    }
+    const record: HarneryInboxMessageRecordV1 = {
+      schema: HARNERY_INBOX_RECORD_SCHEMA,
+      kind: "message",
+      message_id: `msg_${this.#options.id?.() ?? randomUUID()}`,
+      sender_instance_id: opaqueId(input.sender_instance_id, "sender instance"),
+      sender_display_name: boundedDisplay(input.sender_display_name),
+      recipient_instance_id: recipient,
+      recipient_display_name: boundedDisplay(input.recipient_display_name),
+      created_at: now(this.#options).toISOString(),
+      body: input.body,
+      body_bytes: bodyBytes,
+    };
+    const path = inboxPath(this.#options.coord_root, recipient);
+    return updateCrashSafeJsonlFile<HarneryInboxRecordV1, HarneryInboxSendReceipt>(
+      path,
+      readOptions(limits),
+      (records) => {
+        const projection = project(records);
+        capacityCheck(projection, record, path, limits);
+        return {
+          append: [record],
+          result: {
+            state: "queued",
+            message_id: record.message_id,
+            body_bytes: bodyBytes,
+            synced: true,
+          },
+        };
+      },
+    );
+  }
+
+  records(recipientInstanceId: string): HarneryInboxRecordV1[] {
+    return readCrashSafeJsonlFile<HarneryInboxRecordV1>(
+      inboxPath(this.#options.coord_root, opaqueId(recipientInstanceId, "recipient instance")),
+      readOptions(this.#options.limits),
+    );
+  }
+
+  pending(recipientInstanceId: string): HarneryInboxMessageRecordV1[] {
+    return project(this.records(recipientInstanceId)).pending;
+  }
+
+  status(recipientInstanceId: string): HarneryInboxStatusV1 {
+    const recipient = opaqueId(recipientInstanceId, "recipient instance");
+    const path = inboxPath(this.#options.coord_root, recipient);
+    const projection = project(this.records(recipient));
+    const pendingBytes = projection.pending.reduce((sum, record) => sum + record.body_bytes, 0);
+    const ratio = Math.max(
+      projection.pending.length / this.#options.limits.max_pending_count,
+      pendingBytes / this.#options.limits.max_pending_bytes,
+    );
+    return {
+      schema: HARNERY_INBOX_STATUS_SCHEMA,
+      recipient_instance_id: recipient,
+      pending_count: projection.pending.length,
+      pending_bytes: pendingBytes,
+      total_history_bytes: existsSync(path) ? statSync(path).size : 0,
+      ...(projection.pending[0] ? { oldest_pending_at: projection.pending[0].created_at } : {}),
+      pressure:
+        ratio >= 1
+          ? "exhausted"
+          : ratio >= this.#options.limits.warning_pressure_ratio
+            ? "warning"
+            : "normal",
+      ...(projection.lastSurfaceAt ? { last_surface_at: projection.lastSurfaceAt } : {}),
+    };
+  }
+
+  async surface(
+    recipientInstanceId: string,
+    emit: (messages: readonly HarneryInboxMessageRecordV1[]) => Promise<void> | void,
+    budget: HarneryInboxSurfaceBudget = {
+      max_count: this.#options.limits.max_surface_count,
+      max_bytes: this.#options.limits.max_surface_bytes,
+      max_tokens: this.#options.limits.max_surface_tokens,
+    },
+  ): Promise<HarneryInboxSurfaceResult> {
+    validateSurfaceBudget(budget);
+    const recipient = opaqueId(recipientInstanceId, "recipient instance");
+    const selected = selectOldestFitting(this.pending(recipient), budget);
+    await emit(selected);
+    if (selected.length > 0) {
+      const surfacedAt = now(this.#options).toISOString();
+      updateCrashSafeJsonlFile<HarneryInboxRecordV1, void>(
+        inboxPath(this.#options.coord_root, recipient),
+        readOptions(this.#options.limits),
+        (records) => {
+          const stillPending = new Set(
+            project(records).pending.map(({ message_id }) => message_id),
+          );
+          return {
+            append: selected
+              .filter(({ message_id }) => stillPending.has(message_id))
+              .map(({ message_id }) => ({
+                schema: HARNERY_INBOX_RECORD_SCHEMA,
+                kind: "surfaced" as const,
+                message_id,
+                surfaced_at: surfacedAt,
+              })),
+            result: undefined,
+          };
+        },
+      );
+    }
+    const remaining = this.pending(recipient);
+    return {
+      emitted: selected,
+      remaining_pending_count: remaining.length,
+      remaining_pending_bytes: remaining.reduce((sum, record) => sum + record.body_bytes, 0),
+      repeated_after_crash_possible: true,
+    };
+  }
+}
+
+export function inboxPath(coordRoot: string, recipientInstanceId: string): string {
+  const id = opaqueId(recipientInstanceId, "recipient instance");
+  return join(resolve(coordRoot), ".harnery", "inbox", `${id}.jsonl`);
+}
+
+export function project(records: readonly HarneryInboxRecordV1[]): {
+  pending: HarneryInboxMessageRecordV1[];
+  surfaced: ReadonlySet<string>;
+  lastSurfaceAt?: string;
+} {
+  const messages = new Map<string, HarneryInboxMessageRecordV1>();
+  const surfaced = new Set<string>();
+  let lastSurfaceAt: string | undefined;
+  for (const record of records) {
+    validateRecord(record);
+    if (record.kind === "message") {
+      if (messages.has(record.message_id))
+        throw new Error(`duplicate inbox message ${record.message_id}`);
+      messages.set(record.message_id, record);
+    } else {
+      if (!messages.has(record.message_id))
+        throw new Error(`surfaced marker precedes ${record.message_id}`);
+      surfaced.add(record.message_id);
+      if (!lastSurfaceAt || record.surfaced_at > lastSurfaceAt) lastSurfaceAt = record.surfaced_at;
+    }
+  }
+  return {
+    pending: [...messages.values()].filter(({ message_id }) => !surfaced.has(message_id)),
+    surfaced,
+    ...(lastSurfaceAt ? { lastSurfaceAt } : {}),
+  };
+}
+
+function selectOldestFitting(
+  pending: readonly HarneryInboxMessageRecordV1[],
+  budget: HarneryInboxSurfaceBudget,
+): HarneryInboxMessageRecordV1[] {
+  const selected: HarneryInboxMessageRecordV1[] = [];
+  let bytes = 0;
+  let tokens = 0;
+  for (const record of pending) {
+    const recordTokens = Math.ceil(record.body_bytes / 4);
+    if (
+      selected.length >= budget.max_count ||
+      bytes + record.body_bytes > budget.max_bytes ||
+      tokens + recordTokens > budget.max_tokens
+    ) {
+      break;
+    }
+    selected.push(record);
+    bytes += record.body_bytes;
+    tokens += recordTokens;
+  }
+  return selected;
+}
+
+function capacityCheck(
+  projection: ReturnType<typeof project>,
+  record: HarneryInboxMessageRecordV1,
+  path: string,
+  limits: HarneryInboxLimits,
+): void {
+  const pendingBytes = projection.pending.reduce((sum, item) => sum + item.body_bytes, 0);
+  if (projection.pending.length + 1 > limits.max_pending_count) {
+    throw new HarneryInboxCapacityError(
+      "pending_count_limit",
+      projection.pending.length,
+      limits.max_pending_count,
+    );
+  }
+  if (pendingBytes + record.body_bytes > limits.max_pending_bytes) {
+    throw new HarneryInboxCapacityError(
+      "pending_bytes_limit",
+      pendingBytes,
+      limits.max_pending_bytes,
+    );
+  }
+  const nextHistoryBytes =
+    (existsSync(path) ? statSync(path).size : 0) + Buffer.byteLength(`${JSON.stringify(record)}\n`);
+  if (nextHistoryBytes > limits.max_history_bytes) {
+    throw new HarneryInboxCapacityError(
+      "history_bytes_limit",
+      nextHistoryBytes,
+      limits.max_history_bytes,
+    );
+  }
+}
+
+function readOptions(limits: HarneryInboxLimits) {
+  return {
+    max_record_bytes: Math.max(limits.max_message_body_bytes * 2, 4_096),
+    max_records: limits.max_history_records,
+  };
+}
+
+function now(options: HarneryInboxServiceOptions): Date {
+  return options.now?.() ?? new Date();
+}
+
+function opaqueId(value: string, field: string): string {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value)) throw new Error(`invalid ${field} id`);
+  return value;
+}
+
+function boundedDisplay(value: string): string {
+  const result = value.trim();
+  if (result.length === 0 || Buffer.byteLength(result) > 256)
+    throw new Error("invalid display name");
+  return result;
+}
+
+function validateRecord(record: HarneryInboxRecordV1): void {
+  if (record.schema !== HARNERY_INBOX_RECORD_SCHEMA) throw new Error("unknown inbox record schema");
+  if (record.kind === "message" && Buffer.byteLength(record.body) !== record.body_bytes) {
+    throw new Error(`inbox message ${record.message_id} has invalid body_bytes`);
+  }
+}
+
+function validateLimits(limits: HarneryInboxLimits): void {
+  for (const [field, value] of Object.entries(limits)) {
+    if (field === "warning_pressure_ratio") continue;
+    if (!Number.isSafeInteger(value) || value <= 0) throw new Error(`invalid inbox limit ${field}`);
+  }
+  if (limits.warning_pressure_ratio <= 0 || limits.warning_pressure_ratio >= 1) {
+    throw new Error("warning_pressure_ratio must be between zero and one");
+  }
+}
+
+function validateSurfaceBudget(budget: HarneryInboxSurfaceBudget): void {
+  for (const value of Object.values(budget)) {
+    if (!Number.isSafeInteger(value) || value <= 0) throw new Error("invalid inbox surface budget");
+  }
+}

package/src/core/inbox/watcher.ts

@@ -0,0 +1,36 @@
+import type { HarneryInboxMessageRecordV1 } from "./contract.ts";
+import type { HarneryInboxService } from "./service.ts";
+
+export async function* watchInbox(
+  service: HarneryInboxService,
+  recipientInstanceId: string,
+  options: { signal: AbortSignal; poll_ms?: number },
+): AsyncGenerator<HarneryInboxMessageRecordV1> {
+  const seen = new Set<string>();
+  while (!options.signal.aborted) {
+    try {
+      for (const message of service.pending(recipientInstanceId)) {
+        if (seen.has(message.message_id)) continue;
+        seen.add(message.message_id);
+        yield message;
+      }
+    } catch {
+      // A transient missing or incomplete source is retried; no cursor is advanced.
+    }
+    await delay(options.poll_ms ?? 250, options.signal);
+  }
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}

package/src/core/presence/codec-digest.ts

@@ -131,16 +131,22 @@ export function projectPresenceCodecDigests(
         break;
       case "context.observed": {
         const measurement = event.payload.measurement;
-        if (measurement.state === "observed" && measurement.value.limit_tokens > 0) {
+        if (measurement.state === "observed") {
+          const usedPercent =
+            "used_percent" in measurement.value
+              ? measurement.value.used_percent
+              : measurement.value.limit_tokens > 0
+                ? (measurement.value.used_tokens / measurement.value.limit_tokens) * 100
+                : undefined;
+          if (usedPercent === undefined) break;
           slot.context = {
-            used_percent: Math.min(
-              100,
-              Math.max(
-                0,
-                Math.round((measurement.value.used_tokens / measurement.value.limit_tokens) * 100),
-              ),
-            ),
-            confidence: measurement.confidence === "exact" ? "exact" : "reported",
+            used_percent: Math.min(100, Math.max(0, Math.round(usedPercent))),
+            confidence:
+              measurement.attestation === "inferred"
+                ? "estimated"
+                : measurement.confidence === "exact"
+                  ? "exact"
+                  : "reported",
             event_id: event.event_id,
             observed_at: event.time.observed_at,
           };