agentex-creator-sdk 1.0.0

package/dist/packages/contracts/src/kinds.js

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+import { AtomicAmountSchema, contentHash, ResearchInputSchema, SupportedTokenResearcherManifestSchema, TOKEN_RESEARCHER_MANIFEST, TOKEN_RESEARCHER_MANIFEST_V2, TokenResearchReportSchema } from './index.js';
+import { SupportedTransactionInspectorManifestSchema, TRANSACTION_INSPECTOR_MANIFEST, TRANSACTION_INSPECTOR_MANIFEST_V2, TransactionInspectionInputSchema, TransactionInspectionReportSchema } from './inspection.js';
+import { SOLANA_INSPECTION_RPC_CEILING, SOLANA_INSPECTION_SCHEMA_ID, SOLANA_INSPECTION_TOOL, SolanaTransactionInspectionInputSchema, SolanaTransactionInspectionReportSchema } from './solana-inspection.js';
+import { SupportedWatchtowerManifestSchema, WATCHTOWER_MANIFEST, WATCHTOWER_MANIFEST_V2, WATCHTOWER_MANIFEST_V3, WatchtowerWindowInputSchema, WatchtowerWindowReportSchema } from './watchtower.js';
+import { WORKFLOW_SCHEMA_ID, WorkflowManifestSchema, WorkflowReportSchema, WorkflowRunInputSchema } from './workflow.js';
+import { DEPLOYER_INVESTIGATOR_MANIFEST, DEPLOYER_SCHEMA_ID, DeployerInvestigationInputSchema, DeployerInvestigationReportSchema, SupportedDeployerInvestigatorManifestSchema } from './deployer-investigation.js';
+import { SupportedWalletAnalystManifestSchema, WALLET_ANALYST_MANIFEST, WALLET_SCHEMA_ID, WalletAnalysisInputSchema, WalletAnalysisReportSchema } from './wallet-analysis.js';
+/**
+ * Solana Transaction Inspector as an agent kind (P05). The executable contract (input, report, RPC ceiling) is owned by
+ * solana-inspection.ts; this file adds only the immutable manifest, its supported subset and the buyer result contract.
+ * The manifest uses its own strict schema (like workflows), so `AgentManifestSchema` and every existing manifest hash stay unchanged.
+ */
+const Identifier = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+const Semver = z.string().regex(/^\d+\.\d+\.\d+$/);
+const SOLANA_INSPECTOR_TEMPLATE_SOURCE = {
+    schemaVersion: '1.0', id: 'solana-transaction-inspector', version: '0.1.0', name: 'Solana Transaction Inspector',
+    description: 'Decode a proposed Solana legacy or v0 payload offline, resolve address lookup tables at a confirmed lower-bound slot and run simulateTransaction with signature verification disabled. It never signs or broadcasts, computes no asset flows and gives no safety verdict.',
+    author: { id: 'agentex', name: 'AGENTEX', ownership: 'first-party' }, license: 'Proprietary', visibility: 'source-visible', chains: ['solana'],
+    inputSchema: { type: 'object', additionalProperties: false, required: ['analysisChain', 'network', 'encoding', 'payloadBase64'], properties: {
+            analysisChain: { type: 'string', description: 'Explicit analysis chain; independent of the EVM sign-in network', enum: ['solana'] },
+            network: { type: 'string', description: 'Solana cluster', enum: ['mainnet-beta', 'devnet'] }, encoding: { type: 'string', description: 'Serialized transaction or message', enum: ['transaction', 'message'] },
+            payloadBase64: { type: 'string', description: 'Canonical base64 payload, at most 1232 bytes' }, simulate: { type: 'boolean', description: 'Run simulateTransaction (default true)' },
+            accounts: { type: 'array', description: 'Up to eight accounts whose post-simulation state is reported' }
+        } },
+    outputSchemaId: SOLANA_INSPECTION_SCHEMA_ID,
+    tools: [{ id: 'solana.inspect-transaction', version: '0.1.0', capability: 'solana.read', chains: ['solana'], addressScope: 'input-transaction', maximumCalls: SOLANA_INSPECTION_RPC_CEILING }],
+    modelPolicy: { mode: 'deterministic', maximumModelTokens: 0 },
+    limits: { maximumRpcCalls: SOLANA_INSPECTION_RPC_CEILING, maximumDurationMs: 60000, maximumOutputBytes: 262144, maximumGraphDepth: 3, maximumPages: 0, maximumExecutionAtomic: '0' },
+    workflow: [{ id: 'input', type: 'input', dependsOn: [] }, { id: 'inspect', type: 'tool', tool: 'solana.inspect-transaction', dependsOn: ['input'], arguments: { payload: { source: 'input', path: 'payloadBase64' } } }, { id: 'report', type: 'output', dependsOn: ['inspect'], from: 'inspect' }],
+    testCases: ['legacy-system-spl-token', 'v0-lookup-table', 'unknown-program', 'simulation-failure', 'budget-stop', 'wrong-genesis'],
+};
+export const SolanaTransactionInspectorManifestSchema = z.strictObject({
+    schemaVersion: z.literal('1.0'), id: Identifier, version: Semver, name: z.string().min(1).max(100), description: z.string().min(1).max(2000),
+    author: z.strictObject({ id: Identifier, name: z.string().min(1).max(100), ownership: z.enum(['first-party', 'independent']) }),
+    license: z.string().min(1).max(100), visibility: z.enum(['private', 'source-visible', 'source-private']), chains: z.tuple([z.literal('solana')]),
+    inputSchema: z.json(), outputSchemaId: z.literal(SOLANA_INSPECTION_SCHEMA_ID),
+    tools: z.tuple([z.strictObject({ id: z.literal('solana.inspect-transaction'), version: z.literal('0.1.0'), capability: z.literal('solana.read'), chains: z.tuple([z.literal('solana')]), addressScope: z.literal('input-transaction'), maximumCalls: z.number().int().min(1).max(SOLANA_INSPECTION_RPC_CEILING) })]),
+    modelPolicy: z.strictObject({ mode: z.literal('deterministic'), maximumModelTokens: z.literal(0) }),
+    limits: z.strictObject({ maximumRpcCalls: z.number().int().min(1).max(SOLANA_INSPECTION_RPC_CEILING), maximumDurationMs: z.number().int().min(1000).max(60000), maximumOutputBytes: z.number().int().min(1024).max(262144), maximumGraphDepth: z.number().int().min(3).max(4), maximumPages: z.literal(0), maximumExecutionAtomic: AtomicAmountSchema }),
+    workflow: z.json(), testCases: z.array(Identifier).min(1).max(100),
+}).superRefine((manifest, ctx) => {
+    if (contentHash(manifest.workflow) !== contentHash(SOLANA_INSPECTOR_TEMPLATE_SOURCE.workflow))
+        ctx.addIssue({ code: 'custom', path: ['workflow'], message: 'The executor supports only the bounded Solana Transaction Inspector graph.' });
+    if (contentHash(manifest.inputSchema) !== contentHash(SOLANA_INSPECTOR_TEMPLATE_SOURCE.inputSchema))
+        ctx.addIssue({ code: 'custom', path: ['inputSchema'], message: 'The input declaration must match the supported Solana payload inputs.' });
+    if (manifest.tools[0].maximumCalls > manifest.limits.maximumRpcCalls)
+        ctx.addIssue({ code: 'custom', path: ['tools', 0, 'maximumCalls'], message: 'The tool ceiling exceeds the run RPC budget.' });
+});
+const deepFreeze = (value) => { if (value !== null && typeof value === 'object') {
+    for (const child of Object.values(value))
+        deepFreeze(child);
+    Object.freeze(value);
+} return value; };
+export const SOLANA_TRANSACTION_INSPECTOR_MANIFEST = deepFreeze(SolanaTransactionInspectorManifestSchema.parse(structuredClone(SOLANA_INSPECTOR_TEMPLATE_SOURCE)));
+/** Buyer result contract for Solana inspections. Asset flows are never claimed; simulation is a snapshot at its context slot. */
+export const SOLANA_INSPECTION_RESULT_CONTRACT = { id: 'solana-inspection-observed-v1', description: 'Charge only for a complete inspection: the payload decoded with no invalid instruction, the cluster genesis hash was captured, and a simulateTransaction outcome (succeeded or failed) was observed with its captured receipt at a confirmed lower-bound slot. Nothing is signed or broadcast; asset flows are not computed.' };
+export function solanaInspectionResultContractIssues(raw) {
+    const parsed = SolanaTransactionInspectionReportSchema.safeParse(raw);
+    if (!parsed.success)
+        return ['The report does not match agentex.solana-transaction-inspection.v1.'];
+    const report = parsed.data;
+    const issues = [];
+    const evidence = new Map(report.evidence.map((item) => [item.id, item]));
+    if (report.status !== 'complete')
+        issues.push(`The inspection is ${report.status}.`);
+    if (report.payload.version === null || report.instructions.some((item) => item.status === 'invalid'))
+        issues.push('The payload was not fully decoded.');
+    if (!report.genesisHash || !report.evidence.some((item) => item.source.method === 'getGenesisHash' && item.completeness === 'complete-for-request'))
+        issues.push('The cluster identity was not captured.');
+    if (report.finalizedSlotLowerBound === null)
+        issues.push('No confirmed lower-bound slot was captured.');
+    if (!['succeeded', 'failed'].includes(report.simulation.status) || !report.simulation.evidenceIds.length
+        || report.simulation.evidenceIds.some((id) => evidence.get(id)?.source.method !== 'simulateTransaction' || evidence.get(id)?.completeness !== 'complete-for-request'))
+        issues.push('No simulation outcome is backed by a captured simulateTransaction receipt.');
+    if (report.evidence.some((item) => item.tool !== SOLANA_INSPECTION_TOOL))
+        issues.push('Evidence came from a tool other than the declared inspector.');
+    return issues;
+}
+export const satisfiesSolanaInspectionResultContract = (raw) => solanaInspectionResultContractIssues(raw).length === 0;
+/**
+ * Executable agent kinds. A manifest's `outputSchemaId` is its explicit kind; there is no inference from names or graphs.
+ * Services that support only some kinds must call `requireAgentKind` before any work, quote, listing or review.
+ * `workflow` is the general creator workflow (`agentex.workflow.v1`); its manifests use `WorkflowManifestSchema`, not `AgentManifestSchema`.
+ * `solana-transaction-inspection` uses `SolanaTransactionInspectorManifestSchema`.
+ */
+export const AgentKindSchema = z.enum(['token-research', 'transaction-inspection', 'watchtower', 'workflow', 'solana-transaction-inspection', 'deployer-investigation', 'wallet-analysis']);
+export const AGENT_KINDS = {
+    'token-research': { outputSchemaId: 'agentex.token-research.v1', template: TOKEN_RESEARCHER_MANIFEST_V2, supportedManifest: SupportedTokenResearcherManifestSchema, input: ResearchInputSchema, report: TokenResearchReportSchema },
+    'transaction-inspection': { outputSchemaId: 'agentex.transaction-inspection.v1', template: TRANSACTION_INSPECTOR_MANIFEST_V2, supportedManifest: SupportedTransactionInspectorManifestSchema, input: TransactionInspectionInputSchema, report: TransactionInspectionReportSchema },
+    watchtower: { outputSchemaId: 'agentex.watchtower-window.v1', template: WATCHTOWER_MANIFEST_V3, supportedManifest: SupportedWatchtowerManifestSchema, input: WatchtowerWindowInputSchema, report: WatchtowerWindowReportSchema },
+    /** Workflow templates depend on the tool registry and live in packages/workflow. */
+    workflow: { outputSchemaId: WORKFLOW_SCHEMA_ID, template: null, supportedManifest: WorkflowManifestSchema, input: WorkflowRunInputSchema, report: WorkflowReportSchema },
+    'solana-transaction-inspection': { outputSchemaId: SOLANA_INSPECTION_SCHEMA_ID, template: SOLANA_TRANSACTION_INSPECTOR_MANIFEST, supportedManifest: SolanaTransactionInspectorManifestSchema, input: SolanaTransactionInspectionInputSchema, report: SolanaTransactionInspectionReportSchema },
+    /** P02/P03 indexed first-party agents: strict manifests of their own schema (packages/contracts deployer-investigation.ts, wallet-analysis.ts). */
+    'deployer-investigation': { outputSchemaId: DEPLOYER_SCHEMA_ID, template: DEPLOYER_INVESTIGATOR_MANIFEST, supportedManifest: SupportedDeployerInvestigatorManifestSchema, input: DeployerInvestigationInputSchema, report: DeployerInvestigationReportSchema },
+    'wallet-analysis': { outputSchemaId: WALLET_SCHEMA_ID, template: WALLET_ANALYST_MANIFEST, supportedManifest: SupportedWalletAnalystManifestSchema, input: WalletAnalysisInputSchema, report: WalletAnalysisReportSchema },
+};
+/** Indexed-agent kinds whose manifests use their own strict schema, tool evidence envelopes and the one-request AI-assisted summary. */
+export const INDEXED_AGENT_KINDS = Object.freeze(['deployer-investigation', 'wallet-analysis']);
+export const isIndexedAgentKind = (kind) => kind === 'deployer-investigation' || kind === 'wallet-analysis';
+/** Indexed first-party templates (0.1.0), offered for new drafts beside `AGENT_TEMPLATES` (which keeps only `AgentManifestSchema` manifests). */
+export const INDEXED_AGENT_TEMPLATES = Object.freeze([DEPLOYER_INVESTIGATOR_MANIFEST, WALLET_ANALYST_MANIFEST]);
+/**
+ * Current first-party EVM templates offered for new drafts (0.2.0, instant-read wording). The 0.1.0 manifests stay exported and byte-identical;
+ * versions created from them keep their stored text and still validate. The Solana template is `AGENT_KINDS['solana-transaction-inspection'].template`.
+ */
+export const AGENT_TEMPLATES = Object.freeze([TOKEN_RESEARCHER_MANIFEST_V2, TRANSACTION_INSPECTOR_MANIFEST_V2, WATCHTOWER_MANIFEST_V3]);
+/** Every first-party EVM template version, oldest first. */
+export const AGENT_TEMPLATE_VERSIONS = Object.freeze([TOKEN_RESEARCHER_MANIFEST, TOKEN_RESEARCHER_MANIFEST_V2, TRANSACTION_INSPECTOR_MANIFEST, TRANSACTION_INSPECTOR_MANIFEST_V2, WATCHTOWER_MANIFEST, WATCHTOWER_MANIFEST_V2, WATCHTOWER_MANIFEST_V3]);
+export function agentKindOf(manifest) {
+    const id = manifest?.outputSchemaId;
+    for (const kind of AgentKindSchema.options)
+        if (AGENT_KINDS[kind].outputSchemaId === id)
+            return kind;
+    return null;
+}
+export class UnsupportedAgentKindError extends Error {
+    kind;
+    code = 'UNSUPPORTED_AGENT_KIND';
+    constructor(kind, context) {
+        super(`${context} does not support ${kind ?? 'this unknown'} agent versions.`);
+        this.kind = kind;
+        this.name = 'UnsupportedAgentKindError';
+    }
+}
+export function requireAgentKind(manifest, allowed, context) {
+    const kind = agentKindOf(manifest);
+    if (!kind || !allowed.includes(kind))
+        throw new UnsupportedAgentKindError(kind, context);
+    return kind;
+}
+/** Union for typing and generic clients. Use `parseRunInput` for precise per-kind validation messages. */
+export const RunInputSchema = z.union([ResearchInputSchema, TransactionInspectionInputSchema, WatchtowerWindowInputSchema, WorkflowRunInputSchema, SolanaTransactionInspectionInputSchema, DeployerInvestigationInputSchema, WalletAnalysisInputSchema]);
+/** Workflow inputs carry `workflow`, Solana inspections `analysisChain`, deployer investigations `contract`, wallet analyses `wallet`, token research `address`, Watchtower windows `rules`, EVM payload inspections `from`. */
+export const runInputKind = (input) => 'workflow' in input ? 'workflow' : 'analysisChain' in input ? 'solana-transaction-inspection' : 'wallet' in input ? 'wallet-analysis' : 'contract' in input ? 'deployer-investigation'
+    : 'address' in input ? 'token-research' : 'rules' in input ? 'watchtower' : 'transaction-inspection';
+/** The manifest chain an input targets (`solana` for either Solana cluster). */
+export const runAnalysisChain = (input) => 'analysisChain' in input ? input.analysisChain : input.chain;
+/** The E05 coverage chain: Solana devnet is a separate coverage entry. */
+export const runCoverageChain = (input) => 'analysisChain' in input ? (input.network === 'mainnet-beta' ? 'solana' : 'solana-devnet') : input.chain;
+export function parseRunInput(raw, kind) {
+    const object = raw !== null && typeof raw === 'object' && !Array.isArray(raw);
+    const selected = kind ?? (object && Object.hasOwn(raw, 'workflow') ? 'workflow' : object && Object.hasOwn(raw, 'analysisChain') ? 'solana-transaction-inspection'
+        : object && Object.hasOwn(raw, 'wallet') && !Object.hasOwn(raw, 'address') ? 'wallet-analysis' : object && Object.hasOwn(raw, 'contract') && !Object.hasOwn(raw, 'address') && !Object.hasOwn(raw, 'rules') ? 'deployer-investigation'
+            : object && !Object.hasOwn(raw, 'address') && Object.hasOwn(raw, 'rules') ? 'watchtower'
+                : object && !Object.hasOwn(raw, 'address') && (Object.hasOwn(raw, 'from') || Object.hasOwn(raw, 'data')) ? 'transaction-inspection' : 'token-research');
+    return selected === 'workflow' ? WorkflowRunInputSchema.parse(raw) : selected === 'solana-transaction-inspection' ? SolanaTransactionInspectionInputSchema.parse(raw) : selected === 'token-research' ? ResearchInputSchema.parse(raw)
+        : selected === 'deployer-investigation' ? DeployerInvestigationInputSchema.parse(raw) : selected === 'wallet-analysis' ? WalletAnalysisInputSchema.parse(raw)
+            : selected === 'watchtower' ? WatchtowerWindowInputSchema.parse(raw) : TransactionInspectionInputSchema.parse(raw);
+}
+export function parseRunOutput(kind, raw) {
+    return kind === 'workflow' ? WorkflowReportSchema.parse(raw) : kind === 'solana-transaction-inspection' ? SolanaTransactionInspectionReportSchema.parse(raw) : kind === 'token-research' ? TokenResearchReportSchema.parse(raw)
+        : kind === 'deployer-investigation' ? DeployerInvestigationReportSchema.parse(raw) : kind === 'wallet-analysis' ? WalletAnalysisReportSchema.parse(raw)
+            : kind === 'watchtower' ? WatchtowerWindowReportSchema.parse(raw) : TransactionInspectionReportSchema.parse(raw);
+}

