indusagi-coding-agent 0.2.8 → 0.2.10

package/src/kit/external-editor.ts

@@ -0,0 +1,48 @@
+/**
+ * External-editor kit — hand the composer buffer off to the user's `$EDITOR`,
+ * wait for them to close it, and read the edited text back.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const FALLBACK_EDITOR = "vi";
+
+export interface ExternalEditorOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly dir?: string;
+}
+
+function resolveEditor(env: NodeJS.ProcessEnv): string[] {
+  const configured = env.VISUAL || env.EDITOR || FALLBACK_EDITOR;
+  const parts = configured.split(/\s+/).filter((part) => part.length > 0);
+  return parts.length > 0 ? parts : [FALLBACK_EDITOR];
+}
+
+export function openInExternalEditor(
+  buffer: string,
+  options: ExternalEditorOptions = {},
+): string | null {
+  const env = options.env ?? process.env;
+  const dir = options.dir ?? tmpdir();
+  const name = `indus-editor-${Date.now().toString(36)}-${Math.random()
+    .toString(36)
+    .slice(2, 8)}.md`;
+  const path = join(dir, name);
+  const [editor, ...editorArgs] = resolveEditor(env);
+  try {
+    writeFileSync(path, buffer, "utf8");
+    const result = spawnSync(editor, [...editorArgs, path], { stdio: "inherit" });
+    if (result.error || result.status !== 0) return null;
+    return readFileSync(path, "utf8").replace(/\n$/, "");
+  } catch {
+    return null;
+  } finally {
+    try {
+      unlinkSync(path);
+    } catch {
+      /* ignore cleanup errors */
+    }
+  }
+}

package/src/kit/image.ts

@@ -0,0 +1,59 @@
+/**
+ * Image kit — magic-byte sniffing for the two raster formats the agent ships
+ * support for, plus a tiny asset-naming helper.
+ */
+
+export type ImageFormat = "png" | "jpeg";
+export type ImageMediaType = "image/png" | "image/jpeg";
+
+const PNG_SIGNATURE: readonly number[] = [137, 80, 78, 71, 13, 10, 26, 10];
+const JPEG_SIGNATURE: readonly number[] = [255, 216, 255];
+
+export const IMAGE_SNIFF_BYTES: number = PNG_SIGNATURE.length;
+
+export type ByteSource = ArrayLike<number>;
+
+function startsWith(bytes: ArrayLike<number>, signature: readonly number[]): boolean {
+  if (bytes.length < signature.length) return false;
+  for (let index = 0; index < signature.length; index += 1) {
+    if (bytes[index] !== signature[index]) return false;
+  }
+  return true;
+}
+
+export function sniffImageFormat(bytes: ByteSource): ImageFormat | null {
+  if (startsWith(bytes, PNG_SIGNATURE)) return "png";
+  if (startsWith(bytes, JPEG_SIGNATURE)) return "jpeg";
+  return null;
+}
+
+export function mediaTypeForImageFormat(format: ImageFormat): ImageMediaType {
+  return format === "png" ? "image/png" : "image/jpeg";
+}
+
+export function detectImageMediaType(bytes: ByteSource): ImageMediaType | null {
+  const format = sniffImageFormat(bytes);
+  return format === null ? null : mediaTypeForImageFormat(format);
+}
+
+export function isSupportedImage(bytes: ByteSource): boolean {
+  return sniffImageFormat(bytes) !== null;
+}
+
+export interface AssetNameContext {
+  readonly platform?: string;
+  readonly arch?: string;
+  readonly version?: string;
+  readonly name?: string;
+}
+
+const ASSET_TOKENS = ["platform", "arch", "version", "name"];
+
+export function resolveAssetName(template: string, context: AssetNameContext): string {
+  let rendered = template;
+  for (const token of ASSET_TOKENS) {
+    const value = context[token as keyof AssetNameContext] ?? "";
+    rendered = rendered.split(`{${token}}`).join(value);
+  }
+  return rendered;
+}

package/src/kit/index.ts

