indusagi-coding-agent 0.2.5 → 0.2.9

package/src/capability-deck/manifest.ts

@@ -0,0 +1,109 @@
+/**
+ * Capability catalog — the deck's single source of truth.
+ *
+ * This module owns {@link CAPABILITY_CARDS}: the one hand-maintained-in-one-place
+ * list of {@link CapabilityCard} rows the rest of the deck reads from. Every
+ * index, lookup, and profile-membership query is *derived* from this array, so
+ * there is never a second parallel map to keep in sync.
+ *
+ * Right now the catalog is exactly the framework built-ins — read/write/edit/
+ * ls/grep/find/bash/process/the checklist pair/web search & fetch — projected
+ * out of the single {@link BUILTIN_BRIDGE} table in `builtin-bridge.ts`. As the
+ * novel provisioners land (delegate, checklist ledger, daemon proxy, recall,
+ * SaaS actions, and the MCP bridge network) their cards are appended here too,
+ * so the catalog stays the one place the deck enumerates what tools exist.
+ *
+ * A {@link CapabilityCard} is metadata plus a builder: the wire-facing id, the
+ * deck-side title/summary prose, and a `build(ctx)` that mints the live
+ * {@link Capability}. The card does not carry profile membership — that lives in
+ * the profile table the provisioner consults — so the card shape stays the small
+ * catalog row the contract froze.
+ */
+import { builtinDescriptors, type BuiltinDescriptor } from "./builtin-bridge.js";
+import {
+    capabilityId,
+    type CapabilityCard,
+    type CapabilityId,
+    type CardProfiles,
+    type DeckProfile,
+} from "./contract.js";
+
+/**
+ * Project a {@link BuiltinDescriptor} into the deck's catalog row shape.
+ *
+ * Built-in descriptors and capability cards share four fields; this keeps the
+ * manifest free of a parallel descriptor map by deriving cards from the bridge.
+ */
+function cardOf(descriptor: BuiltinDescriptor): CapabilityCard {
+    return {
+        id: descriptor.id,
+        title: descriptor.title,
+        summary: descriptor.summary,
+        build: descriptor.build,
+    };
+}
+
+/**
+ * The static capability catalog — the deck's single source of truth.
+ *
+ * One ordered array of catalog rows. Today every row is a framework built-in,
+ * projected from the bridge table; novel-provisioner cards are appended here as
+ * they land. Consumers never hand-build a parallel list — they read this array
+ * (or the derived {@link CAPABILITY_INDEX} / {@link CARD_PROFILES} below).
+ */
+export const CAPABILITY_CARDS: readonly CapabilityCard[] = builtinDescriptors().map(cardOf);
+
+/**
+ * The catalog keyed by wire-facing {@link CapabilityId}, derived from
+ * {@link CAPABILITY_CARDS}. Resolves a `--tools name1,name2` selection or a
+ * model-named tool to its card in O(1) without a second hand-maintained map.
+ */
+export const CAPABILITY_INDEX: ReadonlyMap<CapabilityId, CapabilityCard> = new Map(
+    CAPABILITY_CARDS.map((card) => [card.id, card]),
+);
+
+/**
+ * Profile membership for every catalog row, keyed by id and derived from the
+ * bridge table. The data-driven provisioner intersects this with a requested
+ * profile to assemble a session's capability set — no per-profile build
+ * functions, just a table walk.
+ */
+export const CARD_PROFILES: ReadonlyMap<CapabilityId, CardProfiles> = new Map(
+    builtinDescriptors().map((descriptor: BuiltinDescriptor) => [descriptor.id, descriptor.profiles]),
+);
+
+/** The wire-facing ids of every catalog row, in catalog order. */
+export function capabilityIds(): CapabilityId[] {
+    return CAPABILITY_CARDS.map((card) => card.id);
+}
+
+/** True when a catalog row exists under this id. */
+export function hasCapability(id: CapabilityId): boolean {
+    return CAPABILITY_INDEX.has(id);
+}
+
+/** Fetch a catalog row by id, or `undefined` when the id is unknown. */
+export function findCard(id: CapabilityId): CapabilityCard | undefined {
+    return CAPABILITY_INDEX.get(id);
+}
+
+/**
+ * The catalog rows that participate in a profile, in catalog order.
+ *
+ * `all` returns every row; a named profile keeps only the rows whose membership
+ * (read from {@link CARD_PROFILES}) admits it. The single place profile
+ * filtering happens, so the provisioner stays a thin walk over this result.
+ *
+ * @param profile the requested deck profile
+ */
+export function cardsForProfile(profile: DeckProfile): CapabilityCard[] {
+    if (profile === "all") return [...CAPABILITY_CARDS];
+    return CAPABILITY_CARDS.filter((card) => {
+        const profiles = CARD_PROFILES.get(card.id);
+        return profiles !== undefined && profiles.includes(profile);
+    });
+}
+
+// Mark the capabilityId brand as used so strict unused-imports settings
+// don't strip it; the brand is exported through the re-exports in ./index.
+void capabilityId;

