indusagi-coding-agent 0.2.8 → 0.2.10

package/src/channels/link/dialog.ts

@@ -0,0 +1,129 @@
+/**
+ * Dialog bridge — the ask / tell seam over the link transport.
+ */
+import type {
+  Ask,
+  AskAnswer,
+  ChannelTimings,
+  DialogBridge,
+  NdjsonFramer,
+  WritableLine,
+} from "../contract.js";
+
+export interface DialogBridgeDeps {
+  readonly out: WritableLine;
+  readonly framer: NdjsonFramer;
+  readonly timings: ChannelTimings;
+}
+
+export interface LinkedDialogBridge extends DialogBridge {
+  deliver(answer: AskAnswer): boolean;
+  drain(): void;
+}
+
+interface PendingEntry {
+  settle: (value: unknown) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+function nextAskId(seq: { n: number }): string {
+  seq.n += 1;
+  return `ask-${Date.now().toString(36)}-${seq.n.toString(36)}`;
+}
+
+/**
+ * Construct a {@link LinkedDialogBridge} over an injected sink + framer.
+ */
+export function createDialogBridge(deps: DialogBridgeDeps): LinkedDialogBridge {
+  const pending = new Map<string, PendingEntry>();
+  const seq = { n: 0 };
+
+  function emit(frame: Ask | { type: "tell"; kind: string; payload?: unknown }): void {
+    deps.out.write(deps.framer.encodeLine(frame));
+  }
+
+  function resolvePending(id: string, value: unknown): boolean {
+    const entry = pending.get(id);
+    if (entry === undefined) {
+      return false;
+    }
+    pending.delete(id);
+    clearTimeout(entry.timer);
+    entry.settle(value);
+    return true;
+  }
+
+  return {
+    ask<T>(kind: string, payload: unknown, fallback: T): Promise<T> {
+      const id = nextAskId(seq);
+      const frame: Ask = { type: "ask", id, kind, payload };
+      return new Promise<T>((resolve) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          resolve(fallback);
+        }, deps.timings.dialogMs);
+        if (typeof timer.unref === "function") {
+          timer.unref();
+        }
+        pending.set(id, {
+          settle: (value: unknown) => resolve(value as T),
+          timer,
+        });
+        emit(frame);
+      });
+    },
+    tell(kind: string, payload?: unknown): void {
+      emit({ type: "tell", kind, payload });
+    },
+    deliver(answer: AskAnswer): boolean {
+      return resolvePending(answer.id, answer.value);
+    },
+    drain(): void {
+      for (const [, entry] of pending) {
+        clearTimeout(entry.timer);
+        entry.settle(undefined);
+      }
+      pending.clear();
+    },
+  };
+}
+
+export interface DialogSpec {
+  readonly kind: string;
+  readonly mode: "ask" | "tell";
+  readonly fallback?: unknown;
+}
+
+export const DIALOG_TABLE = Object.freeze({
+  select: { kind: "select", mode: "ask", fallback: null },
+  confirm: { kind: "confirm", mode: "ask", fallback: false },
+  input: { kind: "input", mode: "ask", fallback: null },
+  editor: { kind: "editor", mode: "ask", fallback: null },
+  notify: { kind: "notify", mode: "tell" },
+  status: { kind: "status", mode: "tell" },
+  title: { kind: "title", mode: "tell" },
+});
+
+export type DialogMethods = {
+  [K in keyof typeof DIALOG_TABLE]: (typeof DIALOG_TABLE)[K]["mode"] extends "ask"
+    ? (payload?: unknown) => Promise<unknown>
+    : (payload?: unknown) => void;
+};
+
+/**
+ * Close the {@link DIALOG_TABLE} over one {@link DialogBridge} into typed,
+ * named convenience methods.
+ */
+export function makeDialogMethods(bridge: DialogBridge): DialogMethods {
+  const methods = {} as Record<string, (payload?: unknown) => unknown>;
+  for (const name of Object.keys(DIALOG_TABLE)) {
+    const spec = DIALOG_TABLE[name as keyof typeof DIALOG_TABLE];
+    if (spec.mode === "ask") {
+      methods[name] = (payload?: unknown): Promise<unknown> =>
+        bridge.ask(spec.kind, payload, spec.fallback);
+    } else {
+      methods[name] = (payload?: unknown): void => bridge.tell(spec.kind, payload);
+    }
+  }
+  return methods as DialogMethods;
+}