@@ -0,0 +1,51 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Kit subsystem — public barrel.
+ *
+ * `kit/` holds the agent's framework-agnostic leaf helpers: small, pure, Node-
+ * builtin-only utilities with no dependency on the framework or on any sibling
+ * subsystem. It re-exports three groups:
+ *
+ *   - **tool-fetch** — the managed-binary provisioner stub (fd / rg): managed
+ *     path resolution, regex-driven release-asset selection, and a download-
+ *     request builder stamped with this kit's own {@link KIT_USER_AGENT}. The
+ *     network is injected, never imported.
+ *   - **image** — PNG / JPEG magic-byte sniffing (interface-dictated
+ *     signatures) and the `{token}` asset-name renderer.
+ *   - **shell** — POSIX shell-argument quoting and command assembly.
+ *
+ * Consumers import from `src/kit` rather than reaching into individual modules.
+ * The upstream filler libraries (generic array / string / date / json / etc.
+ * stdlib clones) are intentionally omitted: they had zero consumers, so they
+ * are not rebuilt here.
+ */
+export type {
+  ToolDescriptor,
+  ReleaseAsset,
+  ReleaseInfo,
+  ReleaseLookup,
+  DownloadRequest,
+  ProvisionPlan,
+} from "./tool-fetch.js";
+export {
+  KIT_USER_AGENT,
+  resolveManagedBinaryPath,
+  pickReleaseAsset,
+  buildDownloadRequest,
+  planProvision,
+} from "./tool-fetch.js";
+export type { ImageFormat, ImageMediaType, ByteSource, AssetNameContext } from "./image.js";
+export {
+  IMAGE_SNIFF_BYTES,
+  sniffImageFormat,
+  mediaTypeForImageFormat,
+  detectImageMediaType,
+  isSupportedImage,
+  resolveAssetName,
+} from "./image.js";
+export { quoteArg, needsQuoting, buildShellCommand } from "./shell.js";
+export type { ClipboardImageOptions } from "./clipboard-image.js";
+export { readClipboardImage } from "./clipboard-image.js";
+export type { ExternalEditorOptions } from "./external-editor.js";
+export { openInExternalEditor } from "./external-editor.js";

package/src/kit/shell.ts

@@ -0,0 +1,19 @@
+/**
+ * Shell kit — POSIX shell-argument quoting and command assembly.
+ */
+
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+export function quoteArg(arg: string): string {
+  if (arg.length === 0) return "''";
+  if (SHELL_SAFE.test(arg)) return arg;
+  return `'${arg.split("'").join("'\\''")}'`;
+}
+
+export function needsQuoting(arg: string): boolean {
+  return arg.length === 0 || !SHELL_SAFE.test(arg);
+}
+
+export function buildShellCommand(args: readonly string[]): string {
+  return args.map(quoteArg).join(" ");
+}

package/src/kit/tool-fetch.ts

