@autoview/cli 0.1.0

package/lib/agent/toolSurface.js

@@ -0,0 +1,342 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolSurface = buildToolSurface;
+exports.analyzeConsumability = analyzeConsumability;
+exports.coverToolSurface = coverToolSurface;
+const classifyEndpoints_1 = require("../utils/classifyEndpoints");
+const extractFields_1 = require("../utils/extractFields");
+const toEndpoints_1 = require("../utils/toEndpoints");
+const READ_ROLES = new Set(["list", "search", "detail"]);
+/** Field names that identify a record (the value a path param consumes). */
+const ID_NAMES = ["id", "uuid"];
+/** The first identifying field name present (`id` preferred over `uuid`), or null. */
+const firstIdName = (names) => {
+    var _a;
+    const set = new Set([...names].map((n) => n.toLowerCase()));
+    return (_a = ID_NAMES.find((n) => set.has(n))) !== null && _a !== void 0 ? _a : null;
+};
+/**
+ * Whether a read endpoint's response element carries an identifying field
+ * (`id` / `uuid`) — i.e. whether it can PRODUCE an id for a consumer. Handles
+ * both named component responses and INLINE response schemas, and collection
+ * wrappers named generically (`data`/`entries`) OR after the resource
+ * (`{ databases: [...] }`, DigitalOcean), including inline array items.
+ */
+function producedIdField(op, doc) {
+    var _a;
+    // Named-type path (nestia/AutoBE convention).
+    if (op.responseBody !== null) {
+        const elementFields = op.responseBody.isArray
+            ? (0, extractFields_1.extractFields)(op.responseBody.typeName, doc)
+            : (() => {
+                var _a;
+                const top = (0, extractFields_1.extractFields)(op.responseBody.typeName, doc);
+                // The collection field is either generically named (`data`/`entries`)
+                // or named after the resource (`{ namespaces: [...] }`, common on
+                // DigitalOcean once nestia promotes the inline response to a named
+                // type). Fall back to the first array field so the latter is found —
+                // producedIdField only runs on list/search reads, so an array IS the
+                // collection.
+                const col = (_a = (0, extractFields_1.findCollectionField)(top)) !== null && _a !== void 0 ? _a : top.find((f) => f.kind === "array" && f.ref !== undefined);
+                return (col === null || col === void 0 ? void 0 : col.ref) !== undefined ? (0, extractFields_1.extractFields)(col.ref, doc) : top;
+            })();
+        const named = firstIdName(elementFields.map((f) => f.name));
+        if (named !== null)
+            return named;
+        // else: the promoted type was a dead/empty ref (nestia emits a `*.GetResponse`
+        // not registered in components, just like `*.GetQuery`) — fall through to the
+        // raw inline response schema, which still carries the real array.
+    }
+    // Inline response schema (DigitalOcean): introspect the raw schema.
+    if (op.responseSchema === null)
+        return null;
+    const { properties } = (0, extractFields_1.resolveProperties)(op.responseSchema, doc);
+    // The collection array: a known-named one, else the sole/first array property.
+    const arrayEntries = Object.entries(properties).filter(([, p]) => p.type === "array");
+    const collection = (_a = arrayEntries.find(([n]) => extractFields_1.COLLECTION_FIELD_NAMES.has(n.toLowerCase()))) !== null && _a !== void 0 ? _a : arrayEntries[0];
+    if (collection !== undefined) {
+        const items = collection[1].items;
+        if (items !== undefined) {
+            return firstIdName(Object.keys((0, extractFields_1.resolveProperties)(items, doc).properties));
+        }
+    }
+    // A single object (detail) returning an inline schema.
+    return firstIdName(Object.keys(properties));
+}
+/** Roles whose response is a browsable collection — the only legitimate id
+ *  PRODUCERS. A `detail` read returns one object but needs the id to be called,
+ *  so it cannot produce that id (circular); excluding it keeps navigability honest. */
+const COLLECTION_ROLES = new Set(["list", "search"]);
+/**
+ * The shared producer model used by BOTH the tool surface and the consumability
+ * report, so they never disagree on what is navigable. For each resource, the
+ * collection read (list/search) whose element exposes an id — keyed by the
+ * endpoint's CLASSIFIED resource (so a verb path like `/pet/findByStatus` is
+ * bucketed under `pet`, not `findByStatus`).
+ */
+function producerIndex(document) {
+    var _a, _b;
+    const endpoints = (0, toEndpoints_1.toEndpoints)(document);
+    const roleOf = new Map();
+    const resourceOf = new Map();
+    for (const g of (0, classifyEndpoints_1.classifyEndpoints)(endpoints, document)) {
+        for (const c of g.endpoints) {
+            roleOf.set(c.endpoint, c.role);
+            resourceOf.set(c.endpoint, (_b = (_a = c.chain.at(-1)) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : c.resource);
+        }
+    }
+    const producerOf = new Map();
+    const readableResources = new Set();
+    for (const e of endpoints) {
+        const role = roleOf.get(e);
+        const resource = resourceOf.get(e);
+        if (role === undefined || resource === undefined)
+            continue;
+        if (READ_ROLES.has(role))
+            readableResources.add(resource);
+        if (!COLLECTION_ROLES.has(role))
+            continue;
+        // A genuine producer ENUMERATES the resource. One that is itself scoped by
+        // that resource's own id (`/files/{file_id}/trash` → resource `files`, but
+        // it requires `file_id`) cannot produce that id — it is circular, so skip it.
+        const selfScoped = e.parameters.some((p) => resourceOfParam(e.path, p.name) === resource);
+        if (selfScoped)
+            continue;
+        const field = producedIdField(e, document);
+        if (field !== null && !producerOf.has(resource)) {
+            producerOf.set(resource, { tool: e.accessor.join("."), field });
+        }
+    }
+    const nested = nestedProducers(endpoints, document, roleOf);
+    return { endpoints, roleOf, producerOf, readableResources, nested };
+}
+/** The named element type of a read endpoint's response (for recursion). */
+function responseElementTypeName(op, doc) {
+    var _a;
+    if (op.responseBody === null)
+        return null;
+    if (op.responseBody.isArray)
+        return op.responseBody.typeName;
+    const col = (0, extractFields_1.findCollectionField)((0, extractFields_1.extractFields)(op.responseBody.typeName, doc));
+    return (_a = col === null || col === void 0 ? void 0 : col.ref) !== null && _a !== void 0 ? _a : op.responseBody.typeName;
+}
+/**
+ * Resources whose ids are obtainable NESTED inside a read response, not from a
+ * dedicated endpoint — `order` detail returns `goods: IShoppingOrderGood[]`,
+ * `sale` returns `units: IShoppingSaleUnit[]` (each unit holds `stocks: […]`).
+ * Walks each read's response type graph (depth-bounded) and, for every
+ * array-field whose element carries an id, records WHICH read tool exposes it
+ * and the nested path — so the tool surface can hand the agent a real producer
+ * hint ("stockId ← sale.get, at units[].stocks[].id"), not just say it exists.
+ */
+function nestedProducers(endpoints, doc, roleOf) {
+    const out = new Map();
+    const visit = (typeName, tool, parts, depth, seen) => {
+        if (depth > 3 || seen.has(typeName))
+            return;
+        seen.add(typeName);
+        for (const f of (0, extractFields_1.extractFields)(typeName, doc)) {
+            if (f.kind === "array" && f.ref !== undefined) {
+                const childParts = [...parts, f.name];
+                const idField = firstIdName((0, extractFields_1.extractFields)(f.ref, doc).map((x) => x.name));
+                const key = f.name.toLowerCase();
+                if (idField !== null) {
+                    // Prefer the SHALLOWEST path (fewest array hops) — `sale → units[]`
+                    // beats `order → goods[].units[]` for the same `units` id, so the
+                    // agent is pointed at the most direct producer.
+                    const existing = out.get(key);
+                    if (existing === undefined || childParts.length < existing.path.split(".").length) {
+                        out.set(key, {
+                            tool,
+                            path: childParts.map((p) => `${p}[]`).join("."),
+                            field: idField,
+                        });
+                    }
+                }
+                visit(f.ref, tool, childParts, depth + 1, seen); // recurse: units → stocks
+            }
+            else if (f.kind === "ref" && f.ref !== undefined) {
+                visit(f.ref, tool, parts, depth + 1, seen);
+            }
+        }
+    };
+    for (const e of endpoints) {
+        const role = roleOf.get(e);
+        if (role === undefined || !READ_ROLES.has(role))
+            continue;
+        const el = responseElementTypeName(e, doc);
+        if (el !== null)
+            visit(el, e.accessor.join("."), [], 0, new Set());
+    }
+    return out;
+}
+/** The static path segment that an `{param}` addresses (`/sales/{saleId}` → `sales`). */
+function resourceOfParam(path, param) {
+    const segs = path.split("/").filter((s) => s.length > 0);
+    for (let i = 0; i < segs.length; i++) {
+        if (segs[i] === `{${param}}`)
+            return i > 0 ? segs[i - 1] : null;
+    }
+    return null;
+}
+function paramType(schema) {
+    const type = schema === null || schema === void 0 ? void 0 : schema.type;
+    return type === "integer" || type === "number" ? "number" : "string";
+}
+/**
+ * Build the agent tool surface from an OpenAPI document.
+ */
+function buildToolSurface(document) {
+    const { endpoints, roleOf, producerOf, nested } = producerIndex(document);
+    return endpoints.map((e) => {
+        const role = roleOf.get(e);
+        const readOnly = role !== undefined && READ_ROLES.has(role);
+        const method = e.method.toUpperCase();
+        const name = e.accessor.join(".");
+        const properties = {};
+        const required = [];
+        const producers = [];
+        for (const p of e.parameters) {
+            const resource = resourceOfParam(e.path, p.name);
+            const direct = resource !== null ? producerOf.get(resource) : undefined;
+            const nestedP = resource !== null ? nested.get(resource.toLowerCase()) : undefined;
+            let description = p.description || `path parameter ${p.name}`;
+            if (direct !== undefined && direct.tool !== name) {
+                // a dedicated list/search produces this id directly
+                producers.push({ param: p.name, tool: direct.tool, field: direct.field });
+                description = `the ${direct.field} of a ${resource}; obtain it from the \`${direct.tool}\` tool — use each item's \`${direct.field}\` field`;
+            }
+            else if (nestedP !== undefined && nestedP.tool !== name) {
+                // the id lives nested inside a parent read's response
+                producers.push({
+                    param: p.name,
+                    tool: nestedP.tool,
+                    field: `${nestedP.path}.${nestedP.field}`,
+                });
+                description = `the ${nestedP.field} of a ${resource}; obtain it from the \`${nestedP.tool}\` tool's response at \`${nestedP.path}.${nestedP.field}\``;
+            }
+            properties[p.name] = { type: paramType(p.schema), description };
+            required.push(p.name);
+        }
+        if (e.query !== null) {
+            properties.query = {
+                type: "object",
+                description: "optional search / filter / pagination",
+            };
+        }
+        if (e.requestBody !== null) {
+            properties.body = {
+                type: "object",
+                description: `request body (${e.requestBody.typeName})`,
+            };
+            required.push("body");
+        }
+        const tag = readOnly ? "[READ]" : "[WRITE — mutates server state]";
+        const chainNote = producers.length > 0
+            ? ` Inputs come from: ${producers.map((p) => `${p.param} ← ${p.tool}.${p.field}`).join("; ")}.`
+            : "";
+        return {
+            name,
+            description: `${tag} ${e.description || `${method} ${e.path}`}`.trim() + chainNote,
+            inputSchema: { type: "object", properties, required },
+            annotations: {
+                readOnlyHint: readOnly,
+                destructiveHint: method === "DELETE",
+                idempotentHint: method === "GET" || method === "PUT" || method === "DELETE",
+            },
+            operation: {
+                method,
+                path: e.path,
+                pathParams: e.parameters.map((p) => p.name),
+                hasQuery: e.query !== null,
+                hasBody: e.requestBody !== null,
+            },
+            producers,
+        };
+    });
+}
+/**
+ * True when a path param names an entity identifier (`id`, `*_id`, `*Id`,
+ * `uuid`) — the kind that must be produced by another endpoint. A param that is
+ * a human-known key instead (`repository_name`, `template_key`, `scope`, a
+ * `slug`/`code`) is caller-supplied, so its absence of a producer is not a gap.
+ */
+function isIdLikeParam(name) {
+    return /(^id$)|(_id$)|([a-z]Id$)|(^uuid$)|(_uuid$)|([a-z]Uuid$)/.test(name);
+}
+function analyzeConsumability(document) {
+    // ONE producer model, shared with the tool surface — so the report never
+    // claims an input is navigable that the tools give no producer hint for.
+    const { endpoints, roleOf, producerOf, readableResources, nested } = producerIndex(document);
+    const isReadTool = (e) => {
+        const role = roleOf.get(e);
+        return role !== undefined && READ_ROLES.has(role);
+    };
+    // Classify every id input once, then aggregate purely (no mutable counters).
+    const inputs = endpoints.flatMap((e) => e.parameters.map((p) => {
+        const resource = resourceOfParam(e.path, p.name);
+        const ref = { tool: e.accessor.join("."), param: p.name, resource: resource !== null && resource !== void 0 ? resource : "?" };
+        const status = resource !== null && producerOf.has(resource)
+            ? "resolved"
+            : resource !== null && nested.has(resource.toLowerCase())
+                ? "nested"
+                : // a non-id param (`username`, `scope`, `*_name`) is a caller-known
+                    // key regardless of whether its resource is readable — not a gap.
+                    !isIdLikeParam(p.name)
+                        ? "userInput"
+                        : // an entity id: readable resource but no producer traced =
+                            // undetermined; never read at all = a genuine orphan.
+                            resource !== null && readableResources.has(resource)
+                                ? "untraceable"
+                                : "orphan";
+        return Object.assign(Object.assign({}, ref), { status });
+    }));
+    const readTools = endpoints.filter(isReadTool).length;
+    return {
+        tools: endpoints.length,
+        readTools,
+        writeTools: endpoints.length - readTools,
+        referenceInputs: inputs.length,
+        resolved: inputs.filter((i) => i.status === "resolved").length,
+        nested: inputs.filter((i) => i.status === "nested").length,
+        untraceable: inputs
+            .filter((i) => i.status === "untraceable")
+            .map(({ tool, param, resource }) => ({ tool, param, resource })),
+        userInputs: inputs
+            .filter((i) => i.status === "userInput")
+            .map(({ tool, param, resource }) => ({ tool, param, resource })),
+        orphan: inputs
+            .filter((i) => i.status === "orphan")
+            .map(({ tool, param, resource }) => ({ tool, param, resource })),
+    };
+}
+/**
+ * Deterministic structural coverage of a tool surface — the LLM-independent
+ * verification: is the tool graph navigable (every id input has a declared
+ * producer)? Reported as a report card, distinct from running an agent.
+ */
+function coverToolSurface(tools) {
+    // Classify every path param once, then aggregate purely (no mutable counters).
+    const inputs = tools.flatMap((t) => {
+        const producerParams = new Set(t.producers.map((p) => p.param));
+        return t.operation.pathParams.map((param) => ({
+            tool: t.name,
+            param,
+            resolved: producerParams.has(param),
+        }));
+    });
+    const readTools = tools.filter((t) => t.annotations.readOnlyHint).length;
+    const resolvedInputs = inputs.filter((i) => i.resolved).length;
+    return {
+        tools: tools.length,
+        readTools,
+        writeTools: tools.length - readTools,
+        referenceInputs: inputs.length,
+        resolvedInputs,
+        orphanInputs: inputs.length - resolvedInputs,
+        orphans: inputs
+            .filter((i) => !i.resolved)
+            .map(({ tool, param }) => ({ tool, param })),
+    };
+}
+//# sourceMappingURL=toolSurface.js.map

package/lib/agent/toolSurface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolSurface.js","sourceRoot":"","sources":["../../src/agent/toolSurface.ts"],"names":[],"mappings":"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"}

package/lib/agent/verifyAgentTasks.d.ts

@@ -0,0 +1,87 @@
+import { OpenApi } from "@typia/interface";
+import { IAgentTool } from "./toolSurface";
+/**
+ * Behavioral verification of an agent tool surface — the trust layer.
+ *
+ * The consumability report proves the surface is *structurally* navigable
+ * (every id has a producer). This proves it *behaviorally*: a real agent, given
+ * the tools, completes named tasks end-to-end against the live backend. It is
+ * how "the API works for an agent" is demonstrated rather than asserted — the
+ * agent analogue of the frontend's workflow verifier.
+ *
+ * The deterministic parts (tool conversion + HTTP execution) are pure and
+ * unit-tested; the agent loop is driven by a configurable model (the operator's
+ * choice via env / opts), since which model an API's agents will use is the
+ * operator's call, not ours.
+ */
+/** OpenAI / OpenRouter function-calling tool shape. */
+export interface IFunctionTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+    };
+}
+/** OpenAI function names allow only `[a-zA-Z0-9_-]` — the dotted accessor (fine
+ * for MCP) is not valid, so sanitize for the function-calling path. */
+export declare const functionName: (toolName: string) => string;
+/** Convert the agent tool surface to OpenAI function-calling tools. */
+export declare function toFunctionTools(tools: IAgentTool[]): IFunctionTool[];
+/**
+ * Execute one tool call against a live backend: substitute path params, attach
+ * query / body, issue the HTTP request, return the response text. Pure aside
+ * from the network call — deterministic in how it maps a call to a request.
+ */
+export declare function executeToolCall(tools: IAgentTool[], name: string, args: Record<string, unknown>, opts: {
+    baseUrl: string;
+    auth?: string;
+}): Promise<{
+    ok: boolean;
+    text: string;
+}>;
+export interface IAgentTask {
+    id: string;
+    prompt: string;
+    /** Optional success predicate over the agent's final answer (e.g. contains a known value). */
+    expect?: (answer: string) => boolean;
+}
+export interface IAgentTaskResult {
+    id: string;
+    answer: string;
+    toolCalls: string[];
+    passed: boolean | null;
+}
+/** Minimal OpenAI-compatible client surface this verifier needs (so the SDK is injected, not imported). */
+export interface IChatClient {
+    chat: {
+        completions: {
+            create(req: unknown): Promise<{
+                choices: Array<{
+                    message: {
+                        content: string | null;
+                        tool_calls?: Array<{
+                            id: string;
+                            function: {
+                                name: string;
+                                arguments: string;
+                            };
+                        }>;
+                    };
+                }>;
+            }>;
+        };
+    };
+}
+/**
+ * Run the agent through each task against the tool surface + backend. The chat
+ * client and model are injected by the caller (configurable, e.g. from `.env`).
+ */
+export declare function verifyAgentTasks(document: OpenApi.IDocument, opts: {
+    client: IChatClient;
+    model: string;
+    baseUrl: string;
+    auth?: string;
+    tasks: IAgentTask[];
+    maxTurns?: number;
+}): Promise<IAgentTaskResult[]>;

