@stevenvincentone/intidev-agentloops 0.1.0

package/dist/knowledge.d.ts

@@ -0,0 +1,101 @@
+import { Ticket } from "./types";
+export declare const KNOWLEDGE_SCHEMA_VERSION: 1;
+export interface KnowledgeEntry {
+    id: string;
+    alias: string;
+    kind: string;
+    source: string;
+    family: string;
+    severity: string;
+    tags: string[];
+    title: string;
+    /** The original symptom (ticket summary). */
+    problem: string;
+    /** How it was fixed (ticket resolutionSummary). */
+    resolution: string;
+    verification?: string;
+    /** True when both a resolution and a verification record are present. */
+    verified: boolean;
+    guardStatus?: string;
+    guardSummary?: string;
+    resolvedAt?: string;
+}
+export interface KnowledgeSearchOptions {
+    family?: string;
+    kind?: string;
+    source?: string;
+    tag?: string;
+    /** Free-text query; every whitespace-separated term must appear. */
+    query?: string;
+    limit?: number;
+}
+export interface ResolutionKnowledgeReport {
+    schemaVersion: typeof KNOWLEDGE_SCHEMA_VERSION;
+    generatedAt: string;
+    filters: {
+        family: string | null;
+        kind: string | null;
+        source: string | null;
+        tag: string | null;
+        query: string | null;
+    };
+    summary: {
+        /** Resolved tickets that carry a resolution summary (the corpus size). */
+        resolvedWithKnowledge: number;
+        /** Of those, how many also have verification evidence. */
+        verified: number;
+        /** Entries returned after filters (before any limit). */
+        matched: number;
+    };
+    entries: KnowledgeEntry[];
+}
+/**
+ * Resolution-knowledge corpus (ported concept from Inti's resolution knowledge):
+ * the reusable record of how each resolved ticket was fixed, so an agent facing
+ * a new ticket can retrieve prior art by family/kind/source/tag/free text.
+ *
+ * Pure and deterministic apart from `generatedAt`. Newest resolutions first.
+ */
+export declare function resolutionKnowledge(tickets: Ticket[], options?: KnowledgeSearchOptions): ResolutionKnowledgeReport;
+export type KnowledgeGapReason = "no_resolution" | "unverified";
+export interface KnowledgeGapsOptions {
+    family?: string;
+    severity?: string;
+    source?: string;
+}
+export interface KnowledgeGap {
+    id: string;
+    alias: string;
+    kind: string;
+    source: string;
+    family: string;
+    severity: string;
+    title: string;
+    reason: KnowledgeGapReason;
+    resolvedAt?: string;
+}
+export interface KnowledgeGapsReport {
+    schemaVersion: typeof KNOWLEDGE_SCHEMA_VERSION;
+    generatedAt: string;
+    filters: {
+        family: string | null;
+        severity: string | null;
+        source: string | null;
+    };
+    summary: {
+        resolved: number;
+        complete: number;
+        gaps: number;
+        noResolution: number;
+        unverified: number;
+    };
+    gaps: KnowledgeGap[];
+}
+/**
+ * Resolved tickets whose knowledge is incomplete for reuse: missing a resolution
+ * summary, or resolved without verification evidence. The contracts doc's
+ * `knowledge-gaps` cleanup backlog, scoped by family/severity/source.
+ *
+ * Pure and deterministic apart from `generatedAt`.
+ */
+export declare function knowledgeGaps(tickets: Ticket[], options?: KnowledgeGapsOptions): KnowledgeGapsReport;

