@strayl/agent 0.1.3 → 0.1.4

package/src/checkpoints/manager.ts

@@ -1,112 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { Message, TodoItem, Usage, CheckpointData } from "../types.js";
-import type { Emitter } from "../emitter.js";
-
-export type Checkpoint = CheckpointData;
-
-export class CheckpointManager {
-  private dir: string;
-  private checkpoints: Map<string, Checkpoint> = new Map();
-
-  constructor(workDir: string, sessionId: string) {
-    this.dir = path.join(workDir, ".strayl", "checkpoints", sessionId);
-  }
-
-  async init(): Promise<void> {
-    await fs.mkdir(this.dir, { recursive: true });
-
-    // Load existing checkpoints from disk
-    try {
-      const files = await fs.readdir(this.dir);
-      for (const file of files) {
-        if (!file.endsWith(".json")) continue;
-        try {
-          const content = await fs.readFile(path.join(this.dir, file), "utf-8");
-          const cp = JSON.parse(content) as Checkpoint;
-          this.checkpoints.set(cp.id, cp);
-        } catch {
-          // Corrupted checkpoint — skip
-        }
-      }
-    } catch {
-      // No checkpoints dir yet — fine
-    }
-  }
-
-  async save(
-    iteration: number,
-    messages: Message[],
-    todos: TodoItem[],
-    usage: Usage,
-    emitter: Emitter,
-  ): Promise<string> {
-    const id = `cp_${iteration}_${Date.now()}`;
-    const checkpoint: Checkpoint = {
-      id,
-      iteration,
-      timestamp: Date.now(),
-      messages: structuredClone(messages),
-      todos: structuredClone(todos),
-      usage: { ...usage },
-    };
-
-    this.checkpoints.set(id, checkpoint);
-
-    // Write atomically: tmp → rename
-    const tmpPath = path.join(this.dir, `${id}.tmp`);
-    const finalPath = path.join(this.dir, `${id}.json`);
-    await fs.writeFile(tmpPath, JSON.stringify(checkpoint));
-    await fs.rename(tmpPath, finalPath);
-
-    emitter.emit({ type: "checkpoint-saved", id, iteration, checkpoint });
-
-    // Keep only last 50 checkpoints on disk
-    await this.pruneOld(50);
-
-    return id;
-  }
-
-  get(id: string): Checkpoint | undefined {
-    return this.checkpoints.get(id);
-  }
-
-  /** Get the most recent checkpoint at or before the given iteration */
-  getByIteration(iteration: number): Checkpoint | undefined {
-    let best: Checkpoint | undefined;
-    for (const cp of this.checkpoints.values()) {
-      if (cp.iteration <= iteration) {
-        if (!best || cp.iteration > best.iteration) {
-          best = cp;
-        }
-      }
-    }
-    return best;
-  }
-
-  /** Get the latest checkpoint */
-  latest(): Checkpoint | undefined {
-    let best: Checkpoint | undefined;
-    for (const cp of this.checkpoints.values()) {
-      if (!best || cp.timestamp > best.timestamp) {
-        best = cp;
-      }
-    }
-    return best;
-  }
-
-  list(): Checkpoint[] {
-    return [...this.checkpoints.values()].sort((a, b) => a.iteration - b.iteration);
-  }
-
-  private async pruneOld(keep: number): Promise<void> {
-    const sorted = this.list();
-    if (sorted.length <= keep) return;
-
-    const toRemove = sorted.slice(0, sorted.length - keep);
-    for (const cp of toRemove) {
-      this.checkpoints.delete(cp.id);
-      await fs.unlink(path.join(this.dir, `${cp.id}.json`)).catch(() => {});
-    }
-  }
-}

package/src/context/manager.ts