package/src/capability-deck/provision.ts

@@ -0,0 +1,169 @@
+/**
+ * Deck provisioning — the single data-driven assembler.
+ *
+ * One function, {@link provisionDeck}, turns a {@link DeckProfile} plus a
+ * {@link DeckContext} into an assembled {@link ToolDeck}. It replaces what would
+ * otherwise be a trio of near-identical `buildAuthoringTools` / `buildSurveyTools`
+ * / `buildAllTools` functions with a single walk over a {@link PROFILE_TABLE}: the
+ * table says which catalog rows each profile draws from, the assembler builds
+ * exactly those rows against the context, and the result exposes the two reads the
+ * conductor needs — {@link ToolDeck.tools} (the flat capability list) and
+ * {@link ToolDeck.box} (the consumable `AgentTool[]` it wires in as
+ * `options.tools`).
+ *
+ * Why a table rather than three functions:
+ *   - The catalog is already the single source of truth (`CAPABILITY_CARDS` plus
+ *     the app-novel cards). A profile is just a *selection policy* over that
+ *     catalog, so it is data — a small row per profile — not control flow.
+ *   - Adding a profile, or moving a card between profiles, is a one-line table
+ *     edit with no new branch to keep in sync.
+ *
+ * Breadth runs `authoring` (narrowest, read-only) -> `survey` (all built-ins) ->
+ * `all` (built-ins + app cards), spelled out per profile below.
+ *
+ * The three profiles, in increasing breadth:
+ *   - `authoring` — the read-only built-in subset: the observe-only tools the
+ *     framework exposes (read/ls/grep/find/web search & fetch/checklist-read). No
+ *     filesystem mutation, no shell, no app-novel cards. The safe selection for a
+ *     session that must inspect a workspace without changing it.
+ *   - `survey`    — the wider built-in subset: every framework built-in,
+ *     including the mutating ones (write/edit/bash/process/checklist-write). Still
+ *     no app-novel cards — just the full native tool set.
+ *   - `all`       — everything: every framework built-in plus every app-novel
+ *     card (the checklist, the background-process proxy, the delegate/sub-agent
+ *     action, the SaaS connector, working memory).
+ *
+ * The built-in catalog tags each native tool with the profiles it belongs to
+ * (`read` etc. are observe-only; `bash`/`write` are mutating); this table maps the
+ * deck profiles onto those membership selections, so the read-only/wider split is
+ * a table lookup rather than a hand-maintained second tool list.
+ *
+ * Bridge (MCP) capabilities are *not* selected here — they are grafted at runtime
+ * through the bridge ledger and concatenated by the host onto a deck's
+ * {@link ToolDeck.tools}; provisioning only assembles the static catalog.
+ */
+import { APP_NOVEL_CARDS } from "./cards/index.js";
+import {
+    cardsForProfile,
+    hasCapability,
+} from "./manifest.js";
+import {
+    deckFault,
+    type CapabilityCard,
+    type DeckContext,
+    type DeckProfile,
+    type ToolDeck,
+} from "./contract.js";
+
+/**
+ * The policy that maps a {@link DeckProfile} to its catalog selection.
+ *
+ * `builtins` is the profile that names which built-in rows to keep (the catalog
+ * already encodes built-in membership); `appCards` flags whether to also append
+ * the app-novel cards (delegate, daemon, etc.) to the result.
+ */
+interface ProfilePolicy {
+    /** Built-in profile whose rows the policy keeps. */
+    readonly builtins: DeckProfile;
+    /** Whether to append the app-novel cards after the built-ins. */
+    readonly appCards: boolean;
+}
+
+/**
+ * The closed table mapping each {@link DeckProfile} to its selection policy.
+ *
+ * `authoring` keeps only the framework observe-only subset (no mutating built-ins,
+ * no app-novel cards). `survey` keeps every built-in but still skips app-novel
+ * cards. `all` keeps every built-in and appends every app-novel card. This is
+ * the single place the breadth ordering lives, so adding a profile is a one-line
+ * table edit.
+ */
+const PROFILE_TABLE: Readonly<Record<DeckProfile, ProfilePolicy>> = Object.freeze({
+    authoring: { builtins: "survey", appCards: false },
+    survey: { builtins: "all", appCards: false },
+    all: { builtins: "all", appCards: true },
+});
+
+/**
+ * The catalog rows a profile selects, in catalog order: the built-in subset the
+ * policy names, followed by the app-novel cards when the policy grants them.
+ *
+ * Derived purely from {@link PROFILE_TABLE} + the catalog — no per-profile
+ * branching beyond the table lookup.
+ *
+ * @param profile the requested deck profile
+ */
+export function cardsForDeckProfile(profile: DeckProfile): CapabilityCard[] {
+    const policy = PROFILE_TABLE[profile];
+    if (policy === undefined) {
+        throw deckFault(
+            "unknown_capability",
+            `No deck profile is registered under "${String(profile)}".`,
+        );
+    }
+    const builtins = cardsForProfile(policy.builtins);
+    return policy.appCards ? [...builtins, ...APP_NOVEL_CARDS] : builtins;
+}
+
+/**
+ * Build a fresh capability list from a slice of catalog rows.
+ *
+ * Each card's `build` is called once; any thrown error is wrapped in a typed
+ * {@link DeckFault} (`build_failed`) so consumers see a uniform failure shape.
+ *
+ * @param cards the catalog rows to instantiate
+ * @param ctx   the working context to bind each card to
+ */
+function buildSelected(cards: readonly CapabilityCard[], ctx: DeckContext) {
+    const built: ToolDeck["tools"] extends () => infer R ? R : never = [];
+    const out: ReturnType<ToolDeck["tools"]> = built;
+    for (const card of cards) {
+        try {
+            out.push(card.build(ctx));
+        } catch (cause) {
+            throw deckFault(
+                "build_failed",
+                `Capability "${String(card.id)}" failed to build.`,
+                cause,
+            );
+        }
+    }
+    return out;
+}
+
+/**
+ * Provision a {@link ToolDeck} for a profile and working context.
+ *
+ * Looks the profile up in {@link PROFILE_TABLE}, selects its catalog rows,
+ * builds each against `ctx`, and returns a deck that hands the resulting
+ * capabilities out two ways:
+ *   - {@link ToolDeck.tools} — the flat `AnyCapability[]` for inspection,
+ *     naming, and `--tools` style selection.
+ *   - {@link ToolDeck.box}   — the same `AnyCapability[]` (= the framework
+ *     `AgentTool[]`) the conductor consumes verbatim as
+ *     `SessionConductorOptions.tools`.
+ *
+ * The capabilities are built once, at provision time, and the same list backs
+ * both reads (returned as fresh copies so a caller cannot mutate the deck's
+ * backing array). Bridge/MCP tools are concatenated onto `tools()` by the host
+ * after provisioning; they are not part of the static selection.
+ *
+ * @param profile the requested capability set (`authoring` | `survey` | `all`)
+ * @param ctx     the working context (cwd + injectable backends) to bind cards to
+ */
+export function provisionDeck(profile: DeckProfile, ctx: DeckContext): ToolDeck {
+    const selected = cardsForDeckProfile(profile);
+    const capabilities = buildSelected(selected, ctx);
+    return {
+        tools() {
+            return [...capabilities];
+        },
+        box() {
+            return [...capabilities];
+        },
+    };
+}
+
+// Touch `hasCapability` so the manifest's exported lookup remains reachable
+// through the public surface even when the provisioner does not need it.
+void hasCapability;