@@ -0,0 +1,85 @@
+/**
+ * Tool-fetch kit — a managed-binary provisioner stub for the native helpers the
+ * agent shells out to (a fast file finder and a fast content grep, fd / rg).
+ */
+import { join } from "node:path";
+
+export const KIT_USER_AGENT = "indusagi-kit-provisioner/1.0";
+
+export interface ToolDescriptor {
+  readonly bin: string;
+  readonly repo: string;
+  readonly assetMatcher: RegExp;
+}
+
+export function resolveManagedBinaryPath(
+  binDir: string,
+  bin: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const fileName = platform === "win32" ? `${bin}.exe` : bin;
+  return join(binDir, fileName);
+}
+
+export interface ReleaseAsset {
+  readonly name: string;
+  readonly url: string;
+}
+
+export interface ReleaseInfo {
+  readonly tag: string;
+  readonly assets: readonly ReleaseAsset[];
+}
+
+export type ReleaseLookup = (repo: string) => Promise<ReleaseInfo>;
+
+export function pickReleaseAsset(
+  descriptor: ToolDescriptor,
+  release: ReleaseInfo,
+): ReleaseAsset | null {
+  for (const asset of release.assets) {
+    if (descriptor.assetMatcher.test(asset.name)) return asset;
+  }
+  return null;
+}
+
+export interface DownloadRequest {
+  readonly url: string;
+  readonly assetName: string;
+  readonly headers: Readonly<Record<string, string>>;
+}
+
+export function buildDownloadRequest(asset: ReleaseAsset): DownloadRequest {
+  return {
+    url: asset.url,
+    assetName: asset.name,
+    headers: {
+      "User-Agent": KIT_USER_AGENT,
+      Accept: "application/octet-stream",
+    },
+  };
+}
+
+export interface ProvisionPlan {
+  readonly bin: string;
+  readonly targetPath: string;
+  readonly tag: string;
+  readonly download: DownloadRequest;
+}
+
+export async function planProvision(
+  descriptor: ToolDescriptor,
+  binDir: string,
+  lookup: ReleaseLookup,
+  platform: NodeJS.Platform = process.platform,
+): Promise<ProvisionPlan | null> {
+  const release = await lookup(descriptor.repo);
+  const asset = pickReleaseAsset(descriptor, release);
+  if (asset === null) return null;
+  return {
+    bin: descriptor.bin,
+    targetPath: resolveManagedBinaryPath(binDir, descriptor.bin, platform),
+    tag: release.tag,
+    download: buildDownloadRequest(asset),
+  };
+}

package/src/launch/catalog.ts