@@ -1,185 +0,0 @@
-import type { Message, Usage, ContentPart } from "../types.js";
-import type { Emitter } from "../emitter.js";
-import type { LLMClient } from "../llm/client.js";
-import { summarizeMessages } from "./summarizer.js";
-import { trimContext } from "./trim.js";
-
-export class ContextManager {
-  private msgs: Message[] = [];
-  private totalUsageData: Usage = { input_tokens: 0, output_tokens: 0, cost: 0 };
-  private peakInput = 0;
-  private existingSummary: string | null;
-  private pendingSummary: Promise<string> | null = null;
-  readonly maxInputTokens: number;
-  private summarizationThreshold: number;
-  private preSummarizationRatio: number;
-
-  constructor(config: {
-    maxInputTokens: number;
-    summarizationThreshold?: number;
-    preSummarizationRatio?: number;
-    previousSummary?: string;
-  }) {
-    this.maxInputTokens = config.maxInputTokens;
-    // Pre-summarize at 65% (background, non-blocking — best UX)
-    this.preSummarizationRatio = config.preSummarizationRatio ?? 0.65;
-    // Hard summarize at 83% (Claude Code threshold — leaves room for completion)
-    this.summarizationThreshold = config.summarizationThreshold ?? Math.floor(config.maxInputTokens * 0.83);
-    this.existingSummary = config.previousSummary ?? null;
-  }
-
-  addSystem(content: string): void {
-    this.msgs.push({ role: "system", content });
-  }
-
-  addUser(content: string, images?: Array<{ base64: string; contentType: string }>): void {
-    if (images && images.length > 0) {
-      const parts: ContentPart[] = [{ type: "text", text: content }];
-      for (const img of images) {
-        parts.push({
-          type: "image_url",
-          image_url: { url: `data:${img.contentType};base64,${img.base64}` },
-        });
-      }
-      this.msgs.push({ role: "user", content: parts });
-    } else {
-      this.msgs.push({ role: "user", content });
-    }
-  }
-
-  addAssistant(text: string, toolCalls?: import("../types.js").ToolCall[]): void {
-    const msg: Message = { role: "assistant", content: text || null };
-    if (toolCalls && toolCalls.length > 0) {
-      msg.tool_calls = toolCalls;
-    }
-    this.msgs.push(msg);
-  }
-
-  addToolResult(toolCallId: string, toolName: string, result: string): void {
-    this.msgs.push({
-      role: "tool",
-      content: result,
-      tool_call_id: toolCallId,
-      name: toolName,
-    });
-  }
-
-  messages(): Message[] {
-    return [...this.msgs];
-  }
-
-  /** Replace messages (used by checkpoint restore) */
-  restoreMessages(msgs: Message[]): void {
-    this.msgs = structuredClone(msgs);
-    this.pendingSummary = null;
-  }
-
-  recordUsage(usage: { input_tokens: number; output_tokens: number; cost?: number }): void {
-    this.totalUsageData.input_tokens += usage.input_tokens;
-    this.totalUsageData.output_tokens += usage.output_tokens;
-    if (usage.cost) this.totalUsageData.cost = (this.totalUsageData.cost ?? 0) + usage.cost;
-    if (usage.input_tokens > this.peakInput) this.peakInput = usage.input_tokens;
-  }
-
-  totalUsage(): Usage {
-    return { ...this.totalUsageData };
-  }
-
-  peakInputTokens(): number {
-    return this.peakInput;
-  }
-
-  // ~4 chars per token estimation
-  estimateTokens(): number {
-    let total = 0;
-    for (const msg of this.msgs) {
-      const content = typeof msg.content === "string"
-        ? msg.content
-        : JSON.stringify(msg.content ?? "");
-      total += Math.ceil(content.length / 4);
-      if (msg.tool_calls) total += Math.ceil(JSON.stringify(msg.tool_calls).length / 4);
-    }
-    return total;
-  }
-
-  shouldPreSummarize(): boolean {
-    return this.estimateTokens() > this.maxInputTokens * this.preSummarizationRatio;
-  }
-
-  shouldSummarize(): boolean {
-    return this.estimateTokens() > this.summarizationThreshold;
-  }
-
-  maybeTriggerPreSummarization(client: LLMClient, emitter: Emitter): void {
-    if (!this.shouldPreSummarize() || this.pendingSummary) return;
-    this.pendingSummary = this.createSummary(client).catch(() => "");
-  }
-
-  async applyPendingSummary(emitter: Emitter): Promise<boolean> {
-    if (!this.pendingSummary) return false;
-    try {
-      const summary = await this.pendingSummary;
-      this.pendingSummary = null;
-      if (summary) {
-        this.replaceSummarizedMessages(summary, emitter);
-        return true;
-      }
-      return false;
-    } catch {
-      this.pendingSummary = null;
-      return false;
-    }
-  }
-
-  async summarize(client: LLMClient, emitter: Emitter): Promise<void> {
-    try {
-      const summary = await this.createSummary(client);
-      if (summary) {
-        this.replaceSummarizedMessages(summary, emitter);
-      }
-    } catch {
-      // Summarization is optimization, not critical
-    }
-  }
-
-  private async createSummary(client: LLMClient): Promise<string> {
-    return summarizeMessages(this.msgs, this.existingSummary, client);
-  }
-
-  private replaceSummarizedMessages(summary: string, emitter: Emitter): void {
-    const KEEP = 8;
-    if (this.msgs.length <= KEEP + 2) return; // Not enough to summarize
-
-    // Keep system messages (first 1-2) and last KEEP messages
-    const systemMsgs = this.msgs.filter(m => m.role === "system");
-    const recentMsgs = this.msgs.slice(-KEEP);
-
-    // Don't break tool call pairs
-    let startIdx = this.msgs.length - KEEP;
-    while (startIdx > systemMsgs.length && this.msgs[startIdx]?.role === "tool") {
-      startIdx--;
-    }
-    const keptRecent = this.msgs.slice(startIdx);
-
-    const removedCount = this.msgs.length - systemMsgs.length - keptRecent.length;
-
-    this.existingSummary = summary;
-    this.msgs = [
-      ...systemMsgs,
-      { role: "user", content: `[Previous conversation summary]\n${summary}` },
-      { role: "assistant", content: "I understand the context from the summary. Let me continue." },
-      ...keptRecent,
-    ];
-
-    emitter.emit({
-      type: "summarized",
-      removed_msgs: removedCount,
-      kept_msgs: keptRecent.length,
-      summary_chars: summary.length,
-    });
-  }
-
-  applyTrim(): void {
-    this.msgs = trimContext(this.msgs, this.maxInputTokens);
-  }
-}

