@appliqation/agent-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appliqation Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @appliqation/agent-core
+
+**The shared engine every standalone Appliqation agent is built from.** Not an app on its own — no CLI, no `.env` — just the generic, workflow-agnostic pieces that [`appliqation-autotest`](https://github.com/appliqation/appliqation-autotest), [`appliqation-scriptgen`](https://github.com/appliqation/appliqation-scriptgen), and [`appliqation-defect-fix`](https://github.com/appliqation/appliqation-defect-fix) each build on:
+
+- **`/engine`** — the think→act→observe tool-calling loop, budget tracking (calls/pages/time/turns), and a workflow runner that fetches a named prompt (from Appliqation's MCP server or a local file) and runs it through that loop.
+- **`/appq`** — a JSON-RPC client for Appliqation's MCP API, plus scenario/test-set/run resolvers that always derive `project_id`/`url` from a source of truth (a scenario ID, a TC UUID) rather than accepting a second, possibly-diverging input.
+- **`/providers`** — Anthropic and OpenAI adapters implementing one common interface, including prompt caching and image-handling for both wire formats.
+- **`/tools`** — a Playwright-backed browser-tool palette, the tool-allowlist gating mechanism every agent's own safety boundary is built on, a destructive-action click gate, auth-session resolution, and per-test-case role inference.
+- **`/evidence`** — screenshot/console/network/accessibility-snapshot capture with cursor-based delta reads.
+
+## Design principle: mechanism shared, domain knowledge local
+
+Every module here is either genuinely universal, or an explicit injection point so a consuming agent can supply its own domain knowledge without this package needing to know about it. Two examples:
+
+- **Tool-dispatch gating** (`tools/gatedDispatcher.ts`) enforces "only call tools in this allowlist" — but the allowlist *itself* (which tools an executor vs. validator vs. any other stage may touch) is each consuming agent's own knowledge, kept in that agent's own code, never here.
+- **Browser tools** (`tools/browserTools.ts`) take optional `{onBeforeClick, screenshotSink}` hooks instead of hardcoding a destructive-action policy or an upload destination — a consuming agent with no write access, or a different safety posture, supplies its own.
+
+## Installation
+
+Not yet published to npm — consumed via a `file:` dependency by every agent in this family until it is:
+
+```json
+"dependencies": {
+  "@appliqation/agent-core": "file:../appliqation-agent-core"
+}
+```
+
+## Development
+
+```bash
+npm run build
+npm run typecheck
+npm test
+```
+
+See `CLAUDE.md` for a map of this repo if you're working in it with an AI coding assistant.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/appq/index.d.ts

@@ -0,0 +1,3 @@
+export { createMcpClient, type McpClient, type McpClientOptions, type ToolCallOutcome, type McpTextContent, type McpMessage } from './mcpClient.js';
+export { resolveRun, scenarioIdFromTcUuid, resolveScenarioId, fetchScenarioInfo, fetchTestSetInfo, resolveUrl } from './scenarioResolvers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/appq/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/appq/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACpJ,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/appq/index.js

@@ -0,0 +1,3 @@
+export { createMcpClient } from './mcpClient.js';
+export { resolveRun, scenarioIdFromTcUuid, resolveScenarioId, fetchScenarioInfo, fetchTestSetInfo, resolveUrl } from './scenarioResolvers.js';
+//# sourceMappingURL=index.js.map

package/dist/appq/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/appq/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqG,MAAM,gBAAgB,CAAC;AACpJ,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/appq/mcpClient.d.ts

@@ -0,0 +1,52 @@
+export interface McpClientOptions {
+    origin: string;
+    apiKey: string;
+}
+export interface McpTextContent {
+    type: 'text';
+    text: string;
+}
+export interface McpMessage {
+    role: string;
+    content: McpTextContent | {
+        type: string;
+        [k: string]: unknown;
+    };
+}
+export interface ToolCallOutcome {
+    ok: boolean;
+    text: string;
+    raw?: unknown;
+}
+export interface McpClient {
+    /** Fetches a named appq workflow's prose via the standard MCP `prompts/get` method. */
+    fetchPrompt(name: string, args?: Record<string, unknown>): Promise<string>;
+    /**
+     * Fetches a named workflow via the `start_workflow` tool instead of
+     * `prompts/get`. Functionally identical content (both terminate in
+     * McpPromptRegistry::buildMessages() server-side) — this path additionally
+     * carries the directive prefix appq prepends for non-slash-command clients.
+     * Prefer fetchPrompt() unless you specifically want that directive framing.
+     */
+    startWorkflow(name: string, args?: Record<string, unknown>): Promise<string>;
+    /** Generic `tools/call` — the one entry point every appq MCP tool goes through. */
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallOutcome>;
+    listTools(): Promise<Array<{
+        name: string;
+        description: string;
+        inputSchema: unknown;
+    }>>;
+    /**
+     * Claims a locally-captured screenshot for attachment (create_defect's
+     * screenshot_upload_id, or submit_execution_evidence's), via appq's
+     * two-step upload flow: POST the blob, get an upload_id back.
+     *
+     * Content-Type MUST be one appq's endpoint whitelists (image/png, jpeg,
+     * gif, webp) — it validates both the header and the actual magic bytes
+     * against it and rejects anything else with 415. application/octet-stream
+     * (a very natural first guess for "raw binary") fails this every time.
+     */
+    uploadScreenshot(pngBuffer: Buffer, label: string): Promise<string>;
+}
+export declare function createMcpClient(opts: McpClientOptions): McpClient;
+//# sourceMappingURL=mcpClient.d.ts.map

package/dist/appq/mcpClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpClient.d.ts","sourceRoot":"","sources":["../../src/appq/mcpClient.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,cAAc,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAClE;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,uFAAuF;IACvF,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3E;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7E,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChF,SAAS,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;IACzF;;;;;;;;;OASG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAkFjE"}

package/dist/appq/mcpClient.js

@@ -0,0 +1,79 @@
+// JSON-RPC client for appq's MCP server (POST /api/appq/mcp). A factory, not
+// a module-level singleton — each consuming agent has its own .env/config
+// shape, so origin/apiKey are supplied by the caller rather than read from a
+// shared global.
+export function createMcpClient(opts) {
+    let requestId = 0;
+    async function rpc(method, params) {
+        const id = ++requestId;
+        const res = await fetch(`${opts.origin}/api/appq/mcp`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': opts.apiKey,
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+        });
+        if (!res.ok) {
+            throw new Error(`appq MCP HTTP ${res.status}: ${await res.text()}`);
+        }
+        const body = (await res.json());
+        if (body.error) {
+            throw new Error(`appq MCP error ${body.error.code}: ${body.error.message}`);
+        }
+        if (body.result === undefined) {
+            throw new Error('appq MCP response had no result and no error');
+        }
+        return body.result;
+    }
+    const client = {
+        async fetchPrompt(name, args = {}) {
+            const result = await rpc('prompts/get', { name, arguments: args });
+            const text = result.messages
+                .map((m) => (m.content.type === 'text' ? m.content.text : ''))
+                .filter(Boolean)
+                .join('\n\n');
+            if (!text)
+                throw new Error(`appq prompt "${name}" returned no text content`);
+            return text;
+        },
+        async startWorkflow(name, args = {}) {
+            const result = await client.callTool('start_workflow', { name, arguments: args });
+            if (!result.ok)
+                throw new Error(`start_workflow "${name}" failed: ${result.text}`);
+            return result.text;
+        },
+        async callTool(name, args) {
+            const result = await rpc('tools/call', {
+                name,
+                arguments: args,
+            });
+            const text = result.content
+                .map((c) => (c.type === 'text' ? c.text : ''))
+                .filter(Boolean)
+                .join('\n');
+            return { ok: !result.isError, text, raw: result };
+        },
+        async listTools() {
+            const result = await rpc('tools/list', {});
+            return result.tools;
+        },
+        async uploadScreenshot(pngBuffer, label) {
+            const res = await fetch(`${opts.origin}/api/appq/mcp/upload-screenshot`, {
+                method: 'POST',
+                headers: {
+                    'X-API-Key': opts.apiKey,
+                    'Content-Type': 'image/png',
+                    'X-Screenshot-Label': label,
+                },
+                body: new Uint8Array(pngBuffer),
+            });
+            if (!res.ok)
+                throw new Error(`screenshot upload failed: HTTP ${res.status}`);
+            const body = (await res.json());
+            return body.upload_id;
+        },
+    };
+    return client;
+}
+//# sourceMappingURL=mcpClient.js.map

package/dist/appq/mcpClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpClient.js","sourceRoot":"","sources":["../../src/appq/mcpClient.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,0EAA0E;AAC1E,6EAA6E;AAC7E,iBAAiB;AAyDjB,MAAM,UAAU,eAAe,CAAC,IAAsB;IACpD,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,UAAU,GAAG,CAAI,MAAc,EAAE,MAA+B;QACnE,MAAM,EAAE,GAAG,EAAE,SAAS,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,eAAe,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,IAAI,CAAC,MAAM;aACzB;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;SAC7D,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,CAAC,MAAM,KAAK,MAAM,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuB,CAAC;QACtD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAClE,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,MAAM,MAAM,GAAc;QACxB,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE;YAC/B,MAAM,MAAM,GAAG,MAAM,GAAG,CAA6B,aAAa,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/F,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ;iBACzB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAE,CAAC,CAAC,OAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;iBACjF,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,MAAM,CAAC,CAAC;YAChB,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,4BAA4B,CAAC,CAAC;YAC7E,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE;YACjC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAClF,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,aAAa,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;YACnF,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI;YACvB,MAAM,MAAM,GAAG,MAAM,GAAG,CAAmD,YAAY,EAAE;gBACvF,IAAI;gBACJ,SAAS,EAAE,IAAI;aAChB,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO;iBACxB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;iBAC7C,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,OAAO,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;QACpD,CAAC;QAED,KAAK,CAAC,SAAS;YACb,MAAM,MAAM,GAAG,MAAM,GAAG,CACtB,YAAY,EACZ,EAAE,CACH,CAAC;YACF,OAAO,MAAM,CAAC,KAAK,CAAC;QACtB,CAAC;QAED,KAAK,CAAC,gBAAgB,CAAC,SAAS,EAAE,KAAK;YACrC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,iCAAiC,EAAE;gBACvE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,WAAW,EAAE,IAAI,CAAC,MAAM;oBACxB,cAAc,EAAE,WAAW;oBAC3B,oBAAoB,EAAE,KAAK;iBAC5B;gBACD,IAAI,EAAE,IAAI,UAAU,CAAC,SAAS,CAAC;aAChC,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7E,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0B,CAAC;YACzD,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;KACF,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/appq/scenarioResolvers.d.ts

@@ -0,0 +1,60 @@
+import type { McpClient } from './mcpClient.js';
+import type { TcInfo } from '../tools/roleInference.js';
+export declare function resolveRun(client: McpClient, opts: {
+    runId?: string;
+    scenarioId?: string;
+    projectId?: string;
+    environment?: string;
+}): Promise<string>;
+/** A TC UUID is always "{scenario_id}-{uuid4}" — appq's own tools parse it the same way (e.g. CreateDefectTool). */
+export declare function scenarioIdFromTcUuid(tcUuid: string): number;
+/**
+ * scenario_id is never accepted as a separate input alongside a TC UUID —
+ * it's mathematically embedded in the UUID, so a caller-supplied value
+ * could only ever be a stale/typo'd duplicate, never a legitimate override.
+ * In whole-scenario mode there's nothing to derive it from, so scenarioId is
+ * the one genuinely required primary input there.
+ */
+export declare function resolveScenarioId(opts: {
+    scenarioId?: string;
+    testCaseUuid?: string;
+}): number;
+/**
+ * project_id is always derived, never accepted as a separate input — a
+ * scenario belongs to exactly one project, so a caller-supplied value that
+ * diverges from the real one can only be wrong. get_scenario needs only
+ * scenario_id; its response always includes "Project ID: N" plus each TC's
+ * name/UUID/tag — fetched once and reused for role inference too, rather
+ * than a second call for the same data.
+ */
+export declare function fetchScenarioInfo(client: McpClient, scenarioId: number): Promise<{
+    projectId: number;
+    tcs: TcInfo[];
+}>;
+/**
+ * project_id is always derived here too, same reasoning as
+ * fetchScenarioInfo() — get_test_set already returns "Project ID: N" since
+ * a test set belongs to exactly one project, even though its test cases
+ * can span multiple *scenarios* (that's the whole point of a test set —
+ * a curated cross-scenario collection, e.g. a regression/smoke/sanity
+ * suite for CI). Each returned TcInfo's own scenario_id is NOT included as
+ * a separate field — derive it per-TC via scenarioIdFromTcUuid() when
+ * needed, the same single source of truth every other TC-scoped
+ * resolution in this package already trusts, rather than a second parsed
+ * value that could quietly disagree with it.
+ */
+export declare function fetchTestSetInfo(client: McpClient, testSetId: number): Promise<{
+    projectId: number;
+    tcs: TcInfo[];
+}>;
+/**
+ * url is always derived from an environment name, never accepted as a
+ * separate input. Unlike project_id (which create_run itself validates
+ * against the scenario and rejects on mismatch), there's no server-side
+ * check that a caller-supplied URL actually matches the named environment —
+ * a diverging value would silently test the wrong target while the run gets
+ * recorded against a different environment, with nothing to catch it.
+ * get_project_settings already stores a URL per named environment.
+ */
+export declare function resolveUrl(client: McpClient, environment: string, projectId: number): Promise<string>;
+//# sourceMappingURL=scenarioResolvers.d.ts.map

package/dist/appq/scenarioResolvers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarioResolvers.d.ts","sourceRoot":"","sources":["../../src/appq/scenarioResolvers.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AAGxD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACA,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,oHAAoH;AACpH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAI9F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAO5H;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAO1H;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW3G"}

package/dist/appq/scenarioResolvers.js

@@ -0,0 +1,114 @@
+// Scenario/project/run/url resolution against appq's MCP tools. Pure
+// appq-response-shape parsing, no agent-specific meaning — every consuming
+// agent needs the identical scenario/project/url derivation, including the
+// "never accept project_id/url as separate, possibly-diverging inputs"
+// invariant: a scenario belongs to exactly one project, and there's no
+// server-side check that a caller-supplied URL actually matches a named
+// environment — a diverging value would silently test the wrong target. Take
+// an McpClient explicitly rather than importing a global one, matching
+// mcpClient.ts's factory-not-singleton design.
+import { parseScenarioTcList, parseTestSetTcList } from '../tools/roleInference.js';
+export async function resolveRun(client, opts) {
+    if (opts.runId)
+        return opts.runId;
+    if (!opts.scenarioId || !opts.projectId) {
+        throw new Error('--scenario-id and --project-id are required to create a run (or pass --run-id to reuse one).');
+    }
+    const created = await client.callTool('update_run_results', {
+        action: 'create_run',
+        scenario_id: Number(opts.scenarioId),
+        project_id: Number(opts.projectId),
+        ...(opts.environment ? { environment: opts.environment } : {}),
+    });
+    if (!created.ok)
+        throw new Error(`Failed to create run: ${created.text}`);
+    const parsed = JSON.parse(created.text);
+    console.error(`[setup] created run ${parsed.run_id}`);
+    return parsed.run_id;
+}
+/** A TC UUID is always "{scenario_id}-{uuid4}" — appq's own tools parse it the same way (e.g. CreateDefectTool). */
+export function scenarioIdFromTcUuid(tcUuid) {
+    const prefix = tcUuid.split('-', 1)[0];
+    const id = Number(prefix);
+    if (!Number.isFinite(id) || id <= 0) {
+        throw new Error(`Could not derive a scenario ID from test case UUID "${tcUuid}" — expected "{scenario_id}-{uuid4}".`);
+    }
+    return id;
+}
+/**
+ * scenario_id is never accepted as a separate input alongside a TC UUID —
+ * it's mathematically embedded in the UUID, so a caller-supplied value
+ * could only ever be a stale/typo'd duplicate, never a legitimate override.
+ * In whole-scenario mode there's nothing to derive it from, so scenarioId is
+ * the one genuinely required primary input there.
+ */
+export function resolveScenarioId(opts) {
+    if (opts.testCaseUuid)
+        return scenarioIdFromTcUuid(opts.testCaseUuid);
+    if (opts.scenarioId)
+        return Number(opts.scenarioId);
+    throw new Error('--scenario-id is required in whole-scenario mode (no --test-case-uuid given).');
+}
+/**
+ * project_id is always derived, never accepted as a separate input — a
+ * scenario belongs to exactly one project, so a caller-supplied value that
+ * diverges from the real one can only be wrong. get_scenario needs only
+ * scenario_id; its response always includes "Project ID: N" plus each TC's
+ * name/UUID/tag — fetched once and reused for role inference too, rather
+ * than a second call for the same data.
+ */
+export async function fetchScenarioInfo(client, scenarioId) {
+    const result = await client.callTool('get_scenario', { scenario_id: scenarioId });
+    if (!result.ok)
+        throw new Error(`get_scenario failed while resolving scenario ${scenarioId}: ${result.text}`);
+    const match = result.text.match(/Project ID:\s*(\d+)/);
+    if (!match)
+        throw new Error(`Could not find a project ID in get_scenario's response for scenario ${scenarioId}.`);
+    console.error(`[setup] project ${match[1]} (scenario ${scenarioId})`);
+    return { projectId: Number(match[1]), tcs: parseScenarioTcList(result.text) };
+}
+/**
+ * project_id is always derived here too, same reasoning as
+ * fetchScenarioInfo() — get_test_set already returns "Project ID: N" since
+ * a test set belongs to exactly one project, even though its test cases
+ * can span multiple *scenarios* (that's the whole point of a test set —
+ * a curated cross-scenario collection, e.g. a regression/smoke/sanity
+ * suite for CI). Each returned TcInfo's own scenario_id is NOT included as
+ * a separate field — derive it per-TC via scenarioIdFromTcUuid() when
+ * needed, the same single source of truth every other TC-scoped
+ * resolution in this package already trusts, rather than a second parsed
+ * value that could quietly disagree with it.
+ */
+export async function fetchTestSetInfo(client, testSetId) {
+    const result = await client.callTool('get_test_set', { testset_id: testSetId });
+    if (!result.ok)
+        throw new Error(`get_test_set failed while resolving test set ${testSetId}: ${result.text}`);
+    const match = result.text.match(/Project ID:\s*(\d+)/);
+    if (!match)
+        throw new Error(`Could not find a project ID in get_test_set's response for test set ${testSetId}.`);
+    console.error(`[setup] project ${match[1]} (test set ${testSetId})`);
+    return { projectId: Number(match[1]), tcs: parseTestSetTcList(result.text) };
+}
+/**
+ * url is always derived from an environment name, never accepted as a
+ * separate input. Unlike project_id (which create_run itself validates
+ * against the scenario and rejects on mismatch), there's no server-side
+ * check that a caller-supplied URL actually matches the named environment —
+ * a diverging value would silently test the wrong target while the run gets
+ * recorded against a different environment, with nothing to catch it.
+ * get_project_settings already stores a URL per named environment.
+ */
+export async function resolveUrl(client, environment, projectId) {
+    const result = await client.callTool('get_project_settings', { project_id: projectId });
+    if (!result.ok)
+        throw new Error(`get_project_settings failed while resolving the URL for environment "${environment}": ${result.text}`);
+    const settings = JSON.parse(result.text);
+    const env = (settings.environments ?? []).find((e) => e.name === environment);
+    if (!env) {
+        const available = (settings.environments ?? []).map((e) => e.name).join(', ') || '(none configured)';
+        throw new Error(`No environment named "${environment}" on project ${projectId}. Available: ${available}`);
+    }
+    console.error(`[setup] url ${env.url} (environment "${environment}")`);
+    return env.url;
+}
+//# sourceMappingURL=scenarioResolvers.js.map

package/dist/appq/scenarioResolvers.js.map

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

package/dist/audit/index.d.ts

@@ -0,0 +1,2 @@
+export { type AuditRecord, type AuditSink, type AuditEnv, noopAuditSink, createJsonlAuditSink, createMongoAuditSink, resolveAuditSink, safeRecord, createUsageAccumulator, } from './sink.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,sBAAsB,GACvB,MAAM,WAAW,CAAC"}

package/dist/audit/index.js

@@ -0,0 +1,2 @@
+export { noopAuditSink, createJsonlAuditSink, createMongoAuditSink, resolveAuditSink, safeRecord, createUsageAccumulator, } from './sink.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,EACV,sBAAsB,GACvB,MAAM,WAAW,CAAC"}

package/dist/audit/sink.d.ts

@@ -0,0 +1,69 @@
+export interface AuditRecord {
+    /** e.g. 'appliqation-autotest', 'appliqation-autopilot'. */
+    agent: string;
+    /** e.g. 'judge', 'generate', 'fix', 'explore', 'raise', 'run'. */
+    subcommand: string;
+    startedAt: number;
+    endedAt: number;
+    durationMillis: number;
+    /** Absent for agents with no LLM loop at all (appliqation-pr-raise). */
+    model?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        cacheWriteTokens?: number;
+        cacheReadTokens?: number;
+    };
+    turns?: number;
+    budgetExceeded?: boolean;
+    exitCode: number;
+    /** The CLI's own already-built --json summary object, verbatim — no second schema to maintain. */
+    outcome: Record<string, unknown>;
+}
+export interface AuditSink {
+    record(entry: AuditRecord): Promise<void>;
+}
+export declare const noopAuditSink: AuditSink;
+export declare function createJsonlAuditSink(opts: {
+    filePath: string;
+}): AuditSink;
+export declare function createMongoAuditSink(opts: {
+    uri: string;
+    dbName: string;
+    collection: string;
+}): AuditSink;
+/**
+ * The one function CLIs should actually call — never `sink.record()` directly.
+ * An audit write is observability, not part of the task it's describing: a
+ * failure here (a down Mongo instance, a bad path) must never affect the real
+ * run's exit code or output, so it's caught and logged as a warning, not
+ * propagated. Same reasoning as browserTools.ts's screenshot-staging failure
+ * already being non-fatal.
+ */
+export declare function safeRecord(sink: AuditSink, entry: AuditRecord): Promise<void>;
+export interface AuditEnv {
+    auditMongoUri?: string;
+    auditMongoDb?: string;
+    auditMongoCollection?: string;
+    auditJsonlPath?: string;
+}
+/**
+ * Precedence mirrors resolveProvider()'s own shape: Mongo (if fully
+ * configured) > JSONL > noop. Nothing writes anywhere unless explicitly
+ * configured — same BYO-credential/optional posture as every LLM key and
+ * resolveApiAuth() elsewhere in this family.
+ */
+export declare function resolveAuditSink(env: AuditEnv): AuditSink;
+interface UsageDelta {
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens?: number;
+    cacheReadTokens?: number;
+}
+/** Sums usage across however many 'usage' onEvent callbacks a run emits into one invocation-level total. */
+export declare function createUsageAccumulator(): {
+    onUsage(u: UsageDelta): void;
+    totals(): AuditRecord["usage"];
+};
+export {};
+//# sourceMappingURL=sink.d.ts.map

