@pikku/core 0.12.71 → 0.12.74

package/dist/wirings/virtual-user/run-virtual-user.js

@@ -0,0 +1,478 @@
+import { getDurationInMilliseconds } from '../../time-utils.js';
+import { catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, } from './virtual-user-catalogue.js';
+import { dispositionProfile, } from './virtual-user-dispositions.js';
+import { IntentStack, intentsForPersona } from './virtual-user-intents.js';
+import { createRng } from './virtual-user-rng.js';
+/** One turn: what the user decided to do next, and why. */
+const ACTION_SCHEMA = {
+    type: 'object',
+    properties: {
+        thought: { type: 'string' },
+        kind: {
+            type: 'string',
+            enum: ['describe', 'call', 'talkTo', 'upload', 'complete', 'stuck'],
+        },
+        rpcName: { type: 'string' },
+        /**
+         * A JSON object, as a string. Not `type: 'object'`: structured output is
+         * strict, and a schema-less object is the one thing strict mode cannot
+         * express — OpenAI rejects the whole request with "'additionalProperties'
+         * is required to be supplied and to be false", so every turn 400s and the
+         * run never takes a step. The arguments differ per endpoint and are only
+         * known from the `describe` the user just did, so there is no schema to
+         * give here; a string is how a free-form object crosses that boundary.
+         */
+        args: { type: 'string' },
+        agent: { type: 'string' },
+        task: { type: 'string' },
+        file: { type: 'string' },
+        summary: { type: 'string' },
+    },
+    required: ['kind'],
+};
+const DEFAULT_MAX_STEPS = 40;
+const DEFAULT_MAX_STEPS_PER_INTENT = 20;
+const RESPONSE_EXCERPT = 600;
+const msg = (role, content) => ({
+    id: globalThis.crypto.randomUUID(),
+    role,
+    content,
+    createdAt: new Date(),
+});
+/** Read a structured result, falling back to parsing JSON out of the text. */
+const readObject = (result) => {
+    if (result.object && typeof result.object === 'object')
+        return result.object;
+    if (result.text) {
+        try {
+            return JSON.parse(result.text);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+};
+/**
+ * The arguments for a call, however the model chose to spell them.
+ *
+ * `ACTION_SCHEMA` asks for a JSON string because strict structured output
+ * cannot carry a schema-less object, but a model reading the endpoint's own
+ * schema will sometimes send the object anyway, and a scripted or non-strict
+ * provider always will. Both are the same intent, so both are accepted; text
+ * that is not JSON at all is not arguments, and calling with it would only
+ * produce a 400 attributable to the wrong thing.
+ */
+const readArgs = (args) => {
+    if (args && typeof args === 'object')
+        return args;
+    if (typeof args === 'string' && args.trim()) {
+        try {
+            const parsed = JSON.parse(args);
+            if (parsed && typeof parsed === 'object') {
+                return parsed;
+            }
+        }
+        catch {
+            // Not JSON — fall through to no arguments.
+        }
+    }
+    return {};
+};
+/** Keys worth remembering across intents — the things a person writes down. */
+const MEMORABLE = /(id|slug|token|email|name|key|url|code)$/i;
+/**
+ * Pull identifiers out of a response so later intents can refer to them.
+ *
+ * This is what makes a run cohesive without ever handing the user a dataflow
+ * map: it discovers that a project has an id by looking at one, the same way a
+ * person reads it off the screen.
+ */
+export const rememberIds = (body, into, depth = 0) => {
+    if (depth > 4 || body === null || typeof body !== 'object')
+        return into;
+    if (Array.isArray(body)) {
+        for (const item of body.slice(0, 5))
+            rememberIds(item, into, depth + 1);
+        return into;
+    }
+    for (const [key, value] of Object.entries(body)) {
+        if (typeof value === 'string' && MEMORABLE.test(key) && value.length < 200) {
+            into[key] = value;
+        }
+        else if (typeof value === 'object') {
+            rememberIds(value, into, depth + 1);
+        }
+    }
+    return into;
+};
+const personaInstructions = (persona, profile, catalogue, agents, fixtures) => [
+    `You are a real person using a product through its API. Stay in character; you are the user, not the system.`,
+    `Your name is ${persona.name}.`,
+    persona.jobTitle ? `Your role: ${persona.jobTitle}.` : '',
+    persona.personality ? `Your manner: ${persona.personality}.` : '',
+    '',
+    profile.instructions,
+    '',
+    `Each turn you take exactly ONE action:`,
+    `- describe: read an endpoint's schema. You MUST describe an endpoint before you may call it.`,
+    `- call: invoke an endpoint with arguments that fit its schema. Put them in 'args' as a JSON object written as a string, e.g. "{\\"id\\":\\"abc\\"}".`,
+    agents.length
+        ? `- talkTo: ask one of the product's assistants to do something for you in plain language.`
+        : '',
+    fixtures.length ? `- upload: send one of your files.` : '',
+    `- complete: you got what you came for.`,
+    `- stuck: you cannot get there, and you can say why.`,
+    '',
+    agents.length
+        ? `Assistants you can talk to:\n${agents
+            .map((agent) => `- ${agent.name}${agent.description ? `: ${agent.description}` : ''}`)
+            .join('\n')}`
+        : '',
+    fixtures.length ? `Files you have: ${fixtures.join(', ')}` : '',
+    '',
+    `The endpoints available to you, as name(inputs) -> outputs:`,
+    catalogue,
+]
+    .filter(Boolean)
+    .join('\n');
+/**
+ * Run one virtual user against a live target until its budget runs out.
+ *
+ * The engine schedules which intent is live and the model decides what to do
+ * within it — that split is what lets a run be replayed from its seed while the
+ * work inside it stays genuinely open-ended.
+ */
+export const runVirtualUser = async (params) => {
+    const { persona, personaId, disposition = 'realistic', tuning, target, llm, model, budget, stop, validateOutput, classify, fixtures = [], agents = [], scopes, allowApprovalRequired = false, maxStepsPerIntent = DEFAULT_MAX_STEPS_PER_INTENT, } = params;
+    const profile = dispositionProfile(disposition, tuning);
+    const seed = params.seed ?? Math.floor(Math.random() * 2 ** 31);
+    const rng = createRng(seed);
+    const startedAt = Date.now();
+    // An adversarial user is offered the whole surface on purpose — probing what
+    // it should not reach is the behaviour under test — while `scopes` stays live
+    // below as the oracle that says a success there was a finding.
+    const reachable = reachableCatalogue(params.catalogue, {
+        readOnly: profile.readOnly,
+        allowApprovalRequired,
+        scopes: profile.invertedOracle ? undefined : scopes,
+    });
+    const index = catalogueIndex(reachable);
+    const sources = [
+        ...intentsForPersona(params.intents, personaId),
+        ...(params.goals ?? []).map((goal, i) => ({
+            id: `goal_${i + 1}`,
+            title: goal,
+        })),
+    ];
+    const stack = new IntentStack(sources, rng, profile);
+    const memory = profile.emptyMemory
+        ? {}
+        : { ...(params.memory ?? {}) };
+    const described = new Set();
+    const findings = [];
+    const steps = [];
+    const history = new Map();
+    const tally = {
+        steps: 0,
+        calls: 0,
+        mutations: 0,
+        tokensIn: 0,
+        tokensOut: 0,
+        model,
+        elapsedMs: 0,
+        findings: 0,
+    };
+    const maxSteps = budget?.steps ?? DEFAULT_MAX_STEPS;
+    const maxDurationMs = budget?.duration === undefined
+        ? undefined
+        : typeof budget.duration === 'number'
+            ? budget.duration
+            : getDurationInMilliseconds(budget.duration);
+    const instructions = personaInstructions(persona, profile, renderCatalogue(reachable), agents, fixtures);
+    const addFinding = (finding) => {
+        findings.push(finding);
+        tally.findings++;
+    };
+    // Every other exit sets this and breaks; running the loop out means the step
+    // budget is what ended it.
+    let stoppedBy = 'budget-steps';
+    for (let step = 0; step < maxSteps; step++) {
+        tally.elapsedMs = Date.now() - startedAt;
+        if (maxDurationMs !== undefined && tally.elapsedMs >= maxDurationMs) {
+            stoppedBy = 'budget-duration';
+            break;
+        }
+        if (budget?.mutations !== undefined && tally.mutations >= budget.mutations) {
+            stoppedBy = 'budget-mutations';
+            break;
+        }
+        if (stop && (await stop({ ...tally }))) {
+            stoppedBy = 'stop-hook';
+            break;
+        }
+        const tick = stack.next(step);
+        if (!tick) {
+            // Nothing left to schedule: either this user was given no intents at all,
+            // or it saw every one of them through.
+            stoppedBy = stack.records().length === 0 ? 'no-intents' : 'exhausted';
+            break;
+        }
+        // A user who cannot get anywhere gives up rather than looping forever.
+        if (tick.intent.steps.length > maxStepsPerIntent) {
+            stack.stuck('gave up after going in circles');
+            continue;
+        }
+        const intentId = tick.intent.id;
+        if (!history.has(intentId)) {
+            const source = tick.intent.source;
+            history.set(intentId, [
+                msg('user', [
+                    `What you want to do right now: ${source.title}`,
+                    source.description ?? '',
+                    source.steps?.length
+                        ? `Roughly how it goes:\n${source.steps.map((s) => `- ${s}`).join('\n')}`
+                        : '',
+                    `Work it out through the API yourself — nobody has told you which endpoints do this.`,
+                ]
+                    .filter(Boolean)
+                    .join('\n')),
+            ]);
+        }
+        const messages = history.get(intentId);
+        if (tick.move === 'resume' || tick.move === 'suspend') {
+            messages.push(msg('user', `You were pulled away and have come back to this. Things may have changed since.`));
+        }
+        // Whether this user trusts its notes this turn or goes and looks again.
+        // `stale` almost always trusts them, a newcomer has none to trust, and an
+        // auditor checks nearly everything — which is the whole difference between
+        // those runs, expressed as one roll rather than as prose.
+        if (Object.keys(memory).length && !rng.chance(profile.reReadRate)) {
+            messages.push(msg('user', `Things you have noted down: ${Object.entries(memory)
+                .slice(-25)
+                .map(([key, value]) => `${key}=${value}`)
+                .join(', ')}`));
+        }
+        else if (Object.keys(memory).length) {
+            messages.push(msg('user', `You are not sure your notes are current. Look things up.`));
+        }
+        const result = await llm({
+            model,
+            temperature: profile.temperature,
+            instructions,
+            messages,
+            tools: [],
+            maxSteps: 1,
+            toolChoice: 'none',
+            outputSchema: ACTION_SCHEMA,
+        });
+        tally.steps++;
+        tally.tokensIn += result.usage?.inputTokens ?? 0;
+        tally.tokensOut += result.usage?.outputTokens ?? 0;
+        const raw = readObject(result);
+        const record = {
+            index: step,
+            intentId,
+            action: { kind: 'invalid', detail: 'no action produced' },
+            tokensIn: result.usage?.inputTokens ?? 0,
+            tokensOut: result.usage?.outputTokens ?? 0,
+        };
+        if (!raw || typeof raw.kind !== 'string') {
+            steps.push(record);
+            messages.push(msg('user', 'That was not a valid action. Choose one action.'));
+            continue;
+        }
+        const action = { ...raw, kind: raw.kind };
+        record.action = action;
+        messages.push(msg('assistant', JSON.stringify(raw)));
+        /** Tell the user what happened, so the next turn is informed. */
+        const reply = (text) => messages.push(msg('user', text));
+        if (action.kind === 'complete') {
+            stack.complete(action.summary);
+            steps.push(record);
+            continue;
+        }
+        if (action.kind === 'stuck') {
+            stack.stuck(action.reason);
+            steps.push(record);
+            continue;
+        }
+        if (action.kind === 'describe') {
+            const entry = catalogueLookup(index, action.rpcName);
+            if (!entry) {
+                reply(`There is no endpoint called '${action.rpcName}'.`);
+                steps.push(record);
+                continue;
+            }
+            described.add(entry.name);
+            // Saying the gate is now open matters: reading a schema is free and
+            // calling is not, so a model left to infer it will happily spend a whole
+            // budget describing one endpoint after another and never touch the app.
+            reply(`${JSON.stringify(describeEntry(entry))}\nYou have read this one, so you may now call '${entry.name}'.`);
+            steps.push(record);
+            continue;
+        }
+        if (action.kind === 'talkTo') {
+            if (!target.talkTo) {
+                reply('There is nobody to talk to here.');
+                steps.push(record);
+                continue;
+            }
+            const verdict = await target.talkTo(action.agent, action.task);
+            record.ok = verdict.passed;
+            record.response = verdict.reasoning.slice(0, RESPONSE_EXCERPT);
+            reply(`You spoke to ${action.agent}. ${verdict.passed ? 'It sorted it out.' : 'It did not.'} ${verdict.reasoning}`);
+            steps.push(record);
+            continue;
+        }
+        if (action.kind === 'upload') {
+            if (!target.upload) {
+                reply('You have nowhere to send a file.');
+                steps.push(record);
+                continue;
+            }
+            const response = await target.upload(action.file);
+            record.status = response.status;
+            record.ok = response.ok;
+            record.response = response.serialized.slice(0, RESPONSE_EXCERPT);
+            if (response.status >= 500) {
+                record.findingKinds = ['server-error'];
+                addFinding({
+                    kind: 'server-error',
+                    detail: `upload '${action.file}' returned ${response.status}`,
+                    status: response.status,
+                    intentId,
+                    step,
+                });
+            }
+            reply(`Upload came back ${response.status}: ${record.response}`);
+            steps.push(record);
+            continue;
+        }
+        // Everything below is a call.
+        const entry = catalogueLookup(index, action.rpcName);
+        if (!entry) {
+            reply(`There is no endpoint called '${action.rpcName}'.`);
+            steps.push(record);
+            continue;
+        }
+        if (!described.has(entry.name)) {
+            // Enforced rather than merely asked for: guessing field names is
+            // unproductive fuzz that turns every 400 into a typo. Handing back the
+            // schema makes this self-correcting in one turn.
+            reply(`You do not know this endpoint's fields yet. Its schema is: ${JSON.stringify(describeEntry(entry))}`);
+            described.add(entry.name);
+            steps.push(record);
+            continue;
+        }
+        // What may be called is decided once, when the catalogue is narrowed: a
+        // read-only disposition is never offered a mutation and an approval-gated
+        // endpoint is never offered at all, so `index` is the gate and there is no
+        // second one here to drift out of step with it.
+        const mutating = !isReadOnly(entry);
+        const args = readArgs(action.args);
+        const repeats = profile.repeatRate > 0 && rng.chance(profile.repeatRate) ? 2 : 1;
+        let lastResponseText = '';
+        for (let attempt = 0; attempt < repeats; attempt++) {
+            let response;
+            try {
+                response = await target.call(entry.name, args);
+            }
+            catch (error) {
+                record.findingKinds = [...(record.findingKinds ?? []), 'transport-error'];
+                addFinding({
+                    kind: 'transport-error',
+                    detail: `${entry.name} threw: ${error.message}`,
+                    rpcName: entry.name,
+                    intentId,
+                    step,
+                });
+                lastResponseText = `The request failed outright: ${error.message}`;
+                break;
+            }
+            tally.calls++;
+            if (mutating)
+                tally.mutations++;
+            record.status = response.status;
+            record.ok = response.ok;
+            record.response = response.serialized.slice(0, RESPONSE_EXCERPT);
+            lastResponseText = `${response.status}: ${record.response}`;
+            const kinds = [];
+            if (response.status >= 500) {
+                kinds.push('server-error');
+                addFinding({
+                    kind: 'server-error',
+                    detail: `${entry.name} returned ${response.status}`,
+                    rpcName: entry.name,
+                    status: response.status,
+                    intentId,
+                    step,
+                });
+            }
+            if (response.ok && validateOutput) {
+                const problem = validateOutput(entry.name, response.body);
+                if (problem) {
+                    kinds.push('schema-violation');
+                    addFinding({
+                        kind: 'schema-violation',
+                        detail: `${entry.name} answered outside its own output schema: ${problem}`,
+                        rpcName: entry.name,
+                        status: response.status,
+                        intentId,
+                        step,
+                    });
+                }
+            }
+            // This persona does not hold the scopes this endpoint declares, and the
+            // server served it anyway — the declaration and the enforcement disagree.
+            if (response.ok &&
+                scopes &&
+                entry.scopes?.some((scope) => !scopes.includes(scope))) {
+                kinds.push('unexpected-success');
+                addFinding({
+                    kind: 'unexpected-success',
+                    detail: `${entry.name} succeeded for '${personaId}', who does not hold ${entry.scopes
+                        .filter((scope) => !scopes.includes(scope))
+                        .join(', ')}`,
+                    rpcName: entry.name,
+                    status: response.status,
+                    intentId,
+                    step,
+                });
+            }
+            for (const finding of classify?.({
+                rpcName: entry.name,
+                args,
+                status: response.status,
+                ok: response.ok,
+                body: response.body,
+                intentId,
+                step,
+                disposition,
+            }) ?? []) {
+                kinds.push(finding.kind);
+                addFinding({ ...finding, step });
+            }
+            if (kinds.length) {
+                record.findingKinds = [...(record.findingKinds ?? []), ...kinds];
+            }
+            if (response.ok)
+                rememberIds(response.body, memory);
+            if (attempt + 1 < repeats) {
+                lastResponseText += ` (you were not sure it went through, so you sent it again)`;
+            }
+        }
+        reply(lastResponseText);
+        steps.push(record);
+    }
+    tally.elapsedMs = Date.now() - startedAt;
+    return {
+        seed,
+        tally,
+        findings,
+        intents: stack.records(),
+        steps,
+        memory,
+        stoppedBy,
+    };
+};

package/dist/wirings/virtual-user/virtual-user-agents.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Which of the product's agents a persona can actually talk to.
+ *
+ * An agent is not something a persona declares. It is something a persona
+ * *reaches*, under exactly the rule an RPC is reached by: `CoreAIAgent.scopes`
+ * is checked against the session, so a persona holding the scopes an agent
+ * requires finds it in front of them, and one that does not, does not.
+ *
+ * That is the whole reason a persona has no `agent:` field. Naming one would
+ * add no capability the roles do not already confer, and would narrow the
+ * persona to a single brain when the interesting behaviour is the choice
+ * between calling the API directly and handing the work to a specialist.
+ */
+/** The part of an agent's meta this needs. */
+export interface AgentReachability {
+    name?: string;
+    description?: string;
+    scopes?: readonly string[];
+    auth?: boolean;
+}
+/** One agent, as it is offered to a virtual user. */
+export interface ReachableAgent {
+    name: string;
+    description?: string;
+}
+/**
+ * The agents to offer, keyed by the name they are declared under.
+ *
+ * Like {@link reachableCatalogue}, this narrows *what is offered* and never
+ * what is enforced: the server decides who may talk to what, and an agent
+ * answering a persona this filter would have withheld is a finding rather than
+ * a bug here.
+ *
+ * An agent declaring no scopes is offered to everybody, on the same terms as a
+ * function that gates itself with none — undeclared is not the same as denied,
+ * and inventing a denial here would hide the endpoints that really are open.
+ */
+export declare const reachableAgents: (agents: Readonly<Record<string, AgentReachability>>, scopes?: readonly string[]) => ReachableAgent[];

package/dist/wirings/virtual-user/virtual-user-agents.js

@@ -0,0 +1,24 @@
+import { hasScopes } from '../../scopes.js';
+/**
+ * The agents to offer, keyed by the name they are declared under.
+ *
+ * Like {@link reachableCatalogue}, this narrows *what is offered* and never
+ * what is enforced: the server decides who may talk to what, and an agent
+ * answering a persona this filter would have withheld is a finding rather than
+ * a bug here.
+ *
+ * An agent declaring no scopes is offered to everybody, on the same terms as a
+ * function that gates itself with none — undeclared is not the same as denied,
+ * and inventing a denial here would hide the endpoints that really are open.
+ */
+export const reachableAgents = (agents, scopes) => Object.entries(agents)
+    .filter(([, agent]) => {
+    if (!scopes || !agent.scopes?.length) {
+        return true;
+    }
+    return hasScopes(agent.scopes, scopes);
+})
+    .map(([id, agent]) => ({
+    name: agent.name ?? id,
+    ...(agent.description ? { description: agent.description } : {}),
+}));

package/dist/wirings/virtual-user/virtual-user-catalogue.d.ts

@@ -0,0 +1,92 @@
+import type { ApiCatalogueEntry } from './virtual-user.types.js';
+/**
+ * Whether a call only reads.
+ *
+ * An explicit annotation always wins. Without one, the name decides — because
+ * an unannotated function means "nobody said", not "safe", and silently
+ * treating 395 unannotated endpoints as read-only is how a virtual user
+ * deploys something. {@link catalogueClassification} reports how much of the
+ * catalogue rests on this guess so the gap is visible rather than assumed.
+ */
+export declare const isReadOnly: (entry: ApiCatalogueEntry) => boolean;
+/** How much of a catalogue's read/write split is annotation and how much is guess. */
+export declare const catalogueClassification: (entries: readonly ApiCatalogueEntry[]) => {
+    total: number;
+    annotated: number;
+    inferred: number;
+};
+/**
+ * The whole reachable API as one compact index, for the instructions.
+ *
+ * Every endpoint is listed rather than retrieved against. Measured on a 430-RPC
+ * project this is ~8k tokens, cached for the life of the run — cheaper than any
+ * retrieval step, and it hides nothing. A ranking function would make the
+ * virtual user only as adventurous as the ranking, which loses exactly the
+ * endpoints worth stumbling into.
+ */
+export declare const renderCatalogue: (entries: readonly ApiCatalogueEntry[]) => string;
+/**
+ * The entries a given user may reach: approval-gated calls dropped unless the
+ * run opted in, mutations dropped for a read-only disposition, and anything the
+ * actor's tier cannot satisfy dropped when the caller supplied one.
+ *
+ * This narrows *what is offered*, never what is enforced — the server is the
+ * only thing that decides who may call what, and a call this filter would have
+ * denied still going through is a finding rather than a bug in the filter.
+ */
+export declare const reachableCatalogue: (entries: readonly ApiCatalogueEntry[], { readOnly, allowApprovalRequired, scopes, }?: {
+    readOnly?: boolean;
+    allowApprovalRequired?: boolean;
+    /**
+     * The scopes this persona holds, resolved from its roles. Omit to keep
+     * every entry.
+     *
+     * Scopes rather than permission-function names: a function's `scopes` are
+     * declared and checkable, whereas a permission is arbitrary code whose
+     * verdict nobody can predict without running it. Narrowing by something
+     * unpredictable produced a catalogue that was wrong in both directions.
+     */
+    scopes?: readonly string[];
+}) => ApiCatalogueEntry[];
+/**
+ * Endpoints this persona is *not* entitled to reach.
+ *
+ * The adversarial oracle. Withheld from the catalogue, so reaching one takes
+ * initiative — and a 2xx from one is the finding, because the server is the
+ * only thing that decides who may call what.
+ */
+export declare const unreachableCatalogue: (entries: readonly ApiCatalogueEntry[], scopes: readonly string[]) => ApiCatalogueEntry[];
+/** Index a catalogue by name for the engine's lookups. */
+export declare const catalogueIndex: (entries: readonly ApiCatalogueEntry[]) => Map<string, ApiCatalogueEntry>;
+/**
+ * Find an entry by the name a model gave, forgiving the signature it just read.
+ *
+ * The catalogue renders as `name(inputs) -> outputs`, and a model that has the
+ * line in front of it will sometimes hand the whole line back — `whoAmI() ->
+ * userId,scopes` instead of `whoAmI`. Measured on a live run, 8 of 24 steps
+ * went that way and every one of them was answered with "there is no endpoint
+ * called that", which is true and useless.
+ *
+ * Forgiving it is not the same as guessing: an rpc name never contains a
+ * bracket, so everything from the first one is the signature the catalogue
+ * printed, and taking it off is unambiguous.
+ */
+export declare const catalogueLookup: (index: Map<string, ApiCatalogueEntry>, rpcName: string) => ApiCatalogueEntry | undefined;
+/**
+ * What `describe` hands back: the full schemas, so the next call can be made
+ * correctly rather than guessed at.
+ *
+ * Guessing field names is unproductive fuzz — every 400 becomes a typo and
+ * nothing is learned from any of them. Reading the schema first is also what a
+ * person does, since the form tells them the fields. It makes a subsequent 400
+ * mean something: either the schema and the implementation disagree, or the
+ * misuse is genuine and worth seeing.
+ */
+export declare const describeEntry: (entry: ApiCatalogueEntry) => {
+    name: string;
+    description: string | undefined;
+    readonly: boolean;
+    approvalRequired: boolean;
+    input: Record<string, unknown>;
+    output: Record<string, unknown> | null;
+};