package/src/context/summarizer.ts

@@ -1,104 +0,0 @@
-import type { Message } from "../types.js";
-import type { LLMClient } from "../llm/client.js";
-import { SUMMARIZATION_MODEL } from "../llm/models.js";
-import { LLMClient as LLMClientClass } from "../llm/client.js";
-
-const SUMMARIZATION_KEEP_MESSAGES = 20;
-const SUMMARIZATION_MAX_CHARS = 200_000;
-const MSG_TRUNCATE_THRESHOLD = 4000;
-const MSG_TRUNCATE_HEAD = 2000;
-const MSG_TRUNCATE_TAIL = 1500;
-
-const FRESH_SUMMARY_PROMPT = `You are a conversation summarizer for a coding agent.
-Extract the essential context so the agent can continue working without the original messages.
-
-You MUST include:
-- **Task**: What is being built/fixed and why
-- **Decisions**: Key architectural and implementation decisions with rationale
-- **Files changed**: Every file created, modified, or deleted (full relative paths)
-- **Current state**: What is done, what is in progress, what remains
-- **Unresolved issues**: Bugs, errors, or blockers not yet fixed
-- **Environment**: Packages installed, APIs configured, env vars set
-
-Be concise but maximize recall — losing a detail here means the agent loses it forever.
-Use bullet points. Do NOT include raw command output or tool call arguments.`;
-
-const INCREMENTAL_SUMMARY_PROMPT = `You are updating an existing conversation summary for a coding agent.
-
-Existing summary:
-{existing_summary}
-
-Incorporate the new messages below:
-- Add new files changed (full relative paths), decisions, and progress
-- Update current state to reflect the latest status
-- Remove information that has been superseded
-- Keep unresolved issues until they are explicitly fixed
-- Be concise but maximize recall — lost details cannot be recovered
-
-Output the complete updated summary, not a diff.`;
-
-export async function summarizeMessages(
-  messages: Message[],
-  existingSummary: string | null,
-  _parentClient: LLMClient,
-): Promise<string> {
-  // Create a dedicated client for summarization using a cheap model
-  const sumClient = new LLMClientClass({
-    modelTier: SUMMARIZATION_MODEL,
-    env: process.env as Record<string, string>,
-  });
-
-  // Format messages for summarization
-  const formatted = formatMessagesForSummary(messages);
-
-  const systemPrompt = existingSummary
-    ? INCREMENTAL_SUMMARY_PROMPT.replace("{existing_summary}", existingSummary)
-    : FRESH_SUMMARY_PROMPT;
-
-  const sumMessages: Message[] = [
-    { role: "system", content: systemPrompt },
-    { role: "user", content: formatted },
-  ];
-
-  // Collect response (no streaming needed)
-  let result = "";
-  for await (const chunk of sumClient.stream(sumMessages, [])) {
-    if (chunk.type === "text") result += chunk.text;
-  }
-
-  return result;
-}
-
-function formatMessagesForSummary(messages: Message[]): string {
-  // Skip system messages and previous summary messages
-  const relevant = messages.filter(
-    m => m.role !== "system" && !(typeof m.content === "string" && m.content.startsWith("[Previous conversation summary]")),
-  );
-
-  // Take last N messages
-  const toSummarize = relevant.slice(-SUMMARIZATION_KEEP_MESSAGES);
-
-  let totalChars = 0;
-  const parts: string[] = [];
-
-  for (const msg of toSummarize) {
-    let content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? "");
-
-    // Truncate long messages
-    if (content.length > MSG_TRUNCATE_THRESHOLD) {
-      content = content.slice(0, MSG_TRUNCATE_HEAD) +
-        `\n[... ${content.length - MSG_TRUNCATE_HEAD - MSG_TRUNCATE_TAIL} chars truncated ...]\n` +
-        content.slice(-MSG_TRUNCATE_TAIL);
-    }
-
-    const label = msg.role === "tool" ? `tool(${msg.name})` : msg.role;
-    const line = `[${label}]: ${content}`;
-
-    totalChars += line.length;
-    if (totalChars > SUMMARIZATION_MAX_CHARS) break;
-
-    parts.push(line);
-  }
-
-  return parts.join("\n\n");
-}