package/dist/packages/contracts/src/report-presentation.d.ts

@@ -0,0 +1,346 @@
+import { z } from 'zod';
+/**
+ * Shared report presentation (R01). Every AGENTEX report renders in one shell (Overview, Findings, Evidence, Sources, Execution, Export);
+ * the archetype and blocks choose how its content is laid out. A workflow version declares them in its manifest: which tool outputs become
+ * bounded tables (`datasets`), which tool observations are carried into the report (`signals`), which log windows state coverage, and the
+ * ordered blocks that render them. Presentation is layout only: it never grants a capability, adds a read or changes a finding, and every
+ * row it carries keeps the evidence of the step that produced it. Fixed first-party kinds map their reports to the same blocks in the web.
+ */
+export declare const REPORT_ARCHETYPES: readonly ["token-protocol", "wallet-flow", "contract-security", "market-liquidity", "governance-treasury", "monitoring-events"];
+export declare const ReportArchetypeSchema: z.ZodEnum<{
+    "token-protocol": "token-protocol";
+    "wallet-flow": "wallet-flow";
+    "contract-security": "contract-security";
+    "market-liquidity": "market-liquidity";
+    "governance-treasury": "governance-treasury";
+    "monitoring-events": "monitoring-events";
+}>;
+export type ReportArchetype = z.infer<typeof ReportArchetypeSchema>;
+/** Column types decide formatting only (addresses shorten and link, amounts keep their exact text); values are never converted. */
+export declare const DatasetColumnTypeSchema: z.ZodEnum<{
+    boolean: "boolean";
+    address: "address";
+    integer: "integer";
+    label: "label";
+    text: "text";
+    amount: "amount";
+    percent: "percent";
+    block: "block";
+    transaction: "transaction";
+    time: "time";
+}>;
+export type DatasetColumnType = z.infer<typeof DatasetColumnTypeSchema>;
+export declare const DatasetSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    node: z.ZodString;
+    path: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            address: "address";
+            integer: "integer";
+            label: "label";
+            text: "text";
+            amount: "amount";
+            percent: "percent";
+            block: "block";
+            transaction: "transaction";
+            time: "time";
+        }>;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    maxRows: z.ZodNumber;
+}, z.core.$strict>;
+export type DatasetSpec = z.infer<typeof DatasetSpecSchema>;
+export declare const ReportBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"metrics">;
+    title: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        section: z.ZodString;
+        finding: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"section">;
+    section: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"table">;
+    dataset: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"bars">;
+    dataset: z.ZodString;
+    label: z.ZodString;
+    value: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"timeline">;
+    dataset: z.ZodString;
+    at: z.ZodString;
+    label: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"flow">;
+    dataset: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    amount: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"graph">;
+    dataset: z.ZodString;
+    to: z.ZodString;
+    relation: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"signals">;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"coverage">;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"limitations">;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+export type ReportBlock = z.infer<typeof ReportBlockSchema>;
+export declare const WorkflowPresentationSchema: z.ZodObject<{
+    archetype: z.ZodEnum<{
+        "token-protocol": "token-protocol";
+        "wallet-flow": "wallet-flow";
+        "contract-security": "contract-security";
+        "market-liquidity": "market-liquidity";
+        "governance-treasury": "governance-treasury";
+        "monitoring-events": "monitoring-events";
+    }>;
+    headline: z.ZodOptional<z.ZodObject<{
+        section: z.ZodString;
+        finding: z.ZodString;
+    }, z.core.$strict>>;
+    datasets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        node: z.ZodString;
+        path: z.ZodString;
+        columns: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            label: z.ZodString;
+            type: z.ZodEnum<{
+                boolean: "boolean";
+                address: "address";
+                integer: "integer";
+                label: "label";
+                text: "text";
+                amount: "amount";
+                percent: "percent";
+                block: "block";
+                transaction: "transaction";
+                time: "time";
+            }>;
+            path: z.ZodString;
+        }, z.core.$strict>>;
+        maxRows: z.ZodNumber;
+    }, z.core.$strict>>>;
+    signals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    coverage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        node: z.ZodString;
+        path: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>>;
+    blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"metrics">;
+        title: z.ZodString;
+        items: z.ZodArray<z.ZodObject<{
+            section: z.ZodString;
+            finding: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"section">;
+        section: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"table">;
+        dataset: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"bars">;
+        dataset: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"timeline">;
+        dataset: z.ZodString;
+        at: z.ZodString;
+        label: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"flow">;
+        dataset: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        amount: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"graph">;
+        dataset: z.ZodString;
+        to: z.ZodString;
+        relation: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"signals">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"coverage">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"limitations">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;
+export type WorkflowPresentation = z.infer<typeof WorkflowPresentationSchema>;
+/** Reference checks against the manifest: nodes are tool nodes, datasets and columns exist, findings are declared. */
+export declare function presentationIssues(presentation: WorkflowPresentation, manifest: {
+    workflow: readonly {
+        id: string;
+        type: string;
+    }[];
+    outputSchema: {
+        sections: readonly {
+            id: string;
+            findings: readonly {
+                code: string;
+            }[];
+        }[];
+    };
+}): {
+    path: (string | number)[];
+    message: string;
+}[];
+export declare const ReportDatasetSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    node: z.ZodString;
+    status: z.ZodEnum<{
+        observed: "observed";
+        unavailable: "unavailable";
+        absent: "absent";
+    }>;
+    reason: z.ZodNullable<z.ZodString>;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            address: "address";
+            integer: "integer";
+            label: "label";
+            text: "text";
+            amount: "amount";
+            percent: "percent";
+            block: "block";
+            transaction: "transaction";
+            time: "time";
+        }>;
+    }, z.core.$strict>>;
+    rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    totalRows: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    evidenceIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ReportDataset = z.infer<typeof ReportDatasetSchema>;
+export declare const ReportSignalSchema: z.ZodObject<{
+    node: z.ZodString;
+    code: z.ZodString;
+    message: z.ZodString;
+    evidenceIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type ReportSignal = z.infer<typeof ReportSignalSchema>;
+export declare const ReportCoverageSchema: z.ZodObject<{
+    node: z.ZodString;
+    label: z.ZodString;
+    status: z.ZodEnum<{
+        observed: "observed";
+        unavailable: "unavailable";
+        absent: "absent";
+    }>;
+    fromBlock: z.ZodNullable<z.ZodString>;
+    toBlock: z.ZodNullable<z.ZodString>;
+    blocks: z.ZodNullable<z.ZodNumber>;
+    requestedBlocks: z.ZodNullable<z.ZodNumber>;
+    complete: z.ZodNullable<z.ZodBoolean>;
+    reason: z.ZodNullable<z.ZodString>;
+    approximateDuration: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ReportCoverage = z.infer<typeof ReportCoverageSchema>;
+/** `agentName` is the listed version's name, so shared and saved reports can title themselves without the manifest. */
+export declare const ReportPresentationSchema: z.ZodObject<{
+    archetype: z.ZodEnum<{
+        "token-protocol": "token-protocol";
+        "wallet-flow": "wallet-flow";
+        "contract-security": "contract-security";
+        "market-liquidity": "market-liquidity";
+        "governance-treasury": "governance-treasury";
+        "monitoring-events": "monitoring-events";
+    }>;
+    agentName: z.ZodOptional<z.ZodString>;
+    headline: z.ZodNullable<z.ZodObject<{
+        section: z.ZodString;
+        finding: z.ZodString;
+    }, z.core.$strict>>;
+    blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"metrics">;
+        title: z.ZodString;
+        items: z.ZodArray<z.ZodObject<{
+            section: z.ZodString;
+            finding: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"section">;
+        section: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"table">;
+        dataset: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"bars">;
+        dataset: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"timeline">;
+        dataset: z.ZodString;
+        at: z.ZodString;
+        label: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"flow">;
+        dataset: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+        amount: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"graph">;
+        dataset: z.ZodString;
+        to: z.ZodString;
+        relation: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"signals">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"coverage">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"limitations">;
+        title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+}, z.core.$strict>;

package/dist/packages/contracts/src/report-presentation.js

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+/**
+ * Shared report presentation (R01). Every AGENTEX report renders in one shell (Overview, Findings, Evidence, Sources, Execution, Export);
+ * the archetype and blocks choose how its content is laid out. A workflow version declares them in its manifest: which tool outputs become
+ * bounded tables (`datasets`), which tool observations are carried into the report (`signals`), which log windows state coverage, and the
+ * ordered blocks that render them. Presentation is layout only: it never grants a capability, adds a read or changes a finding, and every
+ * row it carries keeps the evidence of the step that produced it. Fixed first-party kinds map their reports to the same blocks in the web.
+ */
+export const REPORT_ARCHETYPES = ['token-protocol', 'wallet-flow', 'contract-security', 'market-liquidity', 'governance-treasury', 'monitoring-events'];
+export const ReportArchetypeSchema = z.enum(REPORT_ARCHETYPES);
+const Identifier = z.string().regex(/^[a-z][a-z0-9._-]{0,63}$/);
+/** A dot path into a tool output (`summary.poolsText`, `pools`, `largestTransfers.0`). Empty means the value itself. */
+const OutputPath = z.string().max(120).regex(/^([A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*)?$/);
+const Title = z.string().min(1).max(80);
+/** Column keys may be camelCase (they name output fields). */
+const ColumnKey = z.string().regex(/^[a-z][a-zA-Z0-9_-]{0,39}$/);
+/** Column types decide formatting only (addresses shorten and link, amounts keep their exact text); values are never converted. */
+export const DatasetColumnTypeSchema = z.enum(['text', 'label', 'address', 'amount', 'integer', 'percent', 'block', 'transaction', 'boolean', 'time']);
+export const DatasetSpecSchema = z.strictObject({
+    id: Identifier, title: Title, node: Identifier, path: OutputPath,
+    columns: z.array(z.strictObject({ key: ColumnKey, label: z.string().min(1).max(60), type: DatasetColumnTypeSchema, path: OutputPath })).min(1).max(8),
+    maxRows: z.number().int().min(1).max(25),
+});
+const FindingRef = z.strictObject({ section: Identifier, finding: Identifier });
+const DatasetColumnRef = ColumnKey;
+export const ReportBlockSchema = z.discriminatedUnion('type', [
+    /** Headline figures: up to eight findings shown as a metric grid, each with its evidence. */
+    z.strictObject({ type: z.literal('metrics'), title: Title, items: z.array(FindingRef).min(1).max(8) }),
+    /** One declared section as a labelled list of its findings. */
+    z.strictObject({ type: z.literal('section'), section: Identifier }),
+    z.strictObject({ type: z.literal('table'), dataset: Identifier, title: Title.optional() }),
+    /** Horizontal bars of one numeric column per row (amounts and percentages keep their exact text beside the bar). */
+    z.strictObject({ type: z.literal('bars'), dataset: Identifier, label: DatasetColumnRef, value: DatasetColumnRef, title: Title.optional() }),
+    /** Rows ordered by a block or integer column. */
+    z.strictObject({ type: z.literal('timeline'), dataset: Identifier, at: DatasetColumnRef, label: DatasetColumnRef, detail: DatasetColumnRef.optional(), title: Title.optional() }),
+    /** Movements between two parties per row, with an optional amount. */
+    z.strictObject({ type: z.literal('flow'), dataset: Identifier, from: DatasetColumnRef, to: DatasetColumnRef, amount: DatasetColumnRef.optional(), title: Title.optional() }),
+    /** Entity relationships: the report subject (or a `from` column) linked to each row's `to` entity by `relation`. */
+    z.strictObject({ type: z.literal('graph'), dataset: Identifier, to: DatasetColumnRef, relation: DatasetColumnRef.optional(), from: DatasetColumnRef.optional(), title: Title.optional() }),
+    z.strictObject({ type: z.literal('signals'), title: Title.optional() }),
+    z.strictObject({ type: z.literal('coverage'), title: Title.optional() }),
+    z.strictObject({ type: z.literal('limitations'), title: Title.optional() }),
+]);
+export const WorkflowPresentationSchema = z.strictObject({
+    archetype: ReportArchetypeSchema,
+    /** The finding that states the result in one sentence; it leads the Overview. */
+    headline: FindingRef.optional(),
+    datasets: z.array(DatasetSpecSchema).max(8).optional(),
+    /** Tool nodes whose own observations (code, message, evidence) are carried into the report as signals. */
+    signals: z.array(Identifier).max(6).optional(),
+    /** Tool outputs holding a bounded block window (`coverage` of log-reading tools), shown as stated coverage. */
+    coverage: z.array(z.strictObject({ node: Identifier, path: OutputPath, label: z.string().min(1).max(60) })).max(4).optional(),
+    blocks: z.array(ReportBlockSchema).min(1).max(14),
+});
+/** Reference checks against the manifest: nodes are tool nodes, datasets and columns exist, findings are declared. */
+export function presentationIssues(presentation, manifest) {
+    const issues = [];
+    const at = (...path) => ['presentation', ...path];
+    const toolNodes = new Set(manifest.workflow.filter((node) => node.type === 'tool').map((node) => node.id));
+    const findingExists = (ref) => manifest.outputSchema.sections.some((section) => section.id === ref.section && section.findings.some((item) => item.code === ref.finding));
+    const declared = presentation.datasets ?? [];
+    const signals = presentation.signals ?? [];
+    const coverage = presentation.coverage ?? [];
+    const datasets = new Map(declared.map((dataset) => [dataset.id, dataset]));
+    if (datasets.size !== declared.length)
+        issues.push({ path: at('datasets'), message: 'Duplicate dataset id' });
+    declared.forEach((dataset, position) => {
+        if (!toolNodes.has(dataset.node))
+            issues.push({ path: at('datasets', position, 'node'), message: `Dataset ${dataset.id} must read a tool node` });
+        if (new Set(dataset.columns.map((column) => column.key)).size !== dataset.columns.length)
+            issues.push({ path: at('datasets', position, 'columns'), message: `Duplicate column in dataset ${dataset.id}` });
+    });
+    signals.forEach((node, position) => { if (!toolNodes.has(node))
+        issues.push({ path: at('signals', position), message: `Signals must come from a tool node (${node})` }); });
+    if (new Set(signals).size !== signals.length)
+        issues.push({ path: at('signals'), message: 'Duplicate signal node' });
+    coverage.forEach((item, position) => { if (!toolNodes.has(item.node))
+        issues.push({ path: at('coverage', position, 'node'), message: `Coverage must come from a tool node (${item.node})` }); });
+    if (presentation.headline && !findingExists(presentation.headline))
+        issues.push({ path: at('headline'), message: `Headline ${presentation.headline.section}.${presentation.headline.finding} is not a declared finding` });
+    presentation.blocks.forEach((block, position) => {
+        if (block.type === 'metrics')
+            block.items.forEach((item, index) => { if (!findingExists(item))
+                issues.push({ path: at('blocks', position, 'items', index), message: `Metric ${item.section}.${item.finding} is not a declared finding` }); });
+        if (block.type === 'section' && !manifest.outputSchema.sections.some((section) => section.id === block.section))
+            issues.push({ path: at('blocks', position, 'section'), message: `Section ${block.section} is not declared` });
+        if (block.type === 'signals' && !signals.length)
+            issues.push({ path: at('blocks', position), message: 'A signals block needs at least one signal node' });
+        if (block.type === 'coverage' && !coverage.length)
+            issues.push({ path: at('blocks', position), message: 'A coverage block needs at least one coverage source' });
+        if ('dataset' in block) {
+            const dataset = datasets.get(block.dataset);
+            if (!dataset) {
+                issues.push({ path: at('blocks', position, 'dataset'), message: `Dataset ${block.dataset} is not declared` });
+                return;
+            }
+            const columns = new Set(dataset.columns.map((column) => column.key));
+            for (const key of ['label', 'value', 'at', 'detail', 'from', 'to', 'amount', 'relation']) {
+                const ref = block[key];
+                if (typeof ref === 'string' && !columns.has(ref))
+                    issues.push({ path: at('blocks', position, key), message: `Column ${ref} is not in dataset ${dataset.id}` });
+            }
+        }
+    });
+    return issues;
+}
+/** Report fields a presentation produces. Rows hold exact scalar values from the step output (null where the output has none). */
+const Cell = z.union([z.string().max(200), z.number().finite(), z.boolean(), z.null()]);
+export const ReportDatasetSchema = z.strictObject({
+    id: Identifier, title: Title, node: Identifier, status: z.enum(['observed', 'absent', 'unavailable']), reason: z.string().max(300).nullable(),
+    columns: z.array(z.strictObject({ key: ColumnKey, label: z.string().max(60), type: DatasetColumnTypeSchema })).max(8),
+    rows: z.array(z.array(Cell).max(8)).max(25), totalRows: z.number().int().nonnegative(), truncated: z.boolean(), evidenceIds: z.array(z.string()).max(64),
+});
+export const ReportSignalSchema = z.strictObject({ node: Identifier, code: z.string().max(64), message: z.string().max(600), evidenceIds: z.array(z.string()).max(16) });
+export const ReportCoverageSchema = z.strictObject({
+    node: Identifier, label: z.string().max(60), status: z.enum(['observed', 'absent', 'unavailable']), fromBlock: z.string().max(24).nullable(), toBlock: z.string().max(24).nullable(),
+    blocks: z.number().int().nonnegative().nullable(), requestedBlocks: z.number().int().nonnegative().nullable(), complete: z.boolean().nullable(), reason: z.string().max(300).nullable(), approximateDuration: z.string().max(60).nullable(),
+});
+/** `agentName` is the listed version's name, so shared and saved reports can title themselves without the manifest. */
+export const ReportPresentationSchema = z.strictObject({ archetype: ReportArchetypeSchema, agentName: z.string().max(100).optional(), headline: FindingRef.nullable(), blocks: z.array(ReportBlockSchema).max(14) });