Files
rea/src/contracts/artifactToolContracts.ts
T

128 lines
4.2 KiB
TypeScript

import { z } from "zod";
import type { ToolContract } from "./toolContracts.js";
import { artifactOutputSchemas } from "./toolOutputSchemas.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
const pageInput = {
node_offset: z.number().int().min(0).default(0),
node_limit: z.number().int().min(1).max(500).default(100),
occurrence_offset: z.number().int().min(0).default(0),
occurrence_limit: z.number().int().min(1).max(500).default(100),
edge_offset: z.number().int().min(0).default(0),
edge_limit: z.number().int().min(1).max(500).default(100),
};
const traversalLimitsInput = {
max_entries: z.number().int().min(1).max(1_000_000).default(10_000),
max_total_bytes: z
.number()
.int()
.min(1)
.max(Number.MAX_SAFE_INTEGER)
.default(1_073_741_824),
max_entry_bytes: z
.number()
.int()
.min(1)
.max(Number.MAX_SAFE_INTEGER)
.default(268_435_456),
max_compression_ratio: z.number().min(1).max(100_000).default(1_000),
max_depth: z.number().int().min(0).max(100).default(20),
max_path_bytes: z.number().int().min(1).max(65_535).default(4_096),
};
/** Exact caller boundary for deterministic artifact inventory. */
export const artifactInventoryInputSchema = z
.object({
native_mount_approved: z.boolean().default(false),
integrity_policy: z.enum(["fail", "record-and-continue"]).default("fail"),
integrity_continue_approved: z.boolean().default(false),
max_integrity_mismatches: z.number().int().min(1).max(100).default(10),
...pageInput,
...traversalLimitsInput,
})
.superRefine((input, context) => {
if (
input.integrity_policy === "record-and-continue" &&
input.integrity_continue_approved !== true
)
context.addIssue({
code: "custom",
path: ["integrity_continue_approved"],
message: "record-and-continue requires explicit approval",
});
});
/** Exact caller boundary for approved artifact extraction. */
export const artifactExtractionInputSchema = z.object({
approved: z.literal(true),
output_root: z.string().min(1).max(4_096),
occurrence_ids: z
.array(z.string().regex(/^occ_[a-f0-9]{64}$/u))
.min(1)
.max(500),
offset: z.number().int().min(0).default(0),
limit: z.number().int().min(1).max(500).default(100),
...traversalLimitsInput,
});
const exampleInputSchema = z.record(z.string(), jsonValueSchema);
const examples: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
inventory_artifact: {},
extract_artifact: {
approved: true,
output_root: "/tmp/rea-extracted",
occurrence_ids: [`occ_${"0".repeat(64)}`],
},
};
const artifact = <Name extends string>(
name: Name,
description: string,
inputSchema: z.ZodObject,
mutatesFilesystem: boolean,
): ToolContract<Name> => {
const outputSchema = artifactOutputSchemas[name];
if (outputSchema === undefined)
throw new Error(`Missing artifact output schema for ${name}`);
return {
name,
description,
kind: "artifact-provider",
inputSchema,
outputSchema,
annotations: {
readOnlyHint: !mutatesFilesystem,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
},
examples: [
{
title: `Example ${name.replaceAll("_", " ")} request`,
input: exampleInputSchema.parse(examples[name] ?? {}),
},
],
};
};
/** Artifact-graph inventory and explicitly approved safe extraction contracts. */
export const ARTIFACT_TOOL_CONTRACTS = [
artifact(
"inventory_artifact",
"Inventory the active application or package as a deterministic, content-addressed artifact graph. Returns bounded node and edge pages without extracting or mounting by default.",
artifactInventoryInputSchema,
false,
),
artifact(
"extract_artifact",
"Extract selected graph artifacts beneath an explicit output root. Requires approval, rejects traversal and symlink escapes, never overwrites, enforces bomb limits, and verifies cleanup.",
artifactExtractionInputSchema,
true,
),
] as const satisfies readonly ToolContract[];
/** Names of provider-neutral artifact graph operations. */
export type ArtifactToolName = (typeof ARTIFACT_TOOL_CONTRACTS)[number]["name"];