@kya-os/cli 1.8.1 → 1.8.3

package/dist/orchestrator/journal-writer.js

@@ -0,0 +1,113 @@
+/**
+ * Journal writer (ORC-W1 PR-2).
+ *
+ * Turns hub events into ledger rows. This is the piece that makes the journal
+ * evidence rather than narration: rows land because a verified protocol event
+ * arrived, not because a model chose to record one.
+ *
+ * @module orchestrator/journal-writer
+ */
+import { appendJournal } from "./db/journal.js";
+import { findTicketIdByTaskId, findTicketIdByPr } from "./db/dispatches.js";
+/**
+ * Pull a task id out of an event's untyped `data` bag.
+ *
+ * `data` is `Record<string, unknown>` on the wire, so this narrows rather than
+ * casting. Anything that is not a non-empty string is treated as absent, which
+ * is the honest reading: a malformed taskId must not be used to look up a
+ * ticket and silently attach an observation to the wrong one.
+ */
+export function taskIdOf(event) {
+    const raw = (event.data ?? {})["taskId"];
+    return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+/**
+ * Persist one event.
+ *
+ * Correlates to a ticket through `dispatches` when the event names a task this
+ * orchestrator dispatched. When it does not, the row is still written with a
+ * null ticket, because an uncorrelated observation is worth more than no
+ * observation and guessing at a ticket would be worse than either.
+ *
+ * Returns true when the row was new (false means it was a replay).
+ */
+export function writeEvent(db, event) {
+    return appendJournal(db, { event, ticketId: ticketIdForEvent(db, event) });
+}
+/**
+ * Read a review event's subject out of its untyped `data` bag.
+ *
+ * All three fields or nothing. A verdict missing part of its subject cannot be
+ * attributed, and attributing it to the wrong ticket is worse than leaving the
+ * row uncorrelated.
+ */
+export function reviewSubjectOf(event) {
+    const data = event.data ?? {};
+    const repo = data["repo"];
+    const prNumber = data["prNumber"];
+    const headSha = data["headSha"];
+    if (typeof repo !== "string" || repo.length === 0)
+        return null;
+    // Number.isInteger rejects NaN, Infinity and floats. A bad PR number would
+    // match no dispatch, which reads as "not ours" rather than as bad input.
+    if (typeof prNumber !== "number" || !Number.isInteger(prNumber) || prNumber <= 0)
+        return null;
+    if (typeof headSha !== "string" || headSha.length === 0)
+        return null;
+    return { repo, prNumber, headSha };
+}
+/**
+ * Resolve the ticket an event concerns: task id first, pull request second.
+ *
+ * Task id is exact where present. PR correlation is the fallback and the ONLY
+ * option for `pr_quorum_reached`, which carries no task id -- so before this
+ * existed every quorum event journalled with a null ticket, and the Review lens
+ * could show that something reached quorum but never which ticket it was for.
+ */
+export function ticketIdForEvent(db, event) {
+    const taskId = taskIdOf(event);
+    if (taskId) {
+        const byTask = findTicketIdByTaskId(db, taskId);
+        if (byTask)
+            return byTask;
+    }
+    const subject = reviewSubjectOf(event);
+    return subject ? findTicketIdByPr(db, subject.repo, subject.prNumber) : null;
+}
+/**
+ * Subscribe to the hub and journal everything it emits.
+ *
+ * Returns the unsubscribe, matching the hub's own `onEvent` contract, so the
+ * daemon can detach cleanly on shutdown instead of leaking a handler that
+ * writes to a closed database.
+ *
+ * Deliberately does NOT catch a write failure here. Every real dispatcher
+ * this attaches to -- the hub's own emit loop, `HubObserver.dispatch()` --
+ * already isolates one handler's failure from its siblings and from itself,
+ * so catching AGAIN in here just hides the failure from that dispatcher: a
+ * reconnect's replay retries a write only if it can tell the write failed,
+ * and a handler that always reports success by swallowing its own errors
+ * makes that retry permanently dead code (review finding on #686).
+ */
+export function registerJournalWriter(db, hub) {
+    return hub.onEvent((event) => {
+        writeEvent(db, event);
+    });
+}
+/**
+ * Replay the hub's recent-event window into the journal.
+ *
+ * Called once on boot so a daemon restart recovers what it slept through.
+ * Idempotent by construction: journal ids are derived from event content, so
+ * an event already recorded live is ignored rather than duplicated. Returns
+ * how many rows were genuinely new.
+ */
+export function reconcileRecentEvents(db, hub, limit = 50) {
+    let added = 0;
+    for (const event of hub.getRecentEvents(limit)) {
+        if (writeEvent(db, event))
+            added += 1;
+    }
+    return added;
+}
+//# sourceMappingURL=journal-writer.js.map

package/dist/orchestrator/journal-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-writer.js","sourceRoot":"","sources":["../../src/orchestrator/journal-writer.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/mcp/server.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Ledger MCP server.
+ *
+ * The orchestrator session's tool surface. This is the boundary that makes
+ * approach C work: the daemon owns anything whose correctness a test can
+ * check, and the session owns anything whose correctness requires an opinion.
+ * Every tool here enforces its invariant in SQL, so a model cannot reason its
+ * way past one.
+ *
+ * Two absences are load-bearing:
+ *
+ *   - There is NO tool that creates a Linear issue, and none by which the
+ *     SESSION can create a ticket. That is about the session specifically: the
+ *     ledger does hold agent-native tickets (linear_id NULL), and the daemon
+ *     writes those deterministically from protocol events. What must not exist
+ *     is a path by which a model decides, on its own reading of a situation,
+ *     that some new work exists. A finding it wants to raise goes in the
+ *     journal, and a human promotes it. Without this absence that policy would
+ *     be a sentence in a prompt instead of a property of the surface.
+ *   - There is NO tool that sets the mission note. Reading it is the point;
+ *     writing it is the operator's. A session that can rewrite its own standing
+ *     objective is not following one, and would drift toward whatever it last
+ *     found interesting.
+ *   - There is NO delete tool, for the same reason the store has no delete
+ *     path: a bad autonomous close and a clean backlog are indistinguishable
+ *     once the row is gone.
+ *
+ * JSON-RPC 2.0 is hand-rolled rather than pulled from the MCP SDK, matching
+ * `fleet-mcp.ts` in @kya-os/compute. It keeps a dependency out of a published
+ * CLI for what amounts to a switch statement.
+ *
+ * @module cli/orchestrator/mcp/server
+ */
+import type { Ledger } from "../db/index.js";
+import { SettableTicketStatusSchema, SETTABLE_TICKET_STATUSES, type SettableTicketStatus } from "../db/tickets.js";
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id?: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * The MCP revision this server speaks.
+ *
+ * Named rather than inlined in the handshake response, so the version this
+ * server actually implements is greppable and changes in one place. Deliberately
+ * NOT echoed back from the client's request: the handshake exists for the client
+ * to discover what the server supports, and reflecting whatever it asked for
+ * would claim support for revisions this code has never been tested against,
+ * turning the one honest signal in the exchange into a mirror.
+ */
+export declare const MCP_PROTOCOL_VERSION = "2025-03-26";
+/**
+ * Row cap shared by every list tool.
+ *
+ * journal.list capped and the others did not, which contradicted this file's own
+ * reason for capping: a model must not be able to ask for the whole table. The
+ * cap is uniform so the reason applies uniformly.
+ */
+export declare const MAX_ROWS = 500;
+/** Serialised size limit for a session-written journal payload. */
+export declare const MAX_EVENT_DATA_BYTES = 8000;
+/** Size limit for a session-written event type. */
+export declare const MAX_EVENT_TYPE_BYTES = 120;
+/**
+ * Length limit for a ticket id arriving from the session.
+ *
+ * Generous next to the ids this ledger mints (a UUID is 36 characters), because
+ * its job is to refuse the absurd, not to second-guess the id format.
+ */
+export declare const MAX_TICKET_ID_LENGTH = 200;
+/**
+ * Force a session-authored event into its own namespace.
+ *
+ * Idempotent, so a caller that already prefixes does not end up with
+ * `session.session.x`.
+ */
+export declare function sessionEventType(raw: string): string;
+/**
+ * The statuses this surface may SET.
+ *
+ * `claimed` and `closed` each have a dedicated tool that carries something a
+ * bare status write cannot: an atomic claim, and a recorded close reason.
+ *
+ * The definition itself now lives in the store, which is the layer that has to
+ * hold the line for callers that never pass through this file. Re-exported here
+ * so the advertised JSON Schema, the Zod enforcement and the store's own guard
+ * are provably the same list -- they used to be written twice, with Zod holding
+ * the real enum while the advertised schema said `{ type: "string" }`, so the
+ * model learned the actual constraint only by guessing and reading the error
+ * back.
+ */
+export { SettableTicketStatusSchema, SETTABLE_TICKET_STATUSES, type SettableTicketStatus };
+export declare const TICKET_STATUSES: ["open", "claimed", "in-progress", "in-review", "blocked", "ready", "closed"];
+/** Namespace for anything the orchestrator session writes to the journal. */
+export declare const SESSION_EVENT_PREFIX = "session.";
+/**
+ * The payload a session-authored journal row actually stores.
+ *
+ * One definition, shared by the schema that bounds it and the handler that
+ * writes it. Two copies of this composition is precisely how the size limit
+ * came to guard a value that was not the one being written.
+ */
+export declare function sessionEventPayload(data: Record<string, unknown>, note?: string): Record<string, unknown>;
+export declare const LEDGER_TOOLS: ToolDefinition[];
+/**
+ * Run one tool against the ledger.
+ *
+ * Exported separately from the RPC plumbing so tests exercise the tool
+ * semantics without speaking JSON-RPC, and so the invariants are testable in
+ * isolation from the transport.
+ */
+export declare function callLedgerTool(db: Ledger, name: string, rawArgs: unknown): unknown;
+/**
+ * Handle one JSON-RPC request.
+ *
+ * Errors become JSON-RPC errors rather than thrown exceptions, because a
+ * thrown error here kills the stdio loop and takes every subsequent tool call
+ * with it. A tool that fails should fail one call.
+ */
+export declare function handleLedgerRpc(db: Ledger, req: JsonRpcRequest): JsonRpcResponse | null;
+//# sourceMappingURL=server.d.ts.map

package/dist/orchestrator/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAOL,0BAA0B,EAC1B,wBAAwB,EACxB,KAAK,oBAAoB,EAG1B,MAAM,kBAAkB,CAAC;AAM1B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,MAAM,CAAC;AAE5B,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,mDAAmD;AACnD,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,KAAK,oBAAoB,EAAE,CAAC;AAC3F,eAAO,MAAM,eAAe,+EAA6B,CAAC;AAE1D,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,aAAa,CAAC;AA8D/C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AA8FD,eAAO,MAAM,YAAY,EAAE,cAAc,EA+IxC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CA2GlF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,eAAe,GAAG,IAAI,CAiFvF"}