@stevenvincentone/intidev-agentloops 0.1.0

package/dist/mcp.js

@@ -0,0 +1,442 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_ACTOR_SOURCE = exports.WORKFLOW_STATUSES = exports.GUARD_STATUSES = exports.NOTE_TYPES = exports.CONFIDENCES = exports.SEVERITIES = exports.MCP_SERVER_NAME = exports.MCP_SCHEMA_VERSION = void 0;
+exports.summaryTool = summaryTool;
+exports.listTool = listTool;
+exports.showTool = showTool;
+exports.handoffTool = handoffTool;
+exports.createTicketTool = createTicketTool;
+exports.noteTool = noteTool;
+exports.workflowTool = workflowTool;
+exports.resolveTool = resolveTool;
+exports.guardTool = guardTool;
+exports.createMcpServer = createMcpServer;
+exports.startStdioMcpServer = startStdioMcpServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const store_1 = require("./store");
+const handoff_1 = require("./handoff");
+/**
+ * Schema version for the MCP tool envelopes. Bump only on breaking changes;
+ * add fields freely during dogfood (see docs/tickets agent JSON contracts).
+ */
+exports.MCP_SCHEMA_VERSION = 1;
+exports.MCP_SERVER_NAME = "agentloop";
+function nowIso() {
+    return new Date().toISOString();
+}
+function envelope() {
+    return { schemaVersion: exports.MCP_SCHEMA_VERSION, generatedAt: nowIso() };
+}
+/**
+ * Pure read-only tool implementations. These are transport-agnostic and
+ * deterministic apart from `generatedAt`, so they can be unit-tested directly
+ * without standing up an MCP transport.
+ */
+async function summaryTool(store) {
+    return { ...envelope(), summary: await store.summary() };
+}
+async function listTool(store, args = {}) {
+    const status = (args.status ?? "all");
+    const tickets = await store.listTickets({ status, kind: args.kind });
+    return {
+        ...envelope(),
+        filters: { status: args.status ?? "all", kind: args.kind ?? null },
+        count: tickets.length,
+        tickets,
+    };
+}
+async function showTool(store, args) {
+    const raw = args.id?.trim();
+    if (!raw) {
+        throw new Error("show requires an id");
+    }
+    if (/^PATTERN-/i.test(raw)) {
+        const pattern = await store.getPattern(raw.toUpperCase());
+        if (!pattern) {
+            throw new Error(`Pattern not found: ${raw}`);
+        }
+        return { ...envelope(), kind: "pattern", pattern };
+    }
+    const ticket = await store.showTicket(raw);
+    if (!ticket) {
+        throw new Error(`Not found: ${raw}`);
+    }
+    return { ...envelope(), kind: "ticket", ticket };
+}
+async function handoffTool(store, args) {
+    const raw = args.id?.trim();
+    if (!raw) {
+        throw new Error("handoff requires an id");
+    }
+    const ticket = await store.showTicket(raw);
+    if (!ticket) {
+        throw new Error(`Not found: ${raw}`);
+    }
+    return {
+        ...envelope(),
+        ticketId: ticket.id,
+        aliases: ticket.aliases,
+        prompt: (0, handoff_1.buildHandoffPrompt)(ticket),
+    };
+}
+exports.SEVERITIES = ["low", "medium", "high", "critical"];
+exports.CONFIDENCES = ["low", "medium", "high"];
+exports.NOTE_TYPES = [
+    "hypothesis",
+    "related_history",
+    "prior_fix",
+    "triage",
+    "investigation",
+];
+exports.GUARD_STATUSES = [
+    "guard_added",
+    "guard_existing",
+    "guard_waived",
+    "guard_deferred",
+    "none",
+];
+/** Workflow transitions exposed over MCP. `resolved` has its own tool. */
+exports.WORKFLOW_STATUSES = ["active", "reopened", "deferred"];
+/** Source recorded for tickets/notes created by an MCP agent client. */
+exports.MCP_ACTOR_SOURCE = "agent";
+async function createTicketTool(store, args) {
+    const config = store.getConfig();
+    const kind = (args.kind ?? config.defaultKind);
+    if (!config.ticketKinds.some((entry) => entry.kind === kind)) {
+        const valid = config.ticketKinds.map((entry) => entry.kind).join(", ");
+        throw new Error(`Unknown kind: ${kind} (valid: ${valid})`);
+    }
+    const ticket = await store.createTicket({
+        title: args.title ?? "",
+        summary: args.summary,
+        family: args.family ?? config.patterns.defaultFamily,
+        kind,
+        source: args.source ?? exports.MCP_ACTOR_SOURCE,
+        severity: args.severity,
+        confidence: args.confidence ?? "medium",
+        tags: args.tags ?? [],
+        handoffText: args.handoff,
+    });
+    return { ...envelope(), action: "created", ticket };
+}
+async function noteTool(store, args) {
+    const ticket = await store.addTicketNote(args.id, args.type ?? "triage", args.body, args.author ?? exports.MCP_ACTOR_SOURCE);
+    return { ...envelope(), action: "noted", ticket };
+}
+async function workflowTool(store, args) {
+    let ticket;
+    if (args.status === "active") {
+        ticket = await store.beginTicket(args.id);
+    }
+    else if (args.status === "reopened") {
+        ticket = await store.reopenTicket(args.id, args.reason ?? "recurrence detected");
+    }
+    else if (args.status === "deferred") {
+        ticket = await store.deferTicket(args.id, args.reason);
+    }
+    else {
+        throw new Error(`Unsupported workflow status: ${args.status} (use active|reopened|deferred; resolve via agentloop_resolve)`);
+    }
+    return { ...envelope(), action: "workflow", ticket };
+}
+async function resolveTool(store, args) {
+    const ticket = await store.resolveTicket({
+        id: args.id,
+        summary: args.summary,
+        verification: args.verification,
+        guardStatus: args.guardStatus ?? "none",
+        guardSummary: args.guardSummary,
+    });
+    return { ...envelope(), action: "resolved", ticket };
+}
+async function guardTool(store, args) {
+    const ticket = await store.setGuard(args.id, args.guardStatus, args.guardSummary);
+    return { ...envelope(), action: "guard", ticket };
+}
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/**
+ * Build an MCP server over the given store. By default only the read-only tools
+ * are exposed; pass `allowWrites: true` to also register the guarded write
+ * tools (create / note / workflow / resolve / guard).
+ */
+function createMcpServer(store, options = {}) {
+    const server = new mcp_js_1.McpServer({
+        name: exports.MCP_SERVER_NAME,
+        version: options.version ?? "0.1.0",
+    });
+    const readOnly = { readOnlyHint: true };
+    server.registerTool("agentloop_summary", {
+        title: "AgentLoop summary",
+        description: "Read-only loop health metrics (ticket and pattern counts).",
+        inputSchema: {},
+        annotations: readOnly,
+    }, async () => {
+        try {
+            return ok(await summaryTool(store));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_list", {
+        title: "List tickets",
+        description: "Read-only list of tickets, optionally filtered by status (triaged|active|resolved|reopened|deferred|all) and kind.",
+        inputSchema: {
+            status: zod_1.z.string().optional(),
+            kind: zod_1.z.string().optional(),
+        },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await listTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_show", {
+        title: "Show ticket or pattern",
+        description: "Read-only details for a ticket (by canonical ISSUE- id or queue alias such as DEV-/USER-) or a PATTERN- id.",
+        inputSchema: { id: zod_1.z.string() },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await showTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_handoff", {
+        title: "Ticket handoff prompt",
+        description: "Read-only copyable agent handoff prompt for a ticket.",
+        inputSchema: { id: zod_1.z.string() },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await handoffTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_convergence", {
+        title: "Source-convergence audit",
+        description: "Read-only report of patterns whose tickets span multiple distinct sources (corroboration across intake channels).",
+        inputSchema: {
+            family: zod_1.z.string().optional(),
+            minSources: zod_1.z.number().int().positive().optional(),
+            includeAll: zod_1.z.boolean().optional(),
+        },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await store.sourceConvergence(args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_guard_gaps", {
+        title: "Guard-gap report",
+        description: "Read-only report of resolved tickets that lack an active regression guard (defects/user reports by default).",
+        inputSchema: {
+            family: zod_1.z.string().optional(),
+            includeWaived: zod_1.z.boolean().optional(),
+            allKinds: zod_1.z.boolean().optional(),
+        },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await store.guardGaps(args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_search_knowledge", {
+        title: "Search resolution knowledge",
+        description: "Read-only search over resolved-ticket fix knowledge (how prior tickets were resolved), by family/kind/source/tag/free-text query.",
+        inputSchema: {
+            family: zod_1.z.string().optional(),
+            kind: zod_1.z.string().optional(),
+            source: zod_1.z.string().optional(),
+            tag: zod_1.z.string().optional(),
+            query: zod_1.z.string().optional(),
+            limit: zod_1.z.number().int().nonnegative().optional(),
+        },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await store.searchKnowledge(args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_knowledge_gaps", {
+        title: "Knowledge-gap report",
+        description: "Read-only report of resolved tickets whose reusable knowledge is incomplete (missing resolution or verification).",
+        inputSchema: {
+            family: zod_1.z.string().optional(),
+            severity: zod_1.z.string().optional(),
+            source: zod_1.z.string().optional(),
+        },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await store.knowledgeGaps(args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_related", {
+        title: "Related tickets (prior art)",
+        description: "Read-only prior-art lookup: tickets most related to the given id by shared family/pattern/tags/kind and title overlap.",
+        inputSchema: {
+            id: zod_1.z.string(),
+            minScore: zod_1.z.number().nonnegative().optional(),
+            limit: zod_1.z.number().int().nonnegative().optional(),
+        },
+        annotations: readOnly,
+    }, async (args) => {
+        try {
+            return ok(await store.related(args.id, { minScore: args.minScore, limit: args.limit }));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    if (options.allowWrites) {
+        registerWriteTools(server, store);
+    }
+    return server;
+}
+/** Register the mutating tools. Only called when writes are explicitly enabled. */
+function registerWriteTools(server, store) {
+    const write = { readOnlyHint: false };
+    server.registerTool("agentloop_create", {
+        title: "Create ticket",
+        description: "Create a ticket. `summary` is required; `kind`/`family`/`source` default from config (source defaults to 'agent').",
+        inputSchema: {
+            summary: zod_1.z.string().min(1),
+            title: zod_1.z.string().optional(),
+            family: zod_1.z.string().optional(),
+            kind: zod_1.z.string().optional(),
+            source: zod_1.z.string().optional(),
+            severity: zod_1.z.enum(exports.SEVERITIES).optional(),
+            confidence: zod_1.z.enum(exports.CONFIDENCES).optional(),
+            tags: zod_1.z.array(zod_1.z.string()).optional(),
+            handoff: zod_1.z.string().optional(),
+        },
+        annotations: write,
+    }, async (args) => {
+        try {
+            return ok(await createTicketTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_note", {
+        title: "Add note",
+        description: "Append a non-resolution note to a ticket (by id or alias).",
+        inputSchema: {
+            id: zod_1.z.string(),
+            body: zod_1.z.string().min(1),
+            type: zod_1.z.enum(exports.NOTE_TYPES).optional(),
+            author: zod_1.z.string().optional(),
+        },
+        annotations: write,
+    }, async (args) => {
+        try {
+            return ok(await noteTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_workflow", {
+        title: "Workflow transition",
+        description: "Transition a ticket: status 'active' begins work, 'reopened' records a recurrence, 'deferred' shelves it (optional reason). Resolve via agentloop_resolve.",
+        inputSchema: {
+            id: zod_1.z.string(),
+            status: zod_1.z.enum(exports.WORKFLOW_STATUSES),
+            reason: zod_1.z.string().optional(),
+        },
+        annotations: write,
+    }, async (args) => {
+        try {
+            return ok(await workflowTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_resolve", {
+        title: "Resolve ticket",
+        description: "Resolve a ticket with a required summary; optionally record verification and a guard decision.",
+        inputSchema: {
+            id: zod_1.z.string(),
+            summary: zod_1.z.string().min(1),
+            verification: zod_1.z.string().optional(),
+            guardStatus: zod_1.z.enum(exports.GUARD_STATUSES).optional(),
+            guardSummary: zod_1.z.string().optional(),
+        },
+        annotations: write,
+    }, async (args) => {
+        try {
+            return ok(await resolveTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("agentloop_guard", {
+        title: "Record guard decision",
+        description: "Set the regression-guard decision for a ticket (by id or alias).",
+        inputSchema: {
+            id: zod_1.z.string(),
+            guardStatus: zod_1.z.enum(exports.GUARD_STATUSES),
+            guardSummary: zod_1.z.string().optional(),
+        },
+        annotations: write,
+    }, async (args) => {
+        try {
+            return ok(await guardTool(store, args));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}
+/**
+ * Start the AgentLoops MCP server over stdio. Reads/writes JSON-RPC on
+ * stdin/stdout, so nothing else may be written to stdout while it runs.
+ */
+async function startStdioMcpServer(opts) {
+    const store = new store_1.AgentLoopStore(opts.cwd, opts.config, { backend: opts.backend });
+    await store.ensureInitialized();
+    const server = createMcpServer(store, {
+        version: opts.version,
+        allowWrites: opts.allowWrites,
+    });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // Stay alive until the client closes stdin, so callers can dispose resources
+    // (e.g. a Postgres pool) cleanly on shutdown.
+    await new Promise((resolve) => {
+        process.stdin.once("end", resolve);
+        process.stdin.once("close", resolve);
+    });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/postgres.d.ts

@@ -0,0 +1,104 @@
+import { LoopState } from "./types";
+import { StateBackend } from "./backend";
+/**
+ * Public relational schema for the ledger. Faithfully mirrors `LoopState`:
+ * timestamps are stored as ISO text to keep round-trips identical to the JSON
+ * backend, and ordered child collections carry an `ord` column.
+ */
+export declare const TICKET_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS loop_meta (\n  id integer PRIMARY KEY DEFAULT 1 CHECK (id = 1),\n  project text NOT NULL,\n  version integer NOT NULL,\n  created_at text NOT NULL,\n  updated_at text NOT NULL,\n  next_ticket_seq integer NOT NULL,\n  next_pattern_seq integer NOT NULL\n);\nCREATE TABLE IF NOT EXISTS ticket_patterns (\n  id text PRIMARY KEY,\n  family text NOT NULL,\n  title text NOT NULL,\n  status text NOT NULL,\n  created_at text NOT NULL,\n  updated_at text NOT NULL\n);\nCREATE TABLE IF NOT EXISTS tickets (\n  id text PRIMARY KEY,\n  family text NOT NULL,\n  kind text NOT NULL,\n  source text NOT NULL,\n  title text NOT NULL,\n  summary text NOT NULL,\n  severity text NOT NULL,\n  confidence text NOT NULL,\n  status text NOT NULL,\n  created_at text NOT NULL,\n  updated_at text NOT NULL,\n  started_at text,\n  resolved_at text,\n  handoff_text text,\n  guard_status text,\n  guard_summary text,\n  pattern_id text,\n  verification text,\n  reproducible boolean,\n  resolution_summary text\n);\nCREATE TABLE IF NOT EXISTS ticket_aliases (ticket_id text NOT NULL, alias text NOT NULL, ord integer NOT NULL);\nCREATE TABLE IF NOT EXISTS ticket_tags (ticket_id text NOT NULL, tag text NOT NULL, ord integer NOT NULL);\nCREATE TABLE IF NOT EXISTS ticket_notes (\n  id text NOT NULL,\n  ticket_id text NOT NULL,\n  type text NOT NULL,\n  body text NOT NULL,\n  author text,\n  created_at text NOT NULL,\n  ord integer NOT NULL\n);\nCREATE TABLE IF NOT EXISTS ticket_pattern_links (pattern_id text NOT NULL, ticket_id text NOT NULL, ord integer NOT NULL);\n";
+interface MetaRows {
+    project: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    nextTicketSeq: number;
+    nextPatternSeq: number;
+}
+interface PatternRow {
+    id: string;
+    family: string;
+    title: string;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface TicketRow {
+    id: string;
+    family: string;
+    kind: string;
+    source: string;
+    title: string;
+    summary: string;
+    severity: string;
+    confidence: string;
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string | null;
+    resolvedAt: string | null;
+    handoffText: string | null;
+    guardStatus: string | null;
+    guardSummary: string | null;
+    patternId: string | null;
+    verification: string | null;
+    reproducible: boolean | null;
+    resolutionSummary: string | null;
+}
+interface AliasRow {
+    ticketId: string;
+    alias: string;
+    ord: number;
+}
+interface TagRow {
+    ticketId: string;
+    tag: string;
+    ord: number;
+}
+interface NoteRow {
+    id: string;
+    ticketId: string;
+    type: string;
+    body: string;
+    author: string | null;
+    createdAt: string;
+    ord: number;
+}
+interface LinkRow {
+    patternId: string;
+    ticketId: string;
+    ord: number;
+}
+export interface RelationalRows {
+    meta: MetaRows;
+    patterns: PatternRow[];
+    tickets: TicketRow[];
+    aliases: AliasRow[];
+    tags: TagRow[];
+    notes: NoteRow[];
+    links: LinkRow[];
+}
+export declare function serializeState(state: LoopState): RelationalRows;
+export declare function deserializeRows(rows: RelationalRows): LoopState;
+/** Minimal client shape; a `pg.Pool` or `pg.Client` satisfies it. */
+export interface PgClient {
+    query<R = unknown>(text: string, params?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Postgres-backed `StateBackend` over the relational `ticket_*` schema. Brings
+ * no `pg` dependency — the host injects a `pg.Pool`/`pg.Client`-shaped client.
+ * Saves are transactional (whole-snapshot replace), so a failed write never
+ * leaves a partially-updated ledger.
+ */
+export declare class PostgresStateBackend implements StateBackend {
+    private readonly client;
+    private migrated;
+    constructor(client: PgClient);
+    migrate(): Promise<void>;
+    private ensureSchema;
+    private withConnection;
+    load(): Promise<LoopState | null>;
+    save(state: LoopState): Promise<void>;
+}
+export {};