indusagi-coding-agent 0.2.8 → 0.2.10

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

@@ -0,0 +1,183 @@
+/**
+ * SaaS-action capability — a thin wrapper over the framework's connector gateway
+ * (Composio-style remote tool execution).
+ *
+ * The heavy lifting (authenticating to a vendor, resolving toolkit scopes,
+ * executing a remote tool slug) lives in the framework's `connectors-saas`
+ * layer. This card does NOT re-implement any of it; it adapts an injected
+ * gateway handle to the deck's {@link Capability} shape so the agent can invoke
+ * remote SaaS actions by slug. When no gateway is wired into the context the card
+ * still builds and returns a typed stub, so the deck assembles in every
+ * environment.
+ *
+ * The single tool keys behavior on an `action` discriminant:
+ *   - `discover` — list executable remote tool slugs (optionally filtered).
+ *   - `execute`  — run one remote tool slug with arguments.
+ *
+ * Vendor-defined identifiers (uppercase tool slugs like `GITHUB_CREATE_ISSUE`)
+ * are passed through verbatim — they are part of the connector's wire contract.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+import { capabilityId, type Capability, type CapabilityCard, type DeckContext } from "../contract.js";
+
+/** Key under which a host wires a live SaaS gateway into the deck context. */
+export const SAAS_GATEWAY_KEY = "saasGateway" as const;
+
+/** One executable remote tool advertised by the connector. */
+export interface RemoteToolSummary {
+    /** Vendor-defined slug, passed through verbatim (e.g. `GITHUB_CREATE_ISSUE`). */
+    readonly slug: string;
+    /** Human-readable description from the connector, if any. */
+    readonly description?: string;
+}
+
+/** The outcome of executing one remote tool slug. */
+export interface RemoteExecution {
+    readonly ok: boolean;
+    /** Connector payload, surfaced to the model as serialized text. */
+    readonly data: unknown;
+}
+
+/**
+ * The slice of a framework SaaS gateway this card adapts.
+ *
+ * Deliberately narrow — the deck only needs to list and execute remote tools.
+ * The framework's full gateway (connection lifecycle, scope planning, status
+ * reporting) is a superset; a host adapts it to this shape when wiring it in.
+ */
+export interface SaasGatewayPort {
+    /** List executable remote tools, optionally filtered by toolkit or query. */
+    discover(filter?: {
+        toolkits?: string[];
+        query?: string;
+    }): Promise<RemoteToolSummary[]>;
+    /** Execute one remote tool slug with arguments. */
+    execute(slug: string, args: Record<string, unknown>): Promise<RemoteExecution>;
+}
+
+const SaasParams = Type.Object(
+    {
+        action: Type.Union([Type.Literal("discover"), Type.Literal("execute")], {
+            description:
+                "`discover` lists available remote tool slugs; `execute` runs one slug with arguments.",
+        }),
+        slug: Type.Optional(
+            Type.String({
+                description:
+                    "Vendor tool slug to run (e.g. GITHUB_CREATE_ISSUE). Required for `execute`.",
+            }),
+        ),
+        arguments: Type.Optional(
+            Type.Record(Type.String(), Type.Unknown(), {
+                description: "Arguments object for the remote tool, as the connector expects.",
+            }),
+        ),
+        toolkits: Type.Optional(
+            Type.Array(Type.String(), {
+                description: "On `discover`, restrict results to these toolkit names.",
+            }),
+        ),
+        query: Type.Optional(
+            Type.String({
+                description: "On `discover`, free-text filter over available tools.",
+            }),
+        ),
+    },
+    { additionalProperties: false },
+);
+
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type SaasParamsType = Static<typeof SaasParams>;
+
+/** Structured detail returned alongside the model-facing content. */
+export interface SaasDetails {
+    readonly action: "discover" | "execute";
+    readonly ok: boolean;
+    readonly slug?: string;
+    readonly count?: number;
+}
+
+const SAAS_DESCRIPTION =
+    'Discover and run third-party SaaS actions (GitHub, Slack, Gmail, etc.) through the connector gateway. Use `action:"discover"` to find the right tool slug, then `action:"execute"` with that `slug` and an `arguments` object to perform the action. Tool slugs are vendor-defined and case-sensitive; pass them exactly as listed.';
+
+const STUB_NOTE =
+    "The SaaS connector gateway is not configured in this environment, so no remote action was performed. Configure a connector (and authenticate the relevant toolkit) to enable these actions.";
+
+/** Read the optional SaaS gateway handle from the deck context. */
+function readGateway(ctx: DeckContext): SaasGatewayPort | undefined {
+    const handle = ctx.framework?.[SAAS_GATEWAY_KEY];
+    if (
+        handle &&
+        typeof (handle as SaasGatewayPort).discover === "function" &&
+        typeof (handle as SaasGatewayPort).execute === "function"
+    ) {
+        return handle as SaasGatewayPort;
+    }
+    return undefined;
+}
+
+/**
+ * Build the SaaS-action capability, adapting an injected gateway when present.
+ *
+ * @param ctx the deck context; an optional gateway is read from
+ *            `ctx.framework[SAAS_GATEWAY_KEY]`.
+ */
+export function buildSaasCapability(ctx: DeckContext): Capability<typeof SaasParams, SaasDetails> {
+    const gateway = readGateway(ctx);
+    return {
+        name: "saas-action",
+        label: "SaaS action",
+        description: SAAS_DESCRIPTION,
+        parameters: SaasParams,
+        async execute(_toolCallId, params) {
+            if (!gateway) {
+                return {
+                    content: [{ type: "text", text: STUB_NOTE }],
+                    details: { action: params.action, ok: false },
+                    isError: true,
+                };
+            }
+            if (params.action === "discover") {
+                const tools = await gateway.discover({
+                    toolkits: params.toolkits,
+                    query: params.query,
+                });
+                const text =
+                    tools.length === 0
+                        ? "No remote tools matched."
+                        : tools
+                              .map((t) =>
+                                  t.description ? `- ${t.slug} \u2014 ${t.description}` : `- ${t.slug}`,
+                              )
+                              .join("\n");
+                return {
+                    content: [{ type: "text", text }],
+                    details: { action: "discover", ok: true, count: tools.length },
+                };
+            }
+            if (!params.slug) {
+                return {
+                    content: [{ type: "text", text: "`slug` is required to execute a SaaS action." }],
+                    details: { action: "execute", ok: false },
+                    isError: true,
+                };
+            }
+            const result = await gateway.execute(params.slug, params.arguments ?? {});
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+                details: { action: "execute", ok: result.ok, slug: params.slug },
+                isError: result.ok ? undefined : true,
+            };
+        },
+    };
+}
+
+/** Catalog row for the SaaS-action capability. */
+export const saasCard: CapabilityCard = {
+    id: capabilityId("saas-action"),
+    title: "SaaS action",
+    summary: "Discover and run third-party SaaS actions through the connector gateway.",
+    // Erase the precisely-typed builder to the `Capability` card surface (through
+    // `unknown`, as TypeBox tools are invariant in their parameter schema).
+    build: (ctx) => buildSaasCapability(ctx),
+};

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