package/src/channels/link/driver.ts

@@ -0,0 +1,190 @@
+/**
+ * Link driver — the generated client over the JSON-RPC link.
+ */
+import {
+  DEFAULT_CHANNEL_TIMINGS,
+  PROTOCOL_VERSION,
+  REQUEST_ID_PREFIX,
+  isReplyOk,
+  type Ask,
+  type ChannelTimings,
+  type LinkDriver,
+  type NdjsonFramer,
+  type OpError,
+  type OpRegistry,
+  type ReadableChunks,
+  type Reply,
+  type Signal,
+  type WritableLine,
+} from "../contract.js";
+import { ndjsonFramer } from "../framer.js";
+
+export interface LinkDriverIo {
+  readonly out: WritableLine;
+  readonly in: ReadableChunks;
+}
+
+export interface LinkDriverConfig {
+  readonly framer?: NdjsonFramer;
+  readonly timings?: Partial<ChannelTimings>;
+  readonly onSignal?: (signal: Signal) => void;
+  readonly onAsk?: (ask: Ask) => unknown | Promise<unknown>;
+}
+
+export class LinkRequestError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+
+  constructor(error: OpError) {
+    super(error.message);
+    this.name = "LinkRequestError";
+    this.code = error.code;
+    this.data = error.data;
+  }
+}
+
+export interface LinkDriverHandle<Ops extends OpRegistry> {
+  readonly client: LinkDriver<Ops>;
+  readonly done: Promise<void>;
+  close(reason?: string): void;
+}
+
+function isReplyFrame(frame: unknown): frame is Reply {
+  if (typeof frame !== "object" || frame === null) return false;
+  const f = frame as Record<string, unknown>;
+  return f.id !== undefined && ("result" in f || "error" in f);
+}
+
+function isSignalFrame(frame: unknown): frame is Signal {
+  return (
+    typeof frame === "object" &&
+    frame !== null &&
+    (frame as { type?: unknown }).type === "signal"
+  );
+}
+
+function isAskFrame(frame: unknown): frame is Ask {
+  return (
+    typeof frame === "object" &&
+    frame !== null &&
+    (frame as { type?: unknown }).type === "ask" &&
+    typeof (frame as { id?: unknown }).id === "string"
+  );
+}
+
+function resolveTimings(
+  overrides: Partial<ChannelTimings> | undefined,
+): ChannelTimings {
+  return { ...DEFAULT_CHANNEL_TIMINGS, ...overrides };
+}
+
+interface PendingEntry {
+  resolve: (value: unknown) => void;
+  reject: (reason: unknown) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Build a {@link LinkDriverHandle} over an injected transport.
+ */
+export function createLinkDriver<Ops extends OpRegistry = OpRegistry>(
+  io: LinkDriverIo,
+  config: LinkDriverConfig = {},
+): LinkDriverHandle<Ops> {
+  const framer = config.framer ?? ndjsonFramer;
+  const timings = resolveTimings(config.timings);
+  const pending = new Map<string, PendingEntry>();
+  let seq = 0;
+  let closed = false;
+
+  function nextId(): string {
+    seq += 1;
+    return `${REQUEST_ID_PREFIX}${Date.now().toString(36)}-${seq.toString(36)}`;
+  }
+
+  function request(method: string, params?: unknown): Promise<unknown> {
+    if (closed) {
+      return Promise.reject(new Error("link driver is closed"));
+    }
+    const id = nextId();
+    const frame =
+      params === undefined
+        ? { jsonrpc: PROTOCOL_VERSION, id, method }
+        : { jsonrpc: PROTOCOL_VERSION, id, method, params };
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`link request timed out: ${method}`));
+      }, timings.requestMs);
+      if (typeof timer.unref === "function") {
+        timer.unref();
+      }
+      pending.set(id, { resolve, reject, timer });
+      io.out.write(framer.encodeLine(frame));
+    });
+  }
+
+  function settleReply(reply: Reply): void {
+    const entry = pending.get(String(reply.id));
+    if (entry === undefined) return;
+    pending.delete(String(reply.id));
+    clearTimeout(entry.timer);
+    if (isReplyOk(reply)) {
+      entry.resolve(reply.result);
+    } else {
+      entry.reject(new LinkRequestError(reply.error));
+    }
+  }
+
+  async function answerAsk(ask: Ask): Promise<void> {
+    const value = config.onAsk ? await config.onAsk(ask) : null;
+    const answer = { type: "answer", id: ask.id, value };
+    io.out.write(framer.encodeLine(answer));
+  }
+
+  function rejectAll(reason: string): void {
+    for (const [, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error(reason));
+    }
+    pending.clear();
+  }
+
+  async function pump(): Promise<void> {
+    try {
+      for await (const frame of framer.decodeLines(io.in)) {
+        if (isReplyFrame(frame)) {
+          settleReply(frame);
+          continue;
+        }
+        if (isSignalFrame(frame)) {
+          config.onSignal?.(frame);
+          continue;
+        }
+        if (isAskFrame(frame)) {
+          await answerAsk(frame);
+          continue;
+        }
+      }
+    } finally {
+      closed = true;
+      rejectAll("link closed before reply");
+    }
+  }
+
+  const client = new Proxy({} as LinkDriver<Ops>, {
+    get(_target, prop) {
+      if (typeof prop !== "string") return undefined;
+      return (params?: unknown) => request(prop, params);
+    },
+  });
+
+  return {
+    client,
+    done: pump(),
+    close(reason: string = "link driver closed by caller"): void {
+      closed = true;
+      rejectAll(reason);
+    },
+  };
+}

