indusagi-coding-agent 0.2.8 → 0.2.9

package/src/addons/dispatch/tool-interceptor.ts

@@ -0,0 +1,208 @@
+/**
+ * ToolInterceptor pipeline — the composable tool-call boundary.
+ */
+import type { AgentToolResult } from "indusagi/agent";
+import {
+  addonFault,
+  type AddonFault,
+  type AddonFaultListener,
+  type AddonId,
+  type EnterOutcome,
+  type InterceptResult,
+  type InterceptorChain,
+  type ToolEnterContext,
+  type ToolInterceptor,
+} from "../contract.js";
+
+type Execute = (
+  args: Readonly<Record<string, unknown>>,
+) => Promise<AgentToolResult<unknown>>;
+
+interface EnterVerdict {
+  args?: Readonly<Record<string, unknown>>;
+  blocked?: { stop: boolean; reason?: string };
+}
+
+function isGate(value: unknown): value is { stop: boolean; reason?: string } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "stop" in value &&
+    typeof (value as { stop: unknown }).stop === "boolean"
+  );
+}
+
+function isArgsRewrite(value: unknown): value is { args: Readonly<Record<string, unknown>> } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "args" in value &&
+    typeof (value as { args: unknown }).args === "object" &&
+    (value as { args: unknown }).args !== null
+  );
+}
+
+function readEnter(outcome: EnterOutcome): EnterVerdict {
+  if (outcome === undefined || outcome === null) return {};
+  if (isGate(outcome)) {
+    return outcome.stop ? { blocked: outcome } : {};
+  }
+  if (isArgsRewrite(outcome)) {
+    return { args: outcome.args };
+  }
+  return {};
+}
+
+function matchesTool(match: string | "*", tool: string): boolean {
+  return match === "*" || match === tool;
+}
+
+function buildExitContext(
+  ctx: ToolEnterContext,
+  result: AgentToolResult<unknown> | undefined,
+  error: unknown,
+): { tool: string; callId: string; result?: AgentToolResult<unknown>; error?: unknown } {
+  const base = { tool: ctx.tool, callId: ctx.callId };
+  if (error !== undefined) return { ...base, error };
+  return result !== undefined ? { ...base, result } : base;
+}
+
+export class AddonInterceptorChain implements InterceptorChain {
+  private readonly interceptors: readonly ToolInterceptor[];
+  private readonly faultListeners: Set<AddonFaultListener>;
+
+  constructor(interceptors: readonly ToolInterceptor[]) {
+    this.interceptors = interceptors;
+    this.faultListeners = new Set();
+  }
+
+  static from(interceptors: readonly ToolInterceptor[]): AddonInterceptorChain {
+    return new AddonInterceptorChain(interceptors);
+  }
+
+  async run(ctx: ToolEnterContext, execute: Execute): Promise<InterceptResult> {
+    const matching = this.interceptors.filter((stage) => matchesTool(stage.match, ctx.tool));
+    if (matching.length === 0) {
+      return { result: await execute(ctx.args) };
+    }
+    const entered = await this.applyEnter(ctx, matching);
+    if (entered.blocked !== undefined) {
+      return { blocked: entered.blocked };
+    }
+    const execCtx = { ...ctx, args: entered.args ?? ctx.args };
+    let result: AgentToolResult<unknown> | undefined;
+    let error: unknown;
+    try {
+      result = await execute(execCtx.args);
+    } catch (cause) {
+      error = cause;
+    }
+    const exited = await this.applyExit(execCtx, matching, result, error);
+    if (exited !== undefined) {
+      return { result: exited };
+    }
+    if (error !== undefined) {
+      throw error;
+    }
+    return { result };
+  }
+
+  matches(tool: string): boolean {
+    return this.interceptors.some((stage) => matchesTool(stage.match, tool));
+  }
+
+  onFault(listener: AddonFaultListener): () => void {
+    this.faultListeners.add(listener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this.faultListeners.delete(listener);
+    };
+  }
+
+  private async applyEnter(
+    ctx: ToolEnterContext,
+    stages: readonly ToolInterceptor[],
+  ): Promise<EnterVerdict> {
+    let args: Readonly<Record<string, unknown>> = ctx.args;
+    for (const stage of stages) {
+      if (stage.enter === undefined) continue;
+      const here = { ...ctx, args };
+      let outcome: EnterOutcome | undefined;
+      try {
+        outcome = await stage.enter(here);
+      } catch (cause) {
+        this.report(
+          addonFault("handler", `Interceptor enter for "${ctx.tool}" threw.`, {
+            addon: stage.addon,
+            cause,
+          }),
+        );
+        continue;
+      }
+      const verdict = readEnter(outcome);
+      if (verdict.blocked !== undefined) {
+        return { args, blocked: verdict.blocked };
+      }
+      if (verdict.args !== undefined) {
+        args = verdict.args;
+      }
+    }
+    return { args };
+  }
+
+  private async applyExit(
+    ctx: ToolEnterContext,
+    stages: readonly ToolInterceptor[],
+    result: AgentToolResult<unknown> | undefined,
+    error: unknown,
+  ): Promise<AgentToolResult<unknown> | undefined> {
+    let current = result;
+    let rewritten = false;
+    for (let i = stages.length - 1; i >= 0; i--) {
+      const stage = stages[i];
+      if (stage.exit === undefined) continue;
+      const exitCtx = buildExitContext(ctx, current, error);
+      let outcome: AgentToolResult<unknown> | undefined;
+      try {
+        outcome = await stage.exit(exitCtx);
+      } catch (cause) {
+        this.report(
+          addonFault("handler", `Interceptor exit for "${ctx.tool}" threw.`, {
+            addon: stage.addon,
+            cause,
+          }),
+        );
+        continue;
+      }
+      if (outcome !== undefined) {
+        current = outcome;
+        rewritten = true;
+      }
+    }
+    return rewritten ? current : undefined;
+  }
+
+  private report(fault: AddonFault): void {
+    for (const listener of [...this.faultListeners]) {
+      try {
+        listener(fault);
+      } catch {
+        /* ignore listener errors */
+      }
+    }
+  }
+}
+
+/**
+ * Record one tool interceptor, stamping it with the matched tool and owning
+ * addon.
+ */
+export function interceptor(
+  addon: AddonId,
+  match: string | "*",
+  stage: Omit<ToolInterceptor, "match" | "addon">,
+): ToolInterceptor {
+  return { ...stage, match, addon };
+}

