@flyingrobots/graft 0.7.0 → 0.7.1

package/src/mcp/receipt.ts

@@ -1,201 +0,0 @@
-// ---------------------------------------------------------------------------
-// Receipt builder — attaches decision metadata to every tool response
-// ---------------------------------------------------------------------------
-
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { MetricsSnapshot } from "./metrics.js";
-import type { Tripwire } from "../session/types.js";
-import type { JsonCodec } from "../ports/codec.js";
-import { attachMcpSchemaMeta, type McpToolName } from "../contracts/output-schemas.js";
-import {
-  burdenKindForTool,
-  isNonReadBurdenKind,
-  projectBurdenByKind,
-  totalNonReadBytesReturned,
-  type BurdenByKind,
-  type BurdenKind,
-} from "./burden.js";
-
-export type McpToolResult = CallToolResult;
-
-export interface ReceiptBudget {
-  readonly total: number;
-  readonly consumed: number;
-  readonly remaining: number;
-  readonly fraction: number;
-}
-
-export interface ReceiptCumulative {
-  readonly reads: number;
-  readonly outlines: number;
-  readonly refusals: number;
-  readonly cacheHits: number;
-  readonly bytesReturned: number;
-  readonly bytesAvoided: number;
-  readonly nonReadBytesReturned: number;
-  readonly burdenByKind: Readonly<BurdenByKind>;
-}
-
-export interface ReceiptBurden {
-  readonly kind: BurdenKind;
-  readonly nonRead: boolean;
-}
-
-export interface McpToolReceipt {
-  readonly sessionId: string;
-  readonly traceId: string;
-  readonly seq: number;
-  readonly ts: string;
-  readonly tool: McpToolName;
-  readonly projection: string;
-  readonly reason: string;
-  readonly latencyMs: number;
-  readonly fileBytes: number | null;
-  readonly returnedBytes: number;
-  readonly burden: ReceiptBurden;
-  readonly cumulative: ReceiptCumulative;
-  readonly budget?: ReceiptBudget;
-  readonly compressionRatio?: number | null;
-}
-
-export interface ReceiptDeps {
-  readonly sessionId: string;
-  readonly traceId: string;
-  readonly seq: number;
-  readonly latencyMs: number;
-  readonly metrics: MetricsSnapshot;
-  readonly tripwires: Tripwire[];
-  readonly codec: JsonCodec;
-  readonly budget?: ReceiptBudget | null;
-}
-
-/** Mutable draft used internally during the size-stabilization loop. */
-interface ReceiptDraft {
-  sessionId: string;
-  traceId: string;
-  seq: number;
-  ts: string;
-  tool: McpToolName;
-  projection: string;
-  reason: string;
-  latencyMs: number;
-  fileBytes: number | null;
-  returnedBytes: number;
-  burden: ReceiptBurden;
-  cumulative: {
-    reads: number;
-    outlines: number;
-    refusals: number;
-    cacheHits: number;
-    bytesReturned: number;
-    bytesAvoided: number;
-    nonReadBytesReturned: number;
-    burdenByKind: Readonly<BurdenByKind>;
-  };
-  budget?: ReceiptBudget;
-  compressionRatio?: number | null;
-}
-
-function extractProjection(data: Record<string, unknown>): string {
-  if (typeof data["projection"] === "string") return data["projection"];
-  return "none";
-}
-
-function extractReason(data: Record<string, unknown>): string {
-  if (typeof data["reason"] === "string") return data["reason"];
-  return "none";
-}
-
-function extractFileBytes(data: Record<string, unknown>): number | null {
-  const actual = data["actual"];
-  if (actual !== null && typeof actual === "object" && "bytes" in actual) {
-    const bytes = (actual as { bytes: unknown }).bytes;
-    if (typeof bytes === "number") return bytes;
-  }
-  return null;
-}
-
-function freezeReceipt(draft: ReceiptDraft): McpToolReceipt {
-  Object.freeze(draft.burden);
-  Object.freeze(draft.cumulative);
-  Object.freeze(draft);
-  return draft as McpToolReceipt;
-}
-
-/**
- * Build a tool response with an attached receipt.
- * Returns the finalized MCP result and the byte count of the serialized text
- * so the caller can feed it back into cumulative metrics.
- */
-export function buildReceiptResult(
-  tool: McpToolName,
-  data: Record<string, unknown>,
-  deps: ReceiptDeps,
-): { result: McpToolResult; textBytes: number; receipt: McpToolReceipt } {
-  const burdenKind = burdenKindForTool(tool);
-
-  const draft: ReceiptDraft = {
-    sessionId: deps.sessionId,
-    traceId: deps.traceId,
-    seq: deps.seq,
-    ts: new Date().toISOString(),
-    tool,
-    projection: extractProjection(data),
-    reason: extractReason(data),
-    latencyMs: deps.latencyMs,
-    fileBytes: extractFileBytes(data),
-    returnedBytes: 0,
-    burden: {
-      kind: burdenKind,
-      nonRead: isNonReadBurdenKind(burdenKind),
-    },
-    cumulative: {
-      reads: deps.metrics.reads,
-      outlines: deps.metrics.outlines,
-      refusals: deps.metrics.refusals,
-      cacheHits: deps.metrics.cacheHits,
-      bytesReturned: 0,
-      bytesAvoided: deps.metrics.bytesAvoided,
-      nonReadBytesReturned: totalNonReadBytesReturned(deps.metrics.burdenByKind),
-      burdenByKind: deps.metrics.burdenByKind,
-    },
-  };
-
-  if (deps.budget != null) {
-    draft.budget = deps.budget;
-  }
-
-  const fullData: Record<string, unknown> & { tripwire?: Tripwire[] } = attachMcpSchemaMeta(tool, {
-    ...data,
-    _receipt: draft,
-  });
-  if (deps.tripwires.length > 0) {
-    fullData.tripwire = deps.tripwires;
-  }
-
-  // Stabilize self-referential size fields (use UTF-8 byte length, not char count)
-  let prev = 0;
-  let text = "";
-  for (let i = 0; i < 5; i++) {
-    text = deps.codec.encode(fullData);
-    const byteLen = Buffer.byteLength(text, "utf8");
-    if (byteLen === prev) break;
-    prev = byteLen;
-    draft.returnedBytes = byteLen;
-    const burdenByKind = projectBurdenByKind(deps.metrics.burdenByKind, tool, byteLen);
-    draft.compressionRatio = draft.fileBytes !== null && draft.fileBytes > 0
-      ? Math.round((byteLen / draft.fileBytes) * 1000) / 1000
-      : null;
-    draft.cumulative.bytesReturned = deps.metrics.bytesReturned + byteLen;
-    draft.cumulative.nonReadBytesReturned = totalNonReadBytesReturned(burdenByKind);
-    draft.cumulative.burdenByKind = burdenByKind;
-  }
-
-  const receipt = freezeReceipt(draft);
-
-  return {
-    result: { content: [{ type: "text", text }] },
-    textBytes: Buffer.byteLength(text, "utf8"),
-    receipt,
-  };
-}

