@twinklerg/coden 0.1.0

package/src/core/events.ts

@@ -0,0 +1,32 @@
+import type { Usage } from "./types.js";
+
+export type RuntimeEvent = {
+  type: string;
+  timestamp: string;
+  turnId?: string;
+  data?: Record<string, unknown>;
+};
+
+export type EventListener = (event: RuntimeEvent) => void | Promise<void>;
+
+export class EventBus {
+  readonly #listeners = new Set<EventListener>();
+  on(listener: EventListener): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+  async emit(type: string, data?: Record<string, unknown>, turnId?: string): Promise<RuntimeEvent> {
+    const event: RuntimeEvent = { type, timestamp: new Date().toISOString() };
+    if (turnId !== undefined) event.turnId = turnId;
+    if (data !== undefined) event.data = data;
+    await Promise.all([...this.#listeners].map((listener) => listener(event)));
+    return event;
+  }
+}
+
+export interface TurnMetrics {
+  tools: number;
+  durationMs: number;
+  usage: Usage;
+  contextTokens: number;
+}

package/src/core/runtime.ts

@@ -0,0 +1,402 @@
+import { randomUUID } from "node:crypto";
+import type { ContextManager } from "../context/manager.js";
+import { toModelRequest } from "../context/manager.js";
+import type { SessionStore } from "../sessions/store.js";
+import type { ToolExecutor } from "../tools/executor.js";
+import type { ToolRegistry } from "../tools/registry.js";
+import type { EventBus } from "./events.js";
+import {
+  type AgentMessage,
+  type AssistantMessage,
+  CodeNError,
+  type ModelEvent,
+  type ModelProvider,
+  type ToolCall,
+  type Usage,
+} from "./types.js";
+
+export interface RuntimeOptions {
+  model: string;
+  maxSteps?: number;
+  retries?: number;
+  retryBaseMs?: number;
+  systemPrompt?: string;
+}
+export interface TurnResult {
+  answer: string;
+  messages: AgentMessage[];
+  toolsExecuted: number;
+  usage: Usage;
+}
+
+export class AgentRuntime {
+  readonly messages: AgentMessage[];
+  private readonly maxSteps: number;
+  private readonly retries: number;
+  private readonly retryBaseMs: number;
+  private systemPersisted: boolean;
+  constructor(
+    private readonly provider: ModelProvider,
+    private readonly registry: ToolRegistry,
+    private readonly executor: ToolExecutor,
+    private readonly context: ContextManager,
+    private readonly sessions: SessionStore,
+    private readonly events: EventBus,
+    private readonly options: RuntimeOptions,
+    initialMessages?: AgentMessage[],
+  ) {
+    this.maxSteps = options.maxSteps ?? 20;
+    this.retries = options.retries ?? 3;
+    this.retryBaseMs = options.retryBaseMs ?? 250;
+    this.systemPersisted = Boolean(initialMessages?.length);
+    this.messages = initialMessages?.length
+      ? [...initialMessages]
+      : [
+          {
+            role: "system",
+            content:
+              options.systemPrompt ??
+              "You are CodeN, a concise coding agent. Inspect before editing, use tools carefully, and verify changes.",
+          },
+        ];
+  }
+
+  async reset(): Promise<void> {
+    const system = this.messages.find((message) => message.role === "system") ?? {
+      role: "system" as const,
+      content: "You are CodeN.",
+    };
+    await this.sessions.append("session.reset", {});
+    this.messages.splice(0, this.messages.length, system);
+    this.context.clearSummary();
+    this.systemPersisted = false;
+  }
+
+  async compact(): Promise<void> {
+    const prepared = this.context.forceCompact(this.messages, this.registry.list());
+    const summary = this.context.getSummary();
+    if (summary) await this.sessions.appendCompaction(summary, this.context.getCompactionRange());
+    await this.events.emit("context.compacted", {
+      manual: true,
+      estimatedTokens: prepared.estimatedTokens,
+    });
+  }
+
+  async run(userText: string, signal = new AbortController().signal): Promise<TurnResult> {
+    const turnId = randomUUID();
+    const start = Date.now();
+    let toolsExecuted = 0;
+    const usage: Usage = { inputTokens: 0, outputTokens: 0 };
+    await this.events.emit("turn.started", { input: userText }, turnId);
+    try {
+      if (!this.systemPersisted) {
+        const system = this.messages[0];
+        if (system?.role === "system") await this.sessions.appendMessage(system);
+        this.systemPersisted = true;
+      }
+      const hasPriorUser = this.messages.some((message) => message.role === "user");
+      const user: AgentMessage = { role: "user", content: userText };
+      this.messages.push(user);
+      await this.sessions.appendMessage(user);
+      if (!hasPriorUser) await this.sessions.setTitle(userText);
+      for (let step = 0; step < this.maxSteps; step++) {
+        let prepared = this.context.prepare(this.messages, this.registry.list());
+        if (prepared.compacted) {
+          let summary = this.context.getSummary();
+          if (summary) {
+            const refined = await this.refineSummary(summary, signal, turnId);
+            if (refined) {
+              const previous = summary;
+              summary = refined;
+              this.context.setSummary(refined, this.context.getCompactionRange()?.end ?? 0);
+              prepared.messages = prepared.messages.map((message) =>
+                message.role === "system" && message.content === previous
+                  ? { role: "system", content: refined }
+                  : message,
+              );
+            }
+            await this.sessions.appendCompaction(summary, this.context.getCompactionRange());
+          }
+          await this.events.emit(
+            "context.compacted",
+            { estimatedTokens: prepared.estimatedTokens },
+            turnId,
+          );
+        }
+        await this.events.emit(
+          "context.prepared",
+          { estimatedTokens: prepared.estimatedTokens, budget: this.context.inputBudget() },
+          turnId,
+        );
+        const accumulated = await this.requestWithRetry(
+          toModelRequest(
+            this.options.model,
+            prepared,
+            this.registry.list(),
+            this.context.budget,
+            signal,
+          ),
+          turnId,
+          async () => {
+            prepared = this.context.forceCompact(this.messages, this.registry.list());
+            const summary = this.context.getSummary();
+            if (summary)
+              await this.sessions.appendCompaction(summary, this.context.getCompactionRange());
+            return toModelRequest(
+              this.options.model,
+              prepared,
+              this.registry.list(),
+              this.context.budget,
+              signal,
+            );
+          },
+        );
+        usage.inputTokens += accumulated.usage.inputTokens;
+        usage.outputTokens += accumulated.usage.outputTokens;
+        const assistant: AssistantMessage = {
+          role: "assistant",
+          content: accumulated.text,
+          toolCalls: accumulated.toolCalls,
+          model: this.options.model,
+          usage: accumulated.usage,
+        };
+        this.messages.push(assistant);
+        await this.sessions.appendMessage(assistant);
+        if (assistant.toolCalls.length === 0) {
+          await this.events.emit(
+            "turn.completed",
+            {
+              tools: toolsExecuted,
+              durationMs: Date.now() - start,
+              inputTokens: usage.inputTokens,
+              outputTokens: usage.outputTokens,
+              contextTokens: prepared.estimatedTokens,
+            },
+            turnId,
+          );
+          return { answer: assistant.content, messages: this.messages, toolsExecuted, usage };
+        }
+        for (const call of assistant.toolCalls) {
+          const result = await this.executor.execute(call, signal, turnId);
+          toolsExecuted++;
+          const message: AgentMessage = {
+            role: "tool",
+            callId: call.callId,
+            name: call.name,
+            content: result.content,
+            isError: result.isError ?? false,
+          };
+          this.messages.push(message);
+          await this.sessions.appendMessage(message);
+        }
+      }
+      throw new CodeNError(
+        "runtime",
+        "runtime.step_limit",
+        `Maximum model steps (${this.maxSteps}) reached`,
+      );
+    } catch (error) {
+      await this.events.emit(
+        "turn.failed",
+        {
+          code: error instanceof CodeNError ? error.code : "runtime.unknown",
+          message: error instanceof Error ? error.message : String(error),
+        },
+        turnId,
+      );
+      throw error;
+    }
+  }
+
+  private async refineSummary(
+    deterministicSummary: string,
+    signal: AbortSignal,
+    turnId: string,
+  ): Promise<string | undefined> {
+    try {
+      await this.events.emit("context.compaction_started", { model: this.options.model }, turnId);
+      const result = await accumulateStream(
+        this.provider.stream({
+          model: this.options.model,
+          messages: [
+            {
+              role: "system",
+              content:
+                "Rewrite the supplied coding-session summary concisely. Preserve goals, constraints, decisions, changed files, tool/test results, unresolved errors, and next steps. Return only the summary.",
+            },
+            { role: "user", content: deterministicSummary },
+          ],
+          tools: [],
+          maxOutputTokens: Math.min(2048, this.context.budget.reservedOutputTokens),
+          signal,
+        }),
+      );
+      if (result.toolCalls.length > 0 || !result.text.trim()) return undefined;
+      return `Compacted conversation summary:\n${result.text.trim()}`;
+    } catch (error) {
+      await this.events.emit(
+        "context.compaction_failed",
+        {
+          message: error instanceof Error ? error.message : String(error),
+          fallback: "deterministic",
+        },
+        turnId,
+      );
+      return undefined;
+    }
+  }
+
+  private async requestWithRetry(
+    initialRequest: ReturnType<typeof toModelRequest>,
+    turnId: string,
+    emergency: () => Promise<ReturnType<typeof toModelRequest>>,
+  ): Promise<{ text: string; toolCalls: ToolCall[]; usage: Usage }> {
+    let request = initialRequest;
+    let emergencyUsed = false;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await this.events.emit("provider.started", { attempt }, turnId);
+        const result = await accumulateStream(
+          this.provider.stream(request),
+          async (text) => {
+            await this.events.emit("provider.delta", { text }, turnId);
+          },
+          async (text) => {
+            await this.events.emit("provider.reasoning_delta", { text }, turnId);
+          },
+        );
+        await this.events.emit("provider.completed", { usage: result.usage }, turnId);
+        return result;
+      } catch (error) {
+        if (request.signal?.aborted) throw error;
+        if (isContextError(error)) {
+          if (!emergencyUsed) {
+            emergencyUsed = true;
+            request = await emergency();
+            await this.events.emit("context.compacted", { emergency: true }, turnId);
+            continue;
+          }
+          throw new CodeNError(
+            "context",
+            "context.exhausted",
+            "Context is still over the provider limit after emergency compaction",
+            false,
+            undefined,
+            { cause: error },
+          );
+        }
+        if (attempt >= this.retries || !isRetryable(error)) throw error;
+        await this.events.emit(
+          "provider.retry",
+          { attempt: attempt + 1, message: error instanceof Error ? error.message : String(error) },
+          turnId,
+        );
+        const retryAfter = retryAfterMs(error);
+        const backoff = this.retryBaseMs * 2 ** attempt * (0.8 + Math.random() * 0.4);
+        await delay(retryAfter ?? Math.min(30_000, backoff), request.signal);
+      }
+    }
+  }
+}
+
+export async function accumulateStream(
+  stream: AsyncIterable<ModelEvent>,
+  onText?: (text: string) => void | Promise<void>,
+  onReasoning?: (text: string) => void | Promise<void>,
+): Promise<{ text: string; toolCalls: ToolCall[]; usage: Usage }> {
+  let text = "";
+  let usage: Usage = { inputTokens: 0, outputTokens: 0 };
+  const builders = new Map<
+    number,
+    { callId: string; name: string; json: string; ended: boolean }
+  >();
+  for await (const event of stream) {
+    if (event.type === "reasoning_delta") {
+      await onReasoning?.(event.text);
+    } else if (event.type === "text_delta") {
+      text += event.text;
+      await onText?.(event.text);
+    } else if (event.type === "tool_call_start")
+      builders.set(event.index, { callId: event.callId, name: event.name, json: "", ended: false });
+    else if (event.type === "tool_call_delta") {
+      const builder = builders.get(event.index);
+      if (!builder)
+        throw new CodeNError(
+          "provider",
+          "provider.invalid_stream",
+          "Tool arguments arrived before tool start",
+        );
+      builder.json += event.argumentsDelta;
+    } else if (event.type === "tool_call_end") {
+      const builder = builders.get(event.index);
+      if (builder) builder.ended = true;
+    } else if (event.type === "usage")
+      usage = {
+        inputTokens: Math.max(usage.inputTokens, event.usage.inputTokens),
+        outputTokens: Math.max(usage.outputTokens, event.usage.outputTokens),
+      };
+  }
+  const toolCalls = [...builders.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([, builder]) => {
+      if (!builder.ended)
+        throw new CodeNError(
+          "provider",
+          "provider.incomplete_tool_call",
+          `Incomplete tool call: ${builder.name}`,
+        );
+      try {
+        return {
+          callId: builder.callId,
+          name: builder.name,
+          input: JSON.parse(builder.json || "{}"),
+        };
+      } catch (cause) {
+        throw new CodeNError(
+          "provider",
+          "provider.invalid_tool_json",
+          `Invalid JSON for tool ${builder.name}`,
+          false,
+          undefined,
+          { cause },
+        );
+      }
+    });
+  return { text, toolCalls, usage };
+}
+function isRetryable(error: unknown): boolean {
+  if (error instanceof CodeNError) return error.retryable;
+  const status = (error as { status?: unknown })?.status;
+  return typeof status !== "number" || status === 429 || status >= 500;
+}
+function retryAfterMs(error: unknown): number | undefined {
+  const headers = (error as { headers?: { get?: (name: string) => string | null } })?.headers;
+  const raw = headers?.get?.("retry-after");
+  if (!raw) return undefined;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const date = Date.parse(raw);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+function isContextError(error: unknown): boolean {
+  const status = (error as { status?: unknown })?.status;
+  const message = error instanceof Error ? error.message : String(error);
+  return status === 413 || /context.{0,20}(?:length|window|limit|too long)/i.test(message);
+}
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason);
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true },
+    );
+  });
+}