package/src/addons/host.ts

@@ -0,0 +1,225 @@
+/**
+ * AddonHost — the assembly point that turns a directory of addon modules into a
+ * single wired runtime.
+ */
+import {
+  addonFault,
+  addonId,
+  type AddonCommand,
+  type AddonDiscovery,
+  type AddonFault,
+  type AddonFaultListener,
+  type AddonId,
+  type AddonSource,
+  type AddonTool,
+  type EventDispatcher,
+  type EventSubscription,
+  type FrameworkHandles,
+  type InterceptorChain,
+  type ModuleLoader,
+  type RegisteredManifest,
+  type ToolInterceptor,
+} from "./contract.js";
+import { AddonEventDispatcher } from "./dispatch/event-dispatcher.js";
+import { AddonInterceptorChain } from "./dispatch/tool-interceptor.js";
+import { discoverSources } from "./manifest.js";
+import { createJitiLoader } from "./sandbox.js";
+import { createSurface } from "./surface.js";
+
+export interface AddonHostDeps {
+  readonly loader?: ModuleLoader;
+  readonly handles?: FrameworkHandles;
+  readonly dispatcher?: (subscriptions: readonly EventSubscription[]) => EventDispatcher;
+  readonly chain?: (interceptors: readonly ToolInterceptor[]) => InterceptorChain;
+  readonly reservedActions?: Iterable<string>;
+}
+
+export interface AddonRegistry {
+  readonly subscriptions: readonly EventSubscription[];
+  readonly interceptors: readonly ToolInterceptor[];
+  readonly commands: readonly AddonCommand[];
+  readonly tools: readonly AddonTool[];
+}
+
+export interface AddonSurfaceBundle {
+  readonly dispatch: EventDispatcher;
+  readonly interceptors: InterceptorChain;
+  readonly commands: readonly AddonCommand[];
+  readonly tools: readonly AddonTool[];
+  readonly loaded: readonly AddonId[];
+}
+
+const RESERVED_ACTION_NAMES: ReadonlySet<string> = new Set([
+  "help",
+  "quit",
+  "exit",
+  "clear",
+  "model",
+  "compact",
+]);
+
+export class AddonHost {
+  private readonly faultListeners: Set<AddonFaultListener> = new Set();
+  private readonly reserved: Set<string>;
+  private readonly subscriptions: EventSubscription[] = [];
+  private readonly interceptors: ToolInterceptor[] = [];
+  private readonly commands: AddonCommand[] = [];
+  private readonly tools: AddonTool[] = [];
+  private readonly claimedCommands: Set<string>;
+  private readonly claimedTools: Set<string> = new Set();
+  private readonly loaded: AddonId[] = [];
+  private readonly loader: ModuleLoader;
+  private readonly handles: FrameworkHandles;
+  private readonly buildDispatcher: (
+    subs: readonly EventSubscription[],
+  ) => EventDispatcher;
+  private readonly buildChain: (interceptors: readonly ToolInterceptor[]) => InterceptorChain;
+
+  constructor(deps: AddonHostDeps = {}) {
+    this.loader = deps.loader ?? createJitiLoader();
+    this.handles = deps.handles ?? {};
+    this.buildDispatcher =
+      deps.dispatcher ?? ((subs) => AddonEventDispatcher.from(subs));
+    this.buildChain = deps.chain ?? ((stages) => AddonInterceptorChain.from(stages));
+    this.reserved =
+      deps.reservedActions === undefined
+        ? new Set(RESERVED_ACTION_NAMES)
+        : new Set(deps.reservedActions);
+    this.claimedCommands = new Set(this.reserved);
+  }
+
+  onFault(listener: AddonFaultListener): () => void {
+    this.faultListeners.add(listener);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this.faultListeners.delete(listener);
+    };
+  }
+
+  async loadAll(where: string | AddonDiscovery): Promise<AddonSurfaceBundle> {
+    const discovery = typeof where === "string" ? { workspace: where } : where;
+    const sources = discoverSources(discovery);
+    for (const source of sources) {
+      await this.loadOne(source);
+    }
+    return this.bundle();
+  }
+
+  async loadOne(source: AddonSource): Promise<void> {
+    let module;
+    try {
+      module = await this.loader.load(source.path);
+    } catch (cause) {
+      this.report(
+        addonFault("load", `Failed to load addon at ${source.path}.`, {
+          addon: source.id,
+          cause,
+        }),
+      );
+      return;
+    }
+    const id = module.id !== undefined ? addonId(module.id) : source.id;
+    const surface = createSurface(id, this.handles, module.version);
+    try {
+      await module.register(surface);
+    } catch (cause) {
+      this.report(
+        addonFault("register", `Addon "${id}" threw during register().`, {
+          addon: id,
+          cause,
+        }),
+      );
+      return;
+    }
+    this.fold(id, surface.manifest());
+    this.loaded.push(id);
+  }
+
+  private bundle(): AddonSurfaceBundle {
+    const dispatch = this.buildDispatcher(this.subscriptions);
+    const interceptors = this.buildChain(this.interceptors);
+    this.wireFaults(dispatch);
+    this.wireFaults(interceptors);
+    return {
+      dispatch,
+      interceptors,
+      commands: [...this.commands],
+      tools: [...this.tools],
+      loaded: [...this.loaded],
+    };
+  }
+
+  get registry(): AddonRegistry {
+    return {
+      subscriptions: [...this.subscriptions],
+      interceptors: [...this.interceptors],
+      commands: [...this.commands],
+      tools: [...this.tools],
+    };
+  }
+
+  private fold(addon: AddonId, manifest: RegisteredManifest): void {
+    for (const sub of manifest.subscriptions) {
+      this.subscriptions.push(sub);
+    }
+    for (const stage of manifest.interceptors) {
+      this.interceptors.push(stage);
+    }
+    for (const command of manifest.commands) {
+      if (this.claimedCommands.has(command.name)) {
+        this.report(
+          addonFault(
+            "conflict",
+            this.reserved.has(command.name)
+              ? `Addon "${addon}" command "${command.name}" is a reserved action name.`
+              : `Addon "${addon}" command "${command.name}" conflicts with an already-registered command.`,
+            { addon },
+          ),
+        );
+        continue;
+      }
+      this.claimedCommands.add(command.name);
+      this.commands.push(command);
+    }
+    for (const tool of manifest.tools) {
+      if (this.claimedTools.has(tool.name)) {
+        this.report(
+          addonFault(
+            "conflict",
+            `Addon "${addon}" tool "${tool.name}" conflicts with an already-registered tool.`,
+            { addon },
+          ),
+        );
+        continue;
+      }
+      this.claimedTools.add(tool.name);
+      this.tools.push(tool);
+    }
+  }
+
+  private wireFaults(source: { onFault?: (listener: AddonFaultListener) => unknown }): void {
+    const onFault = source.onFault;
+    if (typeof onFault === "function") {
+      onFault.call(source, (fault: AddonFault) => this.report(fault));
+    }
+  }
+
+  private report(fault: AddonFault): void {
+    for (const listener of [...this.faultListeners]) {
+      try {
+        listener(fault);
+      } catch {
+        /* ignore listener errors */
+      }
+    }
+  }
+}
+
+/**
+ * Construct an {@link AddonHost} with the given (all-optional) dependencies.
+ */
+export function createAddonHost(deps: AddonHostDeps = {}): AddonHost {
+  return new AddonHost(deps);
+}