@@ -0,0 +1,148 @@
+/**
+ * Model catalog printer — `printModelCatalog`.
+ */
+import { ModelRegistry, type KnownProvider, type Model } from "indusagi/ai";
+import type { CatalogFilter } from "./contract.js";
+
+export interface CatalogIo {
+  print(line: string): void;
+}
+
+export function defaultCatalogIo(): CatalogIo {
+  return {
+    print(line: string): void {
+      process.stdout.write(line.endsWith("\n") ? line : `${line}\n`);
+    },
+  };
+}
+
+export interface CatalogModelSource {
+  providers(): readonly (KnownProvider | string)[];
+  models(provider: string): readonly Model<Model<string>["api"]>[];
+}
+
+export function registrySource(registry: ModelRegistry = new ModelRegistry()): CatalogModelSource {
+  return {
+    providers: (): readonly (KnownProvider | string)[] => registry.getProviders(),
+    models: (provider: string): readonly Model<Model<string>["api"]>[] =>
+      registry.getModels(provider),
+  };
+}
+
+interface CatalogRow {
+  provider: string;
+  modelId: string;
+  contextWindow: number;
+  maxOutput: number;
+  thinking: boolean;
+  images: boolean;
+}
+
+const HEADERS = [
+  "Provider",
+  "Model",
+  "Context",
+  "Max Output",
+  "Thinking",
+  "Images",
+];
+
+function toRow(model: Model<Model<string>["api"]>): CatalogRow {
+  const inputs = Array.isArray(model.input) ? model.input : [];
+  return {
+    provider: String(model.provider),
+    modelId: model.id,
+    contextWindow: typeof model.contextWindow === "number" ? model.contextWindow : 0,
+    maxOutput: typeof model.maxTokens === "number" ? model.maxTokens : 0,
+    thinking: model.reasoning === true,
+    images: inputs.includes("image"),
+  };
+}
+
+function filterRows(rows: readonly CatalogRow[], filter: CatalogFilter): CatalogRow[] {
+  const providerNeedle =
+    filter.provider !== undefined ? String(filter.provider).toLowerCase() : undefined;
+  const searchNeedle = filter.search?.trim().toLowerCase();
+  return rows.filter((row) => {
+    if (providerNeedle !== undefined && row.provider.toLowerCase() !== providerNeedle) {
+      return false;
+    }
+    if (filter.thinkingOnly === true && !row.thinking) return false;
+    if (filter.imagesOnly === true && !row.images) return false;
+    if (searchNeedle !== undefined && searchNeedle.length > 0) {
+      const haystack = `${row.provider}/${row.modelId}`.toLowerCase();
+      if (!haystack.includes(searchNeedle)) return false;
+    }
+    return true;
+  });
+}
+
+function sortRows(rows: readonly CatalogRow[]): CatalogRow[] {
+  return [...rows].sort((a, b) => {
+    if (a.provider !== b.provider) return a.provider < b.provider ? -1 : 1;
+    if (a.modelId !== b.modelId) return a.modelId < b.modelId ? -1 : 1;
+    return 0;
+  });
+}
+
+function formatTokenCount(tokens: number): string {
+  if (tokens <= 0) return "-";
+  if (tokens >= 1e6) {
+    const millions = tokens / 1e6;
+    return `${millions % 1 === 0 ? millions.toFixed(0) : millions.toFixed(1)}M`;
+  }
+  if (tokens >= 1e3) return `${Math.round(tokens / 1e3)}K`;
+  return String(tokens);
+}
+
+function cells(row: CatalogRow): string[] {
+  return [
+    row.provider,
+    row.modelId,
+    formatTokenCount(row.contextWindow),
+    formatTokenCount(row.maxOutput),
+    row.thinking ? "yes" : "no",
+    row.images ? "yes" : "no",
+  ];
+}
+
+function pad(value: string, width: number): string {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+
+function layout(rows: readonly CatalogRow[]): string[] {
+  const body = rows.map(cells);
+  const widths = HEADERS.map(
+    (header, col) => body.reduce((max, row) => Math.max(max, row[col].length), header.length),
+  );
+  const render = (row: string[]): string =>
+    row.map((cell, col) => pad(cell, widths[col])).join("  ").trimEnd();
+  const rule = widths.map((width) => "-".repeat(width)).join("  ");
+  return [render(HEADERS), rule, ...body.map(render)];
+}
+
+/**
+ * Print the model catalog table.
+ */
+export function printModelCatalog(
+  io: CatalogIo = defaultCatalogIo(),
+  filter: CatalogFilter = {},
+  source: CatalogModelSource = registrySource(),
+): void {
+  const all: CatalogRow[] = [];
+  for (const provider of source.providers()) {
+    let models: readonly Model<Model<string>["api"]>[];
+    try {
+      models = source.models(String(provider));
+    } catch {
+      continue;
+    }
+    for (const model of models) all.push(toRow(model));
+  }
+  const selected = sortRows(filterRows(all, filter));
+  if (selected.length === 0) {
+    io.print("No models match the given filter.");
+    return;
+  }
+  for (const line of layout(selected)) io.print(line);
+}

package/src/launch/contract.ts

@@ -0,0 +1,187 @@
+/**
+ * Launch contract — the FROZEN type surface of Phase 10 (command-line surface).
+ *
+ * This module is the single typed seam between a raw `argv` and a fully
+ * configured run. It owns the *application* command line: the declarative flag
+ * table, the parsed {@link Invocation} those flags fold into, the gathered
+ * `@file` {@link Attachments}, and the typed {@link CredentialFault} the
+ * api-key sign-in surface raises.
+ */
+import type { SessionInfo as ResumeRef, SessionListProgress, ThinkingLevel } from "indusagi/agent";
+import type { ImageContent, KnownProvider, ModelRegistry, OAuthCredentials } from "indusagi/ai";
+import type { Settings } from "indusagi/shell-app";
+import type { RunnerId } from "../boot/contract.js";
+
+export type {
+  ResumeRef,
+  ThinkingLevel,
+  SessionListProgress,
+  ImageContent,
+  KnownProvider,
+  ModelRegistry,
+  OAuthCredentials,
+  Settings,
+  RunnerId,
+};
+
+export type OutputMode = "text" | "json" | "rpc";
+
+export const THINKING_EFFORTS = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
+export type ThinkingEffort = (typeof THINKING_EFFORTS)[number];
+
+export function isThinkingEffort(value: string): value is ThinkingEffort {
+  return (THINKING_EFFORTS as readonly string[]).includes(value);
+}
+
+export function isOutputMode(value: string): value is OutputMode {
+  return value === "text" || value === "json" || value === "rpc";
+}
+
+export const TOOL_NAMES = [
+  "read",
+  "write",
+  "edit",
+  "bash",
+  "grep",
+  "find",
+  "ls",
+  "task",
+  "todo_read",
+  "todo_write",
+  "web_fetch",
+  "web_search",
+  "composio",
+] as const;
+
+export type ToolName = (typeof TOOL_NAMES)[number];
+
+export function isToolName(value: string): value is ToolName {
+  return (TOOL_NAMES as readonly string[]).includes(value);
+}
+
+export type FlagKind = "boolean" | "string" | "number" | "list";
+
+export type FlagDefault = boolean | string | number | readonly string[];
+
+export interface FlagSpec {
+  readonly name: string;
+  readonly aliases?: readonly string[];
+  readonly kind: FlagKind;
+  readonly describe: string;
+  readonly default?: FlagDefault;
+}
+
+export interface Invocation {
+  readonly mode: OutputMode;
+  readonly prompt?: string;
+  readonly flags: Record<string, FlagValue>;
+  readonly positionals: string[];
+  readonly attachments?: Attachments;
+  readonly model?: string;
+  readonly fallbackModel?: string;
+  readonly account?: string;
+  readonly cwd?: string;
+  readonly system?: string;
+  readonly appendSystem?: string;
+  readonly thinking?: ThinkingEffort;
+  readonly tools?: ToolName[];
+  readonly noTools: boolean;
+  readonly mcp: string[];
+  readonly print: boolean;
+  readonly interactive: boolean;
+  readonly help: boolean;
+  readonly version: boolean;
+}
+
+export type FlagValue = boolean | string | number | string[];
+
+export interface Attachments {
+  readonly prose: string;
+  readonly media: ImageContent[];
+}
+
+export interface AttachmentOptions {
+  readonly cwd: string;
+}
+
+export type CredentialVerb = "signin" | "signout";
+
+export interface ProviderEntry {
+  readonly id: KnownProvider | string;
+  readonly label: string;
+  readonly envKey: string;
+  readonly docsUrl: string;
+}
+
+export type CredentialFaultKind =
+  | "unknown-provider"
+  | "invalid-key"
+  | "invalid-account"
+  | "name-collision"
+  | "not-found"
+  | "vault"
+  | "aborted";
+
+export interface CredentialFault {
+  readonly kind: CredentialFaultKind;
+  readonly message: string;
+  readonly hint?: string;
+  readonly cause?: unknown;
+}
+
+export function credentialFault(
+  kind: CredentialFaultKind,
+  message: string,
+  extra?: { hint?: string; cause?: unknown },
+): CredentialFault {
+  return {
+    kind,
+    message,
+    ...(extra?.hint !== undefined ? { hint: extra.hint } : {}),
+    ...(extra?.cause !== undefined ? { cause: extra.cause } : {}),
+  };
+}
+
+export interface AuthVault {
+  listAccounts(provider: string): Promise<string[]>;
+  defaultAccount(provider: string): Promise<string | undefined>;
+  putApiKey(provider: string, account: string, apiKey: string, makeDefault?: boolean): Promise<void>;
+  putOAuth(provider: string, account: string, credentials: OAuthCredentials, makeDefault?: boolean): Promise<void>;
+  authKind(provider: string, account: string): Promise<"apiKey" | "oauth" | undefined>;
+  readUsableKey(provider: string, account: string): Promise<string | undefined>;
+  remove(provider: string, account?: string): Promise<boolean>;
+}
+
+export interface CredentialCommandOptions {
+  readonly vault: AuthVault;
+  readonly profileDir: string;
+}
+
+export interface CatalogFilter {
+  readonly provider?: KnownProvider | string;
+  readonly thinkingOnly?: boolean;
+  readonly imagesOnly?: boolean;
+  readonly search?: string;
+}
+
+export type SessionLoader = (onProgress?: SessionListProgress) => Promise<ResumeRef[]>;
+
+export interface ResumeFault {
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+export interface SettingsBrowseOptions {
+  readonly settings: Settings;
+  readonly resolvedPaths: Readonly<Record<string, readonly string[]>>;
+  readonly cwd: string;
+  readonly profileDir: string;
+}