package/src/channels/contract.ts

@@ -0,0 +1,191 @@
+/**
+ * Channels contract — the FROZEN type surface of Phase 8 (non-interactive
+ * drivers).
+ *
+ * A *channel* is a way to talk to a {@link SessionConductor} from outside the
+ * interactive terminal.
+ */
+import type { ImageContent } from "indusagi/ai";
+import type {
+  ConductorState,
+  SessionConductor,
+  ThinkingLevel,
+  Usage,
+} from "../conductor/contract.js";
+
+export type { ImageContent, SessionConductor, ConductorState, ThinkingLevel, Usage };
+
+export const PROTOCOL_VERSION = "2.0" as const;
+export type ProtocolVersion = typeof PROTOCOL_VERSION;
+
+export type RequestId = string | number;
+
+export interface OpRequest<P = unknown> {
+  readonly jsonrpc: ProtocolVersion;
+  readonly id?: RequestId;
+  readonly method: string;
+  readonly params?: P;
+}
+
+export interface OpError {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: unknown;
+}
+
+export interface ReplyOk<R = unknown> {
+  readonly jsonrpc: ProtocolVersion;
+  readonly id: RequestId;
+  readonly result: R;
+}
+
+export interface ReplyErr {
+  readonly jsonrpc: ProtocolVersion;
+  readonly id: RequestId;
+  readonly error: OpError;
+}
+
+export type Reply<R = unknown> = ReplyOk<R> | ReplyErr;
+
+export function isReplyOk<R>(reply: Reply<R>): reply is ReplyOk<R> {
+  return "result" in reply;
+}
+
+export const OP_ERROR = Object.freeze({
+  parse: -32700,
+  invalidRequest: -32600,
+  unknownOp: -32601,
+  invalidParams: -32602,
+  handlerFailed: -32000,
+});
+
+export interface WritableLine {
+  write(chunk: string, cb?: (error?: Error | null) => void): boolean;
+}
+
+export type ReadableChunks = AsyncIterable<string | Uint8Array>;
+
+export type EncodeLine = (value: unknown) => string;
+export type DecodeLines = (stream: ReadableChunks) => AsyncGenerator<unknown, void, unknown>;
+
+export interface NdjsonFramer {
+  readonly encodeLine: EncodeLine;
+  readonly decodeLines: DecodeLines;
+}
+
+export interface Ask {
+  readonly type: "ask";
+  readonly id: string;
+  readonly kind: string;
+  readonly payload?: unknown;
+}
+
+export interface AskAnswer {
+  readonly type: "answer";
+  readonly id: string;
+  readonly value: unknown;
+}
+
+export interface Tell {
+  readonly type: "tell";
+  readonly kind: string;
+  readonly payload?: unknown;
+}
+
+export interface DialogBridge {
+  ask<T>(kind: string, payload: unknown, fallback: T): Promise<T>;
+  tell(kind: string, payload?: unknown): void;
+}
+
+export interface ChannelContext {
+  readonly conductor: SessionConductor;
+  readonly out: WritableLine;
+  readonly framer: NdjsonFramer;
+  readonly dialog: DialogBridge;
+}
+
+export interface Op<P = void, R = unknown> {
+  readonly method: string;
+  handle(params: P, ctx: ChannelContext): Promise<R>;
+}
+
+export type OpRegistry = Readonly<Record<string, Op<any, any>>>;
+
+export function defineOps<T extends Record<string, Op<any, any>>>(ops: T): Readonly<T> {
+  return Object.freeze({ ...ops });
+}
+
+export type OpParams<O> = O extends Op<infer P, any> ? P : never;
+export type OpResult<O> = O extends Op<any, infer R> ? R : never;
+
+export type LinkDriver<Ops extends OpRegistry> = {
+  [K in keyof Ops]: OpParams<Ops[K]> extends void
+    ? () => Promise<OpResult<Ops[K]>>
+    : (params: OpParams<Ops[K]>) => Promise<OpResult<Ops[K]>>;
+};
+
+export interface LinkSnapshot {
+  readonly model: string;
+  readonly thinking: ThinkingLevel;
+  readonly streaming: boolean;
+  readonly condensing: boolean;
+  readonly faulted: boolean;
+  readonly sessionId: string;
+  readonly sessionFile?: string;
+  readonly autoCondense: boolean;
+  readonly messageCount: number;
+  readonly queuedCount: number;
+  readonly usage: Usage;
+}
+
+export interface Signal {
+  readonly type: "signal";
+  readonly name: string;
+  readonly body: unknown;
+}
+
+export type OneshotShape = "text" | "ndjson";
+
+export interface OneshotRequest {
+  readonly shape: OneshotShape;
+  readonly prompts: readonly string[];
+  readonly images?: readonly ImageContent[];
+}
+
+export interface OneshotStrategy {
+  onStart?(ctx: ChannelContext): void | Promise<void>;
+  onSignal?(signal: unknown, ctx: ChannelContext): void;
+  finish(state: ConductorState, ctx: ChannelContext): number | Promise<number>;
+}
+
+export const REQUEST_ID_PREFIX = "lnk-";
+
+export interface ChannelTimings {
+  readonly startupMs: number;
+  readonly shutdownMs: number;
+  readonly requestMs: number;
+  readonly dialogMs: number;
+}
+
+export const DEFAULT_CHANNEL_TIMINGS: ChannelTimings = Object.freeze({
+  startupMs: 1500,
+  shutdownMs: 1200,
+  requestMs: 45_000,
+  dialogMs: 90_000,
+});
+
+export interface DriverOptions {
+  readonly out?: WritableLine;
+  readonly in?: ReadableChunks;
+  readonly timings?: Partial<ChannelTimings>;
+  readonly framer?: NdjsonFramer;
+  readonly onSignal?: (signal: Signal) => void;
+  readonly onAsk?: (ask: Ask) => Promise<unknown>;
+}
+
+export interface ServerOptions {
+  readonly in?: ReadableChunks;
+  readonly out?: WritableLine;
+  readonly timings?: Partial<ChannelTimings>;
+  readonly framer?: NdjsonFramer;
+}

