tinker-agent 1.0.65

package/src/events/stdout-event-printer.ts

@@ -0,0 +1,396 @@
+import type { ToolCall } from "../agent/types";
+import { countPatchChanges, parseDiffHunks } from "../tools/file-diff";
+import type { ToolRawResult } from "../tools/types";
+import { bashResultDetail } from "./bash-result-detail";
+import type { EventSink } from "./event-sink";
+import type { AgentEvent } from "./types";
+
+export type WritableLike = {
+  write(chunk: string): unknown;
+};
+
+export class StdoutEventPrinter implements EventSink {
+  readonly name = "stdout-event-printer";
+
+  constructor(
+    private readonly stdout: WritableLike,
+    private readonly stderr: WritableLike,
+  ) {}
+
+  async append(event: AgentEvent): Promise<void> {
+    switch (event.type) {
+      case "session.started":
+        this.stdout.write(`session.started sessionId=${event.sessionId}\n`);
+        break;
+      case "session.resumed":
+        this.stdout.write(
+          `session.resumed sessionId=${event.sessionId} openCount=${event.data.openCount} recallIndexRebuilt=${event.data.recallIndexRebuilt}\n`,
+        );
+        break;
+      case "session.interrupted_frame_recovered":
+        this.stdout.write(
+          `session.interrupted_frame_recovered frameId=${event.data.frameId} completions=${event.data.syntheticCompletionCount}\n`,
+        );
+        break;
+      case "turn.started":
+        this.stdout.write(
+          `turn.started turn=${event.turnNumber} turnId=${event.turnId}\n`,
+        );
+        break;
+      case "agent.iteration.started":
+        this.stdout.write(
+          `agent.iteration.started iteration=${event.iterationNumber} iterationId=${event.iterationId}\n`,
+        );
+        break;
+      case "model.request.started":
+        this.stdout.write(`model.request.started iteration=${event.iterationNumber}\n`);
+        break;
+      case "model.request.finished":
+        this.stdout.write(
+          `model.request.finished iteration=${event.iterationNumber}\n`,
+        );
+        break;
+      case "context.usage.updated":
+        this.stdout.write(
+          `context.usage.updated phase=${event.data.phase} used=${event.data.snapshot.usedInputTokens} budget=${event.data.snapshot.inputBudgetTokens} source=${event.data.snapshot.source} pressure=${event.data.snapshot.pressure}\n`,
+        );
+        break;
+      case "context.shadow.planned":
+        this.stdout.write(
+          `context.shadow.planned outcome=${event.data.outcome} eligible=${event.data.eligibleCandidateCount} selected=${event.data.selectedCandidateCount} before=${event.data.guardedTokensBefore} after=${event.data.guardedTokensAfter ?? "n/a"}\n`,
+        );
+        break;
+      case "context.shadow.failed":
+        this.stderr.write(
+          `context.shadow.failed stage=${event.data.stage} code=${event.data.errorCode}\n`,
+        );
+        break;
+      case "context.revision.started":
+        this.stdout.write(
+          `context.revision.started reason=${event.data.reason} policy=${event.data.policyVersion}\n`,
+        );
+        break;
+      case "context.revision.finished":
+        this.stdout.write(
+          `context.revision.finished outcome=${event.data.outcome} revision=${event.data.revisionNumber ?? event.data.baseRevisionNumber} added=${event.data.addedOverrideCount} before=${event.data.guardedTokensBefore} after=${event.data.guardedTokensAfter ?? "n/a"}\n`,
+        );
+        break;
+      case "context.revision.failed":
+        this.stderr.write(
+          `context.revision.failed stage=${event.data.stage} code=${event.data.errorCode}\n`,
+        );
+        break;
+      case "assistant.progress":
+        this.stdout.write(
+          `assistant.progress iteration=${event.iterationNumber}\n${event.data.content}\n`,
+        );
+        break;
+      case "tool.started":
+        this.stdout.write(formatToolLine("tool.started", event.data.call));
+        break;
+      case "tool.raw_result": {
+        for (const line of formatToolRawResult(event.data.call, event.data.raw)) {
+          this.stdout.write(line);
+        }
+        break;
+      }
+      case "tool.finished":
+        this.stdout.write(
+          `${formatToolLine("tool.finished", event.data.call).trimEnd()} ok=${event.data.ok}\n`,
+        );
+        break;
+      case "mcp.server.connected":
+        this.stdout.write(
+          `mcp.server.connected name=${event.data.serverName} tools=${event.data.toolCount}\n`,
+        );
+        break;
+      case "bash.task.backgrounded":
+        this.stdout.write(
+          `bash.task.backgrounded task=${event.data.task.taskId} status=${event.data.task.status}\n`,
+        );
+        break;
+      case "bash.task.stopping":
+        this.stdout.write(
+          `bash.task.stopping task=${event.data.task.taskId} status=${event.data.task.status}\n`,
+        );
+        break;
+      case "bash.task.finished":
+        this.stdout.write(
+          `bash.task.finished task=${event.data.task.taskId} status=${event.data.task.status}${
+            event.data.task.exitCode === undefined
+              ? ""
+              : ` exit=${event.data.task.exitCode}`
+          }${event.data.task.signal === undefined ? "" : ` signal=${event.data.task.signal}`}\n`,
+        );
+        break;
+      case "mcp.server.failed":
+        this.stderr.write(
+          `mcp.server.failed name=${event.data.serverName} error=${event.data.error}\n`,
+        );
+        break;
+      case "diagnostic.sink_failed":
+        this.stderr.write(
+          `diagnostic.sink_failed sink=${event.data.sinkName} event=${event.data.failedEventType} error=${event.data.error}\n`,
+        );
+        break;
+      case "turn.finished":
+        this.stdout.write(`turn.finished status=${event.data.status}\n`);
+        break;
+      case "turn.cancelled":
+        this.stdout.write(
+          `turn.cancelled phase=${event.data.cancellation.phase} iteration=${event.data.cancellation.iterationNumber}${
+            event.data.cancellation.toolName === undefined
+              ? ""
+              : ` tool=${event.data.cancellation.toolName}`
+          }\n`,
+        );
+        break;
+      case "turn.failed":
+        this.stderr.write(`turn.failed error=${event.data.error}\n`);
+        break;
+      case "session.finished":
+        this.stdout.write(`session.finished reason=${event.data.reason}\n`);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+function formatToolRawResult(call: ToolCall, raw: ToolRawResult): string[] {
+  switch (raw.kind) {
+    case "write":
+    case "edit":
+      return optionalLine(formatDiff(call, raw));
+    case "bash":
+    case "task_output":
+      return optionalLine(formatBashResult(call, raw));
+    case "task_list":
+    case "task_stop":
+      return optionalLine(formatTaskResult(call, raw));
+    case "read":
+    case "glob":
+    case "grep":
+    case "web_search":
+    case "web_fetch":
+    case "recall":
+    case "mcp":
+    case "generic":
+      return [];
+    default:
+      return assertNever(raw);
+  }
+}
+
+function optionalLine(line: string | undefined): string[] {
+  return line === undefined ? [] : [line];
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled tool raw result: ${JSON.stringify(value)}`);
+}
+
+function formatDiff(call: ToolCall, raw: ToolRawResult): string | undefined {
+  if (raw.kind !== "edit" && raw.kind !== "write") {
+    return undefined;
+  }
+  if (!raw.ok) {
+    return undefined;
+  }
+
+  const hunks = parseDiffHunks(raw.patch);
+  if (hunks === undefined || hunks.length === 0) {
+    return undefined;
+  }
+
+  const changes = countPatchChanges(hunks);
+  const filePath = toolFilePath(call);
+  const lines: string[] = [
+    `tool.diff name=${call.name}${filePath === undefined ? "" : ` path=${filePath}`} +${changes.additions} -${changes.deletions}`,
+  ];
+
+  for (const hunk of hunks) {
+    lines.push(
+      `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`,
+    );
+    lines.push(...hunk.lines);
+  }
+
+  if (raw.patchTruncated === true) {
+    lines.push("(diff truncated)");
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function formatBashResult(_call: ToolCall, raw: ToolRawResult): string | undefined {
+  if (raw.kind !== "bash" && raw.kind !== "task_output") {
+    return undefined;
+  }
+
+  const detail = bashResultDetail(raw);
+  if (detail === undefined) {
+    return undefined;
+  }
+
+  const lines = detail.command
+    .split("\n")
+    .map((line, index) => (index === 0 ? `$ ${line}` : `  ${line}`));
+  lines.push(...(detail.outputPreview ?? []));
+
+  const omitted = detail.omittedOutputLines ?? 0;
+  if (omitted > 0) {
+    const location =
+      detail.outputFilePath === undefined
+        ? ""
+        : ` (full output: ${detail.outputFilePath})`;
+    lines.push(`… +${omitted} line${omitted === 1 ? "" : "s"}${location}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+function formatTaskResult(_call: ToolCall, raw: ToolRawResult): string | undefined {
+  if (!raw.ok) {
+    return undefined;
+  }
+
+  if (raw.kind === "task_list") {
+    return `task.list total=${raw.tasks.length} running=${raw.runningCount}\n`;
+  }
+
+  if (raw.kind === "task_stop") {
+    if (raw.status !== undefined) {
+      const signal = raw.task?.signal;
+      return `task.stop task=${raw.taskId} status=${raw.status}${signal === undefined ? "" : ` signal=${signal}`}\n`;
+    }
+  }
+
+  return undefined;
+}
+
+function formatToolLine(prefix: string, call: ToolCall): string {
+  if (call.name === "Bash") {
+    const description = bashDescription(call);
+    return `${prefix} name=${call.name}${description === undefined ? "" : ` desc=${description}`}\n`;
+  }
+
+  if (call.name === "Grep" || call.name === "Glob") {
+    const pattern = toolPattern(call);
+    return `${prefix} name=${call.name}${pattern === undefined ? "" : ` pattern=${pattern}`}\n`;
+  }
+
+  if (call.name === "WebSearch") {
+    const query = toolQuery(call);
+    return `${prefix} name=${call.name}${query === undefined ? "" : ` query=${query}`}\n`;
+  }
+
+  if (call.name === "WebFetch") {
+    const url = toolUrl(call);
+    return `${prefix} name=${call.name}${url === undefined ? "" : ` url=${url}`}\n`;
+  }
+
+  if (call.name === "TaskList") {
+    return `${prefix} name=${call.name}\n`;
+  }
+
+  if (call.name === "TaskOutput" || call.name === "TaskStop") {
+    const taskId = toolTaskId(call);
+    return `${prefix} name=${call.name}${taskId === undefined ? "" : ` task=${taskId}`}\n`;
+  }
+
+  const filePath = toolFilePath(call);
+  return `${prefix} name=${call.name}${filePath === undefined ? "" : ` path=${filePath}`}\n`;
+}
+
+function bashDescription(call: ToolCall): string | undefined {
+  if (
+    typeof call.args === "object" &&
+    call.args !== null &&
+    !Array.isArray(call.args)
+  ) {
+    if ("description" in call.args && typeof call.args.description === "string") {
+      return call.args.description;
+    }
+
+    if ("command" in call.args && typeof call.args.command === "string") {
+      return call.args.command;
+    }
+  }
+
+  return undefined;
+}
+
+function toolPattern(call: ToolCall): string | undefined {
+  if (
+    typeof call.args === "object" &&
+    call.args !== null &&
+    !Array.isArray(call.args) &&
+    "pattern" in call.args &&
+    typeof call.args.pattern === "string"
+  ) {
+    return call.args.pattern;
+  }
+
+  return undefined;
+}
+
+function toolQuery(call: ToolCall): string | undefined {
+  if (
+    typeof call.args === "object" &&
+    call.args !== null &&
+    !Array.isArray(call.args) &&
+    "query" in call.args &&
+    typeof call.args.query === "string"
+  ) {
+    return call.args.query;
+  }
+
+  return undefined;
+}
+
+function toolUrl(call: ToolCall): string | undefined {
+  if (
+    typeof call.args === "object" &&
+    call.args !== null &&
+    !Array.isArray(call.args) &&
+    "url" in call.args &&
+    typeof call.args.url === "string"
+  ) {
+    return call.args.url;
+  }
+
+  return undefined;
+}
+
+function toolFilePath(call: ToolCall): string | undefined {
+  if (
+    typeof call.args === "object" &&
+    call.args !== null &&
+    !Array.isArray(call.args) &&
+    "file_path" in call.args &&
+    typeof call.args.file_path === "string"
+  ) {
+    return call.args.file_path;
+  }
+
+  return undefined;
+}
+
+function toolTaskId(call: ToolCall): string | undefined {
+  const args = asRecord(call.args);
+  return stringProperty(args, "task_id");
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function stringProperty(
+  record: Record<string, unknown>,
+  property: string,
+): string | undefined {
+  return typeof record[property] === "string" ? record[property] : undefined;
+}

package/src/events/types.ts

@@ -0,0 +1,263 @@
+import type {
+  IterationIdentity,
+  ToolCall,
+  ToolCallIdentity,
+  TurnCancellation,
+  TurnIdentity,
+} from "../agent/types";
+import type {
+  IterationId,
+  ProtocolFrameId,
+  SessionId,
+  ToolCallId,
+  TurnId,
+} from "../ids/runtime-id";
+import type { ModelRequestOutput } from "../model/model-client";
+import type {
+  ModelContextBudget,
+  ModelContextProfile,
+} from "../model/model-context-profile";
+import type { ContextUsageSnapshot } from "../agent/context-meter";
+import type { ShellTaskSnapshot } from "../tools/bash-task";
+import type { ToolObservation } from "../observation/observation-builder";
+import type { ToolRawResult } from "../tools/types";
+import type {
+  ProjectInstructionFileName,
+  ProjectInstructionManifest,
+} from "../instructions/project-instructions";
+
+export type SessionStartedData = {
+  workspaceRoot: string;
+  model: string;
+  profileName?: string;
+  maxIterations: number;
+  includeReasoningContent: boolean;
+  contextProfile: ModelContextProfile;
+  contextBudget: ModelContextBudget;
+  projectInstructions: {
+    instruction?: ProjectInstructionManifest;
+  };
+};
+
+export type ContextUsageUpdatedData = {
+  phase: "initial" | "preflight" | "measured" | "revision";
+  snapshot: ContextUsageSnapshot;
+};
+
+export type ContextRevisionStartedData = {
+  strategy: "swap";
+  reason: "manual";
+  policyVersion: "swap-only-v1";
+  rendererFormat: "swap-observation-v1";
+};
+
+export type ContextRevisionFinishedData = {
+  strategy: "swap";
+  reason: "manual";
+  policyVersion: "swap-only-v1";
+  outcome:
+    | "below_target"
+    | "no_eligible_candidates"
+    | "target_reached"
+    | "insufficient_candidates";
+  baseRevisionNumber: number;
+  revisionNumber?: number;
+  addedOverrideCount: number;
+  totalOverrideCount: number;
+  originalObservationBytes: number;
+  projectedObservationBytes: number;
+  rawTokensBefore: number;
+  rawTokensAfter?: number;
+  guardedTokensBefore: number;
+  guardedTokensAfter?: number;
+  targetTokens: number;
+  planHash?: string;
+  durationMs: number;
+};
+
+export type ContextRevisionFailedData = {
+  strategy: "swap";
+  reason: "manual";
+  stage: "snapshot" | "plan" | "validate" | "commit" | "activate";
+  errorCode: string;
+  error: string;
+};
+
+export type ContextShadowPlannedData = {
+  policyVersion: "swap-only-v1";
+  trigger: "runtime_pressure" | "benchmark_forced";
+  outcome:
+    | "below_trigger"
+    | "below_target"
+    | "no_eligible_candidates"
+    | "target_reached"
+    | "insufficient_candidates";
+  canonicalMessageCount: number;
+  eligibleCandidateCount: number;
+  selectedCandidateCount: number;
+  excludedByReason: Record<string, number>;
+  selectedByRawKind: Record<string, number>;
+  originalObservationBytes: number;
+  projectedObservationBytes: number;
+  rawTokensBefore: number;
+  rawTokensAfter?: number;
+  guardedTokensBefore: number;
+  guardedTokensAfter?: number;
+  targetTokens: number;
+  planHash?: string;
+  durationMs: number;
+};
+
+export type ContextShadowFailedData = {
+  policyVersion: "swap-only-v1";
+  stage: "candidate" | "render" | "prepare" | "validate";
+  errorCode: string;
+  error: string;
+};
+
+export type SessionFinishedData = {
+  reason:
+    | "oneshot_complete"
+    | "tui_exit"
+    | "session_switch"
+    | "runner_failed"
+    | "initialization_failed";
+  error?: string;
+};
+
+export type SessionResumedData = {
+  openCount: number;
+  recoveredTurnId?: TurnId;
+  recoveredFrameId?: ProtocolFrameId;
+  syntheticCompletionCount: number;
+  recallIndexRebuilt: boolean;
+  projectInstructionFile?: ProjectInstructionFileName;
+};
+
+export type InterruptedFrameRecoveredData = {
+  turnId: TurnId;
+  frameId: ProtocolFrameId;
+  syntheticCompletionCount: number;
+};
+
+export type TurnFinishedData = {
+  status: "completed";
+  finalText: string;
+  lastIteration: IterationIdentity;
+  messageCount: number;
+};
+
+export type AgentEventDataMap = {
+  "session.started": SessionStartedData;
+  "session.resumed": SessionResumedData;
+  "session.interrupted_frame_recovered": InterruptedFrameRecoveredData;
+  "session.finished": SessionFinishedData;
+  "turn.started": { userPrompt: string };
+  "turn.finished": TurnFinishedData;
+  "turn.failed": { error: string };
+  "turn.cancelled": { cancellation: TurnCancellation };
+  "agent.iteration.started": { iterationNumber: number };
+  "model.request.started": Record<string, never>;
+  "model.request.finished": { output: ModelRequestOutput };
+  "context.usage.updated": ContextUsageUpdatedData;
+  "context.revision.started": ContextRevisionStartedData;
+  "context.revision.finished": ContextRevisionFinishedData;
+  "context.revision.failed": ContextRevisionFailedData;
+  "context.shadow.planned": ContextShadowPlannedData;
+  "context.shadow.failed": ContextShadowFailedData;
+  "assistant.progress": { content: string };
+  "tool.started": { call: ToolCall };
+  "tool.raw_result": { call: ToolCall; raw: ToolRawResult };
+  "tool.finished": { call: ToolCall; ok: boolean };
+  "tool.observation": { call: ToolCall; observation: ToolObservation };
+  "agent.iteration.finished": {
+    outcome: "continue" | "completed";
+    toolCallCount: number;
+  };
+  "bash.task.backgrounded": { task: ShellTaskSnapshot };
+  "bash.task.stopping": { task: ShellTaskSnapshot };
+  "bash.task.finished": { task: ShellTaskSnapshot };
+  "mcp.server.connected": { serverName: string; toolCount: number };
+  "mcp.server.failed": { serverName: string; error: string };
+  "diagnostic.sink_failed": {
+    sinkName: string;
+    failedEventType: AgentEventType;
+    error: string;
+  };
+};
+
+export type AgentEventType = keyof AgentEventDataMap;
+
+type AgentEventEnvelope<TType extends AgentEventType> = {
+  type: TType;
+  sessionId: SessionId;
+  turnId?: TurnId;
+  iterationId?: IterationId;
+  toolCallId?: ToolCallId;
+  turnNumber?: number;
+  iterationNumber?: number;
+  toolCallNumber?: number;
+  eventSequence: number;
+  timestamp: string;
+  data: AgentEventDataMap[TType];
+};
+
+export type AgentEvent = {
+  [TType in AgentEventType]: AgentEventEnvelope<TType>;
+}[AgentEventType];
+
+type SessionEventInput<TType extends AgentEventType> = {
+  type: TType;
+  sessionId: SessionId;
+  data: AgentEventDataMap[TType];
+};
+
+type TurnEventInput<TType extends AgentEventType> = TurnIdentity & {
+  type: TType;
+  data: AgentEventDataMap[TType];
+};
+
+type IterationEventInput<TType extends AgentEventType> = IterationIdentity & {
+  type: TType;
+  data: AgentEventDataMap[TType];
+};
+
+type ToolEventInput<TType extends AgentEventType> = ToolCallIdentity & {
+  type: TType;
+  data: AgentEventDataMap[TType];
+};
+
+export type AgentEventInput =
+  | SessionEventInput<
+      | "session.started"
+      | "session.resumed"
+      | "session.interrupted_frame_recovered"
+      | "session.finished"
+      | "context.usage.updated"
+      | "context.revision.started"
+      | "context.revision.finished"
+      | "context.revision.failed"
+    >
+  | SessionEventInput<"mcp.server.connected" | "mcp.server.failed">
+  | SessionEventInput<"diagnostic.sink_failed">
+  | TurnEventInput<"turn.started" | "turn.finished">
+  | (
+      | TurnEventInput<"turn.failed" | "turn.cancelled">
+      | IterationEventInput<"turn.failed" | "turn.cancelled">
+    )
+  | IterationEventInput<
+      | "agent.iteration.started"
+      | "model.request.started"
+      | "model.request.finished"
+      | "context.usage.updated"
+      | "context.shadow.planned"
+      | "context.shadow.failed"
+      | "assistant.progress"
+      | "agent.iteration.finished"
+    >
+  | ToolEventInput<
+      "tool.started" | "tool.raw_result" | "tool.finished" | "tool.observation"
+    >
+  | ToolEventInput<
+      "bash.task.backgrounded" | "bash.task.stopping" | "bash.task.finished"
+    >;