@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/receipt.ts

@@ -6,16 +6,120 @@ 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?: { total: number; consumed: number; remaining: number; fraction: number } | null;
+  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;
 }
 
 /**
@@ -24,19 +128,27 @@ export interface ReceiptDeps {
  * so the caller can feed it back into cumulative metrics.
  */
 export function buildReceiptResult(
-  tool: string,
+  tool: McpToolName,
   data: Record<string, unknown>,
   deps: ReceiptDeps,
-): { result: McpToolResult; textBytes: number } {
-  const receipt: Record<string, unknown> = {
+): { 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: (data["projection"] as string | undefined) ?? "none",
-    reason: (data["reason"] as string | undefined) ?? "none",
-    fileBytes: (data["actual"] as { bytes: number } | undefined)?.bytes ?? null,
+    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,
@@ -44,16 +156,21 @@ export function buildReceiptResult(
       cacheHits: deps.metrics.cacheHits,
       bytesReturned: 0,
       bytesAvoided: deps.metrics.bytesAvoided,
+      nonReadBytesReturned: totalNonReadBytesReturned(deps.metrics.burdenByKind),
+      burdenByKind: deps.metrics.burdenByKind,
     },
   };
 
   if (deps.budget != null) {
-    receipt["budget"] = deps.budget;
+    draft.budget = deps.budget;
   }
 
-  const fullData: Record<string, unknown> = { ...data, _receipt: receipt };
+  const fullData: Record<string, unknown> & { tripwire?: Tripwire[] } = attachMcpSchemaMeta(tool, {
+    ...data,
+    _receipt: draft,
+  });
   if (deps.tripwires.length > 0) {
-    fullData["tripwire"] = deps.tripwires;
+    fullData.tripwire = deps.tripwires;
   }
 
   // Stabilize self-referential size fields (use UTF-8 byte length, not char count)
@@ -64,20 +181,21 @@ export function buildReceiptResult(
     const byteLen = Buffer.byteLength(text, "utf8");
     if (byteLen === prev) break;
     prev = byteLen;
-    receipt["returnedBytes"] = byteLen;
-    const fb = receipt["fileBytes"] as number | null;
-    receipt["compressionRatio"] = fb !== null && fb > 0
-      ? Math.round((byteLen / fb) * 1000) / 1000
+    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;
-    (receipt["cumulative"] as Record<string, number>)["bytesReturned"] =
-      deps.metrics.bytesReturned + byteLen;
+    draft.cumulative.bytesReturned = deps.metrics.bytesReturned + byteLen;
+    draft.cumulative.nonReadBytesReturned = totalNonReadBytesReturned(burdenByKind);
+    draft.cumulative.burdenByKind = burdenByKind;
   }
 
-  Object.freeze(receipt["cumulative"]);
-  Object.freeze(receipt);
+  const receipt = freezeReceipt(draft);
 
   return {
     result: { content: [{ type: "text", text }] },
     textBytes: Buffer.byteLength(text, "utf8"),
+    receipt,
   };
 }

package/src/mcp/repo-concurrency.ts

@@ -0,0 +1,392 @@
+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

@@ -0,0 +1,44 @@
+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,
+  };
+}