package/dist/audit/sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sink.d.ts","sourceRoot":"","sources":["../../src/audit/sink.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,eAAO,MAAM,aAAa,EAAE,SAI3B,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAM1E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAqBzG;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAMnF;AAED,MAAM,WAAW,QAAQ;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,SAAS,CASzD;AAED,UAAU,UAAU;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,4GAA4G;AAC5G,wBAAgB,sBAAsB;eAOvB,UAAU,GAAG,IAAI;cAMlB,WAAW,CAAC,OAAO,CAAC;EAIjC"}

package/dist/audit/sink.js

@@ -0,0 +1,93 @@
+// Observability, not a knowledge channel: an AuditRecord is a record of what
+// an invocation did, for a human to read later (a dashboard, an ad-hoc query)
+// — never something fed back into a future agent's own decision-making, which
+// is exactly what keeps this distinct from the write-trust boundary
+// enrich_project_context's action=write sits behind (see tools/projectContext.ts).
+// A write here failing must never affect the real task it's describing — see
+// safeRecord() below, the one function every CLI should actually call.
+import { MongoClient } from 'mongodb';
+import { appendFile } from 'node:fs/promises';
+export const noopAuditSink = {
+    async record() {
+        // Intentionally does nothing — the default when no sink is configured.
+    },
+};
+export function createJsonlAuditSink(opts) {
+    return {
+        async record(entry) {
+            await appendFile(opts.filePath, JSON.stringify(entry) + '\n', 'utf8');
+        },
+    };
+}
+export function createMongoAuditSink(opts) {
+    let collectionPromise;
+    function getCollection() {
+        // Lazy-connect-once: the client is created and connected on the first
+        // record() call, then reused — a CLI invocation that never calls
+        // record() (e.g. audit unconfigured elsewhere in the same process)
+        // never opens a connection at all.
+        if (!collectionPromise) {
+            const client = new MongoClient(opts.uri);
+            collectionPromise = client.connect().then(() => client.db(opts.dbName).collection(opts.collection));
+        }
+        return collectionPromise;
+    }
+    return {
+        async record(entry) {
+            const collection = await getCollection();
+            await collection.insertOne(entry);
+        },
+    };
+}
+/**
+ * The one function CLIs should actually call — never `sink.record()` directly.
+ * An audit write is observability, not part of the task it's describing: a
+ * failure here (a down Mongo instance, a bad path) must never affect the real
+ * run's exit code or output, so it's caught and logged as a warning, not
+ * propagated. Same reasoning as browserTools.ts's screenshot-staging failure
+ * already being non-fatal.
+ */
+export async function safeRecord(sink, entry) {
+    try {
+        await sink.record(entry);
+    }
+    catch (err) {
+        console.error(`[audit] failed to record: ${err.message}`);
+    }
+}
+/**
+ * Precedence mirrors resolveProvider()'s own shape: Mongo (if fully
+ * configured) > JSONL > noop. Nothing writes anywhere unless explicitly
+ * configured — same BYO-credential/optional posture as every LLM key and
+ * resolveApiAuth() elsewhere in this family.
+ */
+export function resolveAuditSink(env) {
+    if (env.auditMongoUri) {
+        if (!env.auditMongoDb || !env.auditMongoCollection) {
+            throw new Error('AUDIT_MONGO_URI is set but AUDIT_MONGO_DB/AUDIT_MONGO_COLLECTION are missing — no collection-name fallback.');
+        }
+        return createMongoAuditSink({ uri: env.auditMongoUri, dbName: env.auditMongoDb, collection: env.auditMongoCollection });
+    }
+    if (env.auditJsonlPath)
+        return createJsonlAuditSink({ filePath: env.auditJsonlPath });
+    return noopAuditSink;
+}
+/** Sums usage across however many 'usage' onEvent callbacks a run emits into one invocation-level total. */
+export function createUsageAccumulator() {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let cacheWriteTokens = 0;
+    let cacheReadTokens = 0;
+    return {
+        onUsage(u) {
+            inputTokens += u.inputTokens;
+            outputTokens += u.outputTokens;
+            cacheWriteTokens += u.cacheWriteTokens ?? 0;
+            cacheReadTokens += u.cacheReadTokens ?? 0;
+        },
+        totals() {
+            return { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens };
+        },
+    };
+}
+//# sourceMappingURL=sink.js.map

package/dist/audit/sink.js.map

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

package/dist/config/helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function required(name: string): string;
+export declare function optional(name: string): string | undefined;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/config/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/config/helpers.ts"],"names":[],"mappings":"AAOA,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEzD"}

package/dist/config/helpers.js

@@ -0,0 +1,16 @@
+// Two pure primitives, shared because every consuming agent needs exactly
+// this env-var-reading pattern. Deliberately NOT a shared config schema/
+// singleton — each agent's .env shape is genuinely different, and a schema
+// DSL flexible enough to cover more than one shape today is speculative
+// machinery with no current payoff. Each agent keeps its own frozen config
+// object built from these.
+export function required(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`Missing required env var: ${name}`);
+    return value;
+}
+export function optional(name) {
+    return process.env[name] || undefined;
+}
+//# sourceMappingURL=helpers.js.map

package/dist/config/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/config/helpers.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,yEAAyE;AACzE,2EAA2E;AAC3E,wEAAwE;AACxE,2EAA2E;AAC3E,2BAA2B;AAE3B,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,EAAE,CAAC,CAAC;IACjE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;AACxC,CAAC"}