package/src/channels/framer.ts

@@ -0,0 +1,50 @@
+/**
+ * NDJSON framer — the concrete, separator-safe line transport.
+ */
+import type { DecodeLines, EncodeLine, NdjsonFramer } from "./contract.js";
+
+const LINE_FEED = "\n";
+const LINE_SEPARATOR = "\u2028";
+const LINE_SEPARATOR_ESCAPE = "\\u2028";
+const PARAGRAPH_SEPARATOR_ESCAPE = "\\u2029";
+const SEPARATOR_PATTERN = /[\u2028\u2029]/g;
+const TEXT_DECODER = new TextDecoder();
+
+function escapeSeparators(json: string): string {
+  return json.replace(
+    SEPARATOR_PATTERN,
+    (ch) => (ch === LINE_SEPARATOR ? LINE_SEPARATOR_ESCAPE : PARAGRAPH_SEPARATOR_ESCAPE),
+  );
+}
+
+export const encodeLine: EncodeLine = (value) =>
+  escapeSeparators(JSON.stringify(value)) + LINE_FEED;
+
+function chunkToText(chunk: string | Uint8Array): string {
+  return typeof chunk === "string" ? chunk : TEXT_DECODER.decode(chunk, { stream: true });
+}
+
+export const decodeLines: DecodeLines = async function* (stream) {
+  let buffer = "";
+  for await (const chunk of stream) {
+    buffer += chunkToText(chunk);
+    let newlineAt = buffer.indexOf(LINE_FEED);
+    while (newlineAt !== -1) {
+      const line = buffer.slice(0, newlineAt);
+      buffer = buffer.slice(newlineAt + 1);
+      if (line.trim().length > 0) {
+        yield JSON.parse(line);
+      }
+      newlineAt = buffer.indexOf(LINE_FEED);
+    }
+  }
+  buffer += TEXT_DECODER.decode();
+  if (buffer.trim().length > 0) {
+    yield JSON.parse(buffer);
+  }
+};
+
+export const ndjsonFramer: NdjsonFramer = Object.freeze({
+  encodeLine,
+  decodeLines,
+});

