jeo-code 0.1.0

package/src/agent/engine.ts

@@ -0,0 +1,208 @@
+/**
+ * Reusable agentic tool-call loop — the shared core behind `joc team`
+ * (per-task executor) and `joc launch` (interactive coding agent).
+ *
+ * The model is driven in JSON tool-call mode: each step it emits exactly one
+ * `{ "tool": "...", "arguments": { ... } }` object; the engine dispatches it,
+ * appends the result to history, and continues until the model calls `done`
+ * or the step budget is exhausted.
+ */
+import { callLlm, type Message } from "./loop";
+import { extractJsonObject } from "./json";
+import { readTool, writeTool, editTool, bashTool, findTool, searchTool, type ToolResult } from "./tools";
+
+export interface ToolInvocation {
+  tool: string;
+  arguments?: Record<string, any>;
+}
+
+export type ToolHandler = (args: Record<string, any>, cwd: string) => Promise<ToolResult>;
+
+/** The default executor toolset (read / write / edit / bash / find / search). */
+export const DEFAULT_TOOLS: Record<string, ToolHandler> = {
+  read: (a, cwd) => readTool(a.filePath ?? a.path, a.lineRange, cwd),
+  write: (a, cwd) => writeTool(a.filePath ?? a.path, a.content ?? "", cwd),
+  edit: (a, cwd) => editTool(a.filePath ?? a.path, a.editBlock ?? a.edit ?? "", cwd),
+  bash: (a, cwd) => bashTool(a.command ?? a.cmd, cwd, typeof a.timeoutMs === "number" ? a.timeoutMs : undefined),
+  find: (a, cwd) => findTool(a.globPattern ?? a.pattern, cwd),
+  search: (a, cwd) => searchTool(a.pattern, a.globPattern ?? "*", cwd),
+};
+
+/** Tool-protocol description injected into the system prompt. */
+export const TOOL_PROTOCOL = [
+  "You have these tools (call exactly ONE per step):",
+  "1. read   {filePath, lineRange?}      — read a file (lineRange: \"start-end\", \"start-\", or \"start\")",
+  "2. write  {filePath, content}         — create/overwrite a file",
+  "3. edit   {filePath, editBlock}       — ≔A..B replace lines; ≔A+ insert after line A; ≔$ append EOF (payload on next line)",
+  "4. bash   {command, timeoutMs?}       — run a shell command (tests, build, mkdir, ...); timeoutMs default 120000",
+  "5. find   {globPattern}               — find files by name",
+  "6. search {pattern, globPattern?}     — grep for a pattern",
+  "7. done   {reason?}                   — call when the task is fully implemented AND verified",
+  "",
+  "Reply with STRICT JSON only — no prose, no code fences:",
+  '{ "tool": "<name>", "arguments": { ... } }',
+].join("\n");
+
+export function executorSystemPrompt(role = "Executor Agent, a senior software developer"): string {
+  return (
+    `You are the ${role}.\n` +
+    `Accomplish the user's request by calling tools and verifying your work.\n\n` +
+    `${TOOL_PROTOCOL}\n\n` +
+    `Always verify (run tests / execute the program) before calling done.`
+  );
+}
+
+export interface AgentLoopEvents {
+  onStep?(step: number): void;
+  onAssistant?(raw: string, invocation: ToolInvocation | null): void;
+  onToolResult?(tool: string, success: boolean, output: string): void;
+  onError?(message: string): void;
+}
+
+export interface AgentLoopOptions {
+  cwd: string;
+  maxSteps?: number;
+  model?: string;
+  /** Max generation tokens per step (drives the thinking budget). */
+  maxTokens?: number;
+  tools?: Record<string, ToolHandler>;
+  signal?: AbortSignal;
+  events?: AgentLoopEvents;
+}
+
+export interface AgentLoopResult {
+  done: boolean;
+  steps: number;
+  doneReason?: string;
+  /** Summed provider token usage across the turn's steps, when reported. */
+  usage?: { inputTokens: number; outputTokens: number };
+}
+
+/**
+ * Cap a tool result fed back to the model, keeping both ends: the head holds the
+ * start (e.g. a file's top / a command's invocation) and the tail holds what's
+ * usually decisive (test summaries, the final error). A pure head-cut loses that.
+ */
+export function truncateToolOutput(s: string, max = 4000): string {
+  if (s.length <= max) return s;
+  const head = Math.floor(max * 0.6);
+  const tail = max - head;
+  return `${s.slice(0, head)}\n…(${s.length - max} chars truncated)…\n${s.slice(s.length - tail)}`;
+}
+
+/**
+ * Drive `history` through the tool-call loop, mutating it in place so callers
+ * (e.g. an interactive REPL) can keep the conversation across multiple turns.
+ */
+export async function runAgentLoop(history: Message[], opts: AgentLoopOptions): Promise<AgentLoopResult> {
+  const { cwd } = opts;
+  const tools = opts.tools ?? DEFAULT_TOOLS;
+  const maxSteps = opts.maxSteps ?? 15;
+  const ev = opts.events ?? {};
+
+  let step = 1;
+  const acc = { inputTokens: 0, outputTokens: 0 };
+  let sawUsage = false;
+  const finish = (r: AgentLoopResult): AgentLoopResult => (sawUsage ? { ...r, usage: { ...acc } } : r);
+  // No-progress guard: weak/local models often repeat the same tool call without
+  // ever emitting `done`. Stop after MAX_REPEAT identical consecutive calls.
+  const MAX_REPEAT = 3;
+  // Consecutive-failure guard: a model that keeps emitting *different* but failing
+  // calls (bad edits, failing commands) would otherwise burn the whole step budget.
+  const MAX_FAILURES = 5;
+  let consecutiveFailures = 0;
+  let lastSig = "";
+  let repeatCount = 0;
+  while (step <= maxSteps) {
+    if (opts.signal?.aborted) {
+      return finish({ done: false, steps: step - 1, doneReason: "Cancelled." });
+    }
+    ev.onStep?.(step);
+
+    let responseText: string;
+    try {
+      responseText = await callLlm(history, {
+              jsonMode: true,
+              model: opts.model,
+              maxTokens: opts.maxTokens,
+              signal: opts.signal,
+              onUsage: u => { acc.inputTokens += u.inputTokens ?? 0; acc.outputTokens += u.outputTokens ?? 0; sawUsage = true; },
+            });
+    } catch (err) {
+      const message = (err as Error).message;
+      ev.onError?.(message);
+      // Surface the real cause so callers don't print a misleading "step limit" message.
+      return finish({ done: false, steps: step, doneReason: `Error: ${message}` });
+    }
+
+    let invocation: ToolInvocation;
+    try {
+      invocation = extractJsonObject<ToolInvocation>(responseText);
+    } catch (err) {
+      // Not valid tool-call JSON — show the model the error and let it retry.
+      ev.onAssistant?.(responseText, null);
+      history.push({ role: "assistant", content: responseText });
+      history.push({
+        role: "user",
+        content:
+          `Your last reply was not a valid tool call (${(err as Error).message}). ` +
+          `Reply with exactly one JSON object: {"tool":"<name>","arguments":{...}}.`,
+      });
+      step++;
+      continue;
+    }
+
+    ev.onAssistant?.(responseText, invocation);
+
+    if (invocation.tool === "done") {
+      return finish({ done: true, steps: step, doneReason: (invocation.arguments?.reason as string) ?? "" });
+    }
+
+    // Detect repeated identical tool calls (no forward progress).
+    const sig = `${invocation.tool}:${JSON.stringify(invocation.arguments ?? {})}`;
+    if (sig === lastSig) repeatCount++;
+    else {
+      repeatCount = 1;
+      lastSig = sig;
+    }
+    if (repeatCount >= MAX_REPEAT) {
+      return finish({
+        done: false,
+        steps: step,
+        doneReason: `Stopped: repeated the same '${invocation.tool}' call ${MAX_REPEAT}× with no new progress (the model never signaled done).`,
+      });
+    }
+
+    const handler = tools[invocation.tool];
+    let success: boolean;
+    let output: string;
+    if (!handler) {
+      success = false;
+      output = `Unknown tool: ${invocation.tool}. Available: ${Object.keys(tools).join(", ")}, done.`;
+    } else {
+      const res = await handler(invocation.arguments ?? {}, cwd);
+      success = res.success;
+      output = res.success ? res.output : (res.error ? (res.output ? `${res.error}\n${res.output}` : res.error) : res.output);
+    }
+
+    ev.onToolResult?.(invocation.tool, success, output);
+    history.push({ role: "assistant", content: responseText });
+    history.push({
+      role: "user",
+      content: `Tool [${invocation.tool}] result (${success ? "ok" : "fail"}):\n${truncateToolOutput(output)}`,
+    });
+
+    if (success) {
+      consecutiveFailures = 0;
+    } else if (++consecutiveFailures >= MAX_FAILURES) {
+      return finish({
+        done: false,
+        steps: step,
+        doneReason: `Stopped: ${MAX_FAILURES} consecutive failing tool calls (last '${invocation.tool}'); the model could not recover.`,
+      });
+    }
+    step++;
+  }
+
+  return finish({ done: false, steps: maxSteps });
+}