package/src/context/trim.ts

@@ -1,55 +0,0 @@
-import type { Message } from "../types.js";
-
-export function trimContext(messages: Message[], maxInputTokens: number): Message[] {
-  const estimateTokens = (msgs: Message[]): number => {
-    let total = 0;
-    for (const msg of msgs) {
-      const content = typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content ?? "");
-      total += Math.ceil(content.length / 4);
-      if (msg.tool_calls) total += Math.ceil(JSON.stringify(msg.tool_calls).length / 4);
-    }
-    return total;
-  };
-
-  const currentTokens = estimateTokens(messages);
-  if (currentTokens <= maxInputTokens) return messages;
-
-  // Keep first 2 messages (system prompt)
-  const kept: Message[] = messages.slice(0, 2);
-  const budget = maxInputTokens - estimateTokens(kept) - 100; // 100 token margin for trim notice
-
-  // Walk backwards from end, adding messages until budget is exhausted
-  const recent: Message[] = [];
-  let recentTokens = 0;
-
-  for (let i = messages.length - 1; i >= 2; i--) {
-    const msg = messages[i];
-    const msgTokens = Math.ceil(
-      (typeof msg.content === "string" ? msg.content.length : JSON.stringify(msg.content ?? "").length) / 4,
-    ) + (msg.tool_calls ? Math.ceil(JSON.stringify(msg.tool_calls).length / 4) : 0);
-
-    if (recentTokens + msgTokens > budget) break;
-    recent.unshift(msg);
-    recentTokens += msgTokens;
-  }
-
-  // Don't start with a tool message (breaks assistant↔tool pairing)
-  while (recent.length > 0 && recent[0].role === "tool") {
-    recent.shift();
-  }
-
-  const removedCount = messages.length - kept.length - recent.length;
-
-  if (removedCount > 0) {
-    kept.push({
-      role: "user",
-      content: `[Context trimmed: ${removedCount} older messages removed to fit within context window]`,
-    });
-    kept.push({
-      role: "assistant",
-      content: "Understood, I'll continue with the available context.",
-    });
-  }
-
-  return [...kept, ...recent];
-}