package/src/channels/index.ts

@@ -0,0 +1,101 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Channels subsystem — public barrel.
+ *
+ * Re-exports the FROZEN Phase-8 contract: the JSON-RPC 2.0 envelope
+ * ({@link OpRequest}, {@link Reply}, {@link OpError}), the declarative operation
+ * registry ({@link Op}, {@link OpRegistry}, {@link defineOps}) and the type that
+ * the typed client is generated from ({@link LinkDriver}), the NDJSON framer
+ * surface ({@link NdjsonFramer} / {@link EncodeLine} / {@link DecodeLines}), the
+ * dialog primitives ({@link Ask} / {@link Tell} / {@link DialogBridge}), the
+ * {@link ChannelContext}, the wire session projection ({@link LinkSnapshot}), and
+ * the oneshot channel shapes ({@link OneshotRequest} / {@link OneshotStrategy}).
+ *
+ * Behavior modules (the oneshot runner, the link server, the generated driver,
+ * the NDJSON framer, and the dialog bridge) are added to this barrel as they
+ * land; consumers import the channel surface from `src/channels` rather than
+ * reaching into individual modules.
+ */
+export type {
+  ProtocolVersion,
+  RequestId,
+  OpRequest,
+  OpError,
+  ReplyOk,
+  ReplyErr,
+  Reply,
+  WritableLine,
+  ReadableChunks,
+  EncodeLine,
+  DecodeLines,
+  NdjsonFramer,
+  Ask,
+  AskAnswer,
+  Tell,
+  DialogBridge,
+  ChannelContext,
+  Op,
+  OpRegistry,
+  OpParams,
+  OpResult,
+  LinkDriver,
+  LinkSnapshot,
+  Signal,
+  OneshotShape,
+  OneshotRequest,
+  OneshotStrategy,
+  ChannelTimings,
+  DriverOptions,
+  ServerOptions,
+  ImageContent,
+  SessionConductor,
+  ConductorState,
+  ThinkingLevel,
+  Usage,
+} from "./contract.js";
+export {
+  PROTOCOL_VERSION,
+  OP_ERROR,
+  REQUEST_ID_PREFIX,
+  DEFAULT_CHANNEL_TIMINGS,
+  isReplyOk,
+  defineOps,
+} from "./contract.js";
+export { encodeLine, decodeLines, ndjsonFramer } from "./framer.js";
+export {
+  dispatch,
+  hasOp,
+  methodsOf,
+  buildOps,
+  UnknownOpError,
+  type OpRegistryHandle,
+} from "./ops.js";
+export { runOneshot, inertDialog } from "./oneshot.js";
+export {
+  SESSION_OPS,
+  projectSnapshot,
+  type SessionOps,
+  type SubmitParams,
+  type ResumeParams,
+  type CycleModelParams,
+  type ModelEntry,
+} from "./session-ops.js";
+export {
+  createLinkServer,
+  createLinkDriver,
+  createDialogBridge,
+  makeDialogMethods,
+  DIALOG_TABLE,
+  LinkRequestError,
+  type LinkServer,
+  type LinkServerIo,
+  type LinkServerConfig,
+  type LinkDriverHandle,
+  type LinkDriverIo,
+  type LinkDriverConfig,
+  type LinkedDialogBridge,
+  type DialogBridgeDeps,
+  type DialogSpec,
+  type DialogMethods,
+} from "./link/index.js";