indusagi-coding-agent 0.2.5 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indusagi-coding-agent",
-  "version": "0.2.5",
+  "version": "0.2.9",
   "description": "Indusagi coding agent — a terminal-first AI coding agent, built from scratch on the indusagi framework.",
   "author": "Varun Israni",
   "license": "AGPL-3.0",
@@ -40,6 +40,7 @@
   },
   "files": [
     "dist",
+    "src",
     "CHANGELOG.md",
     "CREDITS.md",
     "NOTICE",
@@ -58,7 +59,7 @@
     "@sinclair/typebox": "^0.34.49",
     "chalk": "^5.6.2",
     "highlight.js": "^11.11.1",
-    "indusagi": "^0.13.8",
+    "indusagi": "^0.13.9",
     "ink": "^5.2.1",
     "jiti": "^2.7.0",
     "marked": "^18.0.4",

package/src/_decls/entry.ts

@@ -0,0 +1,18 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Process entry point — the bin the OS launches.
+ *
+ * Responsibilities, in order:
+ *   1. Set `process.title` to the brand's primary bin name so the process is
+ *      identifiable in `ps` / activity monitors.
+ *   2. Install exactly one console filter that suppresses the transport-layer
+ *      `[MCP]` noise the MCP stack emits on stdout/stderr (unless the brand's
+ *      debug env var is set, in which case nothing is filtered).
+ *   3. Hand the sliced `argv` to {@link boot} and adopt its resolved exit code.
+ *
+ * The boot call is guarded by an `import.meta` entry check so importing this
+ * module (e.g. from a test) does not launch the agent — only running it as the
+ * program entry does.
+ */
+export {};

package/src/_decls/guardrails.ts

@@ -0,0 +1,35 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Thin guardrails entry — the headless, library-consumable surface of the
+ * indusagi coding agent.
+ *
+ * This barrel re-exports ONLY the deterministic guardrail primitives (the
+ * permission rule engine, the bash blocklist, prompt assembly, deck
+ * provisioning, and the read-before-edit / checkpoint stores). It deliberately
+ * imports from the LEAF modules — never the root `src/index.ts` barrel — so a
+ * consumer can pull in the guardrails without dragging in the Ink/React console
+ * tree (`export * as consoleUi from "./console.js"` lives only on the root barrel).
+ *
+ * Reachable from a published install as `indusagi-coding-agent/guardrails`.
+ */
+export { resolveRuleDecision, makeRule, createPermissionGate, READ_ONLY_TOOL_NAMES, EDIT_TOOL_NAMES, } from "./conductor/permissions";
+export type { PermissionRule, PermissionMode, PermissionBehavior, PermissionDecision, } from "./conductor/permissions";
+export { evaluateCatastrophic, bashSubcommandSubjects } from "./conductor/bash-guard";
+export { composeBriefing } from "./briefing/compose";
+export { gatherContextDocs } from "./briefing/context-docs";
+export type { AgentTool, BriefingContext, ContextDoc } from "./briefing/contract";
+export { provisionDeck } from "./capability-deck/provision";
+export { createReadStateStore, READ_STATE_HANDLE_KEY, ReadStateStore } from "./boot/runners/read-state";
+export { createCheckpointStore, CHECKPOINT_HANDLE_KEY, CheckpointStore } from "./boot/runners/checkpoint";
+/**
+ * The byte-stable refusal emitted when an edit/write is attempted on a file the
+ * agent has not read this session.
+ *
+ * Surfaced here as the guardrails contract for consumers (e.g. eval fixtures)
+ * that assert the refusal verbatim. The literal is intentionally duplicated
+ * rather than re-exported because the upstream message lives only as a private
+ * module-local const in the framework's read-state gate — it is not part of any
+ * public barrel. A reword on either side must update both sites, by design.
+ */
+export declare const READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";

package/src/_decls/index.ts

@@ -0,0 +1,26 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Package root barrel — the public library surface of the indusagi coding agent.
+ *
+ * The terminal binary is `entry.ts` (the `indus` / `indusagi` bin). This barrel
+ * exposes each subsystem as a namespace for embedding or testing. The agent
+ * depends only on the `indusagi` framework package.
+ */
+export * as boot from "./boot.js";
+export * as workspace from "./workspace.js";
+export * as conductor from "./conductor.js";
+export * as windowBudget from "./window-budget.js";
+export * as capabilityDeck from "./capability-deck.js";
+export * as runtimeBridge from "./runtime-bridge.js";
+export * as addons from "./addons.js";
+export * as consoleUi from "./console.js";
+export * as channels from "./channels.js";
+export * as briefing from "./briefing.js";
+export * as transcriptExport from "./transcript-export.js";
+export * as launch from "./launch.js";
+export * as insight from "./insight.js";
+export * as kit from "./kit.js";
+export * as settings from "./settings.js";
+export * as sessions from "./sessions.js";
+export { VERSION } from "./workspace.js";

package/src/addons/contract.ts

@@ -0,0 +1,236 @@
+/**
+ * Addons contract — the FROZEN type surface of the third-party customization
+ * layer.
+ *
+ * This module is the single typed seam between the coding-agent *product* and
+ * code that does not ship with it.
+ */
+import type { AgentMessage, AgentTool, AgentToolResult, ThinkingLevel } from "indusagi/agent";
+import type { Model } from "indusagi/ai";
+import type { Component, KeyId } from "indusagi/tui";
+import type { Static, TSchema } from "@sinclair/typebox";
+
+export type {
+  AgentMessage,
+  AgentTool,
+  AgentToolResult,
+  ThinkingLevel,
+  Model,
+  Component,
+  KeyId,
+  TSchema,
+  Static,
+};
+
+export type BundledNamespace =
+  | "indusagi/agent"
+  | "indusagi/ai"
+  | "indusagi/tui"
+  | "@sinclair/typebox";
+
+export const BUNDLED_NAMESPACES: readonly BundledNamespace[] = [
+  "indusagi/agent",
+  "indusagi/ai",
+  "indusagi/tui",
+  "@sinclair/typebox",
+];
+
+export type AddonId = string & { readonly __addon: unique symbol };
+
+export function addonId(raw: string): AddonId {
+  return raw as AddonId;
+}
+
+export interface AddonManifest {
+  readonly id?: string;
+  readonly version?: string;
+  register(surface: AddonSurface): void | Promise<void>;
+}
+
+export interface RegisteredManifest {
+  readonly addon: AddonId;
+  readonly version?: string;
+  readonly subscriptions: readonly EventSubscription[];
+  readonly interceptors: readonly ToolInterceptor[];
+  readonly commands: readonly AddonCommand[];
+  readonly tools: readonly AddonTool[];
+}
+
+export function emptyManifest(addon: AddonId, version?: string): RegisteredManifest {
+  return version === undefined
+    ? { addon, subscriptions: [], interceptors: [], commands: [], tools: [] }
+    : { addon, version, subscriptions: [], interceptors: [], commands: [], tools: [] };
+}
+
+export type HookEvent =
+  | "session:start"
+  | "session:end"
+  | "turn:start"
+  | "turn:end"
+  | "tool:before"
+  | "tool:after"
+  | "chat:params"
+  | "chat:message"
+  | "shell:env"
+  | "input:submit"
+  | "context:build"
+  | "compact:build"
+  | "compact:before";
+
+export type HookKind = "observe" | "transform" | "gate";
+
+export interface GateDecision {
+  readonly stop: boolean;
+  readonly reason?: string;
+}
+
+export type HookHandler<TPayload = unknown> =
+  | { readonly kind: "observe"; run(payload: TPayload): void | Promise<void> }
+  | { readonly kind: "transform"; run(payload: TPayload): TPayload | Promise<TPayload> }
+  | {
+      readonly kind: "gate";
+      run(payload: TPayload): GateDecision | void | Promise<GateDecision | void>;
+    };
+
+export interface EventSubscription {
+  readonly event: HookEvent;
+  readonly handler: HookHandler;
+  readonly addon: AddonId;
+}
+
+export interface DispatchOutcome<TPayload> {
+  readonly payload: TPayload;
+  readonly gate?: GateDecision;
+}
+
+export interface EventDispatcher {
+  dispatch<TPayload>(event: HookEvent, payload: TPayload): Promise<DispatchOutcome<TPayload>>;
+  has(event: HookEvent): boolean;
+  onFault(listener: AddonFaultListener): () => void;
+}
+
+export interface ToolEnterContext {
+  readonly tool: string;
+  readonly callId: string;
+  readonly args: Readonly<Record<string, unknown>>;
+}
+
+export interface ToolExitContext {
+  readonly tool: string;
+  readonly callId: string;
+  readonly result?: AgentToolResult<unknown>;
+  readonly error?: unknown;
+}
+
+export type EnterOutcome =
+  | void
+  | { readonly args: Readonly<Record<string, unknown>> }
+  | GateDecision;
+
+export type ExitOutcome = void | AgentToolResult<unknown>;
+
+export interface ToolInterceptor {
+  readonly match: string | "*";
+  readonly addon: AddonId;
+  enter?(ctx: ToolEnterContext): EnterOutcome | Promise<EnterOutcome>;
+  exit?(ctx: ToolExitContext): ExitOutcome | Promise<ExitOutcome>;
+}
+
+export interface InterceptResult {
+  readonly result?: AgentToolResult<unknown>;
+  readonly blocked?: GateDecision;
+}
+
+export interface InterceptorChain {
+  run(
+    ctx: ToolEnterContext,
+    execute: (args: Readonly<Record<string, unknown>>) => Promise<AgentToolResult<unknown>>,
+  ): Promise<InterceptResult>;
+  matches(tool: string): boolean;
+}
+
+export type AddonTool<TParameters extends TSchema = TSchema, TDetails = unknown> = AgentTool<
+  TParameters,
+  TDetails
+>;
+
+export interface CommandContext {
+  readonly args: string;
+  readonly cwd: string;
+  readonly handles: FrameworkHandles;
+}
+
+export interface AddonCommand {
+  readonly name: string;
+  readonly summary: string;
+  readonly addon: AddonId;
+  run(ctx: CommandContext): void | Promise<void>;
+}
+
+export interface ExecOutcome {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly code: number | null;
+}
+
+export interface FrameworkHandles {
+  readonly sendMessage?: (text: string) => void | Promise<void>;
+  readonly setModel?: (id: string) => void | Promise<void>;
+  readonly setThinking?: (level: ThinkingLevel) => void;
+  readonly render?: (component: Component) => void;
+  readonly exec?: (command: string) => Promise<ExecOutcome>;
+}
+
+export interface AddonSurface {
+  readonly id: AddonId;
+  on<TPayload>(event: HookEvent, handler: HookHandler<TPayload>): void;
+  interceptTool(name: string | "*", interceptor: Omit<ToolInterceptor, "match" | "addon">): void;
+  addCommand(name: string, handler: Omit<AddonCommand, "name" | "addon">): void;
+  addTool(card: AddonTool): void;
+  readonly handles: FrameworkHandles;
+  manifest(): RegisteredManifest;
+}
+
+export interface ModuleLoader {
+  load(path: string): Promise<AddonManifest>;
+}
+
+export interface AddonDiscovery {
+  readonly workspace?: string;
+  readonly dir?: string;
+  readonly explicitPaths?: readonly string[];
+}
+
+export const ADDONS_DIR = ".indus/addons" as const;
+export const ADDON_MANIFEST_FIELD = "indusAddon" as const;
+
+export interface AddonSource {
+  readonly id: AddonId;
+  readonly path: string;
+}
+
+export type AddonFaultKind = "load" | "register" | "handler" | "command" | "conflict";
+
+export interface AddonFault {
+  readonly kind: AddonFaultKind;
+  readonly message: string;
+  readonly addon?: AddonId;
+  readonly cause?: unknown;
+}
+
+export type AddonFaultListener = (fault: AddonFault) => void;
+
+export function addonFault(
+  kind: AddonFaultKind,
+  message: string,
+  detail?: { addon?: AddonId; cause?: unknown },
+): AddonFault {
+  const fault = { kind, message };
+  const addon = detail?.addon;
+  const cause = detail?.cause;
+  return {
+    ...fault,
+    ...(addon !== undefined ? { addon } : {}),
+    ...(cause !== undefined ? { cause } : {}),
+  };
+}

package/src/addons/dispatch/event-dispatcher.ts

@@ -0,0 +1,164 @@
+/**
+ * EventDispatcher — the single fan-out / transform / veto engine for the unified
+ * colon-named event taxonomy.
+ */
+import {
+  addonFault,
+  type AddonFault,
+  type AddonFaultListener,
+  type AddonId,
+  type DispatchOutcome,
+  type EventDispatcher,
+  type EventSubscription,
+  type HookEvent,
+  type HookHandler,
+} from "../contract.js";
+
+interface EventTrait {
+  guards: boolean;
+}
+
+const EVENT_TRAITS: Readonly<Record<HookEvent, EventTrait>> = Object.freeze({
+  "session:start": { guards: false },
+  "session:end": { guards: false },
+  "turn:start": { guards: false },
+  "turn:end": { guards: false },
+  "tool:before": { guards: true },
+  "tool:after": { guards: false },
+  "chat:params": { guards: false },
+  "chat:message": { guards: false },
+  "shell:env": { guards: false },
+  "input:submit": { guards: true },
+  "context:build": { guards: false },
+  "compact:build": { guards: false },
+  "compact:before": { guards: true },
+});
+
+const RESERVED_EVENTS: ReadonlySet<HookEvent> = new Set(
+  (Object.keys(EVENT_TRAITS) as HookEvent[]).filter(
+    (event) => EVENT_TRAITS[event].guards,
+  ),
+);
+
+function groupByEvent(
+  subscriptions: readonly EventSubscription[],
+): Map<HookEvent, EventSubscription[]> {
+  const grouped = new Map<HookEvent, EventSubscription[]>();
+  for (const sub of subscriptions) {
+    const list = grouped.get(sub.event);
+    if (list === undefined) {
+      grouped.set(sub.event, [sub]);
+    } else {
+      list.push(sub);
+    }
+  }
+  return grouped;
+}
+
+export class AddonEventDispatcher implements EventDispatcher {
+  private readonly byEvent: Map<HookEvent, EventSubscription[]>;
+  private readonly faultListeners: Set<AddonFaultListener>;
+
+  constructor(subscriptions: readonly EventSubscription[]) {
+    this.byEvent = groupByEvent(subscriptions);
+    this.faultListeners = new Set();
+  }
+
+  static from(subscriptions: readonly EventSubscription[]): AddonEventDispatcher {
+    return new AddonEventDispatcher(subscriptions);
+  }
+
+  get reserved(): ReadonlySet<HookEvent> {
+    return RESERVED_EVENTS;
+  }
+
+  async dispatch<TPayload>(
+    event: HookEvent,
+    payload: TPayload,
+  ): Promise<DispatchOutcome<TPayload>> {
+    const subscriptions = this.byEvent.get(event);
+    if (subscriptions === undefined || subscriptions.length === 0) {
+      return { payload };
+    }
+    let current = payload;
+    for (const sub of subscriptions) {
+      const gate = await this.run(event, sub, current, (next) => {
+        current = next;
+      });
+      if (gate !== undefined && gate.stop) {
+        return { payload: current, gate };
+      }
+    }
+    return { payload: current };
+  }
+
+  has(event: HookEvent): boolean {
+    const subscriptions = this.byEvent.get(event);
+    return subscriptions !== undefined && subscriptions.length > 0;
+  }
+
+  onFault(listener: AddonFaultListener): () => void {
+    this.faultListeners.add(listener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this.faultListeners.delete(listener);
+    };
+  }
+
+  private async run<TPayload>(
+    event: HookEvent,
+    sub: EventSubscription,
+    payload: TPayload,
+    commit: (next: TPayload) => void,
+  ): Promise<{ stop: boolean } | undefined> {
+    const handler = sub.handler;
+    try {
+      switch (handler.kind) {
+        case "observe": {
+          await handler.run(payload);
+          return undefined;
+        }
+        case "transform": {
+          const next = await handler.run(payload);
+          commit(next);
+          return undefined;
+        }
+        case "gate": {
+          const decision = await handler.run(payload);
+          return decision ?? undefined;
+        }
+      }
+    } catch (cause) {
+      this.report(
+        addonFault("handler", `Handler for "${event}" threw during dispatch.`, {
+          addon: sub.addon,
+          cause,
+        }),
+      );
+      return undefined;
+    }
+  }
+
+  private report(fault: AddonFault): void {
+    for (const listener of [...this.faultListeners]) {
+      try {
+        listener(fault);
+      } catch {
+        /* ignore listener errors */
+      }
+    }
+  }
+}
+
+/**
+ * Record one event subscription, stamping it with the owning addon.
+ */
+export function subscription(
+  addon: AddonId,
+  event: HookEvent,
+  handler: HookHandler,
+): EventSubscription {
+  return { event, handler, addon };
+}

package/src/addons/dispatch/index.ts

@@ -0,0 +1,25 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Dispatch subsystem — public barrel.
+ *
+ * The unified hook + tool-interception runtime, written against the frozen
+ * {@link module:../contract} surface:
+ *
+ *   - {@link AddonEventDispatcher} — the single fan-out / transform / veto engine
+ *     for the colon-named {@link HookEvent} taxonomy. Folds every addon's
+ *     {@link EventSubscription}s into one ordered middleware pass (observe /
+ *     transform / gate), short-circuits on the first veto, and derives its
+ *     reserved (gate-bearing) event set from a data table rather than a literal.
+ *   - {@link AddonInterceptorChain} — the composable tool-call boundary. Folds
+ *     every addon's {@link ToolInterceptor} stages around one tool execution
+ *     (enter forward, exit reverse), rewriting args/results or blocking the call,
+ *     replacing the old tool wrapper plus before/after hook runner.
+ *
+ * Both isolate handler/stage faults into {@link AddonFault}s routed to listeners
+ * so a misbehaving addon never crashes the agent loop. The `subscription` and
+ * `interceptor` helpers mint the contract's recorded shapes for hosts/tests that
+ * assemble them outside the full surface builder.
+ */
+export { AddonEventDispatcher, subscription } from "./event-dispatcher.js";
+export { AddonInterceptorChain, interceptor } from "./tool-interceptor.js";