indusagi-coding-agent 0.2.5 → 0.2.9

package/src/capability-deck/cards/index.ts

@@ -0,0 +1,115 @@
+/**
+ * Capability cards — the app-novel capabilities the deck builds in-house.
+ *
+ * Each card is a {@link CapabilityCard}: metadata plus a `build(ctx)` factory
+ * that mints a live {@link Capability} (the framework `AgentTool` shape) for a
+ * working context. These are written fresh against the framework contract — not
+ * derived from any prior tooling layer — and stay framework-agnostic where the
+ * behavior is original (todo and bg-process wrap only Node + the deck contract).
+ *
+ * The connector and memory cards expose a thin, clearly-typed adapter seam over
+ * a framework handle injected through {@link DeckContext.framework}; when no
+ * handle is wired they degrade to a typed stub so every card builds and runs in
+ * any environment, including tests.
+ *
+ * {@link APP_NOVEL_CARDS} is the contribution this module makes to the catalog;
+ * the manifest module composes it with the builtin-bridge cards (the framework's
+ * file/shell/search/web tools) to form the single `CAPABILITY_CARDS` source of
+ * truth from which the deck's index and profiles are derived.
+ */
+import type { CapabilityCard } from "../contract.js";
+
+export {
+    todoCard,
+    buildTodoCapability,
+    TodoLedger,
+    type TodoItem,
+    type TodoState,
+    type TodoWeight,
+    type TodoParamsType,
+    type TodoDetails,
+} from "./todo-card.js";
+export {
+    daemonCard,
+    buildDaemonCapability,
+    DaemonTable,
+    type DaemonState,
+    type DaemonParamsType,
+    type DaemonDetails,
+} from "./bg-process-card.js";
+export {
+    taskCard,
+    buildTaskCapability,
+    DELEGATE_HANDLE_KEY,
+    type DelegateRunner,
+    type DelegateRequest,
+    type DelegateResult,
+    type TaskParamsType,
+    type TaskDetails,
+} from "./task-card.js";
+export {
+    workflowCard,
+    buildWorkflowCapability,
+    WORKFLOW_HANDLE_KEY,
+    type WorkflowParamsType,
+    type WorkflowDetails,
+} from "./workflow-card.js";
+export {
+    saasCard,
+    buildSaasCapability,
+    SAAS_GATEWAY_KEY,
+    type SaasGatewayPort,
+    type RemoteToolSummary,
+    type RemoteExecution,
+    type SaasParamsType,
+    type SaasDetails,
+} from "./saas-card.js";
+export {
+    memoryCard,
+    buildMemoryCapability,
+    InMemoryStore,
+    MEMORY_HANDLE_KEY,
+    type MemoryStore,
+    type MemoryParamsType,
+    type MemoryDetails,
+} from "./memory-card.js";
+export {
+    enterPlanModeCard,
+    exitPlanModeCard,
+    buildEnterPlanModeCapability,
+    buildExitPlanModeCapability,
+    PLAN_HANDLE_KEY,
+    type PlanController,
+    type EnterPlanParamsType,
+    type EnterPlanDetails,
+    type ExitPlanParamsType,
+    type ExitPlanDetails,
+} from "./plan-tools.js";
+export { planSlug, planFilePath, writePlan, readPlan, PLANS_DIRNAME } from "./plan-file.js";
+
+import { todoCard } from "./todo-card.js";
+import { daemonCard } from "./bg-process-card.js";
+import { taskCard } from "./task-card.js";
+import { workflowCard } from "./workflow-card.js";
+import { saasCard } from "./saas-card.js";
+import { memoryCard } from "./memory-card.js";
+import { enterPlanModeCard, exitPlanModeCard } from "./plan-tools.js";
+
+/**
+ * The app-novel cards, in catalog order. The manifest module concatenates these
+ * with the builtin-bridge cards to build the full `CAPABILITY_CARDS` array.
+ *
+ * The plan-mode tools live here (the broadest `all` profile only): plan mode is a
+ * gate over mutating work, so the tools are only meaningful in a full-access deck —
+ * never the read-only `authoring` subset.
+ */
+export const APP_NOVEL_CARDS: readonly CapabilityCard[] = [
+    todoCard,
+    daemonCard,
+    taskCard,
+    workflowCard,
+    saasCard,
+    memoryCard,
+    enterPlanModeCard,
+    exitPlanModeCard,
+];

package/src/capability-deck/cards/memory-card.ts

