@flyingrobots/graft 0.4.0 → 0.6.0

package/src/contracts/output-schema-mcp.ts

@@ -0,0 +1,282 @@
+import { z } from "zod";
+import {
+  attributionSummarySchema,
+  readEventSchema,
+  stageEventSchema,
+  transitionEventSchema,
+} from "./causal-ontology.js";
+import {
+  mcpFragmentSchemas,
+} from "./output-schema-fragments.js";
+import type { McpToolName } from "./capabilities.js";
+
+const {
+  actualSchema,
+  thresholdsSchema,
+  budgetSchema,
+  outlineEntrySchema,
+  jumpEntrySchema,
+  outlineDiffSchema,
+  mapFileSchema,
+  mapDirectorySchema,
+  mapModeSchema,
+  fileDiffSchema,
+  burdenByKindSchema,
+  burdenSummarySchema,
+  runtimeObservabilitySchema,
+  runtimeCausalContextSchema,
+  runtimeStagedTargetSchema,
+  persistedLocalHistorySummarySchema,
+  repoConcurrencySummarySchema,
+  precisionSymbolMatchSchema,
+  codeRefsMatchSchema,
+  codeRefsProvenanceSchema,
+  structuralRefusalSchema,
+  worldlineLayerSchema,
+  activityViewSchema,
+  causalStatusSchema,
+  causalAttachSchema,
+  workspaceAuthorizeSchema,
+  workspaceRevokeSchema,
+  workspaceStatusSchema,
+  workspaceActionSchema,
+  workspaceOverlaySummarySchema,
+  workspaceOverlayFootingSchema,
+  authorizedWorkspaceSchema,
+  policyBoundarySchema,
+  daemonStatusSchema,
+  daemonSessionSchema,
+  daemonRepoSchema,
+  monitorStatusSchema,
+  monitorActionSchema,
+  repoTransitionSchema,
+  repoSemanticTransitionSchema,
+  sessionDepthSchema,
+} = mcpFragmentSchemas;
+
+export const mcpOutputBodySchemas = {
+  safe_read: z.object({
+    path: z.string(),
+    projection: z.enum(["content", "outline", "refused", "error", "cache_hit", "diff"]),
+    reason: z.string(),
+    actual: actualSchema.optional(),
+    thresholds: thresholdsSchema.optional(),
+    sessionDepth: sessionDepthSchema.optional(),
+    content: z.string().optional(),
+    outline: z.array(outlineEntrySchema).optional(),
+    jumpTable: z.array(jumpEntrySchema).optional(),
+    estimatedBytesAvoided: z.number().int().nonnegative().optional(),
+    next: z.array(z.string()).optional(),
+    reasonDetail: z.string().optional(),
+    readCount: z.number().int().nonnegative().optional(),
+    lastReadAt: z.string().optional(),
+    diff: outlineDiffSchema.optional(),
+  }).strict(),
+  file_outline: z.union([
+    z.object({
+      path: z.string(),
+      outline: z.array(outlineEntrySchema),
+      jumpTable: z.array(jumpEntrySchema),
+      partial: z.boolean().optional(),
+      reason: z.string().optional(),
+      error: z.string().optional(),
+      cacheHit: z.boolean().optional(),
+    }).strict(),
+    z.object({
+      path: z.string(),
+      projection: z.literal("refused"),
+      reason: z.string(),
+      reasonDetail: z.string().optional(),
+      next: z.array(z.string()).optional(),
+      actual: actualSchema.optional(),
+    }).strict(),
+  ]),
+  read_range: z.object({
+    path: z.string(),
+    content: z.string().optional(),
+    startLine: z.number().int().positive().optional(),
+    endLine: z.number().int().positive().optional(),
+    reason: z.string().optional(),
+    truncated: z.boolean().optional(),
+    clipped: z.boolean().optional(),
+    projection: z.literal("refused").optional(),
+    reasonDetail: z.string().optional(),
+    next: z.array(z.string()).optional(),
+    actual: actualSchema.optional(),
+  }).strict(),
+  changed_since: z.object({
+    status: z.enum(["file_not_found", "refused", "unsupported", "unchanged", "no_previous_observation"]).optional(),
+    reason: z.string().optional(),
+    diff: outlineDiffSchema.optional(),
+    consumed: z.boolean().optional(),
+  }).strict(),
+  graft_diff: z.object({
+    base: z.string(),
+    head: z.string(),
+    files: z.array(fileDiffSchema),
+    refused: z.array(structuralRefusalSchema).optional(),
+    layer: worldlineLayerSchema,
+  }).strict(),
+  graft_since: z.object({
+    base: z.string(),
+    head: z.string(),
+    files: z.array(fileDiffSchema),
+    refused: z.array(structuralRefusalSchema).optional(),
+    summary: z.string(),
+    layer: z.literal("ref_view"),
+  }).strict(),
+  graft_map: z.object({
+    directory: z.string(),
+    files: z.array(mapFileSchema),
+    directories: z.array(mapDirectorySchema).optional(),
+    refused: z.array(structuralRefusalSchema).optional(),
+    mode: mapModeSchema,
+    summary: z.string(),
+  }).strict(),
+  code_show: z.object({
+    symbol: z.string().optional(),
+    kind: z.string().optional(),
+    signature: z.string().optional(),
+    path: z.string().optional(),
+    identityId: z.string().optional(),
+    exported: z.boolean().optional(),
+    startLine: z.number().int().positive().optional(),
+    endLine: z.number().int().positive().optional(),
+    content: z.string().optional(),
+    truncated: z.boolean().optional(),
+    clipped: z.boolean().optional(),
+    source: z.enum(["warp", "live"]),
+    layer: worldlineLayerSchema,
+    ambiguous: z.boolean().optional(),
+    matches: z.array(precisionSymbolMatchSchema).optional(),
+    error: z.string().optional(),
+    projection: z.literal("refused").optional(),
+    reason: z.string().optional(),
+    reasonDetail: z.string().optional(),
+    next: z.array(z.string()).optional(),
+    actual: actualSchema.optional(),
+  }).strict(),
+  code_find: z.object({
+    query: z.string(),
+    kind: z.string().nullable(),
+    matches: z.array(precisionSymbolMatchSchema).optional(),
+    total: z.number().int().nonnegative().optional(),
+    path: z.string().optional(),
+    projection: z.literal("refused").optional(),
+    reason: z.string().optional(),
+    reasonDetail: z.string().optional(),
+    next: z.array(z.string()).optional(),
+    actual: actualSchema.optional(),
+    source: z.enum(["warp", "live"]),
+    layer: worldlineLayerSchema,
+  }).strict(),
+  code_refs: z.object({
+    query: z.string(),
+    mode: z.enum(["text", "import", "call", "property"]),
+    scope: z.string(),
+    matches: z.array(codeRefsMatchSchema).optional(),
+    total: z.number().int().nonnegative().optional(),
+    path: z.string().optional(),
+    projection: z.literal("refused").optional(),
+    reason: z.string().optional(),
+    reasonDetail: z.string().optional(),
+    next: z.array(z.string()).optional(),
+    actual: actualSchema.optional(),
+    source: z.literal("text_fallback"),
+    provenance: codeRefsProvenanceSchema,
+    layer: worldlineLayerSchema,
+  }).strict(),
+  daemon_repos: z.object({
+    repos: z.array(daemonRepoSchema),
+    filter: z.object({
+      repoId: z.string().optional(),
+      cwd: z.string().optional(),
+    }).strict().optional(),
+  }).strict(),
+  daemon_status: daemonStatusSchema,
+  daemon_sessions: z.object({
+    sessions: z.array(daemonSessionSchema),
+  }).strict(),
+  daemon_monitors: z.object({
+    monitors: z.array(monitorStatusSchema),
+  }).strict(),
+  monitor_start: monitorActionSchema,
+  monitor_pause: monitorActionSchema,
+  monitor_resume: monitorActionSchema,
+  monitor_stop: monitorActionSchema,
+  workspace_authorize: workspaceAuthorizeSchema,
+  workspace_authorizations: z.object({
+    workspaces: z.array(authorizedWorkspaceSchema),
+  }).strict(),
+  workspace_revoke: workspaceRevokeSchema,
+  workspace_bind: workspaceActionSchema.extend({ action: z.literal("bind") }).strict(),
+  workspace_status: workspaceStatusSchema,
+  activity_view: activityViewSchema,
+  causal_status: causalStatusSchema,
+  causal_attach: causalAttachSchema,
+  workspace_rebind: workspaceActionSchema.extend({ action: z.literal("rebind") }).strict(),
+  run_capture: z.object({
+    output: z.string(),
+    totalLines: z.number().int().nonnegative(),
+    tailedLines: z.number().int().nonnegative(),
+    logPath: z.string().nullable().optional(),
+    logRedactions: z.number().int().nonnegative().optional(),
+    logPersistenceEnabled: z.boolean().optional(),
+    truncated: z.boolean(),
+    disabled: z.boolean().optional(),
+    error: z.string().optional(),
+    stderr: z.string().optional(),
+    policyBoundary: policyBoundarySchema,
+  }).strict(),
+  state_save: z.object({
+    ok: z.boolean(),
+    reason: z.string().optional(),
+  }).strict(),
+  state_load: z.object({
+    content: z.string().nullable(),
+  }).strict(),
+  set_budget: z.object({
+    budget: budgetSchema.nullable(),
+  }).strict(),
+  explain: z.object({
+    code: z.string(),
+    meaning: z.string().optional(),
+    action: z.string().optional(),
+    error: z.string().optional(),
+    knownCodes: z.string().optional(),
+  }).strict(),
+  doctor: z.object({
+    projectRoot: z.string(),
+    parserHealthy: z.boolean(),
+    thresholds: thresholdsSchema,
+    sessionDepth: z.enum(["early", "mid", "late"]),
+    totalMessages: z.number().int().nonnegative(),
+    burdenSummary: burdenSummarySchema,
+    runtimeObservability: runtimeObservabilitySchema,
+    causalContext: runtimeCausalContextSchema,
+    latestReadEvent: readEventSchema.nullable(),
+    latestStageEvent: stageEventSchema.nullable(),
+    latestTransitionEvent: transitionEventSchema.nullable(),
+    repoConcurrency: repoConcurrencySummarySchema.nullable(),
+    checkoutEpoch: z.number().int().nonnegative(),
+    lastTransition: repoTransitionSchema.nullable(),
+    semanticTransition: repoSemanticTransitionSchema.nullable(),
+    workspaceOverlayId: z.string().nullable(),
+    workspaceOverlay: workspaceOverlaySummarySchema.nullable(),
+    workspaceOverlayFooting: workspaceOverlayFootingSchema,
+    stagedTarget: runtimeStagedTargetSchema,
+    attribution: attributionSummarySchema,
+    persistedLocalHistory: persistedLocalHistorySummarySchema,
+    recommendedNextAction: z.string(),
+  }).strict(),
+  stats: z.object({
+    totalReads: z.number().int().nonnegative(),
+    totalOutlines: z.number().int().nonnegative(),
+    totalRefusals: z.number().int().nonnegative(),
+    totalCacheHits: z.number().int().nonnegative(),
+    totalBytesReturned: z.number().int().nonnegative(),
+    totalBytesAvoidedByCache: z.number().int().nonnegative(),
+    totalNonReadBytesReturned: z.number().int().nonnegative(),
+    burdenByKind: burdenByKindSchema,
+  }).strict(),
+} satisfies Record<McpToolName, z.ZodType>;