package/src/mcp/repo-concurrency.ts

@@ -1,392 +0,0 @@
-import type {
-  AttributionSummary,
-  CausalEvent,
-  RepoConcurrencyAuthority,
-  RepoConcurrencyPosture,
-} from "../contracts/causal-ontology.js";
-
-export interface RepoConcurrencyTouch {
-  readonly contributorKey: string;
-  readonly path: string;
-}
-
-export interface RepoConcurrencyWorktreeHistory {
-  readonly worktreeId: string;
-  readonly active: boolean;
-  readonly checkoutEpochId: string | null;
-  readonly causalSessionIds: readonly string[];
-  readonly actorIds: readonly string[];
-  readonly contributorKeys: readonly string[];
-  readonly explicitHandoff: boolean;
-  readonly touches: readonly RepoConcurrencyTouch[];
-}
-
-export interface RepoConcurrencySummary {
-  readonly posture: RepoConcurrencyPosture;
-  readonly authority: RepoConcurrencyAuthority;
-  readonly observedWorktreeCount: number;
-  readonly observedCausalSessionCount: number;
-  readonly observedActorCount: number;
-  readonly overlappingPathCount: number;
-  readonly summary: string;
-  readonly daemonSessionLiveness?: RepoConcurrencyDaemonSessionLiveness;
-}
-
-export interface RepoConcurrencyDaemonSessionLiveness {
-  readonly idleTimeoutMs: number;
-  readonly liveSessionCount: number;
-  readonly staleSessionCount: number;
-}
-
-interface RepoConcurrencyInput {
-  readonly currentWorktreeId: string;
-  readonly histories: readonly RepoConcurrencyWorktreeHistory[];
-}
-
-export interface RepoConcurrencyLiveSession {
-  readonly bindState: "bound" | "unbound";
-  readonly repoId: string | null;
-  readonly worktreeId: string | null;
-  readonly causalSessionId: string | null;
-  readonly checkoutEpochId: string | null;
-  readonly lastActivityAt: string;
-}
-
-export const DEFAULT_DAEMON_SESSION_IDLE_TIMEOUT_MS = 5 * 60 * 1000;
-
-function countOverlapPaths(touches: readonly RepoConcurrencyTouch[]): number {
-  const contributorsByPath = new Map<string, Set<string>>();
-  for (const touch of touches) {
-    const existing = contributorsByPath.get(touch.path) ?? new Set<string>();
-    existing.add(touch.contributorKey);
-    contributorsByPath.set(touch.path, existing);
-  }
-
-  let count = 0;
-  for (const contributors of contributorsByPath.values()) {
-    if (contributors.size > 1) {
-      count += 1;
-    }
-  }
-  return count;
-}
-
-function buildSummary(
-  posture: RepoConcurrencyPosture,
-  authority: RepoConcurrencyAuthority,
-  observedWorktreeCount: number,
-  observedCausalSessionCount: number,
-  observedActorCount: number,
-  overlappingPathCount: number,
-  summary: string,
-): RepoConcurrencySummary {
-  return {
-    posture,
-    authority,
-    observedWorktreeCount,
-    observedCausalSessionCount,
-    observedActorCount,
-    overlappingPathCount,
-    summary,
-  };
-}
-
-function withObservedCounts(
-  summary: RepoConcurrencySummary,
-  input: {
-    readonly observedWorktreeCount: number;
-    readonly observedCausalSessionCount: number;
-    readonly observedActorCount: number;
-  },
-): RepoConcurrencySummary {
-  return {
-    ...summary,
-    observedWorktreeCount: Math.max(summary.observedWorktreeCount, input.observedWorktreeCount),
-    observedCausalSessionCount: Math.max(summary.observedCausalSessionCount, input.observedCausalSessionCount),
-    observedActorCount: Math.max(summary.observedActorCount, input.observedActorCount),
-  };
-}
-
-function formatDurationMs(durationMs: number): string {
-  if (durationMs % 60000 === 0) {
-    const minutes = durationMs / 60000;
-    return `${String(minutes)} minute${minutes === 1 ? "" : "s"}`;
-  }
-  if (durationMs % 1000 === 0) {
-    const seconds = durationMs / 1000;
-    return `${String(seconds)} second${seconds === 1 ? "" : "s"}`;
-  }
-  return `${String(durationMs)} ms`;
-}
-
-function appendStaleDaemonSessionSummary(
-  summary: string,
-  liveness: RepoConcurrencyDaemonSessionLiveness,
-): string {
-  if (liveness.staleSessionCount === 0) {
-    return summary;
-  }
-  const noun = liveness.staleSessionCount === 1 ? "session" : "sessions";
-  return `${summary} Excluded ${String(liveness.staleSessionCount)} stale daemon ${noun} idle for longer than ${formatDurationMs(liveness.idleTimeoutMs)}.`;
-}
-
-function withDaemonSessionLiveness(
-  summary: RepoConcurrencySummary,
-  liveness: RepoConcurrencyDaemonSessionLiveness,
-): RepoConcurrencySummary {
-  return {
-    ...summary,
-    summary: appendStaleDaemonSessionSummary(summary.summary, liveness),
-    daemonSessionLiveness: liveness,
-  };
-}
-
-function isStaleDaemonSession(
-  session: RepoConcurrencyLiveSession,
-  nowMs: number,
-  idleTimeoutMs: number,
-): boolean {
-  const lastActivityMs = Date.parse(session.lastActivityAt);
-  if (!Number.isFinite(lastActivityMs)) {
-    return true;
-  }
-  return nowMs - lastActivityMs > idleTimeoutMs;
-}
-
-export function deriveRepoConcurrencySummary(input: RepoConcurrencyInput): RepoConcurrencySummary {
-  const activeHistories = input.histories.filter((history) => history.active);
-  const current = activeHistories.find((history) => history.worktreeId === input.currentWorktreeId)
-    ?? input.histories.find((history) => history.worktreeId === input.currentWorktreeId)
-    ?? null;
-
-  if (current === null) {
-    return buildSummary(
-      "unknown",
-      "unknown",
-      0,
-      0,
-      0,
-      0,
-      "No lawful same-repo concurrency evidence is available for the current worktree.",
-    );
-  }
-
-  const observedWorktreeCount = Math.max(1, new Set(activeHistories.map((history) => history.worktreeId)).size);
-  const observedCausalSessionCount = new Set(
-    activeHistories.flatMap((history) => history.causalSessionIds),
-  ).size;
-  const observedActorCount = new Set(
-    activeHistories.flatMap((history) => history.actorIds),
-  ).size;
-  const overlappingPathCount = countOverlapPaths(current.touches);
-  const otherActiveWorktrees = activeHistories.filter((history) => history.worktreeId !== current.worktreeId);
-
-  if (otherActiveWorktrees.some((history) =>
-    history.checkoutEpochId !== null &&
-    current.checkoutEpochId !== null &&
-    history.checkoutEpochId !== current.checkoutEpochId
-  )) {
-    return buildSummary(
-      "divergent_checkout",
-      "active_history_scan",
-      observedWorktreeCount,
-      observedCausalSessionCount,
-      observedActorCount,
-      overlappingPathCount,
-      "Active same-repo work appears to be split across different checkout epochs or branches.",
-    );
-  }
-
-  if (current.contributorKeys.length > 1 && overlappingPathCount > 0 && !current.explicitHandoff) {
-    return buildSummary(
-      "overlapping_actors",
-      "footprint_overlap",
-      observedWorktreeCount,
-      observedCausalSessionCount,
-      observedActorCount,
-      overlappingPathCount,
-      "Multiple contributors appear to touch overlapping paths in the same live worktree without explicit handoff evidence.",
-    );
-  }
-
-  if (current.explicitHandoff && current.contributorKeys.length > 1 && otherActiveWorktrees.length === 0) {
-    return buildSummary(
-      "exclusive",
-      "explicit_handoff",
-      observedWorktreeCount,
-      observedCausalSessionCount,
-      observedActorCount,
-      overlappingPathCount,
-      "Explicit attach or handoff evidence keeps the current live worktree on one lawful line of work.",
-    );
-  }
-
-  if (current.contributorKeys.length > 1) {
-    return buildSummary(
-      "shared_worktree",
-      "active_history_scan",
-      observedWorktreeCount,
-      observedCausalSessionCount,
-      observedActorCount,
-      overlappingPathCount,
-      "Multiple contributors have been observed on the current live worktree, so ownership stays shared rather than exclusive.",
-    );
-  }
-
-  if (otherActiveWorktrees.length > 0) {
-    return buildSummary(
-      "shared_repo_only",
-      "repo_identity_only",
-      observedWorktreeCount,
-      observedCausalSessionCount,
-      observedActorCount,
-      overlappingPathCount,
-      "Other active worktrees share the same canonical repo identity, but not this live worktree footing.",
-    );
-  }
-
-  return buildSummary(
-    "exclusive",
-    "active_history_scan",
-    observedWorktreeCount,
-    observedCausalSessionCount,
-    observedActorCount,
-    overlappingPathCount,
-    "No other active same-repo worktree or overlapping actor evidence is currently visible.",
-  );
-}
-
-export function mergeRepoConcurrencySummaryWithLiveSessions(input: {
-  readonly currentSummary: RepoConcurrencySummary;
-  readonly currentRepoId: string;
-  readonly currentWorktreeId: string;
-  readonly currentCheckoutEpochId: string | null;
-  readonly sessions: readonly RepoConcurrencyLiveSession[];
-  readonly nowMs?: number;
-  readonly sessionIdleTimeoutMs?: number;
-}): RepoConcurrencySummary {
-  const repoSessions = input.sessions.filter((session) =>
-    session.bindState === "bound" &&
-    session.repoId === input.currentRepoId &&
-    session.worktreeId !== null
-  );
-
-  if (repoSessions.length === 0) {
-    return input.currentSummary;
-  }
-
-  const nowMs = input.nowMs ?? Date.now();
-  const idleTimeoutMs = input.sessionIdleTimeoutMs ?? DEFAULT_DAEMON_SESSION_IDLE_TIMEOUT_MS;
-  const liveRepoSessions = repoSessions.filter((session) => !isStaleDaemonSession(session, nowMs, idleTimeoutMs));
-  const liveness: RepoConcurrencyDaemonSessionLiveness = {
-    idleTimeoutMs,
-    liveSessionCount: liveRepoSessions.length,
-    staleSessionCount: repoSessions.length - liveRepoSessions.length,
-  };
-
-  if (liveRepoSessions.length === 0) {
-    return withDaemonSessionLiveness(input.currentSummary, liveness);
-  }
-
-  const observedWorktreeCount = new Set(liveRepoSessions.map((session) => session.worktreeId)).size;
-  const observedCausalSessionCount = new Set(
-    liveRepoSessions
-      .map((session) => session.causalSessionId)
-      .filter((sessionId): sessionId is string => sessionId !== null),
-  ).size;
-  const summaryWithCounts = withDaemonSessionLiveness(
-    withObservedCounts(input.currentSummary, {
-      observedWorktreeCount: Math.max(1, observedWorktreeCount),
-      observedCausalSessionCount,
-      observedActorCount: input.currentSummary.observedActorCount,
-    }),
-    liveness,
-  );
-
-  const currentWorktreeSessions = liveRepoSessions.filter((session) => session.worktreeId === input.currentWorktreeId);
-  const otherWorktreeSessions = liveRepoSessions.filter((session) => session.worktreeId !== input.currentWorktreeId);
-
-  if (
-    otherWorktreeSessions.some((session) =>
-      session.checkoutEpochId !== null &&
-      input.currentCheckoutEpochId !== null &&
-      session.checkoutEpochId !== input.currentCheckoutEpochId
-    )
-  ) {
-    return {
-      ...summaryWithCounts,
-      posture: "divergent_checkout",
-      authority: "daemon_live_sessions",
-      summary: "Active same-repo daemon sessions are split across different checkout epochs or branches.",
-    };
-  }
-
-  if (summaryWithCounts.posture === "overlapping_actors") {
-    return summaryWithCounts;
-  }
-
-  if (currentWorktreeSessions.length > 1) {
-    if (
-      summaryWithCounts.posture === "exclusive" &&
-      summaryWithCounts.authority === "explicit_handoff" &&
-      otherWorktreeSessions.length === 0
-    ) {
-      return summaryWithCounts;
-    }
-    return {
-      ...summaryWithCounts,
-      posture: "shared_worktree",
-      authority: "daemon_live_sessions",
-      summary:
-        "Multiple active daemon sessions share the current live worktree, so ownership stays shared rather than exclusive.",
-    };
-  }
-
-  if (otherWorktreeSessions.length > 0) {
-    return {
-      ...summaryWithCounts,
-      posture: "shared_repo_only",
-      authority: "daemon_live_sessions",
-      summary: "Other active daemon sessions share the same canonical repo identity, but not this live worktree footing.",
-    };
-  }
-
-  return summaryWithCounts;
-}
-
-export function buildRepoConcurrencyContributorKey(input: {
-  readonly actorId: string | null;
-  readonly attribution: AttributionSummary;
-  readonly causalSessionId: string | null;
-  readonly transportSessionId: string | null;
-}): string | null {
-  if (input.actorId !== null && input.attribution.actor.actorKind !== "unknown") {
-    return `actor:${input.actorId}`;
-  }
-  if (input.causalSessionId !== null) {
-    return `causal:${input.causalSessionId}`;
-  }
-  if (input.transportSessionId !== null) {
-    return `transport:${input.transportSessionId}`;
-  }
-  return null;
-}
-
-export function buildRepoConcurrencyTouches(events: readonly CausalEvent[]): RepoConcurrencyTouch[] {
-  const touches: RepoConcurrencyTouch[] = [];
-  for (const event of events) {
-    const contributorKey = buildRepoConcurrencyContributorKey({
-      actorId: event.actorId,
-      attribution: event.attribution,
-      causalSessionId: event.causalSessionId,
-      transportSessionId: event.transportSessionId,
-    });
-    if (contributorKey === null) {
-      continue;
-    }
-    for (const path of event.footprint.paths) {
-      touches.push({ contributorKey, path });
-    }
-  }
-  return touches;
-}

