Files
rea/src/contracts/artifactToolContracts.ts
T

94 lines
3.5 KiB
TypeScript

import { z } from "zod";
import type { ToolContract } from "./toolContracts.js";
import { artifactOutputSchemas } from "./toolOutputSchemas.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
import { toolContractMetadata } from "./toolEffects.js";
import { requireOutputSchema } from "./toolOutputSchemaPrimitives.js";
const integrityInput = {
fail: {
integrity_policy: z.literal("fail").default("fail"),
integrity_continue_approved: z.literal(false).default(false),
},
continue: {
integrity_policy: z.literal("record-and-continue"),
integrity_continue_approved: z.literal(true),
},
} as const;
const artifactInventoryFacts = {
native_mount_approved: z.boolean().default(false),
} as const;
/** Exact caller boundary for deterministic artifact inventory. */
export const artifactInventoryInputSchema = z.union([
z.object({ ...artifactInventoryFacts, ...integrityInput.fail }),
z.object({ ...artifactInventoryFacts, ...integrityInput.continue }),
]);
/** Exact caller boundary for approved artifact extraction. */
export const artifactExtractionInputSchema = z.object({
occurrence_ids: z.array(z.string().regex(/^occ_[a-f0-9]{64}$/u)).min(1),
});
/** Provider input after the local permission boundary chooses its destination. */
export const artifactExtractionExecutionSchema =
artifactExtractionInputSchema.extend({ output_root: z.string().min(1) });
const exampleInputSchema = z.record(z.string(), jsonValueSchema);
const examples: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
inspect_artifact: {},
extract_artifact: {
occurrence_ids: [`occ_${"0".repeat(64)}`],
},
};
const artifact = <
Name extends string,
Schema extends z.ZodType<Readonly<Record<string, unknown>>>,
>(
name: Name,
description: string,
inputSchema: Schema,
) => {
const outputSchema = requireOutputSchema(artifactOutputSchemas, name);
return {
name,
...toolContractMetadata(name),
description,
kind: "artifact-provider",
inputSchema,
outputSchema,
examples: [
{
title: `Example ${name.replaceAll("_", " ")} request`,
input: exampleInputSchema.parse(examples[name] ?? {}),
},
],
} satisfies ToolContract<Name, Schema, typeof outputSchema>;
};
/** Artifact-graph inventory and safe extraction contracts. */
export const ARTIFACT_TOOL_CONTRACTS = [
artifact(
"inspect_artifact",
"Inspect an active archive or application package in one call. Returns the complete content-addressed artifact graph, source Evidence, observations, relationships, integrity contradictions, hypotheses, unexplored branches, limitations, and next probes inline. It does not extract files; use extract_artifact for selected occurrences.",
artifactInventoryInputSchema,
),
artifact(
"extract_artifact",
"Extract selected graph artifacts into a fresh temporary directory chosen by REA. The result includes its location. Rejects traversal and symlink escapes, never overwrites, enforces archive integrity checks, and verifies cleanup.",
artifactExtractionInputSchema,
),
] as const satisfies readonly ToolContract[];
/** Provider operations; inventory remains an internal primitive of inspection. */
export const ARTIFACT_ANALYSIS_OPERATIONS = [
"inventory_artifact",
...ARTIFACT_TOOL_CONTRACTS.map(({ name }) => name),
] as const;
/** Provider-level operations including the inventory primitive used internally. */
export type ArtifactAnalysisOperation =
(typeof ARTIFACT_ANALYSIS_OPERATIONS)[number];