package/src/contracts/output-schema-meta.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import {
+  CLI_COMMAND_NAMES,
+  type CliCommandName,
+  MCP_TOOL_NAMES,
+  type McpToolName,
+} from "./capabilities.js";
+
+export const OUTPUT_SCHEMA_VERSION = "1.0.0" as const;
+
+export interface OutputSchemaMeta {
+  readonly id: string;
+  readonly version: typeof OUTPUT_SCHEMA_VERSION;
+}
+
+export const mcpOutputSchemaMeta = Object.freeze(Object.fromEntries(
+  MCP_TOOL_NAMES.map((tool) => [tool, Object.freeze({
+    id: `graft.mcp.${tool}`,
+    version: OUTPUT_SCHEMA_VERSION,
+  })]),
+) as Record<McpToolName, OutputSchemaMeta>);
+
+export const cliOutputSchemaMeta = Object.freeze(Object.fromEntries(
+  CLI_COMMAND_NAMES.map((command) => [command, Object.freeze({
+    id: `graft.cli.${command}`,
+    version: OUTPUT_SCHEMA_VERSION,
+  })]),
+) as Record<CliCommandName, OutputSchemaMeta>);
+
+export function schemaMetaLiteral(meta: OutputSchemaMeta) {
+  return z.object({
+    id: z.literal(meta.id),
+    version: z.literal(meta.version),
+  }).strict();
+}
+
+export type CliPeerCommandName =
+  | "read_safe"
+  | "read_outline"
+  | "read_range"
+  | "read_changed"
+  | "struct_diff"
+  | "struct_since"
+  | "struct_map"
+  | "symbol_show"
+  | "symbol_find"
+  | "diag_doctor"
+  | "diag_activity"
+  | "diag_explain"
+  | "diag_stats"
+  | "diag_capture";
+
+export interface McpCommonFields {
+  readonly _schema: OutputSchemaMeta;
+  readonly _receipt: Record<string, unknown>;
+  readonly tripwire?: readonly Record<string, unknown>[] | undefined;
+}
+
+export interface CliCommonFields {
+  readonly _schema: OutputSchemaMeta;
+}
+
+export interface CliPeerCommonFields extends CliCommonFields {
+  readonly _receipt: Record<string, unknown>;
+  readonly tripwire?: readonly Record<string, unknown>[] | undefined;
+}
+
+function extendWithCommonFields(
+  schema: z.ZodType,
+  common: z.ZodRawShape,
+): z.ZodType {
+  if (schema instanceof z.ZodObject) {
+    return schema.extend(common).strict();
+  }
+  if (schema instanceof z.ZodUnion) {
+    return z.union(schema.options.map((option) => {
+      if (!(option instanceof z.ZodObject)) {
+        throw new Error("Output schema unions must be composed of objects");
+      }
+      return option.extend(common).strict();
+    }) as [z.ZodObject, z.ZodObject, ...z.ZodObject[]]);
+  }
+  throw new Error("Output schemas must be objects or unions of objects");
+}
+
+export function withMcpCommon(
+  tool: McpToolName,
+  schema: z.ZodType,
+  receiptSchema: z.ZodType,
+  tripwireSchema: z.ZodType,
+): z.ZodType {
+  return extendWithCommonFields(schema, {
+    _schema: schemaMetaLiteral(mcpOutputSchemaMeta[tool]),
+    _receipt: receiptSchema,
+    tripwire: z.array(tripwireSchema).optional(),
+  });
+}
+
+export function withCliCommon(
+  command: CliCommandName,
+  schema: z.ZodType,
+): z.ZodType {
+  return extendWithCommonFields(schema, {
+    _schema: schemaMetaLiteral(cliOutputSchemaMeta[command]),
+  });
+}
+
+export function withCliPeerCommon(
+  command: CliCommandName,
+  schema: z.ZodType,
+  receiptSchema: z.ZodType,
+  tripwireSchema: z.ZodType,
+): z.ZodType {
+  return extendWithCommonFields(schema, {
+    _schema: schemaMetaLiteral(cliOutputSchemaMeta[command]),
+    _receipt: receiptSchema,
+    tripwire: z.array(tripwireSchema).optional(),
+  });
+}