package/src/mcp/repo-overview/filter.ts

@@ -1,44 +0,0 @@
-import type { AuthorizedWorkspaceRecord } from "../daemon-control-plane.js";
-import type { DaemonRepoFilter, DaemonRepoListView, DaemonRepoView } from "./types.js";
-
-// ---------------------------------------------------------------------------
-// Filter normalization
-// ---------------------------------------------------------------------------
-
-export function normalizeFilter(filter: DaemonRepoFilter): DaemonRepoFilter {
-  const next: { repoId?: string; cwd?: string } = {};
-  if (typeof filter.repoId === "string" && filter.repoId.trim().length > 0) {
-    next.repoId = filter.repoId.trim();
-  }
-  if (typeof filter.cwd === "string" && filter.cwd.trim().length > 0) {
-    next.cwd = filter.cwd.trim();
-  }
-  return next;
-}
-
-// ---------------------------------------------------------------------------
-// Workspace sorting
-// ---------------------------------------------------------------------------
-
-export function sortAuthorizedWorkspaces(
-  records: readonly AuthorizedWorkspaceRecord[],
-): readonly AuthorizedWorkspaceRecord[] {
-  return [...records].sort((left, right) => left.worktreeRoot.localeCompare(right.worktreeRoot));
-}
-
-// ---------------------------------------------------------------------------
-// Result builders
-// ---------------------------------------------------------------------------
-
-export function buildResult(
-  filter: DaemonRepoFilter,
-  repos: readonly DaemonRepoView[],
-): DaemonRepoListView {
-  if (Object.keys(filter).length === 0) {
-    return { repos };
-  }
-  return {
-    repos,
-    filter,
-  };
-}

