@stevenvincentone/intidev-agentloops 0.1.0

package/dist/cli.js

@@ -0,0 +1,497 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("./config");
+const node_fs_1 = require("node:fs");
+const store_1 = require("./store");
+const handoff_1 = require("./handoff");
+const dashboard_1 = require("./dashboard");
+const serve_1 = require("./serve");
+const storage_1 = require("./storage");
+const COMMANDS = [
+    "init",
+    "create",
+    "list",
+    "show",
+    "patterns",
+    "begin",
+    "resolve",
+    "reopen",
+    "defer",
+    "note",
+    "guard",
+    "handoff",
+    "summary",
+    "convergence",
+    "guard-gaps",
+    "knowledge",
+    "knowledge-gaps",
+    "related",
+    "dashboard",
+    "serve",
+    "config",
+    "mcp",
+    "help",
+];
+function parseArgs(argv) {
+    const args = [];
+    const options = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (!token.startsWith("--")) {
+            args.push(token);
+            continue;
+        }
+        const split = token.indexOf("=");
+        if (split > -1) {
+            options[token.substring(2, split)] = token.substring(split + 1);
+            continue;
+        }
+        const next = argv[i + 1];
+        if (next && !next.startsWith("--")) {
+            options[token.substring(2)] = next;
+            i += 1;
+            continue;
+        }
+        options[token.substring(2)] = true;
+    }
+    return { args, options };
+}
+function toArray(value) {
+    if (!value || typeof value !== "string")
+        return [];
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function printLine(...parts) {
+    process.stdout.write(parts.join(" ") + "\n");
+}
+function printJson(value) {
+    process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+function shortSummary(status) {
+    return status.toUpperCase().padEnd(8);
+}
+function printHelp() {
+    printLine("IntiDev AgentLoops");
+    printLine("Commands:");
+    printLine("  init                            initialize a project loop");
+    printLine("  create --title ... --summary ... create a new issue/feature/feedback");
+    printLine("  list [--status triaged|active|resolved|all] list tickets");
+    printLine("  show <id>                       inspect ticket");
+    printLine("  patterns [--status open|active|resolved|all] list patterns");
+    printLine("  begin <id>                      begin a triaged item");
+    printLine("  resolve <id> --summary ...      resolve a ticket");
+    printLine("  reopen <id> --summary ...       reopen a resolved/reopen-risk item");
+    printLine("  defer <id> [--summary ...]      defer a ticket (records an optional reason)");
+    printLine("  note <id> --type ... --body ... add a non-resolution note");
+    printLine("  guard <id> --guard-status ...   set guard decision");
+    printLine("  handoff <id>                    print agent handoff prompt");
+    printLine("  summary                         print loop stats");
+    printLine("  convergence [--family ..] [--min-sources N] [--all]  patterns spanning multiple sources");
+    printLine("  guard-gaps [--family ..] [--include-waived] [--all-kinds]  resolved tickets missing a guard");
+    printLine("  knowledge [--family ..] [--kind ..] [--query ..]  search resolved-ticket fix knowledge");
+    printLine("  knowledge-gaps [--family ..] [--severity ..] [--source ..]  resolved tickets lacking reusable knowledge");
+    printLine("  related <id> [--min-score N] [--limit N]  prior-art: tickets related to <id>");
+    printLine("  dashboard [--out file.html] [--stdout]  write a standalone HTML dashboard");
+    printLine("  serve [--port N]                serve the dashboard over HTTP (default 4319)");
+    printLine("  config                          print effective config");
+    printLine("  mcp [--write]                   run the MCP server over stdio (read-only unless --write)");
+    printLine("");
+    printLine("Storage: set DATABASE_URL to run on Postgres; otherwise .agentloops/state.json is used.");
+}
+let openedStore = null;
+let openedSelection = null;
+// Opens (once) the store over the resolved backend — Postgres when DATABASE_URL
+// or config selects it, otherwise the filesystem. Cached so a single process
+// uses one backend (and one Postgres pool).
+async function ensureConfig() {
+    if (openedStore)
+        return openedStore;
+    const cwd = process.cwd();
+    const config = await (0, config_1.loadConfig)(cwd);
+    openedSelection = await (0, storage_1.resolveBackend)({ cwd, config });
+    const store = new store_1.AgentLoopStore(cwd, config, { backend: openedSelection.backend });
+    openedStore = { cwd, config, store, kind: openedSelection.kind };
+    return openedStore;
+}
+// Release storage resources (closes the Postgres pool so the process can exit).
+async function disposeStorage() {
+    if (openedSelection) {
+        await openedSelection.dispose();
+        openedSelection = null;
+        openedStore = null;
+    }
+}
+async function cmdInit(argv, options) {
+    await (0, config_1.writeDefaultConfig)(process.cwd());
+    const { config, store, kind } = await ensureConfig();
+    const project = typeof options.project === "string" ? options.project : config.projectName;
+    const created = await store.ensureInitialized(project);
+    const where = kind === "postgres" ? "Postgres" : ".agentloops/state.json";
+    printLine(`Initialized ${created.project} (${where})`);
+}
+async function cmdCreate(argv, options) {
+    const { store, config } = await ensureConfig();
+    const title = typeof options.title === "string" ? options.title : "";
+    const summary = typeof options.summary === "string" ? options.summary : "";
+    const family = typeof options.family === "string" ? options.family : config.patterns.defaultFamily;
+    const kind = (typeof options.kind === "string" ? options.kind : config.defaultKind);
+    const source = typeof options.source === "string" ? options.source : "manual_admin";
+    const severity = (typeof options.severity === "string"
+        ? options.severity
+        : config.ticketKinds.find((entry) => entry.kind === kind)?.defaultSeverity);
+    const confidence = (typeof options.confidence === "string"
+        ? options.confidence
+        : "medium");
+    const tags = toArray(options.tags);
+    const ticket = await store.createTicket({
+        title,
+        summary,
+        family,
+        kind,
+        source,
+        severity,
+        confidence,
+        tags,
+        handoffText: typeof options.handoff === "string" ? options.handoff : undefined,
+    });
+    if (options.json) {
+        printJson(ticket);
+    }
+    else {
+        printLine(`Created ${ticket.id} (${ticket.aliases.join(", ")})`);
+        printLine(`kind=${ticket.kind} family=${ticket.family} status=${ticket.status}`);
+        printLine(`title: ${ticket.title}`);
+        if (ticket.patternId) {
+            printLine(`Pattern: ${ticket.patternId}`);
+        }
+    }
+}
+async function cmdList(argv, options) {
+    const { store } = await ensureConfig();
+    const status = options.status ? options.status : "all";
+    const rows = await store.listTickets({
+        status: status,
+        kind: typeof options.kind === "string" ? options.kind : undefined,
+    });
+    if (options.json) {
+        printJson(rows);
+        return;
+    }
+    for (const ticket of rows) {
+        printLine(`${shortSummary(ticket.status)} ${ticket.id} ${ticket.aliases[0] ?? ""} ${ticket.kind} [${ticket.family}]`);
+        printLine(`  ${ticket.title}`);
+    }
+    if (rows.length === 0) {
+        printLine("No tickets found");
+    }
+}
+async function cmdShow(argv) {
+    const { store } = await ensureConfig();
+    const raw = argv[1];
+    if (!raw) {
+        throw new Error("show requires an id");
+    }
+    if (raw.startsWith("PATTERN-")) {
+        const pattern = await store.getPattern(raw);
+        if (!pattern)
+            throw new Error(`Pattern not found: ${raw}`);
+        printJson(pattern);
+        return;
+    }
+    const canonical = (0, store_1.normalizeTicketInput)(raw, await store.listTickets({ status: "all" }));
+    if (canonical.startsWith("PATTERN-")) {
+        const pattern = await store.getPattern(canonical);
+        if (!pattern)
+            throw new Error(`Pattern not found: ${raw}`);
+        printJson(pattern);
+        return;
+    }
+    const ticket = await store.showTicket(raw);
+    if (!ticket)
+        throw new Error(`Not found: ${raw}`);
+    printJson(ticket);
+}
+async function cmdPatterns(argv, options) {
+    const { store } = await ensureConfig();
+    const status = options.status ? options.status : "all";
+    const rows = await store.listPatterns({ status });
+    if (options.json) {
+        printJson(rows);
+        return;
+    }
+    for (const p of rows) {
+        printLine(`${p.status.toUpperCase().padEnd(8)} ${p.id} ${p.family} (${p.ticketIds.length} tickets)`);
+        printLine(`  ${p.title}`);
+    }
+    if (rows.length === 0) {
+        printLine("No patterns found");
+    }
+}
+async function cmdBegin(argv) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    if (!id)
+        throw new Error("begin requires an id");
+    const ticket = await store.beginTicket(id);
+    printJson(ticket);
+}
+async function cmdResolve(argv, options) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    const summary = typeof options.summary === "string" ? options.summary : "";
+    if (!id || !summary) {
+        throw new Error("resolve requires <id> and --summary");
+    }
+    const ticket = await store.resolveTicket({
+        id,
+        summary,
+        verification: typeof options.verification === "string" ? options.verification : undefined,
+        guardStatus: typeof options["guard-status"] === "string" ? options["guard-status"] : "none",
+        guardSummary: typeof options["guard-summary"] === "string" ? options["guard-summary"] : undefined,
+    });
+    printJson(ticket);
+}
+async function cmdReopen(argv, options) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    const reason = typeof options.summary === "string" ? options.summary : "recurrence detected";
+    if (!id)
+        throw new Error("reopen requires <id>");
+    const ticket = await store.reopenTicket(id, reason);
+    printJson(ticket);
+}
+async function cmdDefer(argv, options) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    if (!id)
+        throw new Error("defer requires <id>");
+    const reason = typeof options.summary === "string"
+        ? options.summary
+        : typeof options.reason === "string"
+            ? options.reason
+            : undefined;
+    const ticket = await store.deferTicket(id, reason);
+    printJson(ticket);
+}
+async function cmdNote(argv, options) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    const body = typeof options.body === "string" ? options.body : "";
+    const type = (typeof options.type === "string" ? options.type : "triage");
+    if (!id || !body) {
+        throw new Error("note requires <id> and --body");
+    }
+    const ticket = await store.addTicketNote(id, type, body, process.env.USER);
+    printJson(ticket);
+}
+async function cmdGuard(argv, options) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    const status = typeof options["guard-status"] === "string" ? options["guard-status"] : "guard_deferred";
+    const summary = typeof options["guard-summary"] === "string" ? options["guard-summary"] : undefined;
+    if (!id)
+        throw new Error("guard requires <id>");
+    const ticket = await store.setGuard(id, status, summary);
+    printJson(ticket);
+}
+async function cmdHandoff(argv) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    if (!id)
+        throw new Error("handoff requires <id>");
+    const ticket = await store.showTicket(id);
+    if (!ticket)
+        throw new Error(`Not found: ${id}`);
+    const prompt = (0, handoff_1.buildHandoffPrompt)(ticket);
+    printLine(`Ticket: ${ticket.id}`);
+    printLine(`Aliases: ${ticket.aliases.join(", ")}`);
+    printLine("Copyable agent handoff:");
+    printLine(prompt);
+}
+async function cmdSummary() {
+    const { store } = await ensureConfig();
+    printJson(await store.summary());
+}
+async function cmdConvergence(options) {
+    const { store } = await ensureConfig();
+    const family = typeof options.family === "string" ? options.family : undefined;
+    const minSources = typeof options["min-sources"] === "string" ? Number(options["min-sources"]) : undefined;
+    const includeAll = options.all === true;
+    printJson(await store.sourceConvergence({ family, minSources, includeAll }));
+}
+async function cmdGuardGaps(options) {
+    const { store } = await ensureConfig();
+    const family = typeof options.family === "string" ? options.family : undefined;
+    const includeWaived = options["include-waived"] === true;
+    const allKinds = options["all-kinds"] === true;
+    printJson(await store.guardGaps({ family, includeWaived, allKinds }));
+}
+async function cmdKnowledge(options) {
+    const { store } = await ensureConfig();
+    const str = (key) => (typeof options[key] === "string" ? options[key] : undefined);
+    const limit = typeof options.limit === "string" ? Number(options.limit) : undefined;
+    printJson(await store.searchKnowledge({
+        family: str("family"),
+        kind: str("kind"),
+        source: str("source"),
+        tag: str("tag"),
+        query: str("query"),
+        limit,
+    }));
+}
+async function cmdKnowledgeGaps(options) {
+    const { store } = await ensureConfig();
+    const str = (key) => (typeof options[key] === "string" ? options[key] : undefined);
+    printJson(await store.knowledgeGaps({
+        family: str("family"),
+        severity: str("severity"),
+        source: str("source"),
+    }));
+}
+async function cmdRelated(argv, options) {
+    const { store } = await ensureConfig();
+    const id = argv[1];
+    if (!id)
+        throw new Error("related requires an id");
+    const minScore = typeof options["min-score"] === "string" ? Number(options["min-score"]) : undefined;
+    const limit = typeof options.limit === "string" ? Number(options.limit) : undefined;
+    printJson(await store.related(id, { minScore, limit }));
+}
+async function cmdDashboard(options) {
+    const { store } = await ensureConfig();
+    const html = (0, dashboard_1.renderDashboard)(await (0, dashboard_1.gatherDashboardData)(store));
+    if (options.stdout === true) {
+        process.stdout.write(html);
+        return;
+    }
+    const out = typeof options.out === "string" ? options.out : "agentloop-dashboard.html";
+    await node_fs_1.promises.writeFile(out, html, "utf-8");
+    printLine(`Wrote dashboard to ${out}`);
+}
+async function cmdServe(options) {
+    const { store, kind } = await ensureConfig();
+    const port = typeof options.port === "string" ? Number(options.port) : 4319;
+    const server = (0, serve_1.createDashboardServer)(store);
+    await new Promise((resolve) => server.listen(port, resolve));
+    process.stderr.write(`agentloop dashboard on http://localhost:${port} (${kind})\n`);
+    // Run until the process is stopped.
+    await new Promise(() => { });
+}
+async function cmdConfig() {
+    const { config } = await ensureConfig();
+    printJson(config);
+}
+async function cmdMcp(options) {
+    const { cwd, config, kind } = await ensureConfig();
+    // Writes are opt-in: read-only unless --write (alias --allow-writes) is set.
+    const allowWrites = options.write === true || options["allow-writes"] === true;
+    // Lazy-load so the MCP SDK is only required when this command runs, and so
+    // its dependency never affects startup of the other CLI commands.
+    const { startStdioMcpServer } = await import("./mcp.js");
+    // stdout is reserved for the JSON-RPC stream; status goes to stderr.
+    process.stderr.write(`agentloop MCP server ready on stdio (${allowWrites ? "read-write" : "read-only"}, ${kind})\n`);
+    await startStdioMcpServer({ cwd, config, allowWrites, backend: openedSelection?.backend });
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const { args, options } = parseArgs(argv);
+    const command = args[0] ?? "help";
+    if (!COMMANDS.includes(command)) {
+        throw new Error(`Unknown command: ${command}`);
+    }
+    try {
+        switch (command) {
+            case "help":
+                printHelp();
+                break;
+            case "init":
+                await cmdInit(args, options);
+                break;
+            case "create":
+                await cmdCreate(args, options);
+                break;
+            case "list":
+                await cmdList(args, options);
+                break;
+            case "show":
+                await cmdShow(args);
+                break;
+            case "patterns":
+                await cmdPatterns(args, options);
+                break;
+            case "begin":
+                await cmdBegin(args);
+                break;
+            case "resolve":
+                await cmdResolve(args, options);
+                break;
+            case "reopen":
+                await cmdReopen(args, options);
+                break;
+            case "defer":
+                await cmdDefer(args, options);
+                break;
+            case "note":
+                await cmdNote(args, options);
+                break;
+            case "guard":
+                await cmdGuard(args, options);
+                break;
+            case "handoff":
+                await cmdHandoff(args);
+                break;
+            case "summary":
+                await cmdSummary();
+                break;
+            case "convergence":
+                await cmdConvergence(options);
+                break;
+            case "guard-gaps":
+                await cmdGuardGaps(options);
+                break;
+            case "knowledge":
+                await cmdKnowledge(options);
+                break;
+            case "knowledge-gaps":
+                await cmdKnowledgeGaps(options);
+                break;
+            case "related":
+                await cmdRelated(args, options);
+                break;
+            case "dashboard":
+                await cmdDashboard(options);
+                break;
+            case "serve":
+                await cmdServe(options);
+                break;
+            case "config":
+                await cmdConfig();
+                break;
+            case "mcp":
+                await cmdMcp(options);
+                break;
+            default:
+                printHelp();
+        }
+    }
+    finally {
+        await disposeStorage();
+    }
+}
+// Exit quietly when output is piped to a reader that closed early
+// (e.g. `agentloop list | head`), instead of crashing with EPIPE.
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    printLine(`Error: ${message}`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+import { ProjectConfig, TicketKind } from "./types";
+export declare const DEFAULT_CONFIG: ProjectConfig;
+export declare const CONFIG_FILE_NAME = "agentloop.config.json";
+export declare const STATE_DIR = ".agentloops";
+export declare function configPath(cwd: string): string;
+export declare function loadConfig(cwd: string): Promise<ProjectConfig>;
+export declare function writeDefaultConfig(cwd: string): Promise<ProjectConfig>;
+export declare function requiredFields(config: ProjectConfig, kind: TicketKind): string[];
+export declare function ensureKind(config: ProjectConfig, kind: string | undefined): TicketKind;
+export declare function mergeConfig(partial: Partial<ProjectConfig>): ProjectConfig;

package/dist/config.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_DIR = exports.CONFIG_FILE_NAME = exports.DEFAULT_CONFIG = void 0;
+exports.configPath = configPath;
+exports.loadConfig = loadConfig;
+exports.writeDefaultConfig = writeDefaultConfig;
+exports.requiredFields = requiredFields;
+exports.ensureKind = ensureKind;
+exports.mergeConfig = mergeConfig;
+const fs_1 = require("fs");
+const path_1 = require("path");
+exports.DEFAULT_CONFIG = {
+    projectName: "IntiDev AgentLoops",
+    description: "Feedback Loops for Agentic Workflows",
+    defaultKind: "bug",
+    ticketKinds: [
+        { kind: "bug", defaultSeverity: "high", requiredFields: ["summary"] },
+        { kind: "feature", defaultSeverity: "medium", requiredFields: ["summary"] },
+        { kind: "user_feedback", defaultSeverity: "high", requiredFields: ["summary"] },
+        { kind: "investigation", defaultSeverity: "medium", requiredFields: ["summary"] },
+        { kind: "incident", defaultSeverity: "critical", requiredFields: ["summary"] },
+        { kind: "tech_debt", defaultSeverity: "medium", requiredFields: ["summary"] },
+        { kind: "task", defaultSeverity: "medium", requiredFields: ["summary"] },
+    ],
+    queues: [
+        { prefix: "USER", kinds: ["user_feedback"], sources: ["user_report"] },
+        { prefix: "DEV", kinds: ["feature", "task", "investigation", "tech_debt"] },
+        { prefix: "ISSUE", kinds: ["bug", "incident"], default: true },
+    ],
+    sources: ["user_report", "manual_admin", "agent", "smoke", "ci", "ingestion", "unknown"],
+    patterns: {
+        autoCreateByFamily: true,
+        defaultFamily: "general",
+    },
+};
+exports.CONFIG_FILE_NAME = "agentloop.config.json";
+exports.STATE_DIR = ".agentloops";
+function configPath(cwd) {
+    return (0, path_1.join)(cwd, exports.CONFIG_FILE_NAME);
+}
+async function loadConfig(cwd) {
+    try {
+        const text = await fs_1.promises.readFile(configPath(cwd), "utf-8");
+        const parsed = JSON.parse(text);
+        return mergeConfig(parsed);
+    }
+    catch {
+        return { ...exports.DEFAULT_CONFIG };
+    }
+}
+async function writeDefaultConfig(cwd) {
+    const path = configPath(cwd);
+    await fs_1.promises.writeFile(path, JSON.stringify(exports.DEFAULT_CONFIG, null, 2), "utf-8");
+    return { ...exports.DEFAULT_CONFIG };
+}
+function requiredFields(config, kind) {
+    const k = config.ticketKinds.find((entry) => entry.kind === kind);
+    return k?.requiredFields ?? [];
+}
+function ensureKind(config, kind) {
+    const candidate = (kind ?? config.defaultKind).toLowerCase();
+    const has = config.ticketKinds.some((entry) => entry.kind === candidate);
+    if (!has) {
+        return config.defaultKind;
+    }
+    return candidate;
+}
+function mergeConfig(partial) {
+    const mergedKinds = (partial.ticketKinds ?? exports.DEFAULT_CONFIG.ticketKinds).map((kind) => ({ ...kind, defaultSeverity: kind.defaultSeverity ?? "medium" }));
+    return {
+        ...exports.DEFAULT_CONFIG,
+        ...partial,
+        ticketKinds: mergedKinds,
+        queues: partial.queues ?? exports.DEFAULT_CONFIG.queues,
+        patterns: {
+            ...exports.DEFAULT_CONFIG.patterns,
+            ...(partial.patterns ?? {}),
+        },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/convergence.d.ts

@@ -0,0 +1,56 @@
+import { Pattern, PatternStatus, Ticket, TicketStatus } from "./types";
+export declare const SOURCE_CONVERGENCE_SCHEMA_VERSION: 1;
+export declare const DEFAULT_MIN_SOURCES = 2;
+export interface SourceConvergenceOptions {
+    /** Minimum distinct sources for a pattern to count as converged. Default 2. */
+    minSources?: number;
+    /** Restrict the audit to a single family. */
+    family?: string;
+    /** Include non-converged patterns in `patterns` too. Default false. */
+    includeAll?: boolean;
+}
+export interface ConvergenceTicketRef {
+    id: string;
+    alias: string;
+    source: string;
+    kind: string;
+    status: TicketStatus;
+}
+export interface ConvergencePattern {
+    id: string;
+    family: string;
+    title: string;
+    status: PatternStatus;
+    ticketCount: number;
+    /** Number of distinct sources among the pattern's tickets. */
+    sourceCount: number;
+    /** Count of tickets per source. */
+    sources: Record<string, number>;
+    converged: boolean;
+    tickets: ConvergenceTicketRef[];
+}
+export interface SourceConvergenceReport {
+    schemaVersion: typeof SOURCE_CONVERGENCE_SCHEMA_VERSION;
+    generatedAt: string;
+    filters: {
+        family: string | null;
+        minSources: number;
+    };
+    summary: {
+        totalPatterns: number;
+        convergedPatterns: number;
+        /** Highest distinct-source count across the analyzed patterns. */
+        maxSourceConvergence: number;
+    };
+    patterns: ConvergencePattern[];
+}
+/**
+ * Source-convergence audit (ported concept from Inti's ledger): surface the
+ * Patterns whose member tickets were reported through **multiple distinct
+ * sources**. A pattern corroborated by, say, a smoke run + a user report + an
+ * agent is far higher-signal than a single-source cluster.
+ *
+ * Pure and deterministic apart from `generatedAt`. Patterns are returned sorted
+ * by source diversity (then ticket count, then id) so output is stable.
+ */
+export declare function sourceConvergenceReport(tickets: Ticket[], patterns: Pattern[], options?: SourceConvergenceOptions): SourceConvergenceReport;