tinker-agent 1.0.65 → 1.2.0

package/src/tui/prompt-history.ts

@@ -1,23 +1,66 @@
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import type { RuntimeIdFactory } from "../ids/runtime-id";
+import {
+  parseImageAssetId,
+  parseImageAttachmentId,
+  type ImageAttachmentId,
+} from "../image/image-types";
+import { stableJsonStringify } from "../model/model-request-preflight";
+import {
+  createPromptDraft,
+  validatePromptDraft,
+  type DraftImageAttachment,
+  type PromptDraft,
+  type PromptElement,
+} from "./prompt-draft";
 
 const DEFAULT_MAX_ENTRIES = 200;
 
+export type PromptHistoryEntry =
+  | { readonly version: 1; readonly text: string }
+  | {
+      readonly version: 2;
+      readonly text: string;
+      readonly elements: readonly PromptElement[];
+      readonly attachments: readonly DraftImageAttachment[];
+    };
+
+export type LoadedPromptHistoryRecord =
+  | {
+      readonly kind: "valid";
+      readonly lineNumber: number;
+      readonly entry: PromptHistoryEntry;
+    }
+  | {
+      readonly kind: "invalid";
+      readonly lineNumber: number;
+      readonly errorCode: "INVALID_JSON" | "UNSUPPORTED_VERSION" | "INVALID_ENTRY";
+    };
+
 export type PromptHistoryOptions = {
   filePath?: string;
   entries?: string[];
+  records?: LoadedPromptHistoryRecord[];
   maxEntries?: number;
 };
 
 export class PromptHistory {
   readonly filePath?: string;
   private readonly maxEntries: number;
-  private items: string[];
+  private items: LoadedPromptHistoryRecord[];
 
   constructor(options: PromptHistoryOptions = {}) {
     this.filePath = options.filePath;
     this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
-    this.items = trimToMax(options.entries ?? [], this.maxEntries);
+    const records =
+      options.records ??
+      (options.entries ?? []).map((text, index) => ({
+        kind: "valid" as const,
+        lineNumber: index + 1,
+        entry: Object.freeze({ version: 1 as const, text }),
+      }));
+    this.items = trimToMax(records, this.maxEntries);
   }
 
   static async load(
@@ -34,56 +77,285 @@ export class PromptHistory {
       throw error;
     }
 
-    const entries: string[] = [];
-    for (const line of content.split("\n")) {
+    const records: LoadedPromptHistoryRecord[] = [];
+    for (const [index, line] of content.split("\n").entries()) {
       if (line.trim() === "") {
         continue;
       }
-
-      const parsed = parsePromptLine(line);
-      if (parsed !== undefined) {
-        entries.push(parsed);
-      }
+      records.push(parsePromptLine(line, index + 1));
     }
+    return new PromptHistory({
+      filePath,
+      records,
+      maxEntries: options.maxEntries,
+    });
+  }
 
-    return new PromptHistory({ filePath, entries, maxEntries: options.maxEntries });
+  get records(): readonly LoadedPromptHistoryRecord[] {
+    return this.items;
   }
 
   get entries(): readonly string[] {
-    return this.items;
+    return this.items.flatMap((record) =>
+      record.kind === "valid" ? [record.entry.text] : [],
+    );
   }
 
-  async append(prompt: string): Promise<void> {
-    if (prompt === "" || this.items.at(-1) === prompt) {
+  async append(prompt: string | PromptDraft): Promise<void> {
+    const entry =
+      typeof prompt === "string"
+        ? Object.freeze({ version: 1 as const, text: prompt })
+        : historyEntryFromDraft(prompt);
+    if (entry.text === "") {
       return;
     }
-
-    this.items = trimToMax([...this.items, prompt], this.maxEntries);
+    const previous = this.items.at(-1);
+    if (
+      previous?.kind === "valid" &&
+      historySemanticKey(previous.entry) === historySemanticKey(entry)
+    ) {
+      return;
+    }
+    const lineNumber = (this.items.at(-1)?.lineNumber ?? 0) + 1;
+    this.items = trimToMax(
+      [...this.items, { kind: "valid", lineNumber, entry }],
+      this.maxEntries,
+    );
 
     if (this.filePath === undefined) {
       return;
     }
-
     await mkdir(path.dirname(this.filePath), { recursive: true });
-    await appendFile(this.filePath, `${JSON.stringify(prompt)}\n`, "utf8");
+    const serialized =
+      entry.version === 1 ? JSON.stringify(entry.text) : stableJsonStringify(entry);
+    await appendFile(this.filePath, `${serialized}\n`, "utf8");
   }
 }
 
-function parsePromptLine(line: string): string | undefined {
+export function restorePromptHistoryEntry(
+  entry: PromptHistoryEntry,
+  idFactory: Pick<RuntimeIdFactory, "createImageAttachmentId">,
+): PromptDraft {
+  if (entry.version === 1) {
+    return createPromptDraft(entry.text);
+  }
+  const remap = new Map<ImageAttachmentId, ImageAttachmentId>();
+  for (const attachment of entry.attachments) {
+    remap.set(attachment.attachmentId, idFactory.createImageAttachmentId());
+  }
+  const elements = entry.elements.map((element) =>
+    Object.freeze({
+      ...element,
+      attachmentId: requireRemapped(remap, element.attachmentId),
+      range: Object.freeze({ ...element.range }),
+    }),
+  );
+  const attachments = entry.attachments.map((attachment) =>
+    Object.freeze({
+      ...attachment,
+      attachmentId: requireRemapped(remap, attachment.attachmentId),
+      asset: Object.freeze({ ...attachment.asset }),
+    }),
+  );
+  const draft = Object.freeze({
+    editor: Object.freeze({
+      value: entry.text,
+      cursor: [...entry.text].length,
+    }),
+    elements: Object.freeze(elements),
+    attachments: Object.freeze(attachments),
+  });
+  validatePromptDraft(draft);
+  return draft;
+}
+
+function parsePromptLine(line: string, lineNumber: number): LoadedPromptHistoryRecord {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return { kind: "invalid", lineNumber, errorCode: "INVALID_JSON" };
+  }
+  if (typeof parsed === "string") {
+    return parsed === ""
+      ? { kind: "invalid", lineNumber, errorCode: "INVALID_ENTRY" }
+      : {
+          kind: "valid",
+          lineNumber,
+          entry: Object.freeze({ version: 1, text: parsed }),
+        };
+  }
+  if (!isRecord(parsed)) {
+    return { kind: "invalid", lineNumber, errorCode: "INVALID_ENTRY" };
+  }
+  if (parsed.version !== 2) {
+    return { kind: "invalid", lineNumber, errorCode: "UNSUPPORTED_VERSION" };
+  }
   try {
-    const parsed: unknown = JSON.parse(line);
-    return typeof parsed === "string" && parsed !== "" ? parsed : undefined;
+    const entry = decodeV2Entry(parsed);
+    return { kind: "valid", lineNumber, entry };
   } catch {
-    return undefined;
+    return { kind: "invalid", lineNumber, errorCode: "INVALID_ENTRY" };
+  }
+}
+
+function decodeV2Entry(record: Record<string, unknown>): PromptHistoryEntry {
+  assertKeys(record, ["version", "text", "elements", "attachments"]);
+  if (
+    typeof record.text !== "string" ||
+    !Array.isArray(record.elements) ||
+    !Array.isArray(record.attachments) ||
+    record.elements.length === 0
+  ) {
+    throw new Error("Invalid Prompt history v2 entry.");
+  }
+  const elements = record.elements.map((value): PromptElement => {
+    const element = requireRecord(value);
+    assertKeys(element, ["kind", "attachmentId", "label", "range"]);
+    const range = requireRecord(element.range);
+    assertKeys(range, ["start", "end"]);
+    if (
+      element.kind !== "image" ||
+      typeof element.attachmentId !== "string" ||
+      typeof element.label !== "string" ||
+      !Number.isSafeInteger(range.start) ||
+      !Number.isSafeInteger(range.end)
+    ) {
+      throw new Error("Invalid Prompt history image element.");
+    }
+    return Object.freeze({
+      kind: "image",
+      attachmentId: parseImageAttachmentId(element.attachmentId),
+      label: element.label,
+      range: Object.freeze({ start: range.start as number, end: range.end as number }),
+    });
+  });
+  const attachments = record.attachments.map((value): DraftImageAttachment => {
+    const attachment = requireRecord(value);
+    assertKeys(attachment, ["attachmentId", "asset", "originalName"]);
+    const asset = requireRecord(attachment.asset);
+    assertKeys(asset, ["assetId", "mimeType", "byteLength", "width", "height"]);
+    if (
+      typeof attachment.attachmentId !== "string" ||
+      typeof attachment.originalName !== "string" ||
+      typeof asset.assetId !== "string" ||
+      (asset.mimeType !== "image/png" &&
+        asset.mimeType !== "image/jpeg" &&
+        asset.mimeType !== "image/webp") ||
+      !Number.isSafeInteger(asset.byteLength) ||
+      !Number.isSafeInteger(asset.width) ||
+      !Number.isSafeInteger(asset.height)
+    ) {
+      throw new Error("Invalid Prompt history image attachment.");
+    }
+    return Object.freeze({
+      attachmentId: parseImageAttachmentId(attachment.attachmentId),
+      asset: Object.freeze({
+        assetId: parseImageAssetId(asset.assetId),
+        mimeType: asset.mimeType,
+        byteLength: asset.byteLength as number,
+        width: asset.width as number,
+        height: asset.height as number,
+      }),
+      originalName: attachment.originalName,
+    });
+  });
+  const draft = Object.freeze({
+    editor: Object.freeze({
+      value: record.text,
+      cursor: [...record.text].length,
+    }),
+    elements: Object.freeze(elements),
+    attachments: Object.freeze(attachments),
+  });
+  validatePromptDraft(draft);
+  return historyEntryFromDraft(draft);
+}
+
+function historyEntryFromDraft(draft: PromptDraft): PromptHistoryEntry {
+  validatePromptDraft(draft);
+  if (draft.elements.length === 0) {
+    return Object.freeze({ version: 1, text: draft.editor.value });
   }
+  return Object.freeze({
+    version: 2,
+    text: draft.editor.value,
+    elements: Object.freeze(
+      draft.elements.map((element) =>
+        Object.freeze({
+          ...element,
+          range: Object.freeze({ ...element.range }),
+        }),
+      ),
+    ),
+    attachments: Object.freeze(
+      draft.attachments.map((attachment) =>
+        Object.freeze({
+          ...attachment,
+          asset: Object.freeze({ ...attachment.asset }),
+        }),
+      ),
+    ),
+  });
+}
+
+function historySemanticKey(entry: PromptHistoryEntry): string {
+  return stableJsonStringify(
+    entry.version === 1
+      ? entry
+      : {
+          version: 2,
+          text: entry.text,
+          elements: entry.elements.map((element) => {
+            const { attachmentId, ...semantic } = element;
+            void attachmentId;
+            return semantic;
+          }),
+          attachments: entry.attachments.map((attachment) => {
+            const { attachmentId, ...semantic } = attachment;
+            void attachmentId;
+            return semantic;
+          }),
+        },
+  );
 }
 
-function trimToMax(entries: string[], maxEntries: number): string[] {
+function requireRemapped(
+  remap: ReadonlyMap<ImageAttachmentId, ImageAttachmentId>,
+  previous: ImageAttachmentId,
+): ImageAttachmentId {
+  const value = remap.get(previous);
+  if (value === undefined) {
+    throw new Error("Prompt history attachment remap is incomplete.");
+  }
+  return value;
+}
+
+function requireRecord(value: unknown): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new Error("Expected an object.");
+  }
+  return value;
+}
+
+function assertKeys(value: Record<string, unknown>, expected: readonly string[]): void {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  if (stableJsonStringify(actual) !== stableJsonStringify(wanted)) {
+    throw new Error("Prompt history object keys are invalid.");
+  }
+}
+
+function trimToMax<T>(entries: T[], maxEntries: number): T[] {
   return entries.length > maxEntries
     ? entries.slice(entries.length - maxEntries)
     : entries;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function isFileNotFound(error: unknown): boolean {
   return (
     typeof error === "object" &&

package/src/tui/slash-commands.ts

@@ -5,8 +5,16 @@ export type SlashCommand = {
 
 export const SLASH_COMMANDS: readonly SlashCommand[] = [
   { name: "status", description: "Show session and context details" },
-  { name: "compact", description: "Compact eligible historical tool output" },
+  { name: "skills", description: "Show available and active Agent Skills" },
+  { name: "mcp", description: "Show MCP servers and runtime tools" },
+  {
+    name: "compact",
+    description: "Swap tool output or retire a cold history prefix",
+  },
+  { name: "clear", description: "Start a new session and clear conversation" },
+  { name: "fork", description: "Clone the current session" },
   { name: "view", description: "View a local UTF-8 text file" },
+  { name: "copy", description: "Copy the last response as Markdown" },
   { name: "model", description: "Switch model profile (new session)" },
   { name: "resume", description: "Choose or resume a session" },
   { name: "session", description: "Manage stored sessions" },
@@ -15,8 +23,14 @@ export const SLASH_COMMANDS: readonly SlashCommand[] = [
 
 export type ParsedSlashCommand =
   | { type: "status" }
+  | { type: "skills" }
+  | { type: "mcp" }
   | { type: "compact" }
+  | { type: "compact_retire" }
+  | { type: "clear" }
+  | { type: "fork" }
   | { type: "view"; filePath: string }
+  | { type: "copy" }
   | { type: "quit" }
   | { type: "model" }
   | { type: "model_switch"; profileName: string }
@@ -49,11 +63,41 @@ export function parseSlashCommand(input: string): ParsedSlashCommand {
   if (command === "/status" && tokens.length === 1) {
     return { type: "status" };
   }
+  if (command === "/skills" && tokens.length === 1) {
+    return { type: "skills" };
+  }
+  if (command === "/mcp") {
+    if (tokens.length === 1) {
+      return { type: "mcp" };
+    }
+    throw new SlashCommandError("Usage: /mcp");
+  }
   if (command === "/compact") {
     if (tokens.length === 1) {
       return { type: "compact" };
     }
-    throw new SlashCommandError("Usage: /compact");
+    if (tokens.length === 2 && tokens[1] === "retire") {
+      return { type: "compact_retire" };
+    }
+    throw new SlashCommandError("Usage: /compact [retire]");
+  }
+  if (command === "/clear") {
+    if (tokens.length === 1) {
+      return { type: "clear" };
+    }
+    throw new SlashCommandError("Usage: /clear");
+  }
+  if (command === "/fork") {
+    if (tokens.length === 1) {
+      return { type: "fork" };
+    }
+    throw new SlashCommandError("Usage: /fork");
+  }
+  if (command === "/copy") {
+    if (tokens.length === 1) {
+      return { type: "copy" };
+    }
+    throw new SlashCommandError("Usage: /copy");
   }
   if (command === "/quit" && tokens.length === 1) {
     return { type: "quit" };

package/src/tui/tui-session-controller.ts

@@ -1,12 +1,21 @@
-import type { ContextCompactionResult } from "../context/context-manager";
+import type {
+  ContextCompactionResult,
+  ContextRetirementResult,
+} from "../context/context-manager";
 import type {
   ExecuteTurnInput,
+  AcceptedTurn,
   RuntimeSession,
+  RuntimeSkillsSnapshot,
   SessionDisposeReason,
 } from "../agent/runtime-session";
-import type { RunAgentResult } from "../agent/types";
+import type { RunAgentResult, UserMessage } from "../agent/types";
+import type { ImageAssetRef } from "../image/image-types";
+import type { ImportedImageAsset } from "../image/image-asset-store";
 import type { SessionId } from "../ids/runtime-id";
+import { createUuidV7 } from "../ids/uuid-v7";
 import type { ModelProfile } from "../cli/model-profiles";
+import type { McpInventorySnapshot } from "../mcp/mcp-manager";
 import { SessionCatalog, type SessionSummary } from "../session/session-catalog";
 import type { TuiProjectionStore } from "./tui-projection-store";
 
@@ -16,7 +25,20 @@ export type TuiSessionBinding = {
   workspaceRoot: string;
   profileName?: string;
   projectionStore: TuiProjectionStore;
-  executeTurn(userPrompt: string, signal: AbortSignal): Promise<RunAgentResult>;
+  skills(): RuntimeSkillsSnapshot;
+  mcp(): McpInventorySnapshot;
+  supportsImageInput?: () => boolean;
+  importImage?: (
+    sourcePath: string,
+    signal: AbortSignal,
+    prospectiveMessageImageCount: number,
+  ) => Promise<ImportedImageAsset>;
+  verifyImageAssets?: (
+    assets: readonly ImageAssetRef[],
+    signal: AbortSignal,
+  ) => Promise<void>;
+  admitTurn?: (userMessage: UserMessage, signal: AbortSignal) => Promise<AcceptedTurn>;
+  executeTurn(userMessage: UserMessage, signal: AbortSignal): Promise<RunAgentResult>;
 };
 
 export type TuiSessionController = {
@@ -24,6 +46,9 @@ export type TuiSessionController = {
   subscribe: (listener: () => void) => () => void;
   listSessions: () => Promise<readonly SessionSummary[]>;
   compact: () => Promise<ContextCompactionResult>;
+  retire: () => Promise<ContextRetirementResult>;
+  fork: () => Promise<SessionId>;
+  clear: () => Promise<void>;
   resume: (sessionId: SessionId) => Promise<void>;
   delete: (sessionId: SessionId) => Promise<void>;
   switchModel: (profile: ModelProfile) => Promise<void>;
@@ -47,6 +72,9 @@ export class DefaultTuiSessionController implements TuiSessionController {
     private readonly createSessionWithProfile: (
       profile: ModelProfile,
     ) => Promise<ManagedTuiSessionBinding>,
+    private readonly createFreshSession: (
+      current: TuiSessionBinding,
+    ) => Promise<ManagedTuiSessionBinding>,
   ) {
     this.binding = initial;
   }
@@ -68,31 +96,42 @@ export class DefaultTuiSessionController implements TuiSessionController {
     return this.serialize(() => this.binding.runtimeSession.compactContext());
   }
 
+  retire(): Promise<ContextRetirementResult> {
+    return this.serialize(() => this.binding.runtimeSession.retireContext());
+  }
+
+  fork(): Promise<SessionId> {
+    return this.serialize(async () => {
+      const targetSessionId = createUuidV7() as SessionId;
+      await this.replaceSession(
+        "Cannot clone the session while a turn, context operation, or background task is active.",
+        async (current) => {
+          await current.runtimeSession.cloneSession(targetSessionId);
+          return this.openSession(targetSessionId);
+        },
+      );
+      return targetSessionId;
+    });
+  }
+
+  clear(): Promise<void> {
+    return this.serialize(() =>
+      this.replaceSession(
+        "Cannot clear the session while a turn, context operation, or background task is active.",
+        (current) => this.createFreshSession(current),
+      ),
+    );
+  }
+
   resume(sessionId: SessionId): Promise<void> {
     return this.serialize(async () => {
-      const current = this.binding;
-      if (sessionId === current.sessionId) {
+      if (sessionId === this.binding.sessionId) {
         throw new Error(`Session ${sessionId} is already current.`);
       }
-      if (!current.runtimeSession.canSwitchSession()) {
-        throw new Error(
-          "Cannot switch sessions while a turn or background task is active.",
-        );
-      }
-
-      const target = await this.openSession(sessionId);
-      try {
-        await current.runtimeSession.dispose({ type: "session_switch" });
-      } catch (error) {
-        await target.runtimeSession
-          .dispose({ type: "runner_failed", error: errorMessage(error) })
-          .catch(() => undefined);
-        throw error;
-      }
-      this.binding = target;
-      for (const listener of this.listeners) {
-        listener();
-      }
+      await this.replaceSession(
+        "Cannot switch sessions while a turn or background task is active.",
+        () => this.openSession(sessionId),
+      );
     });
   }
 
@@ -101,34 +140,44 @@ export class DefaultTuiSessionController implements TuiSessionController {
   }
 
   switchModel(profile: ModelProfile): Promise<void> {
-    return this.serialize(async () => {
-      const current = this.binding;
-      if (!current.runtimeSession.canSwitchSession()) {
-        throw new Error(
-          "Cannot switch models while a turn or background task is active.",
-        );
-      }
-
-      const target = await this.createSessionWithProfile(profile);
-      try {
-        await current.runtimeSession.dispose({ type: "session_switch" });
-      } catch (error) {
-        await target.runtimeSession
-          .dispose({ type: "runner_failed", error: errorMessage(error) })
-          .catch(() => undefined);
-        throw error;
-      }
-      this.binding = target;
-      for (const listener of this.listeners) {
-        listener();
-      }
-    });
+    return this.serialize(() =>
+      this.replaceSession(
+        "Cannot switch models while a turn or background task is active.",
+        () => this.createSessionWithProfile(profile),
+      ),
+    );
   }
 
   dispose(reason: SessionDisposeReason): Promise<void> {
     return this.binding.runtimeSession.dispose(reason);
   }
 
+  private async replaceSession(
+    unavailableMessage: string,
+    createTarget: (
+      current: ManagedTuiSessionBinding,
+    ) => Promise<ManagedTuiSessionBinding>,
+  ): Promise<void> {
+    const current = this.binding;
+    if (!current.runtimeSession.canSwitchSession()) {
+      throw new Error(unavailableMessage);
+    }
+
+    const target = await createTarget(current);
+    try {
+      await current.runtimeSession.dispose({ type: "session_switch" });
+    } catch (error) {
+      await target.runtimeSession
+        .dispose({ type: "runner_failed", error: errorMessage(error) })
+        .catch(() => undefined);
+      throw error;
+    }
+    this.binding = target;
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+
   private serialize<T>(operation: () => Promise<T>): Promise<T> {
     if (this.operation !== undefined) {
       return Promise.reject(new Error("Another session operation is already running."));
@@ -157,9 +206,22 @@ export function managedTuiBinding(input: {
     profileName: input.profileName,
     projectionStore: input.projectionStore,
     runtimeSession: input.runtimeSession,
-    executeTurn: (userPrompt, signal) =>
+    skills: () => input.runtimeSession.skills(),
+    mcp: () => input.runtimeSession.mcp(),
+    supportsImageInput: () => input.runtimeSession.supportsImageInput(),
+    importImage: (sourcePath, signal, prospectiveMessageImageCount) =>
+      input.runtimeSession.importImage(
+        sourcePath,
+        signal,
+        prospectiveMessageImageCount,
+      ),
+    verifyImageAssets: (assets, signal) =>
+      input.runtimeSession.verifyImageAssets(assets, signal),
+    admitTurn: (userMessage, signal) =>
+      input.runtimeSession.admitTurn({ userMessage, signal }),
+    executeTurn: (userMessage, signal) =>
       input.runtimeSession.executeTurn({
-        userPrompt,
+        userMessage,
         signal,
       } satisfies ExecuteTurnInput),
   };