@twinklerg/coden 0.1.0

package/src/providers/openai.ts

@@ -0,0 +1,96 @@
+import OpenAI from "openai";
+import type { AgentMessage, ModelEvent, ModelProvider, ModelRequest } from "../core/types.js";
+
+export interface OpenAIProviderOptions {
+  apiKey: string;
+  baseURL?: string;
+}
+
+type ReasoningDelta = {
+  reasoning_content?: string | null;
+};
+
+export class OpenAICompatibleProvider implements ModelProvider {
+  private readonly client: OpenAI;
+  constructor(options: OpenAIProviderOptions) {
+    this.client = new OpenAI({ ...options, maxRetries: 0 });
+  }
+  async *stream(request: ModelRequest): AsyncIterable<ModelEvent> {
+    const response = await this.client.chat.completions.create(
+      {
+        model: request.model,
+        messages: toOpenAIMessages(request.messages),
+        ...(request.tools.length
+          ? {
+              tools: request.tools.map((tool) => ({
+                type: "function" as const,
+                function: {
+                  name: tool.name,
+                  description: tool.description,
+                  parameters: tool.inputSchema,
+                },
+              })),
+            }
+          : {}),
+        max_completion_tokens: request.maxOutputTokens,
+        stream: true,
+        stream_options: { include_usage: true },
+      },
+      request.signal ? { signal: request.signal } : undefined,
+    );
+    const started = new Set<number>();
+    for await (const chunk of response) {
+      const delta = chunk.choices[0]?.delta;
+      const reasoning = (delta as (typeof delta & ReasoningDelta) | undefined)?.reasoning_content;
+      if (reasoning) yield { type: "reasoning_delta", text: reasoning };
+      if (delta?.content) yield { type: "text_delta", text: delta.content };
+      for (const call of delta?.tool_calls ?? []) {
+        const index = call.index;
+        if (!started.has(index)) {
+          started.add(index);
+          yield {
+            type: "tool_call_start",
+            index,
+            callId: call.id ?? `call_${index}`,
+            name: call.function?.name ?? "",
+          };
+        }
+        if (call.function?.arguments)
+          yield { type: "tool_call_delta", index, argumentsDelta: call.function.arguments };
+      }
+      if (chunk.usage)
+        yield {
+          type: "usage",
+          usage: {
+            inputTokens: chunk.usage.prompt_tokens,
+            outputTokens: chunk.usage.completion_tokens,
+          },
+        };
+    }
+    for (const index of started) yield { type: "tool_call_end", index };
+    yield { type: "done" };
+  }
+}
+
+export function toOpenAIMessages(
+  messages: AgentMessage[],
+): OpenAI.Chat.Completions.ChatCompletionMessageParam[] {
+  return messages.map((message) => {
+    if (message.role === "system" || message.role === "user")
+      return { role: message.role, content: message.content };
+    if (message.role === "tool")
+      return { role: "tool", tool_call_id: message.callId, content: message.content };
+    const assistant: OpenAI.Chat.Completions.ChatCompletionAssistantMessageParam = {
+      role: "assistant",
+      content: message.content || null,
+    };
+    if (message.toolCalls.length) {
+      assistant.tool_calls = message.toolCalls.map((call) => ({
+        id: call.callId,
+        type: "function" as const,
+        function: { name: call.name, arguments: JSON.stringify(call.input) },
+      }));
+    }
+    return assistant;
+  });
+}

package/src/providers/scripted.ts

@@ -0,0 +1,28 @@
+import type { ModelEvent, ModelProvider, ModelRequest } from "../core/types.js";
+
+export type ScriptStep = ModelEvent[] | Error | ((request: ModelRequest) => ModelEvent[] | Error);
+export class ScriptedProvider implements ModelProvider {
+  readonly requests: ModelRequest[] = [];
+  constructor(private readonly steps: ScriptStep[]) {}
+  async *stream(request: ModelRequest): AsyncIterable<ModelEvent> {
+    this.requests.push(request);
+    const step = this.steps.shift();
+    if (!step) throw new Error("ScriptedProvider exhausted");
+    const result = typeof step === "function" ? step(request) : step;
+    if (result instanceof Error) throw result;
+    for (const event of result) yield event;
+  }
+}
+
+export function scriptedText(text: string): ModelEvent[] {
+  return [{ type: "text_delta", text }, { type: "done" }];
+}
+export function scriptedTool(callId: string, name: string, input: unknown): ModelEvent[] {
+  const json = JSON.stringify(input);
+  return [
+    { type: "tool_call_start", index: 0, callId, name },
+    { type: "tool_call_delta", index: 0, argumentsDelta: json },
+    { type: "tool_call_end", index: 0 },
+    { type: "done" },
+  ];
+}

