@akagilnc/pi-workflow-roles 0.1.5204 → 0.1.5212

package/src/stream-idle-guard.ts

@@ -1,98 +0,0 @@
-/**
- * Stream idle backstop (#102 / #155 a): first-wait + between-event silence only.
- * Not a total wall-clock for long thinking turns.
- *
- * Default silence budget is owner-final 183s (#102 2026-08-04),
- * same numeric value as header timeoutMs but a distinct body-idle clock.
- */
-
-export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 183_000;
-export const STREAM_IDLE_TIMEOUT_CODE = "AK_STREAM_IDLE_TIMEOUT" as const;
-
-export class StreamIdleTimeoutError extends Error {
-  readonly code = STREAM_IDLE_TIMEOUT_CODE;
-  readonly idleTimeoutMs: number;
-
-  constructor(idleTimeoutMs: number, options?: ErrorOptions) {
-    super(`stream idle timeout after ${idleTimeoutMs}ms`, options);
-    this.name = "StreamIdleTimeoutError";
-    this.idleTimeoutMs = idleTimeoutMs;
-  }
-}
-
-export function isStreamIdleTimeoutError(value: unknown): value is StreamIdleTimeoutError {
-  return value instanceof StreamIdleTimeoutError
-    || (
-      typeof value === "object"
-      && value !== null
-      && (value as { name?: unknown }).name === "StreamIdleTimeoutError"
-      && (value as { code?: unknown }).code === STREAM_IDLE_TIMEOUT_CODE
-    );
-}
-
-export type StreamIdleGuardOptions = {
-  idleTimeoutMs?: number;
-  parentSignal?: AbortSignal;
-};
-
-export type StreamIdleGuard = {
-  readonly signal: AbortSignal;
-  poke(): void;
-  dispose(): void;
-};
-
-export function createStreamIdleGuard(
-  options: StreamIdleGuardOptions = {},
-): StreamIdleGuard {
-  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
-  const parentSignal = options.parentSignal;
-
-  const controller = new AbortController();
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  let disposed = false;
-
-  const clear = (): void => {
-    if (timer !== undefined) {
-      clearTimeout(timer);
-      timer = undefined;
-    }
-  };
-
-  const arm = (): void => {
-    if (disposed || controller.signal.aborted || idleTimeoutMs <= 0) return;
-    clear();
-    timer = setTimeout(() => {
-      timer = undefined;
-      if (disposed || controller.signal.aborted) return;
-      controller.abort(new StreamIdleTimeoutError(idleTimeoutMs));
-    }, idleTimeoutMs);
-  };
-
-  const onParentAbort = (): void => {
-    if (controller.signal.aborted) return;
-    clear();
-    controller.abort(parentSignal?.reason);
-  };
-
-  if (parentSignal !== undefined) {
-    if (parentSignal.aborted) {
-      controller.abort(parentSignal.reason);
-    } else {
-      parentSignal.addEventListener("abort", onParentAbort);
-    }
-  }
-
-  arm();
-
-  return {
-    signal: controller.signal,
-    poke(): void {
-      arm();
-    },
-    dispose(): void {
-      disposed = true;
-      clear();
-      parentSignal?.removeEventListener("abort", onParentAbort);
-    },
-  };
-}

package/src/tool-execution-observation.ts