@@ -0,0 +1,146 @@
+/**
+ * Working-memory capability — read and update a persistent scratch note the
+ * agent carries across turns.
+ *
+ * Status: minimal in-memory implementation + clearly-typed seam for the
+ * framework memory subsystem.
+ *
+ * This card ships a self-contained, framework-agnostic default: a single mutable
+ * text buffer the agent overwrites or appends to, scoped to one built capability
+ * (one session). A host that wants persistence injects a durable store under
+ * {@link MEMORY_HANDLE_KEY} via {@link DeckContext.framework} — the boot layer's
+ * `DiskMemoryStore` (`boot/runners/memdir.ts`) does exactly this, persisting the
+ * note to a per-cwd `MEMORY.md` so it survives across sessions. The
+ * {@link Capability} surface and the tool's wire contract do not change either
+ * way; {@link readStore} validates the injected store's three methods and falls
+ * back to {@link InMemoryStore} when none is wired.
+ *
+ * The single tool keys behavior on an `action` discriminant:
+ *   - `read`    — return the current working-memory note.
+ *   - `replace` — overwrite the note with the supplied `content`.
+ *   - `append`  — add a line to the end of the note.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+import { capabilityId, type Capability, type CapabilityCard, type DeckContext } from "../contract.js";
+
+/** Key under which a host may wire a framework-backed memory store in later. */
+export const MEMORY_HANDLE_KEY = "memoryStore" as const;
+
+/**
+ * The narrow port the memory capability binds to.
+ *
+ * The in-memory default below satisfies it; a future framework-backed store can
+ * be adapted to the same three methods and injected through the context.
+ */
+export interface MemoryStore {
+    read(): string;
+    replace(content: string): void;
+    append(line: string): void;
+}
+
+/** A trivial in-process working-memory buffer, one per built capability. */
+export class InMemoryStore implements MemoryStore {
+    private buffer = "";
+
+    read(): string {
+        return this.buffer;
+    }
+
+    replace(content: string): void {
+        this.buffer = content;
+    }
+
+    append(line: string): void {
+        this.buffer = this.buffer.length === 0 ? line : `${this.buffer}\n${line}`;
+    }
+}
+
+const MemoryParams = Type.Object(
+    {
+        action: Type.Union(
+            [Type.Literal("read"), Type.Literal("replace"), Type.Literal("append")],
+            {
+                description:
+                    "`read` returns the note; `replace` overwrites it; `append` adds a line to the end.",
+            },
+        ),
+        content: Type.Optional(
+            Type.String({
+                description:
+                    "New note body (for `replace`) or the line to add (for `append`). Ignored for `read`.",
+            }),
+        ),
+    },
+    { additionalProperties: false },
+);
+
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type MemoryParamsType = Static<typeof MemoryParams>;
+
+/** Structured detail returned alongside the model-facing content. */
+export interface MemoryDetails {
+    readonly action: "read" | "replace" | "append";
+    readonly ok: boolean;
+    /** Length of the note after the call, for quick status. */
+    readonly length: number;
+}
+
+const MEMORY_DESCRIPTION =
+    'Keep a small working-memory note that persists across turns \u2014 durable facts, decisions, or reminders you want to retain even after older messages scroll out of context. Use `action:"read"` to recall it, `action:"replace"` to rewrite it from scratch, and `action:"append"` to add a single line. Keep it concise; it is a scratchpad, not a log.';
+
+/** Read the optional memory store handle from the deck context, falling back to in-memory. */
+function readStore(ctx: DeckContext): MemoryStore {
+    const handle = ctx.framework?.[MEMORY_HANDLE_KEY];
+    if (
+        handle &&
+        typeof (handle as MemoryStore).read === "function" &&
+        typeof (handle as MemoryStore).replace === "function" &&
+        typeof (handle as MemoryStore).append === "function"
+    ) {
+        return handle as MemoryStore;
+    }
+    return new InMemoryStore();
+}
+
+/**
+ * Build the working-memory capability, binding it to an injected store when one
+ * is wired into the context, or a fresh in-memory store otherwise.
+ *
+ * @param ctx the deck context; an optional store is read from
+ *            `ctx.framework[MEMORY_HANDLE_KEY]`.
+ */
+export function buildMemoryCapability(ctx: DeckContext): Capability<typeof MemoryParams, MemoryDetails> {
+    const store = readStore(ctx);
+    return {
+        name: "memory",
+        label: "Working memory",
+        description: MEMORY_DESCRIPTION,
+        parameters: MemoryParams,
+        async execute(_toolCallId, params) {
+            if (params.action === "replace") store.replace(params.content ?? "");
+            else if (params.action === "append" && params.content) store.append(params.content);
+            const note = store.read();
+            const heading =
+                params.action === "read"
+                    ? "Working memory:"
+                    : params.action === "replace"
+                        ? "Working memory replaced:"
+                        : "Working memory appended:";
+            const body = note.length === 0 ? "(empty)" : note;
+            return {
+                content: [{ type: "text", text: `${heading}\n${body}` }],
+                details: { action: params.action, ok: true, length: note.length },
+            };
+        },
+    };
+}
+
+/** Catalog row for the working-memory capability. */
+export const memoryCard: CapabilityCard = {
+    id: capabilityId("memory"),
+    title: "Working memory",
+    summary: "Read and update a persistent scratch note that survives across turns.",
+    // Erase the precisely-typed builder to the `Capability` card surface (through
+    // `unknown`, as TypeBox tools are invariant in their parameter schema).
+    build: (ctx) => buildMemoryCapability(ctx),
+};