package/src/emitter.ts

@@ -1,14 +0,0 @@
-import type { AgentEvent } from "./types.js";
-
-export class Emitter {
-  private seq = 0;
-
-  emit(event: AgentEvent): void {
-    this.seq++;
-    process.stdout.write(JSON.stringify({ ...event, _seq: this.seq }) + "\n");
-  }
-
-  currentSeq(): number {
-    return this.seq;
-  }
-}

package/src/hitl/manager.ts

@@ -1,77 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import crypto from "node:crypto";
-
-/** Convert arbitrary tool call ID into a filesystem-safe filename */
-function safeFileName(id: string): string {
-  // If ID is short and clean, use it directly
-  if (/^[a-zA-Z0-9_-]{1,100}$/.test(id)) return id;
-  // Otherwise hash it — Gemini IDs contain | and base64 chars that break shells/filesystems
-  return crypto.createHash("sha256").update(id).digest("hex").slice(0, 32);
-}
-
-export class HITLManager {
-  private dir: string;
-  // Map original ID → safe filename (so proxy can look up by either)
-  private idMap = new Map<string, string>();
-
-  constructor(hitlDir?: string) {
-    this.dir = hitlDir ?? "/tmp/hitl";
-  }
-
-  async init(): Promise<void> {
-    await fs.mkdir(this.dir, { recursive: true });
-  }
-
-  /** Get the safe filename for a tool call ID */
-  safeId(id: string): string {
-    const cached = this.idMap.get(id);
-    if (cached) return cached;
-    const safe = safeFileName(id);
-    this.idMap.set(id, safe);
-    return safe;
-  }
-
-  async waitForResponse(id: string): Promise<{ decision: string; data?: unknown }> {
-    const safe = this.safeId(id);
-    const filePath = path.join(this.dir, `${safe}.json`);
-    const maxWait = 30 * 60 * 1000; // 30 minutes
-    const start = Date.now();
-
-    while (Date.now() - start < maxWait) {
-      if (await this.isCancelled()) {
-        return { decision: "reject" };
-      }
-
-      try {
-        const content = await fs.readFile(filePath, "utf-8");
-        const response = JSON.parse(content);
-        await fs.unlink(filePath).catch(() => {});
-        return response;
-      } catch {
-        // File doesn't exist yet
-      }
-
-      await new Promise(r => setTimeout(r, 500));
-    }
-
-    return { decision: "reject" }; // Timeout
-  }
-
-  async writeResponse(id: string, response: { decision: string; data?: unknown }): Promise<void> {
-    const safe = this.safeId(id);
-    const tmpPath = path.join(this.dir, `${safe}.tmp`);
-    const finalPath = path.join(this.dir, `${safe}.json`);
-    await fs.writeFile(tmpPath, JSON.stringify(response));
-    await fs.rename(tmpPath, finalPath);
-  }
-
-  async isCancelled(): Promise<boolean> {
-    try {
-      await fs.access(path.join(this.dir, "_cancel"));
-      return true;
-    } catch {
-      return false;
-    }
-  }
-}

package/src/hitl/transport.ts

@@ -1,13 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-export async function writeHITLResponse(
-  dir: string,
-  id: string,
-  response: unknown,
-): Promise<void> {
-  const tmpPath = path.join(dir, `${id}.tmp`);
-  const finalPath = path.join(dir, `${id}.json`);
-  await fs.writeFile(tmpPath, JSON.stringify(response));
-  await fs.rename(tmpPath, finalPath);
-}