@@ -1,168 +0,0 @@
-import { writeSync } from "node:fs";
-import { Type, type Static } from "typebox";
-import { Value } from "typebox/value";
-
-import { writeStderrJsonlRecord } from "./stderr-jsonl.ts";
-
-/** Mandatory coalesce window for tool_execution_update heartbeats (stderr is bounded). */
-export const TOOL_EXECUTION_UPDATE_THROTTLE_MS = 30_000;
-
-/**
- * Heartbeat basis for downstream silence predicates.
- *
- * Production Pi `bash.js` calls `onUpdate` once with empty content at execute entry,
- * then schedules output-driven updates at ~100 ms. This face skips non-producing
- * (empty-content) updates so the first heartbeat is real child output, then
- * coalesces at {@link TOOL_EXECUTION_UPDATE_THROTTLE_MS}.
- *
- * If a future host path stopped delivering output-driven updates, change this to
- * `"duration-only"` and document that silence predicates degrade to pure duration.
- */
-export const TOOL_EXECUTION_UPDATE_HEARTBEAT = "output-driven" as const;
-
-const observationBase = {
-  role: Type.String({ minLength: 1 }),
-  toolCallId: Type.String({ minLength: 1 }),
-  toolName: Type.String({ minLength: 1 }),
-  timestamp: Type.String({ format: "date-time" }),
-} as const;
-
-export const toolExecutionObservationRecordSchema = Type.Union([
-  Type.Object({
-    ...observationBase,
-    event: Type.Literal("tool_execution_start"),
-  }, { additionalProperties: true }),
-  Type.Object({
-    ...observationBase,
-    event: Type.Literal("tool_execution_update"),
-  }, { additionalProperties: true }),
-  Type.Object({
-    ...observationBase,
-    event: Type.Literal("tool_execution_end"),
-    isError: Type.Boolean(),
-  }, { additionalProperties: true }),
-]);
-
-export type ToolExecutionObservationRecord = Static<typeof toolExecutionObservationRecordSchema>;
-export type ToolExecutionObservationWriter = (record: ToolExecutionObservationRecord) => void | Promise<void>;
-
-export function validateToolExecutionObservationRecord(record: unknown): ToolExecutionObservationRecord {
-  if (!Value.Check(toolExecutionObservationRecordSchema, record)) {
-    throw new TypeError("Tool execution observation record does not match its contract");
-  }
-  return record as ToolExecutionObservationRecord;
-}
-
-export function writeToolExecutionObservationRecord(
-  record: ToolExecutionObservationRecord,
-  write: typeof writeSync = writeSync,
-): void {
-  writeStderrJsonlRecord(validateToolExecutionObservationRecord(record), write);
-}
-
-/** True when a tool_execution_update partialResult carries producing content (not bash's empty entry callback). */
-export function isProducingToolUpdate(partialResult: unknown): boolean {
-  if (partialResult == null) return false;
-  if (typeof partialResult !== "object") return true;
-  const content = (partialResult as { content?: unknown }).content;
-  if (!Array.isArray(content)) return true;
-  if (content.length === 0) return false;
-  return content.some((part) => {
-    if (typeof part !== "object" || part === null) return true;
-    const text = (part as { text?: unknown }).text;
-    if (typeof text === "string") return text.length > 0;
-    return true;
-  });
-}
-
-type CallObservationState = {
-  lastUpdateEmitMonoMs: number | undefined;
-};
-
-export type ToolExecutionObservationFace = {
-  onStart(event: { toolCallId: string; toolName: string }): void | Promise<void>;
-  onUpdate(event: { toolCallId: string; toolName: string; partialResult: unknown }): void | Promise<void>;
-  onEnd(event: { toolCallId: string; toolName: string; isError: boolean }): void | Promise<void>;
-  reset(): void;
-};
-
-/**
- * Production throttle clock: genuinely monotonic milliseconds.
- * Wall-clock Date.now() is not safe — NTP/slew can compress two heartbeats under 30s.
- */
-export function systemToolExecutionObservationMonoNow(): number {
-  return performance.now();
-}
-
-export function createToolExecutionObservationFace(options: {
-  role: () => string | undefined;
-  admitted: () => boolean;
-  clock(): string;
-  monoNow(): number;
-  write(record: ToolExecutionObservationRecord): void | Promise<void>;
-}): ToolExecutionObservationFace {
-  const states = new Map<string, CallObservationState>();
-
-  async function emit(record: unknown): Promise<void> {
-    await options.write(validateToolExecutionObservationRecord(record));
-  }
-
-  function activeRole(): string | undefined {
-    if (!options.admitted()) return undefined;
-    const role = options.role();
-    return role === undefined || role === "" ? undefined : role;
-  }
-
-  return {
-    reset() {
-      states.clear();
-    },
-    async onStart(event) {
-      const role = activeRole();
-      if (role === undefined) return;
-      states.set(event.toolCallId, { lastUpdateEmitMonoMs: undefined });
-      await emit({
-        event: "tool_execution_start",
-        role,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        timestamp: options.clock(),
-      });
-    },
-    async onUpdate(event) {
-      const role = activeRole();
-      if (role === undefined) return;
-      if (!isProducingToolUpdate(event.partialResult)) return;
-      const now = options.monoNow();
-      const state = states.get(event.toolCallId) ?? { lastUpdateEmitMonoMs: undefined };
-      if (
-        state.lastUpdateEmitMonoMs !== undefined
-        && now - state.lastUpdateEmitMonoMs < TOOL_EXECUTION_UPDATE_THROTTLE_MS
-      ) {
-        return;
-      }
-      state.lastUpdateEmitMonoMs = now;
-      states.set(event.toolCallId, state);
-      await emit({
-        event: "tool_execution_update",
-        role,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        timestamp: options.clock(),
-      });
-    },
-    async onEnd(event) {
-      const role = activeRole();
-      if (role === undefined) return;
-      states.delete(event.toolCallId);
-      await emit({
-        event: "tool_execution_end",
-        role,
-        toolCallId: event.toolCallId,
-        toolName: event.toolName,
-        timestamp: options.clock(),
-        isError: event.isError,
-      });
-    },
-  };
-}