package/src/capability-deck/cards/plan-file.ts

@@ -0,0 +1,97 @@
+/**
+ * Plan-file persistence — write and read the approved plan a plan-mode session
+ * produces, as a slug-named markdown file under a per-session plans directory.
+ *
+ * Plan mode is a read-only "research first, act second" stance: the agent
+ * explores under {@link EnterPlanMode}, drafts a plan, and proposes leaving plan
+ * mode with {@link ExitPlanMode}. When the user approves the exit, the plan text
+ * the model authored is durable — saved here so it survives the session and can
+ * be reviewed, diffed, or fed back later. The conductor owns the approval
+ * handshake; this module owns only the bytes-on-disk concern.
+ *
+ * The filename is derived from a stable slug of the plan's first line (its de
+ * facto title), prefixed with a short timestamp so successive plans in one
+ * session never collide. Writing is best-effort from the caller's perspective —
+ * a write failure surfaces as a thrown error the conductor swallows into a
+ * non-fatal note rather than faulting the turn.
+ */
+import { mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** The directory plans are written under (relative to the session scope dir). */
+export const PLANS_DIRNAME = "plans" as const;
+
+/** Maximum slug length before truncation. */
+const MAX_SLUG_LEN = 48;
+
+/**
+ * Derive a filesystem-safe slug from a plan's text — its first non-empty line,
+ * lower-cased, with every run of non-alphanumeric characters collapsed to a
+ * single dash and the result trimmed and length-capped. Falls back to `"plan"`
+ * when the text yields nothing usable (empty, or punctuation-only).
+ *
+ * @param plan the plan body whose first line seeds the slug
+ */
+export function planSlug(plan: string): string {
+    const firstLine = plan
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    const base = (firstLine ?? "")
+        .replace(/^#+\s*/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, MAX_SLUG_LEN)
+        .replace(/-+$/g, "");
+    return base.length > 0 ? base : "plan";
+}
+
+/**
+ * Resolve the absolute path a plan with `slug` is written to under `sessionDir`.
+ * The `plans/` sub-directory is implied; callers pass the session scope dir and
+ * get back `<sessionDir>/plans/<slug>.md`.
+ *
+ * @param sessionDir the per-session directory plans live beneath
+ * @param slug       the derived slug (see {@link planSlug})
+ */
+export function planFilePath(sessionDir: string, slug: string): string {
+    return join(sessionDir, PLANS_DIRNAME, `${slug}.md`);
+}
+
+/**
+ * Write the plan body to a slug-named markdown file under `sessionDir/plans`,
+ * creating the directory as needed, and return the absolute path written. The
+ * filename is `<short-timestamp>-<slug>.md` so repeated plans in one session do
+ * not overwrite each other.
+ *
+ * Throws on an I/O failure (the conductor swallows it into a non-fatal note).
+ *
+ * @param sessionDir the per-session directory plans live beneath
+ * @param plan       the plan body to persist
+ */
+export function writePlan(sessionDir: string, plan: string): string {
+    const dir = join(sessionDir, PLANS_DIRNAME);
+    mkdirSync(dir, { recursive: true });
+    const stamp = Date.now().toString(36);
+    const path = join(dir, `${stamp}-${planSlug(plan)}.md`);
+    writeFileSync(path, plan.endsWith("\n") ? plan : `${plan}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return path;
+}
+
+/**
+ * Read a previously-written plan file back, or `undefined` when it is missing or
+ * unreadable. Used by tests and by any review surface that wants the saved plan.
+ *
+ * @param path the absolute plan-file path (see {@link planFilePath} / {@link writePlan})
+ */
+export function readPlan(path: string): string | undefined {
+    try {
+        return readFileSync(path, "utf8");
+    } catch {
+        return undefined;
+    }
+}

package/src/capability-deck/cards/plan-tools.ts

@@ -0,0 +1,185 @@
+/**
+ * Plan-mode capabilities — the two tools that bracket a read-only planning phase.
+ *
+ *   - {@link enterPlanModeTool} (`enter_plan_mode`) is a **read-only** tool: when
+ *     invoked it returns a structured detail `{ enterPlanMode: true }` plus
+ *     explore-only prose. It carries no side effect of its own — the **conductor**
+ *     watches the tool-result seam for `enterPlanMode` and switches the session
+ *     into the `plan` permission mode (research-only — every mutating tool is
+ *     blocked at the permission gate), capturing the pre-plan mode so it can be
+ *     restored on exit. It is marked `readOnly: true` so it is itself always
+ *     permitted, even inside plan mode.
+ *
+ *   - {@link exitPlanModeTool} (`exit_plan_mode`) likewise does NOT flip the mode
+ *     itself — a tool cannot drive the interactive approval dialog. It returns a
+ *     structured detail `{ exitPlan: true, plan }` that the conductor intercepts:
+ *     the conductor raises the user-approval prompt, and on approval restores the
+ *     pre-plan mode + injects the approved plan as context for the next turn,
+ *     persisting it to a plan file. On reject the session stays in plan mode.
+ *
+ * Keeping every side effect (mode flip, approval, persistence) in the conductor
+ * rather than the tool keeps the tools pure, side-effect-light, and assemblable in
+ * any environment, including tests — and lets the conductor own the single
+ * permission-mode source of truth.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+import { capabilityId, type Capability, type CapabilityCard, type DeckContext } from "../contract.js";
+
+/**
+ * Reserved key under which a host MAY wire a plan-mode controller into the deck
+ * context. The conductor-driven design intercepts the plan tools' result details
+ * directly (no handle required), so this is exported only for forward-compat /
+ * an alternate host that wants the tool to drive the flip itself.
+ */
+export const PLAN_HANDLE_KEY = "planController" as const;
+
+/**
+ * The narrow port a host may wire to flip the live session into plan mode. Unused
+ * by the default (conductor-intercept) wiring; kept for hosts that prefer the tool
+ * to signal directly rather than via the tool-result seam.
+ */
+export interface PlanController {
+    /** Switch the session into read-only plan mode for subsequent tool calls. */
+    enterPlanMode(): void;
+}
+
+const EnterPlanParams = Type.Object({}, { additionalProperties: false });
+
+/** Statically-inferred parameter type EnterPlanMode's `execute` receives. */
+export type EnterPlanParamsType = Static<typeof EnterPlanParams>;
+
+/** Structured detail returned by EnterPlanMode. */
+export interface EnterPlanDetails {
+    /**
+     * The marker the conductor intercepts on the tool-result seam to switch the
+     * session into plan mode (and capture the pre-plan mode for a later restore).
+     */
+    readonly enterPlanMode: true;
+    /** Whether an optional in-context controller also applied the switch directly. */
+    readonly applied: boolean;
+}
+
+const ExitPlanParams = Type.Object(
+    {
+        plan: Type.String({
+            description:
+                "The plan you intend to carry out, in markdown. The user reviews this before approving the exit from plan mode; on approval you leave plan mode and begin.",
+        }),
+    },
+    { additionalProperties: false },
+);
+
+/** Statically-inferred parameter type ExitPlanMode's `execute` receives. */
+export type ExitPlanParamsType = Static<typeof ExitPlanParams>;
+
+/**
+ * Structured detail returned by ExitPlanMode. The conductor watches the
+ * tool-result seam for `exitPlan === true`, captures the {@link plan}, and runs
+ * the approval handshake (the tool itself does not flip the mode or prompt).
+ */
+export interface ExitPlanDetails {
+    /** The marker the conductor intercepts to start the exit-plan handshake. */
+    readonly exitPlan: true;
+    /** The plan text the model authored, surfaced to the user for approval. */
+    readonly plan: string;
+}
+
+const ENTER_PLAN_DESCRIPTION =
+    "Enter plan mode: a read-only research phase in which you may only read, search, and inspect \u2014 every file-mutating and shell tool is blocked until you leave. Use this when a task needs investigation and a plan before any change is made. While in plan mode, gather all the context you need, then call `exit_plan_mode` with the plan you intend to carry out; the user reviews and approves it before you act.";
+
+const ENTER_PLAN_PROSE =
+    "You are now in plan mode (read-only). Investigate freely with the read, search, and listing tools, but do not attempt to edit files or run shell commands \u2014 they are blocked here. When you have a concrete plan, call `exit_plan_mode` with the full plan text so the user can approve it before you make any changes.";
+
+const EXIT_PLAN_DESCRIPTION =
+    "Leave plan mode and propose the plan you intend to carry out. Provide the full plan as `plan`; the user reviews it and either approves (you exit plan mode and begin the work) or rejects (you stay in plan mode to revise). Only call this once you have a concrete, reviewed plan \u2014 not to do work, but to ask permission to start it.";
+
+/** Read the optional plan controller handle from the deck context. */
+function readPlanController(ctx: DeckContext): PlanController | undefined {
+    const handle = ctx.framework?.[PLAN_HANDLE_KEY];
+    if (handle && typeof (handle as PlanController).enterPlanMode === "function") {
+        return handle as PlanController;
+    }
+    return undefined;
+}
+
+/**
+ * Build the EnterPlanMode capability. On invoke it asks the wired
+ * {@link PlanController} to switch the session into plan mode, then returns
+ * explore-only prose. It is `readOnly: true`, so the permission gate always
+ * permits it (including inside plan mode itself).
+ *
+ * @param ctx the deck context; an optional controller is read from
+ *            `ctx.framework[PLAN_HANDLE_KEY]`.
+ */
+export function buildEnterPlanModeCapability(
+    ctx: DeckContext,
+): Capability<typeof EnterPlanParams, EnterPlanDetails> {
+    const controller = readPlanController(ctx);
+    return {
+        name: "enter_plan_mode",
+        label: "Enter plan mode",
+        description: ENTER_PLAN_DESCRIPTION,
+        readOnly: true,
+        parameters: EnterPlanParams,
+        async execute() {
+            const applied = controller !== undefined;
+            if (controller) controller.enterPlanMode();
+            return {
+                content: [{ type: "text", text: ENTER_PLAN_PROSE }],
+                details: { enterPlanMode: true, applied },
+            };
+        },
+    };
+}
+
+/**
+ * Build the ExitPlanMode capability. It performs no mode flip and no prompt of
+ * its own — it returns the `{ exitPlan: true, plan }` detail the conductor
+ * intercepts. The model-facing content echoes the proposed plan so a transcript
+ * reader sees what was put up for approval.
+ *
+ * Not marked read-only: it represents the request to RESUME mutating work, so in
+ * plan mode it must still be permitted explicitly (the gate special-cases the
+ * plan tools alongside read-only tools — see the conductor wiring).
+ */
+export function buildExitPlanModeCapability(
+    _ctx: DeckContext,
+): Capability<typeof ExitPlanParams, ExitPlanDetails> {
+    return {
+        name: "exit_plan_mode",
+        label: "Exit plan mode",
+        description: EXIT_PLAN_DESCRIPTION,
+        // Marked read-only so the plan-mode gate never blocks the very tool used to
+        // request leaving plan mode (it mutates nothing — the conductor owns the flip).
+        readOnly: true,
+        parameters: ExitPlanParams,
+        async execute(_toolCallId, params) {
+            const plan = params.plan;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Proposed plan (awaiting your approval to leave plan mode):\n\n${plan}`,
+                    },
+                ],
+                details: { exitPlan: true, plan },
+            };
+        },
+    };
+}
+
+/** Catalog row for the EnterPlanMode capability. */
+export const enterPlanModeCard: CapabilityCard = {
+    id: capabilityId("enter_plan_mode"),
+    title: "Enter plan mode",
+    summary: "Switch into a read-only research phase where mutating tools are blocked.",
+    build: (ctx) => buildEnterPlanModeCapability(ctx),
+};
+
+/** Catalog row for the ExitPlanMode capability. */
+export const exitPlanModeCard: CapabilityCard = {
+    id: capabilityId("exit_plan_mode"),
+    title: "Exit plan mode",
+    summary: "Propose a plan and request approval to leave plan mode and begin work.",
+    build: (ctx) => buildExitPlanModeCapability(ctx),
+};