package/lib/agent/verifyAgentTasks.js

@@ -0,0 +1,126 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.functionName = void 0;
+exports.toFunctionTools = toFunctionTools;
+exports.executeToolCall = executeToolCall;
+exports.verifyAgentTasks = verifyAgentTasks;
+const toolSurface_1 = require("./toolSurface");
+/** OpenAI function names allow only `[a-zA-Z0-9_-]` — the dotted accessor (fine
+ * for MCP) is not valid, so sanitize for the function-calling path. */
+const functionName = (toolName) => toolName.replace(/[^A-Za-z0-9_-]/g, "_");
+exports.functionName = functionName;
+/** Convert the agent tool surface to OpenAI function-calling tools. */
+function toFunctionTools(tools) {
+    return tools.map((t) => ({
+        type: "function",
+        function: {
+            name: (0, exports.functionName)(t.name),
+            description: t.description,
+            parameters: t.inputSchema,
+        },
+    }));
+}
+/**
+ * Execute one tool call against a live backend: substitute path params, attach
+ * query / body, issue the HTTP request, return the response text. Pure aside
+ * from the network call — deterministic in how it maps a call to a request.
+ */
+function executeToolCall(tools, name, args, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const tool = tools.find((t) => t.name === name);
+        if (tool === undefined)
+            return { ok: false, text: `unknown tool: ${name}` };
+        let path = tool.operation.path;
+        for (const p of tool.operation.pathParams) {
+            path = path.replace(`{${p}}`, encodeURIComponent(String((_a = args[p]) !== null && _a !== void 0 ? _a : "")));
+        }
+        const url = new URL(opts.baseUrl.replace(/\/$/, "") + path);
+        if (tool.operation.hasQuery && args.query && typeof args.query === "object") {
+            for (const [k, v] of Object.entries(args.query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const method = tool.operation.method;
+        try {
+            const res = yield fetch(url, {
+                method,
+                headers: Object.assign({ "content-type": "application/json" }, (opts.auth ? { authorization: opts.auth } : {})),
+                body: ["GET", "HEAD", "DELETE"].includes(method) ? undefined : JSON.stringify((_b = args.body) !== null && _b !== void 0 ? _b : {}),
+            });
+            const text = yield res.text();
+            return { ok: res.ok, text };
+        }
+        catch (err) {
+            return { ok: false, text: `request failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    });
+}
+/**
+ * Run the agent through each task against the tool surface + backend. The chat
+ * client and model are injected by the caller (configurable, e.g. from `.env`).
+ */
+function verifyAgentTasks(document, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const tools = (0, toolSurface_1.buildToolSurface)(document);
+        const fnTools = toFunctionTools(tools);
+        // function-calling sanitizes dotted names → map the sanitized name the model
+        // calls back to the real tool for execution.
+        const byFnName = new Map(tools.map((t) => [(0, exports.functionName)(t.name), t.name]));
+        const maxTurns = (_a = opts.maxTurns) !== null && _a !== void 0 ? _a : 10;
+        const results = [];
+        for (const task of opts.tasks) {
+            const messages = [
+                { role: "system", content: "You are an API agent. Use the provided tools to complete the task, then reply in plain text with the answer. Never ask the user questions." },
+                { role: "user", content: task.prompt },
+            ];
+            const toolCalls = [];
+            let answer = "(no answer)";
+            for (let turn = 0; turn < maxTurns; turn++) {
+                const resp = yield opts.client.chat.completions.create({
+                    model: opts.model,
+                    messages,
+                    tools: fnTools,
+                    tool_choice: "auto",
+                    temperature: 0,
+                });
+                const msg = resp.choices[0].message;
+                messages.push(msg);
+                if (msg.tool_calls === undefined || msg.tool_calls.length === 0) {
+                    answer = (_b = msg.content) !== null && _b !== void 0 ? _b : "";
+                    break;
+                }
+                for (const tc of msg.tool_calls) {
+                    let args = {};
+                    try {
+                        args = JSON.parse(tc.function.arguments || "{}");
+                    }
+                    catch ( /* keep {} */_d) { /* keep {} */ }
+                    const realName = (_c = byFnName.get(tc.function.name)) !== null && _c !== void 0 ? _c : tc.function.name;
+                    const result = yield executeToolCall(tools, realName, args, { baseUrl: opts.baseUrl, auth: opts.auth });
+                    toolCalls.push(realName);
+                    messages.push({ role: "tool", tool_call_id: tc.id, content: result.text.slice(0, 2500) });
+                }
+            }
+            results.push({
+                id: task.id,
+                answer,
+                toolCalls,
+                passed: task.expect ? task.expect(answer) : null,
+            });
+        }
+        return results;
+    });
+}
+//# sourceMappingURL=verifyAgentTasks.js.map

package/lib/agent/verifyAgentTasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifyAgentTasks.js","sourceRoot":"","sources":["../../src/agent/verifyAgentTasks.ts"],"names":[],"mappings":";;;;;;;;;;;;AA+BA,0CASC;AAOD,0CA8BC;AAoCD,4CAyDC;AAxKD,+CAA6D;AAuB7D;uEACuE;AAChE,MAAM,YAAY,GAAG,CAAC,QAAgB,EAAU,EAAE,CACvD,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;AAD9B,QAAA,YAAY,gBACkB;AAE3C,uEAAuE;AACvE,SAAgB,eAAe,CAAC,KAAmB;IACjD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACvB,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,IAAA,oBAAY,EAAC,CAAC,CAAC,IAAI,CAAC;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,UAAU,EAAE,CAAC,CAAC,WAAW;SAC1B;KACF,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,SAAsB,eAAe,CACnC,KAAmB,EACnB,IAAY,EACZ,IAA6B,EAC7B,IAAwC;;;QAExC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAChD,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC;QAC5E,IAAI,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YAC1C,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAA,IAAI,CAAC,CAAC,CAAC,mCAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,SAAS,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5E,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAgC,CAAC,EAAE,CAAC;gBAC3E,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;oBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACxE,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;QACrC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM;gBACN,OAAO,kBAAI,cAAc,EAAE,kBAAkB,IAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAE;gBACnG,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAA,IAAI,CAAC,IAAI,mCAAI,EAAE,CAAC;aAC/F,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;YAC9B,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACpG,CAAC;IACH,CAAC;CAAA;AAgCD;;;GAGG;AACH,SAAsB,gBAAgB,CACpC,QAA2B,EAC3B,IAOC;;;QAED,MAAM,KAAK,GAAG,IAAA,8BAAgB,EAAC,QAAQ,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QACvC,6EAA6E;QAC7E,6CAA6C;QAC7C,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAA,oBAAY,EAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,MAAA,IAAI,CAAC,QAAQ,mCAAI,EAAE,CAAC;QACrC,MAAM,OAAO,GAAuB,EAAE,CAAC;QAEvC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,MAAM,QAAQ,GAAmC;gBAC/C,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,4IAA4I,EAAE;gBACzK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE;aACvC,CAAC;YACF,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,IAAI,MAAM,GAAG,aAAa,CAAC;YAC3B,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;oBACrD,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,QAAQ;oBACR,KAAK,EAAE,OAAO;oBACd,WAAW,EAAE,MAAM;oBACnB,WAAW,EAAE,CAAC;iBACf,CAAC,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC;gBACrC,QAAQ,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC;gBAC9C,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBAChE,MAAM,GAAG,MAAA,GAAG,CAAC,OAAO,mCAAI,EAAE,CAAC;oBAC3B,MAAM;gBACR,CAAC;gBACD,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,EAAE,CAAC;oBAChC,IAAI,IAAI,GAA4B,EAAE,CAAC;oBACvC,IAAI,CAAC;wBAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;oBAAC,CAAC;oBAAC,QAAQ,aAAa,IAAf,CAAC,CAAC,aAAa,CAAC,CAAC;oBACjF,MAAM,QAAQ,GAAG,MAAA,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,mCAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;oBACpE,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;oBACxG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;oBACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;gBAC5F,CAAC;YACH,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,MAAM;gBACN,SAAS;gBACT,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;aACjD,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CAAA"}

package/lib/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};