package/src/mcp/repo-overview/types.ts

@@ -1,63 +0,0 @@
-import type { DaemonControlPlane } from "../daemon-control-plane.js";
-import type {
-  MonitorHealth,
-  MonitorLifecycleState,
-  MonitorWorkerKind,
-  PersistentMonitorRuntime,
-} from "../persistent-monitor-runtime.js";
-
-// ---------------------------------------------------------------------------
-// Filter
-// ---------------------------------------------------------------------------
-
-export interface DaemonRepoFilter {
-  readonly repoId?: string | undefined;
-  readonly cwd?: string | undefined;
-}
-
-// ---------------------------------------------------------------------------
-// View projections
-// ---------------------------------------------------------------------------
-
-export interface DaemonRepoWorktreeView {
-  readonly worktreeId: string;
-  readonly worktreeRoot: string;
-  readonly activeSessions: number;
-  readonly lastBoundAt: string | null;
-}
-
-export interface DaemonRepoMonitorView {
-  readonly workerKind: MonitorWorkerKind;
-  readonly lifecycleState: MonitorLifecycleState;
-  readonly health: MonitorHealth;
-  readonly lastTickAt: string | null;
-  readonly lastSuccessAt: string | null;
-  readonly lastError: string | null;
-}
-
-export interface DaemonRepoView {
-  readonly repoId: string;
-  readonly gitCommonDir: string;
-  readonly authorizedWorkspaces: number;
-  readonly boundSessions: number;
-  readonly activeWorktrees: number;
-  readonly backlogCommits: number;
-  readonly lastBoundAt: string | null;
-  readonly lastActivityAt: string | null;
-  readonly monitor: DaemonRepoMonitorView | null;
-  readonly worktrees: readonly DaemonRepoWorktreeView[];
-}
-
-export interface DaemonRepoListView {
-  readonly repos: readonly DaemonRepoView[];
-  readonly filter?: DaemonRepoFilter | undefined;
-}
-
-// ---------------------------------------------------------------------------
-// Options
-// ---------------------------------------------------------------------------
-
-export interface DaemonRepoOverviewOptions {
-  readonly controlPlane: DaemonControlPlane;
-  readonly monitorRuntime: PersistentMonitorRuntime;
-}