package/src/core/types.ts

@@ -0,0 +1,97 @@
+export type JsonSchema = Record<string, unknown>;
+export type ToolRisk = "read" | "modify" | "dangerous";
+
+export interface Usage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface ToolCall {
+  callId: string;
+  name: string;
+  input: unknown;
+}
+
+export interface SystemMessage {
+  role: "system";
+  content: string;
+}
+export interface UserMessage {
+  role: "user";
+  content: string;
+}
+export interface AssistantMessage {
+  role: "assistant";
+  content: string;
+  toolCalls: ToolCall[];
+  model?: string;
+  usage?: Usage;
+}
+export interface ToolResultMessage {
+  role: "tool";
+  callId: string;
+  name: string;
+  content: string;
+  isError: boolean;
+}
+export type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
+
+export interface ToolResult {
+  content: string;
+  isError?: boolean;
+  metadata?: Record<string, unknown>;
+}
+export interface ToolContext {
+  workspace: string;
+  signal: AbortSignal;
+}
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  risk: ToolRisk;
+  execute(input: unknown, context: ToolContext): Promise<ToolResult>;
+}
+
+export interface ModelRequest {
+  model: string;
+  messages: AgentMessage[];
+  tools: ToolDefinition[];
+  maxOutputTokens: number;
+  signal?: AbortSignal;
+}
+
+export type ModelEvent =
+  | { type: "reasoning_delta"; text: string }
+  | { type: "text_delta"; text: string }
+  | { type: "tool_call_start"; index: number; callId: string; name: string }
+  | { type: "tool_call_delta"; index: number; argumentsDelta: string }
+  | { type: "tool_call_end"; index: number }
+  | { type: "usage"; usage: Usage }
+  | { type: "done" };
+
+export interface ModelProvider {
+  stream(request: ModelRequest): AsyncIterable<ModelEvent>;
+}
+
+export type ErrorCategory =
+  | "provider"
+  | "context"
+  | "tool"
+  | "permission"
+  | "plugin"
+  | "session"
+  | "runtime";
+export class CodeNError extends Error {
+  constructor(
+    readonly category: ErrorCategory,
+    readonly code: string,
+    message: string,
+    readonly retryable = false,
+    readonly details?: Record<string, unknown>,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "CodeNError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export * from "./context/manager.js";
+export * from "./core/events.js";
+export * from "./core/runtime.js";
+export * from "./core/types.js";
+export * from "./plugins/api.js";
+export * from "./plugins/installed-loader.js";
+export * from "./plugins/installer.js";
+export * from "./plugins/manifest.js";
+export * from "./plugins/paths.js";
+export * from "./plugins/specifier.js";
+export * from "./providers/scripted.js";
+export * from "./tools/builtin/index.js";
+export * from "./tools/plugin-loader.js";
+export * from "./tools/registry.js";