@@ -0,0 +1,207 @@
+/**
+ * Task capability — delegate a self-contained piece of work to a sub-agent.
+ *
+ * App-novel wiring. The `task` tool lets the primary agent hand off a bounded
+ * objective (e.g. "find every call site of `foo` and summarize them") to a fresh
+ * sub-agent that runs its own tool loop and reports back a single result, keeping
+ * the parent's context window clean.
+ *
+ * The actual sub-agent runner is NOT owned by this card — it is a framework /
+ * swarm concern injected through {@link DeckContext.framework} under the
+ * {@link DELEGATE_HANDLE_KEY} key. When that handle is present the capability
+ * delegates to it; when it is absent (tests, headless tooling, a host that has
+ * not wired the swarm) the capability degrades gracefully to a clearly-typed
+ * stub that reports delegation is unavailable rather than throwing. Either way
+ * the card builds a valid {@link Capability} and the deck typechecks and runs.
+ *
+ * The card produces a framework `AgentTool`; parameters are a TypeBox schema and
+ * the prose is original to this deck.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+import { capabilityId, type Capability, type CapabilityCard, type DeckContext } from "../contract.js";
+
+/** Key under which a host wires a live delegate runner into the deck context. */
+export const DELEGATE_HANDLE_KEY = "delegate" as const;
+
+/** A single delegated objective handed to the sub-agent runner. */
+export interface DelegateRequest {
+    /** Optional named agent profile to run as (e.g. "explorer", "reviewer"). */
+    readonly agent?: string;
+    /** The self-contained objective the sub-agent should accomplish. */
+    readonly objective: string;
+    /** Optional extra context the parent wants the sub-agent to start with. */
+    readonly context?: string;
+}
+
+/** The single result a sub-agent reports back to the parent. */
+export interface DelegateResult {
+    /** Whether the sub-agent considers the objective met. */
+    readonly ok: boolean;
+    /** The sub-agent's final report, surfaced to the parent agent verbatim. */
+    readonly report: string;
+}
+
+/** One line of a sub-agent's live activity stream (for the drill-in view). */
+export interface ActivityLine {
+    /** What kind of step this is, used to colour it. */
+    readonly tone: "reason" | "tool" | "result";
+    /** The display text (already shortened to a single line). */
+    readonly text: string;
+}
+
+/** Live progress a running sub-agent streams back while it works. */
+export interface DelegateProgress {
+    /** Cumulative tokens the sub-agent has spent so far (input + output). */
+    readonly tokens: number;
+    /** The sub-agent's recent activity (reasoning + tool steps), newest last. */
+    readonly activity: readonly ActivityLine[];
+}
+
+/**
+ * The contract a host's sub-agent runner must satisfy to be wired in.
+ *
+ * Intentionally minimal: the deck only needs a way to run one objective under
+ * cancellation and get one report back. How the runner spawns the sub-agent
+ * (in-process loop, worktree, separate process) is entirely the host's concern.
+ */
+export interface DelegateRunner {
+    /** Optional roster of named agent profiles, surfaced in the tool description. */
+    listAgents?(): readonly string[];
+    /**
+     * Run one delegated objective and resolve with the sub-agent's report.
+     *
+     * When an `onProgress` callback is supplied the runner streams live metrics
+     * (token spend) as the sub-agent works, so the host can surface them (the
+     * background-agents panel). Optional — a runner may ignore it.
+     */
+    run(
+        request: DelegateRequest,
+        signal?: AbortSignal,
+        onProgress?: (progress: DelegateProgress) => void,
+    ): Promise<DelegateResult>;
+}
+
+const TaskParams = Type.Object(
+    {
+        objective: Type.String({
+            description:
+                "A complete, self-contained statement of what the sub-agent should accomplish. Include everything it needs; it does not share your conversation history.",
+        }),
+        agent: Type.Optional(
+            Type.String({
+                description:
+                    "Optional named sub-agent profile to run as. Omit to use the default profile.",
+            }),
+        ),
+        context: Type.Optional(
+            Type.String({
+                description:
+                    "Optional extra background the sub-agent should start with.",
+            }),
+        ),
+    },
+    { additionalProperties: false },
+);
+
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type TaskParamsType = Static<typeof TaskParams>;
+
+/** Structured detail returned alongside the model-facing content. */
+export interface TaskDetails {
+    /** True when a delegate runner handled the objective. */
+    readonly delegated: boolean;
+    /** True when the sub-agent (or stub) considers the objective met. */
+    readonly ok: boolean;
+    /** The agent profile that ran, if one was named. */
+    readonly agent?: string;
+    /** Cumulative tokens the sub-agent spent — streamed live on progress updates. */
+    readonly tokens?: number;
+    /** The sub-agent's recent activity — streamed live for the drill-in view. */
+    readonly activity?: readonly ActivityLine[];
+}
+
+const STUB_NOTE =
+    "Sub-agent delegation is not wired in this environment, so the objective was not run. Wire a DelegateRunner into the deck context to enable it, or perform the work inline with the other tools.";
+
+/** Read the optional DelegateRunner handle from the deck context. */
+function readDelegateRunner(ctx: DeckContext): DelegateRunner | undefined {
+    const handle = ctx.framework?.[DELEGATE_HANDLE_KEY];
+    if (handle && typeof (handle as DelegateRunner).run === "function") {
+        return handle as DelegateRunner;
+    }
+    return undefined;
+}
+
+/** Compose the base tool description, appending the available sub-agent profiles. */
+function baseDescription(agents: readonly string[]): string {
+    const roster =
+        agents.length > 0 ? ` Available sub-agent profiles: ${agents.join(", ")}.` : "";
+    return (
+        "Delegate a focused, self-contained piece of work to a sub-agent that runs its own tool loop and returns a single report. Use this to keep your own context clean when a task is well-scoped \u2014 searching a large codebase, drafting a file, or investigating a question end-to-end. Give a complete `objective`; the sub-agent does not see your conversation." +
+        roster
+    );
+}
+
+/**
+ * Build the task/delegate capability.
+ *
+ * If a {@link DelegateRunner} is present on the context it is bound and the tool
+ * truly delegates; otherwise the tool builds anyway and returns a typed,
+ * non-throwing stub result so the deck stays assemblable in every environment.
+ *
+ * @param ctx the deck context; an optional runner is read from
+ *            `ctx.framework[DELEGATE_HANDLE_KEY]`.
+ */
+export function buildTaskCapability(ctx: DeckContext): Capability<typeof TaskParams, TaskDetails> {
+    const runner = readDelegateRunner(ctx);
+    const agents = runner?.listAgents?.() ?? [];
+    return {
+        name: "task",
+        label: "Delegate task",
+        description: baseDescription(agents),
+        parameters: TaskParams,
+        async execute(_toolCallId, params, signal, onUpdate) {
+            if (!runner) {
+                return {
+                    content: [{ type: "text", text: STUB_NOTE }],
+                    details: { delegated: false, ok: false, agent: params.agent },
+                    isError: true,
+                };
+            }
+            const result = await runner.run(
+                { objective: params.objective, agent: params.agent, context: params.context },
+                signal,
+                // Stream live token spend as a tool_update so the background-agents panel
+                // can show a running token count next to the elapsed clock. The `details`
+                // carries the structured `tokens`; the console reads it off the signal.
+                (progress) => {
+                    onUpdate?.({
+                        content: [{ type: "text", text: `${progress.tokens} tokens` }],
+                        details: {
+                            delegated: true,
+                            ok: false,
+                            agent: params.agent,
+                            tokens: progress.tokens,
+                            activity: progress.activity,
+                        },
+                    });
+                },
+            );
+            return {
+                content: [{ type: "text", text: result.report }],
+                details: { delegated: true, ok: result.ok, agent: params.agent },
+                isError: result.ok ? undefined : true,
+            };
+        },
+    };
+}
+
+/** Catalog row for the task/delegate capability. */
+export const taskCard: CapabilityCard = {
+    id: capabilityId("task"),
+    title: "Delegate task",
+    summary: "Hand a self-contained objective to a sub-agent and receive one report back.",
+    // Erase the precisely-typed builder to the `Capability` card surface (through
+    // `unknown`, as TypeBox tools are invariant in their parameter schema).
+    build: (ctx) => buildTaskCapability(ctx),
+};

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