package/src/index.ts

@@ -1,116 +0,0 @@
-#!/usr/bin/env node
-import { parseArgs } from "node:util";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { runAgent } from "./agent.js";
-
-const { values } = parseArgs({
-  options: {
-    model: { type: "string", default: "pro" },
-    mode: { type: "string", default: "normal" },
-    "session-id": { type: "string" },
-    prompt: { type: "string" },
-    image: { type: "string", multiple: true },
-    "blocked-tools": { type: "string", default: "" },
-    "extra-prompt-file": { type: "string" },
-    "hitl-dir": { type: "string", default: "/tmp/hitl" },
-    "skills-dir": { type: "string", default: "./skills" },
-    "previous-summary": { type: "string" },
-    "max-iterations": { type: "string", default: "200" },
-    "work-dir": { type: "string" },
-    "restore-checkpoint": { type: "string" },
-  },
-});
-
-// Session ID
-const sessionId = values["session-id"] ?? crypto.randomUUID();
-
-// Read user message from --prompt only (stdin is reserved for live commands)
-const userMessage = values.prompt;
-
-if (!userMessage) {
-  process.stderr.write("No user message provided. Use --prompt flag.\n");
-  process.exit(1);
-}
-
-// Load images if specified
-const MIME_TYPES: Record<string, string> = {
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".svg": "image/svg+xml",
-  ".bmp": "image/bmp",
-};
-
-const images: Array<{ base64: string; contentType: string }> = [];
-if (values.image) {
-  for (const imgPath of values.image) {
-    try {
-      const resolved = path.resolve(imgPath);
-      const buffer = await fs.readFile(resolved);
-      const ext = path.extname(resolved).toLowerCase();
-      const contentType = MIME_TYPES[ext] || "image/png";
-      images.push({ base64: buffer.toString("base64"), contentType });
-    } catch {
-      process.stderr.write(`Failed to read image: ${imgPath}\n`);
-      process.exit(1);
-    }
-  }
-}
-
-// Load checkpoint if specified
-let restoreCheckpoint: import("./types.js").CheckpointData | undefined;
-if (values["restore-checkpoint"]) {
-  try {
-    const cpContent = await fs.readFile(values["restore-checkpoint"], "utf-8");
-    restoreCheckpoint = JSON.parse(cpContent);
-  } catch {
-    process.stderr.write(`Failed to read checkpoint file: ${values["restore-checkpoint"]}\n`);
-    process.exit(1);
-  }
-}
-
-// Load extra prompt file if specified
-let systemPromptExtra: string | undefined;
-if (values["extra-prompt-file"]) {
-  try {
-    systemPromptExtra = await fs.readFile(values["extra-prompt-file"], "utf-8");
-  } catch (e) {
-    process.stderr.write(`Failed to read extra prompt file: ${values["extra-prompt-file"]}\n`);
-    process.exit(1);
-  }
-}
-
-// Validate mode
-const mode = values.mode as "normal" | "plan" | "implement";
-if (!["normal", "plan", "implement"].includes(mode)) {
-  process.stderr.write(`Invalid mode: ${values.mode}. Use normal, plan, or implement.\n`);
-  process.exit(1);
-}
-
-try {
-  await runAgent({
-    model: values.model!,
-    mode,
-    userMessage,
-    sessionId,
-    workDir: values["work-dir"] ?? process.cwd(),
-    env: process.env as Record<string, string>,
-    systemPromptExtra,
-    blockedTools: values["blocked-tools"]?.split(",").filter(Boolean),
-    maxIterations: parseInt(values["max-iterations"]!),
-    hitlDir: values["hitl-dir"],
-    skillsDir: values["skills-dir"],
-    previousSummary: values["previous-summary"],
-    restoreCheckpoint,
-    images: images.length > 0 ? images : undefined,
-  });
-} catch (e) {
-  const msg = e instanceof Error ? e.message : String(e);
-  process.stderr.write(`Agent error: ${msg}\n`);
-  process.exit(1);
-}
-
-process.exit(0);