package/dist/knowledge.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWLEDGE_SCHEMA_VERSION = void 0;
+exports.resolutionKnowledge = resolutionKnowledge;
+exports.knowledgeGaps = knowledgeGaps;
+exports.KNOWLEDGE_SCHEMA_VERSION = 1;
+function hasText(value) {
+    return Boolean(value && value.trim());
+}
+function toEntry(ticket) {
+    return {
+        id: ticket.id,
+        alias: ticket.aliases[0] ?? ticket.id,
+        kind: ticket.kind,
+        source: ticket.source,
+        family: ticket.family,
+        severity: ticket.severity,
+        tags: ticket.tags,
+        title: ticket.title,
+        problem: ticket.summary,
+        resolution: ticket.resolutionSummary ?? "",
+        verification: ticket.verification,
+        verified: hasText(ticket.resolutionSummary) && hasText(ticket.verification),
+        guardStatus: ticket.guardStatus,
+        guardSummary: ticket.guardSummary,
+        resolvedAt: ticket.resolvedAt,
+    };
+}
+function matchesQuery(entry, query) {
+    const haystack = [entry.title, entry.problem, entry.resolution, entry.tags.join(" ")]
+        .join(" ")
+        .toLowerCase();
+    return query
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean)
+        .every((term) => haystack.includes(term));
+}
+/**
+ * Resolution-knowledge corpus (ported concept from Inti's resolution knowledge):
+ * the reusable record of how each resolved ticket was fixed, so an agent facing
+ * a new ticket can retrieve prior art by family/kind/source/tag/free text.
+ *
+ * Pure and deterministic apart from `generatedAt`. Newest resolutions first.
+ */
+function resolutionKnowledge(tickets, options = {}) {
+    const corpus = tickets
+        .filter((ticket) => ticket.status === "resolved" && hasText(ticket.resolutionSummary))
+        .map(toEntry);
+    let entries = corpus;
+    if (options.family)
+        entries = entries.filter((entry) => entry.family === options.family);
+    if (options.kind)
+        entries = entries.filter((entry) => entry.kind === options.kind);
+    if (options.source)
+        entries = entries.filter((entry) => entry.source === options.source);
+    if (options.tag)
+        entries = entries.filter((entry) => entry.tags.includes(options.tag));
+    if (hasText(options.query)) {
+        entries = entries.filter((entry) => matchesQuery(entry, options.query));
+    }
+    entries = [...entries].sort((a, b) => (b.resolvedAt ?? "").localeCompare(a.resolvedAt ?? "") || a.id.localeCompare(b.id));
+    const matched = entries.length;
+    if (typeof options.limit === "number" && options.limit >= 0) {
+        entries = entries.slice(0, options.limit);
+    }
+    return {
+        schemaVersion: exports.KNOWLEDGE_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        filters: {
+            family: options.family ?? null,
+            kind: options.kind ?? null,
+            source: options.source ?? null,
+            tag: options.tag ?? null,
+            query: hasText(options.query) ? options.query : null,
+        },
+        summary: {
+            resolvedWithKnowledge: corpus.length,
+            verified: corpus.filter((entry) => entry.verified).length,
+            matched,
+        },
+        entries,
+    };
+}
+/**
+ * Resolved tickets whose knowledge is incomplete for reuse: missing a resolution
+ * summary, or resolved without verification evidence. The contracts doc's
+ * `knowledge-gaps` cleanup backlog, scoped by family/severity/source.
+ *
+ * Pure and deterministic apart from `generatedAt`.
+ */
+function knowledgeGaps(tickets, options = {}) {
+    const resolved = tickets.filter((ticket) => {
+        if (ticket.status !== "resolved")
+            return false;
+        if (options.family && ticket.family !== options.family)
+            return false;
+        if (options.severity && ticket.severity !== options.severity)
+            return false;
+        if (options.source && ticket.source !== options.source)
+            return false;
+        return true;
+    });
+    let complete = 0;
+    let noResolution = 0;
+    let unverified = 0;
+    const gaps = [];
+    for (const ticket of resolved) {
+        const resolution = hasText(ticket.resolutionSummary);
+        const verification = hasText(ticket.verification);
+        if (resolution && verification) {
+            complete += 1;
+            continue;
+        }
+        const reason = resolution ? "unverified" : "no_resolution";
+        if (reason === "unverified")
+            unverified += 1;
+        else
+            noResolution += 1;
+        gaps.push({
+            id: ticket.id,
+            alias: ticket.aliases[0] ?? ticket.id,
+            kind: ticket.kind,
+            source: ticket.source,
+            family: ticket.family,
+            severity: ticket.severity,
+            title: ticket.title,
+            reason,
+            resolvedAt: ticket.resolvedAt,
+        });
+    }
+    gaps.sort((a, b) => {
+        if (a.reason !== b.reason)
+            return a.reason === "no_resolution" ? -1 : 1;
+        return a.id.localeCompare(b.id);
+    });
+    return {
+        schemaVersion: exports.KNOWLEDGE_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        filters: {
+            family: options.family ?? null,
+            severity: options.severity ?? null,
+            source: options.source ?? null,
+        },
+        summary: {
+            resolved: resolved.length,
+            complete,
+            gaps: gaps.length,
+            noResolution,
+            unverified,
+        },
+        gaps,
+    };
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/mcp.d.ts

@@ -0,0 +1,130 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AgentLoopStore } from "./store";
+import { StateBackend } from "./backend";
+import { Confidence, GuardStatus, NoteType, Pattern, ProjectConfig, Severity, Ticket } from "./types";
+/**
+ * Schema version for the MCP tool envelopes. Bump only on breaking changes;
+ * add fields freely during dogfood (see docs/tickets agent JSON contracts).
+ */
+export declare const MCP_SCHEMA_VERSION: 1;
+export declare const MCP_SERVER_NAME = "agentloop";
+interface Envelope {
+    schemaVersion: typeof MCP_SCHEMA_VERSION;
+    generatedAt: string;
+}
+export interface SummaryResult extends Envelope {
+    summary: Awaited<ReturnType<AgentLoopStore["summary"]>>;
+}
+export interface ListResult extends Envelope {
+    filters: {
+        status: string;
+        kind: string | null;
+    };
+    count: number;
+    tickets: Ticket[];
+}
+export interface ShowTicketResult extends Envelope {
+    kind: "ticket";
+    ticket: Ticket;
+}
+export interface ShowPatternResult extends Envelope {
+    kind: "pattern";
+    pattern: Pattern;
+}
+export type ShowResult = ShowTicketResult | ShowPatternResult;
+export interface HandoffResult extends Envelope {
+    ticketId: string;
+    aliases: string[];
+    prompt: string;
+}
+/**
+ * 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.
+ */
+export declare function summaryTool(store: AgentLoopStore): Promise<SummaryResult>;
+export declare function listTool(store: AgentLoopStore, args?: {
+    status?: string;
+    kind?: string;
+}): Promise<ListResult>;
+export declare function showTool(store: AgentLoopStore, args: {
+    id: string;
+}): Promise<ShowResult>;
+export declare function handoffTool(store: AgentLoopStore, args: {
+    id: string;
+}): Promise<HandoffResult>;
+/**
+ * Write tools (opt-in via `allowWrites`). These mutate the ledger and are
+ * disabled by default; an agent gets the read-only surface unless the operator
+ * explicitly enables writes.
+ */
+export type WriteAction = "created" | "noted" | "workflow" | "resolved" | "guard";
+export interface WriteResult extends Envelope {
+    action: WriteAction;
+    ticket: Ticket;
+}
+export declare const SEVERITIES: readonly ["low", "medium", "high", "critical"];
+export declare const CONFIDENCES: readonly ["low", "medium", "high"];
+export declare const NOTE_TYPES: readonly ["hypothesis", "related_history", "prior_fix", "triage", "investigation"];
+export declare const GUARD_STATUSES: readonly ["guard_added", "guard_existing", "guard_waived", "guard_deferred", "none"];
+/** Workflow transitions exposed over MCP. `resolved` has its own tool. */
+export declare const WORKFLOW_STATUSES: readonly ["active", "reopened", "deferred"];
+/** Source recorded for tickets/notes created by an MCP agent client. */
+export declare const MCP_ACTOR_SOURCE = "agent";
+export declare function createTicketTool(store: AgentLoopStore, args: {
+    summary: string;
+    title?: string;
+    family?: string;
+    kind?: string;
+    source?: string;
+    severity?: Severity;
+    confidence?: Confidence;
+    tags?: string[];
+    handoff?: string;
+}): Promise<WriteResult>;
+export declare function noteTool(store: AgentLoopStore, args: {
+    id: string;
+    body: string;
+    type?: NoteType;
+    author?: string;
+}): Promise<WriteResult>;
+export declare function workflowTool(store: AgentLoopStore, args: {
+    id: string;
+    status: (typeof WORKFLOW_STATUSES)[number];
+    reason?: string;
+}): Promise<WriteResult>;
+export declare function resolveTool(store: AgentLoopStore, args: {
+    id: string;
+    summary: string;
+    verification?: string;
+    guardStatus?: GuardStatus;
+    guardSummary?: string;
+}): Promise<WriteResult>;
+export declare function guardTool(store: AgentLoopStore, args: {
+    id: string;
+    guardStatus: GuardStatus;
+    guardSummary?: string;
+}): Promise<WriteResult>;
+export interface CreateMcpServerOptions {
+    version?: string;
+    /** Register the mutating write tools. Off by default (read-only surface). */
+    allowWrites?: boolean;
+}
+/**
+ * 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).
+ */
+export declare function createMcpServer(store: AgentLoopStore, options?: CreateMcpServerOptions): McpServer;
+/**
+ * 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.
+ */
+export declare function startStdioMcpServer(opts: {
+    cwd: string;
+    config: ProjectConfig;
+    version?: string;
+    allowWrites?: boolean;
+    backend?: StateBackend;
+}): Promise<void>;
+export {};