@@ -0,0 +1,168 @@
+/**
+ * Todo capability — an in-memory checklist the agent set/reads during a run.
+ *
+ * App-novel and framework-agnostic: the store is a plain in-process array of
+ * items, owned by the card and closed over by the built capability. No file
+ * persistence, no session-branch reconstruction, no framework store — just a
+ * mutable list the agent rewrites wholesale (the model is expected to send the
+ * complete desired list on every `set`, the same convention coding agents use so
+ * the plan stays a single coherent snapshot rather than a diff stream).
+ *
+ * Two operations are folded into one tool keyed by an `action` discriminant:
+ *   - `read` — return the current checklist as model-facing prose.
+ *   - `set`  — replace the checklist with the supplied items (the authoritative
+ *              new plan), then echo it back.
+ *
+ * The card produces a {@link Capability} (the framework `AgentTool` shape) so the
+ * conductor consumes it verbatim as one of `options.tools`. Parameters are a
+ * TypeBox schema; the prose below is original to this deck.
+ */
+import { Type, type Static } from "@sinclair/typebox";
+import { capabilityId, type Capability, type CapabilityCard, type DeckContext } from "../contract.js";
+
+/** Lifecycle state of one checklist item. */
+export type TodoState = "pending" | "active" | "done" | "dropped";
+
+/** Relative importance of one checklist item. */
+export type TodoWeight = "low" | "normal" | "high";
+
+/** One row of the in-memory checklist. */
+export interface TodoItem {
+    /** The work to be done, phrased as a short imperative. */
+    readonly task: string;
+    /** Where the item stands right now. */
+    readonly state: TodoState;
+    /** How much it matters relative to the rest of the list. */
+    readonly weight: TodoWeight;
+}
+
+/**
+ * A minimal in-process checklist store.
+ *
+ * Deliberately tiny and synchronous: the whole list lives in one field, `set`
+ * swaps it atomically, and `read` hands back a frozen copy so a caller cannot
+ * mutate the store's backing array. One store is created per built capability,
+ * so two sessions never share a checklist.
+ */
+export class TodoLedger {
+    private items: readonly TodoItem[] = [];
+
+    /** Replace the entire checklist with `next`; returns the stored snapshot. */
+    set(next: readonly TodoItem[]): readonly TodoItem[] {
+        this.items = Object.freeze([...next]);
+        return this.items;
+    }
+
+    /** Return the current checklist as a frozen, read-only snapshot. */
+    read(): readonly TodoItem[] {
+        return this.items;
+    }
+}
+
+const TodoItemSchema = Type.Object(
+    {
+        task: Type.String({ description: "Short imperative description of the work item." }),
+        state: Type.Union(
+            [
+                Type.Literal("pending"),
+                Type.Literal("active"),
+                Type.Literal("done"),
+                Type.Literal("dropped"),
+            ],
+            { description: "Lifecycle state of the item." },
+        ),
+        weight: Type.Union(
+            [Type.Literal("low"), Type.Literal("normal"), Type.Literal("high")],
+            { description: "Relative importance of the item." },
+        ),
+    },
+    { additionalProperties: false },
+);
+
+const TodoParams = Type.Object(
+    {
+        action: Type.Union([Type.Literal("read"), Type.Literal("set")], {
+            description:
+                "`read` returns the current checklist; `set` replaces it with the items you provide.",
+        }),
+        items: Type.Optional(
+            Type.Array(TodoItemSchema, {
+                description:
+                    "The complete desired checklist. Required for `set` (send the whole list, not a delta); ignored for `read`.",
+            }),
+        ),
+    },
+    { additionalProperties: false },
+);
+
+/** Statically-inferred parameter type the capability's `execute` receives. */
+export type TodoParamsType = Static<typeof TodoParams>;
+
+/** Structured detail returned alongside the model-facing content. */
+export interface TodoDetails {
+    /** The action that was performed. */
+    readonly action: "read" | "set";
+    /** The checklist as it stands after the call. */
+    readonly items: readonly TodoItem[];
+}
+
+const TODO_DESCRIPTION =
+    'Maintain a working checklist for the current task. Call with `action:"set"` and a complete `items` list to record or revise your plan \u2014 always send the full intended list, since the previous one is discarded. Call with `action:"read"` to recall the current plan. Mark items `active` while in progress and `done` when finished so the list reflects real status; use `dropped` for work you decided to skip.';
+
+const STATE_GLYPH: Record<TodoState, string> = {
+    pending: "[ ]",
+    active: "[~]",
+    done: "[x]",
+    dropped: "[-]",
+};
+
+/** Render the checklist as model-facing prose. */
+function renderChecklist(items: readonly TodoItem[]): string {
+    if (items.length === 0) return "The checklist is empty.";
+    const lines = items.map((it) => {
+        const weight = it.weight === "normal" ? "" : ` (${it.weight})`;
+        return `${STATE_GLYPH[it.state]} ${it.task}${weight}`;
+    });
+    return lines.join("\n");
+}
+
+/**
+ * Build the todo capability, binding it to a freshly created in-memory ledger.
+ *
+ * The ledger is closed over by `execute`, so the checklist persists for the life
+ * of this capability instance (i.e. the session) without any external store.
+ *
+ * @param _ctx the deck context (unused — the todo card needs no cwd/backends)
+ */
+export function buildTodoCapability(_ctx: DeckContext): Capability<typeof TodoParams, TodoDetails> {
+    const ledger = new TodoLedger();
+    return {
+        name: "todo",
+        label: "Checklist",
+        description: TODO_DESCRIPTION,
+        parameters: TodoParams,
+        async execute(_toolCallId, params) {
+            const items =
+                params.action === "set" ? ledger.set(params.items ?? []) : ledger.read();
+            const heading =
+                params.action === "set" ? "Checklist updated:" : "Current checklist:";
+            const text = `${heading}\n${renderChecklist(items)}`;
+            return {
+                content: [{ type: "text", text }],
+                details: { action: params.action, items },
+            };
+        },
+    };
+}
+
+/** Catalog row for the todo capability — registered in `CAPABILITY_CARDS`. */
+export const todoCard: CapabilityCard = {
+    id: capabilityId("todo"),
+    title: "Checklist",
+    summary: "Keep an in-memory checklist of the current task's steps; set or read it.",
+    // The card surface is the erased `Capability`; the builder keeps its precise
+    // params/details type for direct callers and erases here. The erasure goes
+    // through `unknown` because TypeBox tools are invariant in their schema (the
+    // framework's own tool arrays are `AgentTool<any>[]` for the same reason).
+    build: (ctx) => buildTodoCapability(ctx),
+};