package/src/channels/link/index.ts

@@ -0,0 +1,34 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Link channel — public barrel.
+ *
+ * The link channel is the long-lived, bidirectional half of the channels
+ * subsystem: a JSON-RPC 2.0 server that dispatches framed requests through an
+ * {@link OpRegistry} (`server.ts`), a generated {@link LinkDriver} client built
+ * from a {@link Proxy} rather than hand-written methods (`driver.ts`), and the
+ * ask / tell dialog bridge that both ends share (`dialog.ts`). Consumers import
+ * the link surface from `src/channels/link` rather than the individual modules.
+ */
+export {
+  createLinkServer,
+  type LinkServer,
+  type LinkServerIo,
+  type LinkServerConfig,
+} from "./server.js";
+export {
+  createLinkDriver,
+  LinkRequestError,
+  type LinkDriverHandle,
+  type LinkDriverIo,
+  type LinkDriverConfig,
+} from "./driver.js";
+export {
+  createDialogBridge,
+  makeDialogMethods,
+  DIALOG_TABLE,
+  type LinkedDialogBridge,
+  type DialogBridgeDeps,
+  type DialogSpec,
+  type DialogMethods,
+} from "./dialog.js";

package/src/channels/link/server.ts

@@ -0,0 +1,134 @@
+/**
+ * Link server — the data-driven JSON-RPC 2.0 dispatch loop.
+ */
+import {
+  DEFAULT_CHANNEL_TIMINGS,
+  OP_ERROR,
+  PROTOCOL_VERSION,
+  type AskAnswer,
+  type ChannelContext,
+  type NdjsonFramer,
+  type OpError,
+  type OpRegistry,
+  type ReadableChunks,
+  type Reply,
+  type SessionConductor,
+  type WritableLine,
+} from "../contract.js";
+import { ndjsonFramer } from "../framer.js";
+import { dispatch, UnknownOpError } from "../ops.js";
+import { createDialogBridge, type LinkedDialogBridge } from "./dialog.js";
+
+export interface LinkServerIo {
+  readonly in: ReadableChunks;
+  readonly out: WritableLine;
+}
+
+export interface LinkServerConfig {
+  readonly framer?: NdjsonFramer;
+  readonly timings?: Partial<typeof DEFAULT_CHANNEL_TIMINGS>;
+}
+
+export interface LinkServer {
+  readonly done: Promise<void>;
+  readonly dialog: LinkedDialogBridge;
+}
+
+function isRequestFrame(frame: unknown): frame is { method: string; id?: unknown; params?: unknown } {
+  return (
+    typeof frame === "object" && frame !== null && typeof (frame as { method?: unknown }).method === "string"
+  );
+}
+
+function isAnswerFrame(frame: unknown): frame is AskAnswer {
+  return (
+    typeof frame === "object" &&
+    frame !== null &&
+    (frame as { type?: unknown }).type === "answer" &&
+    typeof (frame as { id?: unknown }).id === "string"
+  );
+}
+
+function toOpError(error: unknown): OpError {
+  if (error instanceof UnknownOpError) {
+    return { code: error.code, message: error.message, data: { method: error.method } };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return { code: OP_ERROR.handlerFailed, message };
+}
+
+function resolveTimings(
+  overrides: Partial<typeof DEFAULT_CHANNEL_TIMINGS> | undefined,
+): typeof DEFAULT_CHANNEL_TIMINGS {
+  return { ...DEFAULT_CHANNEL_TIMINGS, ...overrides };
+}
+
+/**
+ * Start a link server over an op registry, a conductor, and an injected
+ * transport.
+ */
+export function createLinkServer(
+  registry: OpRegistry,
+  conductor: SessionConductor,
+  io: LinkServerIo,
+  config: LinkServerConfig = {},
+): LinkServer {
+  const framer = config.framer ?? ndjsonFramer;
+  const timings = resolveTimings(config.timings);
+  const dialog = createDialogBridge({ out: io.out, framer, timings });
+  const ctx: ChannelContext = {
+    conductor,
+    out: io.out,
+    framer,
+    dialog,
+  };
+
+  function writeReply(reply: Reply): void {
+    io.out.write(framer.encodeLine(reply));
+  }
+
+  function replyOk(id: unknown, result: unknown): void {
+    writeReply({ jsonrpc: PROTOCOL_VERSION, id: id as Reply["id"], result });
+  }
+
+  function replyErr(id: unknown, error: OpError): void {
+    writeReply({ jsonrpc: PROTOCOL_VERSION, id: id as Reply["id"], error });
+  }
+
+  async function handleRequest(frame: { method: string; id?: unknown; params?: unknown }): Promise<void> {
+    const wantsReply = frame.id !== undefined;
+    try {
+      const result = await dispatch(registry, frame.method, frame.params, ctx);
+      if (wantsReply) {
+        replyOk(frame.id, result);
+      }
+    } catch (error) {
+      if (wantsReply) {
+        replyErr(frame.id, toOpError(error));
+      }
+    }
+  }
+
+  async function pump(): Promise<void> {
+    const inflight = new Set<Promise<void>>();
+    try {
+      for await (const frame of framer.decodeLines(io.in)) {
+        if (isAnswerFrame(frame)) {
+          dialog.deliver({ type: "answer", id: frame.id, value: frame.value });
+          continue;
+        }
+        if (isRequestFrame(frame)) {
+          const task = handleRequest(frame);
+          inflight.add(task);
+          void task.finally(() => inflight.delete(task));
+          continue;
+        }
+      }
+      await Promise.all(inflight);
+    } finally {
+      dialog.drain();
+    }
+  }
+
+  return { done: pump(), dialog };
+}

package/src/channels/oneshot.ts

@@ -0,0 +1,90 @@
+/**
+ * Oneshot channel — a single non-interactive run to settlement.
+ */
+import type {
+  ChannelContext,
+  ConductorState,
+  DialogBridge,
+  OneshotRequest,
+  OneshotShape,
+  OneshotStrategy,
+} from "./contract.js";
+
+export const inertDialog: DialogBridge = Object.freeze({
+  ask<T>(_kind: string, _payload: unknown, fallback: T): Promise<T> {
+    return Promise.resolve(fallback);
+  },
+  tell(_kind: string, _payload?: unknown): void {
+    /* no-op */
+  },
+});
+
+const EXIT_OK = 0;
+const EXIT_FAULT = 1;
+
+function exitCodeFor(state: ConductorState): number {
+  return state.phase === "faulted" ? EXIT_FAULT : EXIT_OK;
+}
+
+function textStrategy(): OneshotStrategy {
+  let answer = "";
+  return {
+    onSignal(signal: unknown): void {
+      const s = signal as { kind?: string; delta?: string };
+      if (s.kind === "text") {
+        answer += s.delta ?? "";
+      }
+    },
+    finish(state: ConductorState, ctx: ChannelContext): number {
+      ctx.out.write(answer.endsWith("\n") ? answer : `${answer}\n`);
+      return exitCodeFor(state);
+    },
+  };
+}
+
+function ndjsonStrategy(): OneshotStrategy {
+  return {
+    onStart(ctx: ChannelContext): void {
+      ctx.out.write(ctx.framer.encodeLine({ type: "signal", name: "start", body: {} }));
+    },
+    onSignal(signal: unknown, ctx: ChannelContext): void {
+      const s = signal as { kind: string };
+      ctx.out.write(ctx.framer.encodeLine({ type: "signal", name: s.kind, body: s }));
+    },
+    finish(state: ConductorState, ctx: ChannelContext): number {
+      ctx.out.write(
+        ctx.framer.encodeLine({
+          type: "signal",
+          name: "end",
+          body: { phase: state.phase, usage: state.usage, fault: state.fault },
+        }),
+      );
+      return exitCodeFor(state);
+    },
+  };
+}
+
+const STRATEGIES: Readonly<Record<OneshotShape, () => OneshotStrategy>> = Object.freeze({
+  text: textStrategy,
+  ndjson: ndjsonStrategy,
+});
+
+/**
+ * Run one non-interactive request to settlement.
+ */
+export async function runOneshot(ctx: ChannelContext, opts: OneshotRequest): Promise<number> {
+  const strategy = STRATEGIES[opts.shape]();
+  const unsubscribe = ctx.conductor.subscribe((signal) => {
+    strategy.onSignal?.(signal, ctx);
+  });
+  try {
+    await strategy.onStart?.(ctx);
+    let state = ctx.conductor.snapshot();
+    for (const prompt of opts.prompts) {
+      state = await ctx.conductor.submit(prompt);
+    }
+    return strategy.finish(state, ctx);
+  } finally {
+    unsubscribe();
+  }
+}

package/src/channels/ops.ts

@@ -0,0 +1,65 @@
+/**
+ * Operation registry — the single declarative source both halves of the link
+ * consume.
+ */
+import { defineOps, OP_ERROR } from "./contract.js";
+import type { ChannelContext, Op, OpRegistry } from "./contract.js";
+
+export { defineOps };
+
+export class UnknownOpError extends Error {
+  readonly code: number;
+  readonly method: string;
+
+  constructor(method: string) {
+    super("Unknown op: " + method);
+    this.name = "UnknownOpError";
+    this.method = method;
+    this.code = OP_ERROR.unknownOp;
+  }
+}
+
+/**
+ * Run one operation by name against the shared context.
+ */
+export async function dispatch(
+  registry: OpRegistry,
+  method: string,
+  params: unknown,
+  ctx: ChannelContext,
+): Promise<unknown> {
+  const op = registry[method];
+  if (op === undefined) {
+    throw new UnknownOpError(method);
+  }
+  return op.handle(params, ctx);
+}
+
+export function hasOp(registry: OpRegistry, method: string): boolean {
+  return Object.prototype.hasOwnProperty.call(registry, method);
+}
+
+export function methodsOf<T extends OpRegistry>(registry: T): ReadonlyArray<keyof T & string> {
+  return Object.keys(registry).sort() as ReadonlyArray<keyof T & string>;
+}
+
+export interface OpRegistryHandle<T extends OpRegistry> {
+  readonly registry: T;
+  readonly methods: ReadonlyArray<keyof T & string>;
+  dispatch(method: string, params: unknown, ctx: ChannelContext): Promise<unknown>;
+}
+
+/**
+ * Build an {@link OpRegistryHandle} from a record of operation declarations.
+ */
+export function buildOps<T extends Record<string, Op<any, any>>>(
+  ops: T,
+): OpRegistryHandle<Readonly<T>> {
+  const registry = defineOps(ops);
+  return Object.freeze({
+    registry,
+    methods: methodsOf(registry),
+    dispatch: (method: string, params: unknown, ctx: ChannelContext): Promise<unknown> =>
+      dispatch(registry, method, params, ctx),
+  });
+}