package/src/addons/index.ts

@@ -0,0 +1,112 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Addons subsystem — public barrel.
+ *
+ * Re-exports the FROZEN third-party customization contract: the
+ * {@link AddonManifest} an addon module returns and the {@link AddonSurface} its
+ * `register` entry point receives, the colon-named {@link HookEvent} taxonomy
+ * with its observe/transform/gate {@link HookHandler} middleware and the
+ * {@link EventDispatcher} that runs them, the tool-boundary {@link ToolInterceptor}
+ * stages and the {@link InterceptorChain} pipeline that folds them around a tool
+ * execution, the capabilities an addon contributes ({@link AddonTool},
+ * {@link AddonCommand}), the injectable {@link ModuleLoader} + {@link AddonDiscovery}
+ * loading seam, and the typed {@link AddonFault}.
+ *
+ * Behavior modules (the jiti-backed sandbox loader, the capability registry, the
+ * surface builder, the event dispatcher, and the interceptor chain) are added to
+ * this barrel as they land; consumers import the addon surface from
+ * `src/addons` rather than reaching into individual modules.
+ */
+export type {
+  BundledNamespace,
+  AddonId,
+  AddonManifest,
+  RegisteredManifest,
+  HookEvent,
+  HookKind,
+  GateDecision,
+  HookHandler,
+  EventSubscription,
+  EventDispatcher,
+  DispatchOutcome,
+  ToolEnterContext,
+  ToolExitContext,
+  EnterOutcome,
+  ExitOutcome,
+  ToolInterceptor,
+  InterceptorChain,
+  InterceptResult,
+  AddonTool,
+  CommandContext,
+  AddonCommand,
+  FrameworkHandles,
+  ExecOutcome,
+  AddonSurface,
+  ModuleLoader,
+  AddonDiscovery,
+  AddonSource,
+  AddonFaultKind,
+  AddonFault,
+  AddonFaultListener,
+  AgentMessage,
+  AgentTool,
+  AgentToolResult,
+  ThinkingLevel,
+  Model,
+  Component,
+  KeyId,
+  TSchema,
+  Static,
+} from "./contract.js";
+export {
+  BUNDLED_NAMESPACES,
+  ADDONS_DIR,
+  ADDON_MANIFEST_FIELD,
+  addonId,
+  emptyManifest,
+  addonFault,
+} from "./contract.js";
+/**
+ * Addon sandbox — the single jiti-backed {@link ModuleLoader}: bridges the
+ * framework {@link BUNDLED_NAMESPACES} into a loaded addon (virtual modules in a
+ * compiled binary, resolved aliases under Node) and turns a path into its
+ * {@link AddonManifest}. Injectable — tests supply a fake of the same interface.
+ */
+export {
+  createJitiLoader,
+  scrubInvisible,
+  expandPath,
+  resolvePath,
+  type JitiLoaderOptions,
+} from "./sandbox.js";
+/**
+ * Addon discovery — scan a `.indus/addons` directory for entry modules and fold
+ * an {@link AddonDiscovery} config into id-stamped {@link AddonSource}s.
+ */
+export { discoverAddons, discoverSources } from "./manifest.js";
+/**
+ * Dispatch runtime — the unified {@link EventDispatcher} (observe / transform /
+ * gate) and the tool-boundary {@link InterceptorChain}, plus the `subscription`
+ * and `interceptor` minters for assembling their recorded shapes by hand.
+ */
+export { AddonEventDispatcher, AddonInterceptorChain, subscription, interceptor } from "./dispatch/index.js";
+/**
+ * Addon surface — the per-addon recording {@link AddonSurface} the host hands to
+ * an addon's `register`; accumulates contributions and reads them back as a
+ * {@link RegisteredManifest}.
+ */
+export { createSurface } from "./surface.js";
+/**
+ * Addon host — the assembly point: discover + load (injectable loader), register
+ * each addon against a fresh surface, fold every {@link RegisteredManifest} into
+ * one registry, and wire the dispatch engine + interceptor chain + collected
+ * commands/tools.
+ */
+export {
+  createAddonHost,
+  AddonHost,
+  type AddonHostDeps,
+  type AddonRegistry,
+  type AddonSurfaceBundle,
+} from "./host.js";