package/src/agent/json.ts

@@ -0,0 +1,87 @@
+/**
+ * Robust JSON object extraction for LLM tool-call responses.
+ *
+ * Models (especially non-jsonMode backends like Anthropic/Ollama) routinely
+ * wrap JSON in prose, ```json fences, or trailing commentary. This recovers the
+ * first balanced top-level `{...}` object, respecting strings and escapes.
+ */
+export function extractJsonObject<T = unknown>(text: string): T {
+  const raw = text.trim();
+
+  // Fast path: already pure JSON.
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    /* fall through to recovery */
+  }
+
+  // Strip common code fences and retry.
+  const defenced = raw.replace(/```(?:json|JSON)?/g, "").trim();
+  try {
+    return JSON.parse(defenced) as T;
+  } catch {
+    /* fall through to brace scan */
+  }
+
+  const parsedFromDefenced = findAndParseBalancedObject<T>(defenced);
+  if (parsedFromDefenced !== null) {
+    return parsedFromDefenced;
+  }
+  const parsedFromRaw = findAndParseBalancedObject<T>(raw);
+  if (parsedFromRaw !== null) {
+    return parsedFromRaw;
+  }
+  throw new Error(`No parseable JSON object found in model output: ${truncate(raw, 200)}`);
+}
+
+/** Like {@link extractJsonObject} but returns null instead of throwing. */
+export function tryExtractJsonObject<T = unknown>(text: string): T | null {
+  try {
+    return extractJsonObject<T>(text);
+  } catch {
+    return null;
+  }
+}
+
+/** Scan for a brace-balanced object starting at startIndex, ignoring braces inside strings. */
+function extractBalancedObject(text: string, startIndex: number): string | null {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = startIndex; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return text.slice(startIndex, i + 1);
+    }
+  }
+  return null;
+}
+
+function findAndParseBalancedObject<T>(text: string): T | null {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "{") {
+      const candidate = extractBalancedObject(text, i);
+      if (candidate) {
+        try {
+          return JSON.parse(candidate) as T;
+        } catch {
+          // ignore, try next
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function truncate(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n) + "…" : s;
+}

package/src/agent/loop.ts

@@ -0,0 +1,22 @@
+import { createModelManager, type Message as AiMessage } from "../ai";
+
+export type Message = AiMessage;
+
+export interface ChatOptions {
+  model?: string;
+  systemPrompt?: string;
+  temperature?: number;
+  maxTokens?: number;
+  jsonMode?: boolean;
+  signal?: AbortSignal;
+  onUsage?: (usage: import("../ai/types").Usage) => void;
+}
+
+const manager = createModelManager();
+
+export async function callLlm(
+  messages: Message[],
+  options: ChatOptions = {}
+): Promise<string> {
+  return manager.call(messages, options);
+}

package/src/agent/session.ts

@@ -0,0 +1,198 @@
+import type { Message } from "./loop";
+import { getLocalJocDir } from "./state";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+export interface SessionHeader {
+  type: "session";
+  version: number;
+  id: string;
+  timestamp: string;
+  cwd: string;
+}
+
+export interface SessionEntry {
+  type: "message";
+  timestamp: string;
+  message: Message;
+}
+
+export interface SessionSummary {
+  id: string;
+  timestamp: string;
+  cwd: string;
+  messageCount: number;
+  preview: string;
+  mtimeMs?: number;
+}
+
+export const SESSION_VERSION = 1;
+
+export function newSessionId(): string {
+  return crypto.randomUUID();
+}
+
+export function sessionsDir(cwd = process.cwd()): string {
+  return path.join(getLocalJocDir(cwd), "sessions");
+}
+
+export function sessionPath(id: string, cwd = process.cwd()): string {
+  return path.join(sessionsDir(cwd), `${id}.jsonl`);
+}
+
+export async function createSession(
+  cwd = process.cwd(),
+  id = newSessionId()
+): Promise<{ id: string; path: string }> {
+  const dir = sessionsDir(cwd);
+  await fs.mkdir(dir, { recursive: true });
+
+  const header: SessionHeader = {
+    type: "session",
+    version: SESSION_VERSION,
+    id,
+    timestamp: new Date().toISOString(),
+    cwd,
+  };
+
+  const file = sessionPath(id, cwd);
+  await fs.writeFile(file, JSON.stringify(header) + "\n", "utf8");
+
+  return { id, path: file };
+}
+
+export async function appendMessage(
+  id: string,
+  message: Message,
+  cwd = process.cwd()
+): Promise<void> {
+  const file = sessionPath(id, cwd);
+  const entry: SessionEntry = {
+    type: "message",
+    timestamp: new Date().toISOString(),
+    message,
+  };
+
+  await fs.appendFile(file, JSON.stringify(entry) + "\n", "utf8");
+}
+
+export async function loadSession(
+  id: string,
+  cwd = process.cwd()
+): Promise<{ header: SessionHeader; messages: Message[] }> {
+  const file = sessionPath(id, cwd);
+  let content: string;
+  try {
+    content = await fs.readFile(file, "utf8");
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      throw new Error(`Session ${id} not found: ${err.message}`);
+    }
+    throw err;
+  }
+
+  const lines = content.split("\n");
+  let header: SessionHeader | undefined;
+  const messages: Message[] = [];
+
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (entry && typeof entry === "object") {
+        if (entry.type === "session" && !header) {
+          header = entry as SessionHeader;
+        } else if (entry.type === "message") {
+          messages.push(entry.message);
+        }
+      }
+    } catch (err) {
+      if (!header) {
+        throw err;
+      }
+      continue;
+    }
+  }
+
+  if (!header) {
+    throw new Error(`Session header missing in session ${id}`);
+  }
+
+  return { header, messages };
+}
+
+export async function listSessions(cwd = process.cwd()): Promise<SessionSummary[]> {
+  const dir = sessionsDir(cwd);
+  let files: string[];
+  try {
+    files = await fs.readdir(dir);
+  } catch (err: any) {
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+
+  const jsonlFiles = files.filter(f => f.endsWith(".jsonl"));
+  const summaries: SessionSummary[] = [];
+
+  for (const file of jsonlFiles) {
+    try {
+      const filePath = path.join(dir, file);
+      const stat = await fs.stat(filePath);
+      const content = await fs.readFile(filePath, "utf8");
+      const lines = content.split("\n");
+      let header: SessionHeader | undefined;
+      let messageCount = 0;
+      let firstUserMessageContent: string | undefined;
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const entry = JSON.parse(line);
+          if (entry && typeof entry === "object") {
+            if (entry.type === "session" && !header) {
+              header = entry as SessionHeader;
+            } else if (entry.type === "message") {
+              messageCount++;
+              if (!firstUserMessageContent && entry.message?.role === "user") {
+                firstUserMessageContent = entry.message.content;
+              }
+            }
+          }
+        } catch (err) {
+          if (!header) {
+            throw err;
+          }
+          continue;
+        }
+      }
+
+      if (!header) {
+        continue;
+      }
+
+      const preview = firstUserMessageContent ? firstUserMessageContent.slice(0, 60) : "";
+
+      summaries.push({
+        id: header.id,
+        timestamp: header.timestamp,
+        cwd: header.cwd,
+        messageCount,
+        preview,
+        mtimeMs: stat.mtimeMs,
+      });
+    } catch {
+      // Tolerate malformed files (skip them)
+      continue;
+    }
+  }
+
+  summaries.sort((a, b) => (b.mtimeMs ?? 0) - (a.mtimeMs ?? 0));
+  return summaries;
+}
+
+export async function latestSessionId(cwd = process.cwd()): Promise<string | undefined> {
+  const list = await listSessions(cwd);
+  return list[0]?.id;
+}