package/src/sessions/store.ts

@@ -0,0 +1,278 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, chmod, mkdir, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import type { AgentMessage } from "../core/types.js";
+
+interface SessionRecord {
+  version: 1;
+  id: string;
+  timestamp: string;
+  type: string;
+  data: unknown;
+}
+export interface RecoveredSession {
+  messages: AgentMessage[];
+  summary?: string;
+  compactionRange?: { start: number; end: number };
+  warnings: string[];
+}
+export interface SessionMeta {
+  id: string;
+  title?: string;
+  messageCount: number;
+  lastActivity: string;
+}
+
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function isValidSessionId(id: string): boolean {
+  return SESSION_ID_RE.test(id);
+}
+
+export function workspaceHash(workspace: string): string {
+  return createHash("sha256").update(path.resolve(workspace)).digest("hex").slice(0, 16);
+}
+export class SessionStore {
+  readonly sessionPath: string;
+  readonly tracePath: string;
+  #queue = Promise.resolve();
+  constructor(
+    dataDir: string,
+    workspace: string,
+    readonly sessionId: string = randomUUID(),
+  ) {
+    if (!isValidSessionId(sessionId)) throw new Error("Invalid session ID");
+    const directory = path.join(dataDir, "sessions", workspaceHash(workspace));
+    this.sessionPath = path.join(directory, `${sessionId}.jsonl`);
+    this.tracePath = path.join(directory, `${sessionId}.trace.jsonl`);
+  }
+  async create(workspace: string): Promise<void> {
+    await this.append("session.created", { workspace, sessionId: this.sessionId });
+  }
+  append(type: string, data: unknown): Promise<void> {
+    const record: SessionRecord = {
+      version: 1,
+      id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      type,
+      data,
+    };
+    const operation = this.#queue.then(async () => {
+      const directory = path.dirname(this.sessionPath);
+      await mkdir(directory, { recursive: true, mode: 0o700 });
+      await chmod(directory, 0o700);
+      await appendFile(this.sessionPath, `${JSON.stringify(record)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+      });
+      await chmod(this.sessionPath, 0o600);
+    });
+    this.#queue = operation.catch(() => {});
+    return operation;
+  }
+  appendMessage(message: AgentMessage): Promise<void> {
+    return this.append("message", message);
+  }
+  appendCompaction(summary: string, sourceRange?: { start: number; end: number }): Promise<void> {
+    return this.append("context.compacted", sourceRange ? { summary, sourceRange } : { summary });
+  }
+  setTitle(title: string): Promise<void> {
+    return this.append("session.title", { title });
+  }
+
+  async list(): Promise<SessionMeta[]> {
+    const directory = path.dirname(this.sessionPath);
+    let names: string[];
+    try {
+      names = await readdir(directory);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
+    }
+    const metas: SessionMeta[] = [];
+    for (const name of names) {
+      // 会话文件形如 <id>.jsonl；trace 文件形如 <id>.trace.jsonl（同样以 .jsonl 结尾），须排除。
+      if (!name.endsWith(".jsonl") || name.endsWith(".trace.jsonl")) continue;
+      const id = name.slice(0, -".jsonl".length);
+      if (!isValidSessionId(id)) continue;
+      try {
+        metas.push(await this.#readMeta(path.join(directory, name), id));
+      } catch {
+        // Skip a session file that cannot be parsed.
+      }
+    }
+    metas.sort((a, b) => b.lastActivity.localeCompare(a.lastActivity));
+    return metas;
+  }
+
+  async #readMeta(filePath: string, id: string): Promise<SessionMeta> {
+    const text = await readFile(filePath, "utf8");
+    let messageCount = 0;
+    let title: string | undefined;
+    let firstUserPrompt: string | undefined;
+    let lastActivity = "";
+    for (const line of text.split("\n")) {
+      if (!line) continue;
+      let record: SessionRecord;
+      try {
+        record = JSON.parse(line) as SessionRecord;
+      } catch {
+        continue;
+      }
+      if (record.version !== 1) continue;
+      if (record.timestamp) lastActivity = record.timestamp;
+      switch (record.type) {
+        case "session.reset":
+          messageCount = 0;
+          firstUserPrompt = undefined;
+          title = undefined;
+          break;
+        case "session.title": {
+          const data = record.data as { title?: unknown };
+          if (typeof data?.title === "string") title = data.title;
+          break;
+        }
+        case "message":
+          messageCount++;
+          if (firstUserPrompt === undefined) {
+            const data = record.data as { role?: unknown; content?: unknown };
+            if (data?.role === "user" && typeof data.content === "string") {
+              firstUserPrompt = data.content;
+            }
+          }
+          break;
+      }
+    }
+    const resolvedTitle = title ?? firstUserPrompt;
+    const meta: SessionMeta = { id, messageCount, lastActivity };
+    if (resolvedTitle !== undefined) meta.title = resolvedTitle;
+    return meta;
+  }
+  async recover(): Promise<RecoveredSession> {
+    const messages: AgentMessage[] = [];
+    const warnings: string[] = [];
+    let summary: string | undefined;
+    let compactionRange: { start: number; end: number } | undefined;
+    const text = await readFile(this.sessionPath, "utf8");
+    const lines = text.split("\n");
+    let lastRecordIndex = -1;
+    for (let index = lines.length - 1; index >= 0; index--) {
+      if (lines[index]) {
+        lastRecordIndex = index;
+        break;
+      }
+    }
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index];
+      if (!line) continue;
+      let record: SessionRecord;
+      try {
+        record = JSON.parse(line) as SessionRecord;
+      } catch (error) {
+        if (index === lastRecordIndex) {
+          warnings.push("Ignored incomplete final JSONL record");
+          break;
+        }
+        throw invalidRecord(index, error);
+      }
+      try {
+        if (record.version !== 1) throw new Error("unsupported schema version");
+        if (record.type === "session.reset") {
+          messages.length = 0;
+          summary = undefined;
+          compactionRange = undefined;
+        }
+        if (record.type === "message") {
+          if (!isMessage(record.data)) throw new Error("invalid message structure");
+          messages.push(record.data);
+        }
+        if (record.type === "context.compacted") {
+          const data = record.data as {
+            summary?: unknown;
+            sourceRange?: { start?: unknown; end?: unknown };
+          };
+          if (typeof data?.summary !== "string") throw new Error("invalid compaction record");
+          summary = data.summary;
+          compactionRange =
+            typeof data.sourceRange?.start === "number" && typeof data.sourceRange.end === "number"
+              ? { start: data.sourceRange.start, end: data.sourceRange.end }
+              : undefined;
+        }
+      } catch (error) {
+        throw invalidRecord(index, error);
+      }
+    }
+    const repairs = repairTrailingToolCalls(messages, warnings);
+    for (const repair of repairs) await this.appendMessage(repair);
+    const recovered: RecoveredSession = { messages, warnings };
+    if (summary !== undefined) recovered.summary = summary;
+    if (compactionRange !== undefined) recovered.compactionRange = compactionRange;
+    return recovered;
+  }
+}
+function isMessage(value: unknown): value is AgentMessage {
+  if (!value || typeof value !== "object") return false;
+  const message = value as Record<string, unknown>;
+  if ((message.role === "system" || message.role === "user") && typeof message.content === "string")
+    return true;
+  if (message.role === "assistant" && typeof message.content === "string") {
+    return (
+      Array.isArray(message.toolCalls) &&
+      message.toolCalls.every(
+        (call) =>
+          !!call &&
+          typeof call === "object" &&
+          typeof (call as Record<string, unknown>).callId === "string" &&
+          typeof (call as Record<string, unknown>).name === "string" &&
+          "input" in (call as Record<string, unknown>),
+      )
+    );
+  }
+  return (
+    message.role === "tool" &&
+    typeof message.callId === "string" &&
+    typeof message.name === "string" &&
+    typeof message.content === "string" &&
+    typeof message.isError === "boolean"
+  );
+}
+function invalidRecord(index: number, error: unknown): Error {
+  return new Error(
+    `Invalid session record at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+function repairTrailingToolCalls(messages: AgentMessage[], warnings: string[]): AgentMessage[] {
+  const pending = new Map<string, string>();
+  const seen = new Set<string>();
+  for (const message of messages) {
+    if (message.role === "assistant") {
+      if (pending.size > 0)
+        throw new Error("Assistant message appeared before pending tool results");
+      for (const call of message.toolCalls) {
+        if (seen.has(call.callId)) throw new Error(`Duplicate tool call ID: ${call.callId}`);
+        seen.add(call.callId);
+        pending.set(call.callId, call.name);
+      }
+    } else if (message.role === "tool") {
+      if (!pending.delete(message.callId)) throw new Error(`Orphan tool result: ${message.callId}`);
+    } else if (pending.size > 0) {
+      throw new Error(`${message.role} message appeared before pending tool results`);
+    }
+  }
+  if (pending.size === 0) return [];
+  const repairs: AgentMessage[] = [];
+  for (const [callId, name] of pending) {
+    const repair: AgentMessage = {
+      role: "tool",
+      callId,
+      name,
+      content:
+        "runtime.interrupted: tool execution did not complete before the previous process exited",
+      isError: true,
+    };
+    messages.push(repair);
+    repairs.push(repair);
+  }
+  warnings.push(`Recovered ${pending.size} interrupted tool call(s)`);
+  return repairs;
+}

package/src/tools/builtin/bash.ts

@@ -0,0 +1,56 @@
+import { truncateOutput } from "../../context/truncate.js";
+import type { ToolDefinition } from "../../core/types.js";
+import { runProcess } from "../../process/runner.js";
+
+export const bashTool: ToolDefinition = {
+  name: "bash",
+  description: "Run a bash command in the workspace with timeout and bounded output.",
+  risk: "modify",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["command"],
+    properties: {
+      command: { type: "string", minLength: 1 },
+      timeout: { type: "integer", minimum: 100, maximum: 60000, default: 30000 },
+      maxOutput: { type: "integer", minimum: 1000, maximum: 100000, default: 30000 },
+    },
+  },
+  async execute(input, context) {
+    const {
+      command,
+      timeout = 30000,
+      maxOutput = 30000,
+    } = input as { command: string; timeout?: number; maxOutput?: number };
+    const result = await runProcess("bash", ["-lc", command], {
+      cwd: context.workspace,
+      env: process.env,
+      signal: context.signal,
+      timeoutMs: timeout,
+      maxOutputChars: maxOutput,
+    });
+    const combined = [
+      result.stdout && `stdout:\n${result.stdout}`,
+      result.stderr && `stderr:\n${result.stderr}`,
+    ]
+      .filter(Boolean)
+      .join("\n");
+    if (result.exitCode === null && !result.timedOut && !result.cancelled && result.signal === null)
+      return { content: `bash.spawn_error: ${result.stderr || "unknown error"}`, isError: true };
+    const status = result.timedOut
+      ? `Timed out after ${timeout}ms`
+      : result.cancelled
+        ? "Cancelled"
+        : `Exit code: ${result.exitCode ?? "null"}${result.signal ? ` (signal ${result.signal})` : ""}`;
+    return {
+      content: truncateOutput(`${status}\n${combined}`.trimEnd(), maxOutput),
+      isError: result.timedOut || result.cancelled || result.exitCode !== 0,
+      metadata: {
+        exitCode: result.exitCode,
+        signal: result.signal,
+        timedOut: result.timedOut,
+        cancelled: result.cancelled,
+      },
+    };
+  },
+};

package/src/tools/builtin/edit.ts

@@ -0,0 +1,42 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import type { ToolDefinition } from "../../core/types.js";
+import { resolveWorkspacePath } from "../../permissions/workspace.js";
+
+export const editTool: ToolDefinition = {
+  name: "edit",
+  description: "Replace one uniquely matching exact text block in a UTF-8 file.",
+  risk: "modify",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["path", "oldText", "newText"],
+    properties: {
+      path: { type: "string" },
+      oldText: { type: "string", minLength: 1 },
+      newText: { type: "string" },
+    },
+  },
+  async execute(input, context) {
+    const {
+      path: requested,
+      oldText,
+      newText,
+    } = input as { path: string; oldText: string; newText: string };
+    const target = await resolveWorkspacePath(context.workspace, requested);
+    const handle = await open(target, constants.O_RDWR | constants.O_NOFOLLOW);
+    try {
+      const content = await handle.readFile("utf8");
+      const first = content.indexOf(oldText);
+      if (first < 0) return { content: "edit.no_match: oldText was not found", isError: true };
+      if (content.indexOf(oldText, first + 1) >= 0)
+        return { content: "edit.multiple_matches: oldText is not unique", isError: true };
+      const updated = `${content.slice(0, first)}${newText}${content.slice(first + oldText.length)}`;
+      await handle.truncate(0);
+      await handle.write(updated, 0, "utf8");
+    } finally {
+      await handle.close();
+    }
+    return { content: `Edited ${requested}` };
+  },
+};

package/src/tools/builtin/index.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from "../../core/types.js";
+import { bashTool } from "./bash.js";
+import { editTool } from "./edit.js";
+import { readTool } from "./read.js";
+import { writeTool } from "./write.js";
+
+export function builtinTools(): ToolDefinition[] {
+  return [readTool, writeTool, editTool, bashTool];
+}

package/src/tools/builtin/read.ts

@@ -0,0 +1,91 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import type { ToolDefinition } from "../../core/types.js";
+import { resolveWorkspacePath } from "../../permissions/workspace.js";
+
+class BoundedText {
+  private text = "";
+  private omitted = 0;
+  constructor(private readonly limit: number) {}
+  add(value: string): void {
+    const available = Math.max(0, this.limit - this.text.length);
+    this.text += value.slice(0, available);
+    this.omitted += Math.max(0, value.length - available);
+  }
+  value(): string {
+    return this.omitted > 0
+      ? `${this.text}\n... [${this.omitted} selected characters omitted]`
+      : this.text;
+  }
+}
+
+export const readTool: ToolDefinition = {
+  name: "read",
+  description: "Read a UTF-8 text file by 1-based line offset and limit.",
+  risk: "read",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["path"],
+    properties: {
+      path: { type: "string" },
+      offset: { type: "integer", minimum: 1, default: 1 },
+      limit: { type: "integer", minimum: 1, maximum: 2000, default: 500 },
+    },
+  },
+  async execute(input, context) {
+    const {
+      path,
+      offset = 1,
+      limit = 500,
+    } = input as { path: string; offset?: number; limit?: number };
+    const target = await resolveWorkspacePath(context.workspace, path);
+    const output = new BoundedText(50_000);
+    let lineNumber = 1;
+    let selectedLines = 0;
+    let selectedStarted = false;
+    const selected = () => lineNumber >= offset && lineNumber < offset + limit;
+    const consume = (segment: string) => {
+      if (!selected()) return;
+      if (!selectedStarted) {
+        if (selectedLines > 0) output.add("\n");
+        selectedLines++;
+        selectedStarted = true;
+      }
+      output.add(segment);
+    };
+    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const stream = handle.createReadStream({
+        encoding: "utf8",
+        autoClose: false,
+        highWaterMark: 64 * 1024,
+        signal: context.signal,
+      });
+      for await (const raw of stream) {
+        const chunk = String(raw);
+        let start = 0;
+        for (
+          let newline = chunk.indexOf("\n", start);
+          newline >= 0;
+          newline = chunk.indexOf("\n", start)
+        ) {
+          consume(chunk.slice(start, newline));
+          lineNumber++;
+          selectedStarted = false;
+          start = newline + 1;
+        }
+        consume(chunk.slice(start));
+      }
+    } finally {
+      await handle.close();
+    }
+    consume("");
+    const totalLines = lineNumber;
+    const omittedLines = Math.max(0, totalLines - (offset - 1 + selectedLines));
+    return {
+      content: output.value() + (omittedLines > 0 ? `\n... [${omittedLines} lines omitted]` : ""),
+      metadata: { totalLines, offset, limit },
+    };
+  },
+};

package/src/tools/builtin/write.ts

@@ -0,0 +1,34 @@
+import { constants } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import path from "node:path";
+import type { ToolDefinition } from "../../core/types.js";
+import { resolveWorkspacePath } from "../../permissions/workspace.js";
+
+export const writeTool: ToolDefinition = {
+  name: "write",
+  description: "Create or overwrite a UTF-8 file inside the workspace.",
+  risk: "modify",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["path", "content"],
+    properties: { path: { type: "string" }, content: { type: "string" } },
+  },
+  async execute(input, context) {
+    const { path: requested, content } = input as { path: string; content: string };
+    let target = await resolveWorkspacePath(context.workspace, requested);
+    await mkdir(path.dirname(target), { recursive: true });
+    target = await resolveWorkspacePath(context.workspace, requested);
+    const handle = await open(
+      target,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW,
+      0o600,
+    );
+    try {
+      await handle.writeFile(content, "utf8");
+    } finally {
+      await handle.close();
+    }
+    return { content: `Wrote ${Buffer.byteLength(content)} bytes to ${requested}` };
+  },
+};