package/src/addons/manifest.ts

@@ -0,0 +1,158 @@
+/**
+ * Addon discovery — scanning a workspace for addon entry modules.
+ *
+ * Where the sandbox module answers "how do I load *this* path", this module
+ * answers "*which* paths are there to load".
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, join, resolve } from "node:path";
+import {
+  ADDON_MANIFEST_FIELD,
+  ADDONS_DIR,
+  addonId,
+  type AddonDiscovery,
+  type AddonSource,
+} from "./contract.js";
+
+const ENTRY_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".js",
+  ".mjs",
+  ".cjs",
+];
+
+const INDEX_BASENAMES = ["index"];
+
+function isHidden(name: string): boolean {
+  return name.startsWith(".");
+}
+
+function hasEntryExtension(name: string): boolean {
+  return (ENTRY_EXTENSIONS as readonly string[]).includes(extname(name).toLowerCase());
+}
+
+function entryKind(path: string): "directory" | "file" | undefined {
+  try {
+    const stat = statSync(path);
+    if (stat.isDirectory()) return "directory";
+    if (stat.isFile()) return "file";
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function listNames(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+function readManifestEntry(packageDir: string): string | undefined {
+  const manifestPath = join(packageDir, "package.json");
+  if (entryKind(manifestPath) !== "file") {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as Record<string, unknown>;
+    if (typeof parsed !== "object" || parsed === null) {
+      return undefined;
+    }
+    const field = parsed[ADDON_MANIFEST_FIELD];
+    return typeof field === "string" ? field : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvePackageEntry(packageDir: string): string | undefined {
+  const declared = readManifestEntry(packageDir);
+  if (declared !== undefined) {
+    const declaredPath = resolve(packageDir, declared);
+    if (entryKind(declaredPath) === "file") {
+      return declaredPath;
+    }
+  }
+  for (const base of INDEX_BASENAMES) {
+    for (const ext of ENTRY_EXTENSIONS) {
+      const candidate = join(packageDir, `${base}${ext}`);
+      if (entryKind(candidate) === "file") {
+        return candidate;
+      }
+    }
+  }
+  return undefined;
+}
+
+function resolveTopLevelEntry(dir: string, name: string): string | undefined {
+  if (isHidden(name)) {
+    return undefined;
+  }
+  const path = join(dir, name);
+  const kind = entryKind(path);
+  if (kind === "file") {
+    return hasEntryExtension(name) ? path : undefined;
+  }
+  if (kind === "directory") {
+    return resolvePackageEntry(path);
+  }
+  return undefined;
+}
+
+/**
+ * Scan one addons directory and return the absolute entry-module paths it holds.
+ */
+export function discoverAddons(dir: string): string[] {
+  const entries: string[] = [];
+  for (const name of listNames(dir)) {
+    const entry = resolveTopLevelEntry(dir, name);
+    if (entry !== undefined) {
+      entries.push(entry);
+    }
+  }
+  return entries.sort();
+}
+
+function deriveAddonId(entryPath: string): string {
+  const file = basename(entryPath);
+  const stem = file.slice(0, file.length - extname(file).length);
+  const label =
+    (INDEX_BASENAMES as readonly string[]).includes(stem)
+      ? basename(join(entryPath, ".."))
+      : stem;
+  return addonId(label.length > 0 ? label : entryPath);
+}
+
+function addonsDirFor(workspace: string, dir: string = ADDONS_DIR): string {
+  return resolve(workspace, dir);
+}
+
+/**
+ * Fold an {@link AddonDiscovery} config into the ordered, deduplicated list of
+ * {@link AddonSource}s.
+ */
+export function discoverSources(discovery: AddonDiscovery): AddonSource[] {
+  const paths: string[] = [];
+  if (discovery.workspace !== undefined) {
+    const dir = addonsDirFor(discovery.workspace, discovery.dir ?? ADDONS_DIR);
+    paths.push(...discoverAddons(dir));
+  }
+  for (const explicit of discovery.explicitPaths ?? []) {
+    paths.push(isAbsolute(explicit) ? explicit : resolve(explicit));
+  }
+  const seen = new Set<string>();
+  const sources: AddonSource[] = [];
+  for (const path of paths) {
+    if (seen.has(path)) {
+      continue;
+    }
+    seen.add(path);
+    sources.push({ id: deriveAddonId(path), path });
+  }
+  return sources;
+}