@shrkcrft/ai 0.1.0-alpha.26 → 0.1.0-alpha.28

package/dist/delegate/delegate-analysis-schema.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The structured judgment an `analysis` delegate recipe asks a local model to
+ * emit. Unlike a `patch` recipe (which emits editable ops — see
+ * `delegate-edit-schema.ts`), an analysis recipe emits READ-ONLY findings: the
+ * model interprets / prioritises / explains a deterministic report the engine
+ * already computed. Each finding may cite `refs` (files / constructs / reason
+ * codes) drawn from the grounding facts; the inspector's grounding cross-check
+ * flags any ref that is NOT present in the ground truth as `unverified`, so the
+ * model adds judgment on top of facts it cannot fabricate.
+ *
+ * This layer (`@shrkcrft/ai`) holds only the wire shape + a structural parse —
+ * the grounding cross-check + report assembly live in `@shrkcrft/inspector`.
+ */
+/** One raw finding the model emits. `refs`/`id` are optional; `message` is not. */
+export interface IDelegateRawFinding {
+    /** Stable-ish id the model may assign (informational; the engine re-keys). */
+    id?: string;
+    /** The judgment / observation. */
+    message: string;
+    /**
+     * Entities this finding references (file paths / construct ids / reason
+     * codes). MUST be drawn from the provided grounding facts — a ref absent from
+     * the ground truth is flagged `unverified` by the cross-check.
+     */
+    refs?: readonly string[];
+}
+/** The full structured analysis returned by an analysis worker. */
+export interface IDelegateRawAnalysis {
+    findings: readonly IDelegateRawFinding[];
+    /** Optional free-form note (informational; never treated as a grounded fact). */
+    note?: string;
+}
+/**
+ * JSON Schema handed to the provider as `responseFormat.schema` so a local model
+ * returns a parseable analysis. Deliberately closed (`additionalProperties:
+ * false`) — a weak model that invents fields fails the parse and is reprompted
+ * once rather than smuggling unstructured prose through.
+ */
+export declare const DELEGATE_ANALYSIS_JSON_SCHEMA: Record<string, unknown>;
+//# sourceMappingURL=delegate-analysis-schema.d.ts.map

package/dist/delegate/delegate-analysis-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-analysis-schema.d.ts","sourceRoot":"","sources":["../../src/delegate/delegate-analysis-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mFAAmF;AACnF,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,mEAAmE;AACnE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAyBjE,CAAC"}

package/dist/delegate/delegate-analysis-schema.js

@@ -0,0 +1,44 @@
+/**
+ * The structured judgment an `analysis` delegate recipe asks a local model to
+ * emit. Unlike a `patch` recipe (which emits editable ops — see
+ * `delegate-edit-schema.ts`), an analysis recipe emits READ-ONLY findings: the
+ * model interprets / prioritises / explains a deterministic report the engine
+ * already computed. Each finding may cite `refs` (files / constructs / reason
+ * codes) drawn from the grounding facts; the inspector's grounding cross-check
+ * flags any ref that is NOT present in the ground truth as `unverified`, so the
+ * model adds judgment on top of facts it cannot fabricate.
+ *
+ * This layer (`@shrkcrft/ai`) holds only the wire shape + a structural parse —
+ * the grounding cross-check + report assembly live in `@shrkcrft/inspector`.
+ */
+/**
+ * JSON Schema handed to the provider as `responseFormat.schema` so a local model
+ * returns a parseable analysis. Deliberately closed (`additionalProperties:
+ * false`) — a weak model that invents fields fails the parse and is reprompted
+ * once rather than smuggling unstructured prose through.
+ */
+export const DELEGATE_ANALYSIS_JSON_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['findings'],
+    properties: {
+        note: { type: 'string' },
+        findings: {
+            type: 'array',
+            items: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['message'],
+                properties: {
+                    id: { type: 'string' },
+                    message: { type: 'string', description: 'the judgment / observation' },
+                    refs: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'files / constructs / reason-codes this finding references — MUST be drawn from the provided grounding facts',
+                    },
+                },
+            },
+        },
+    },
+};

package/dist/delegate/parse-delegate-analysis.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Parse + (lightly) validate the JSON an `analysis` delegate worker emits, and a
+ * one-shot generate→parse→reprompt-once helper. Mirrors `parse-delegate-edit.ts`:
+ * a PARSE failure reprompts once; a provider / TIMEOUT error surfaces immediately
+ * (the CLI orchestrator owns macro-retries).
+ */
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IAiProvider } from '../ai-provider.js';
+import { type IAiMessage } from '../ai-request.js';
+import { type IDelegateRawAnalysis } from './delegate-analysis-schema.js';
+/** Parse a worker's raw output into a structurally-validated `IDelegateRawAnalysis`. */
+export declare function parseDelegateAnalysis(raw: string): Result<IDelegateRawAnalysis, AppError>;
+export interface IDelegateAnalysisCallInput {
+    provider: IAiProvider;
+    messages: readonly IAiMessage[];
+    model?: string;
+    /** Per-call wall-clock budget; a TIMEOUT surfaces immediately (no retry). */
+    timeoutMs?: number;
+    maxTokens?: number;
+    /** Build the reprompt messages after a PARSE failure. */
+    reprompt?: (badOutput: string, error: AppError) => readonly IAiMessage[];
+}
+export interface IDelegateAnalysisCallResult {
+    analysis: IDelegateRawAnalysis;
+    /** The raw model output that parsed (for telemetry / hand-back). */
+    raw: string;
+    model: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /** True when the first output failed to parse and the reprompt succeeded. */
+    retried: boolean;
+}
+/**
+ * Generate an analysis, parsing the output. A provider / TIMEOUT error surfaces
+ * immediately; a PARSE failure reprompts ONCE (when a reprompt builder is
+ * supplied) before giving up.
+ */
+export declare function callDelegateAnalysisWithRetry(input: IDelegateAnalysisCallInput): Promise<Result<IDelegateAnalysisCallResult, AppError>>;
+/** Convenience for callers building reprompt messages. */
+export declare function delegateAnalysisRepromptMessage(badOutput: string, error: AppError): IAiMessage;
+//# sourceMappingURL=parse-delegate-analysis.d.ts.map

package/dist/delegate/parse-delegate-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-delegate-analysis.d.ts","sourceRoot":"","sources":["../../src/delegate/parse-delegate-analysis.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,+BAA+B,CAAC;AAavC,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAwCzF;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,KAAK,SAAS,UAAU,EAAE,CAAC;CAC1E;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;CAClB;AAkBD;;;;GAIG;AACH,wBAAsB,6BAA6B,CACjD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,MAAM,CAAC,2BAA2B,EAAE,QAAQ,CAAC,CAAC,CA0BxD;AAED,0DAA0D;AAC1D,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,UAAU,CAQ9F"}

package/dist/delegate/parse-delegate-analysis.js

@@ -0,0 +1,124 @@
+/**
+ * Parse + (lightly) validate the JSON an `analysis` delegate worker emits, and a
+ * one-shot generate→parse→reprompt-once helper. Mirrors `parse-delegate-edit.ts`:
+ * a PARSE failure reprompts once; a provider / TIMEOUT error surfaces immediately
+ * (the CLI orchestrator owns macro-retries).
+ */
+import { AppErrorImpl, ERROR_CODES, err, ok, } from '@shrkcrft/core';
+import { AiMessageRole } from "../ai-request.js";
+import { DELEGATE_ANALYSIS_JSON_SCHEMA, } from "./delegate-analysis-schema.js";
+function invalid(message, cause) {
+    return new AppErrorImpl(ERROR_CODES.INVALID_INPUT, message, cause !== undefined ? { cause } : undefined);
+}
+/** Strip a leading/trailing markdown code fence weak local models often add. */
+function stripFences(text) {
+    const fence = /^\s*```(?:json)?\s*\n([\s\S]*?)\n```\s*$/;
+    const m = text.match(fence);
+    return m ? m[1] : text;
+}
+/** Parse a worker's raw output into a structurally-validated `IDelegateRawAnalysis`. */
+export function parseDelegateAnalysis(raw) {
+    const text = stripFences(raw).trim();
+    if (text.length === 0)
+        return err(invalid('delegate analysis is empty'));
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        return err(invalid('delegate analysis is not valid JSON', e));
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return err(invalid('delegate analysis must be a JSON object'));
+    }
+    const obj = parsed;
+    const findingsRaw = obj['findings'];
+    if (!Array.isArray(findingsRaw))
+        return err(invalid('delegate analysis "findings" must be an array'));
+    const findings = [];
+    for (let i = 0; i < findingsRaw.length; i += 1) {
+        const f = findingsRaw[i];
+        if (!f || typeof f !== 'object' || Array.isArray(f)) {
+            return err(invalid(`findings[${i}] must be an object`));
+        }
+        const ff = f;
+        const message = ff['message'];
+        if (typeof message !== 'string' || message.trim().length === 0) {
+            return err(invalid(`findings[${i}].message must be a non-empty string`));
+        }
+        const finding = { message };
+        if (typeof ff['id'] === 'string')
+            finding.id = ff['id'];
+        const refs = ff['refs'];
+        if (refs !== undefined) {
+            if (!Array.isArray(refs) || refs.some((r) => typeof r !== 'string')) {
+                return err(invalid(`findings[${i}].refs must be an array of strings`));
+            }
+            finding.refs = refs;
+        }
+        findings.push(finding);
+    }
+    const analysis = { findings };
+    if (typeof obj['note'] === 'string')
+        analysis.note = obj['note'];
+    return ok(analysis);
+}
+async function sendOnce(input, messages) {
+    if (input.model)
+        input.provider.configure({ model: input.model });
+    const res = await input.provider.send({
+        messages,
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}),
+        ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+        responseFormat: { type: 'json_schema', schema: DELEGATE_ANALYSIS_JSON_SCHEMA, schemaName: 'DelegateAnalysis' },
+    });
+    if (!res.ok)
+        return res;
+    return ok({ content: res.value.content, model: res.value.model, ...(res.value.usage ? { usage: res.value.usage } : {}) });
+}
+/**
+ * Generate an analysis, parsing the output. A provider / TIMEOUT error surfaces
+ * immediately; a PARSE failure reprompts ONCE (when a reprompt builder is
+ * supplied) before giving up.
+ */
+export async function callDelegateAnalysisWithRetry(input) {
+    const first = await sendOnce(input, input.messages);
+    if (!first.ok)
+        return first;
+    const parsed = parseDelegateAnalysis(first.value.content);
+    if (parsed.ok) {
+        return ok({
+            analysis: parsed.value,
+            raw: first.value.content,
+            model: first.value.model,
+            ...(first.value.usage ? { usage: first.value.usage } : {}),
+            retried: false,
+        });
+    }
+    if (!input.reprompt)
+        return err(parsed.error);
+    const retryMessages = input.reprompt(first.value.content, parsed.error);
+    const second = await sendOnce(input, retryMessages);
+    if (!second.ok)
+        return second;
+    const reparsed = parseDelegateAnalysis(second.value.content);
+    if (!reparsed.ok)
+        return err(reparsed.error);
+    return ok({
+        analysis: reparsed.value,
+        raw: second.value.content,
+        model: second.value.model,
+        ...(second.value.usage ? { usage: second.value.usage } : {}),
+        retried: true,
+    });
+}
+/** Convenience for callers building reprompt messages. */
+export function delegateAnalysisRepromptMessage(badOutput, error) {
+    return {
+        role: AiMessageRole.User,
+        content: `Your previous reply could not be parsed: ${error.message}\n` +
+            `It must be a single JSON object matching the schema — no prose, no markdown fences.\n` +
+            `Previous reply was:\n${badOutput.slice(0, 2000)}`,
+    };
+}

package/dist/delegate/query-loop.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A bounded, read-only QUERY LOOP for `analysis` delegate recipes (Phase 3).
+ *
+ * Generalises the one-shot `--ai-plan` context-expansion into an iterated loop:
+ * each round the model may REQUEST a few read-only engine facts (as JSON, via the
+ * schema below — NOT native provider tool-calling, which is brittle with weak
+ * local models and would need surgery on the neutral message model); the engine
+ * runs only the allow-listed queries, feeds the results back, and repeats until
+ * the model is `done`, the round cap is hit, or the wall-clock budget is spent.
+ * Then the model produces its final answer with the caller's response format.
+ *
+ * Layer-clean: the query EXECUTION is injected (`executeQuery`) — this AI-layer
+ * runtime never imports the engine. There is deliberately no write/apply/gen/sign
+ * query: this is a fact-fetch loop, not an agent.
+ */
+import { type AppError, type Result } from '@shrkcrft/core';
+import type { IAiProvider } from '../ai-provider.js';
+import { type IAiMessage, type IAiResponseFormat } from '../ai-request.js';
+/** One read-only query the model may request. */
+export interface IQueryDescriptor {
+    name: string;
+    description?: string;
+}
+/** The result of running one read-only query. */
+export interface IQueryResult {
+    /** Compact text the model sees. */
+    content: string;
+    /** Entities this query surfaced — merged into the analysis ground truth. */
+    entities: readonly string[];
+}
+/** Runs one allow-listed read-only query. Injected by the cli (never in this layer). */
+export type QueryExecutor = (name: string, args: Record<string, unknown>) => Promise<IQueryResult>;
+export interface IQueryLogEntry {
+    name: string;
+    args: Record<string, unknown>;
+    /** false = refused (not allow-listed) or the executor threw. */
+    ok: boolean;
+    result: string;
+}
+export interface IRunQueryLoopInput {
+    provider: IAiProvider;
+    messages: readonly IAiMessage[];
+    model?: string;
+    timeoutMs?: number;
+    maxTokens?: number;
+    /** The recipe's read-only query allow-list — the only names the model may call. */
+    allowedQueries: readonly string[];
+    /** Max planning rounds. Clamped to `[0, 4]`; `0` ⇒ straight to the final answer. */
+    maxQueryRounds: number;
+    /** Wall-clock budget for the whole loop (best-effort; checked between rounds). */
+    budgetMs?: number;
+    /** Optional human descriptions of each query, shown to the model. */
+    catalog?: readonly IQueryDescriptor[];
+    executeQuery: QueryExecutor;
+    /** Instruction appended before the final answer turn. */
+    finalInstruction: string;
+    /** Response format for the FINAL answer (e.g. the analysis findings schema). */
+    finalResponseFormat?: IAiResponseFormat;
+    /** Cap on queries executed per round (default 4). */
+    maxQueriesPerRound?: number;
+    /** Injectable clock (default `Date.now`) so budget behaviour is testable. */
+    now?: () => number;
+}
+export interface IRunQueryLoopResult {
+    content: string;
+    model: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+    /** How many planning rounds actually ran. */
+    roundsRun: number;
+    /** Audit log of every query requested (executed or refused). */
+    queries: readonly IQueryLogEntry[];
+    /** Union of entities surfaced by executed queries. */
+    gatheredEntities: readonly string[];
+    /** True when no query was ever run (rounds 0, or the model never queried). */
+    degraded: boolean;
+}
+/**
+ * Run the bounded query loop, then the final answer turn. A provider error at any
+ * point surfaces as `err`. Query fences (allow-list, round cap, budget, per-round
+ * cap) are enforced deterministically here — the model can only influence WHICH
+ * allow-listed facts are fetched, never whether the fence holds.
+ */
+export declare function runBoundedQueryLoop(input: IRunQueryLoopInput): Promise<Result<IRunQueryLoopResult, AppError>>;
+//# sourceMappingURL=query-loop.d.ts.map

package/dist/delegate/query-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-loop.d.ts","sourceRoot":"","sources":["../../src/delegate/query-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAM,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAiB,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1F,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,wFAAwF;AACxF,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEnG,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,gEAAgE;IAChE,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,YAAY,EAAE,aAAa,CAAC;IAC5B,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,iBAAiB,CAAC;IACxC,qDAAqD;IACrD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,sDAAsD;IACtD,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAwED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAC,CAqEhD"}

package/dist/delegate/query-loop.js

@@ -0,0 +1,162 @@
+/**
+ * A bounded, read-only QUERY LOOP for `analysis` delegate recipes (Phase 3).
+ *
+ * Generalises the one-shot `--ai-plan` context-expansion into an iterated loop:
+ * each round the model may REQUEST a few read-only engine facts (as JSON, via the
+ * schema below — NOT native provider tool-calling, which is brittle with weak
+ * local models and would need surgery on the neutral message model); the engine
+ * runs only the allow-listed queries, feeds the results back, and repeats until
+ * the model is `done`, the round cap is hit, or the wall-clock budget is spent.
+ * Then the model produces its final answer with the caller's response format.
+ *
+ * Layer-clean: the query EXECUTION is injected (`executeQuery`) — this AI-layer
+ * runtime never imports the engine. There is deliberately no write/apply/gen/sign
+ * query: this is a fact-fetch loop, not an agent.
+ */
+import { ok } from '@shrkcrft/core';
+import { AiMessageRole } from "../ai-request.js";
+/** JSON schema for the per-round query request, with the allow-list as the enum. */
+function queryRequestSchema(allowed) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['done'],
+        properties: {
+            done: { type: 'boolean', description: 'true when you have enough facts to answer' },
+            queries: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    required: ['name'],
+                    properties: {
+                        name: { type: 'string', enum: [...allowed] },
+                        args: { type: 'object', additionalProperties: true },
+                    },
+                },
+            },
+        },
+    };
+}
+function stripFences(text) {
+    const m = text.match(/^\s*```(?:json)?\s*\n([\s\S]*?)\n```\s*$/);
+    return m ? m[1] : text;
+}
+/** Best-effort parse of a query-request turn; returns null if unusable. */
+function parseQueryRequest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripFences(raw).trim());
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    const done = obj['done'] === true;
+    const out = { done, queries: [] };
+    if (Array.isArray(obj['queries'])) {
+        for (const q of obj['queries']) {
+            if (!q || typeof q !== 'object')
+                continue;
+            const name = q['name'];
+            if (typeof name !== 'string' || name.length === 0)
+                continue;
+            const args = q['args'];
+            out.queries.push({ name, args: args && typeof args === 'object' && !Array.isArray(args) ? args : {} });
+        }
+    }
+    return out;
+}
+function queryInstruction(allowed, catalog, rounds) {
+    const byName = new Map((catalog ?? []).map((c) => [c.name, c.description ?? '']));
+    const lines = allowed.map((n) => `  - ${n}${byName.get(n) ? `: ${byName.get(n)}` : ''}`);
+    return [
+        `You may first pull READ-ONLY facts (up to ${rounds} round(s)) before answering.`,
+        'Available queries:',
+        ...lines,
+        'Respond with JSON: {"done": <bool>, "queries": [{"name": "<query>", "args": {...}}]}.',
+        'Request only the facts you need. Set "done": true (and no queries) when ready to answer.',
+    ].join('\n');
+}
+/**
+ * Run the bounded query loop, then the final answer turn. A provider error at any
+ * point surfaces as `err`. Query fences (allow-list, round cap, budget, per-round
+ * cap) are enforced deterministically here — the model can only influence WHICH
+ * allow-listed facts are fetched, never whether the fence holds.
+ */
+export async function runBoundedQueryLoop(input) {
+    const now = input.now ?? Date.now;
+    const rounds = Math.max(0, Math.min(4, Math.floor(input.maxQueryRounds)));
+    const allowed = new Set(input.allowedQueries);
+    const perRound = Math.max(1, input.maxQueriesPerRound ?? 4);
+    const conversation = [...input.messages];
+    const queries = [];
+    const gathered = new Set();
+    const startedAt = now();
+    let roundsRun = 0;
+    if (rounds > 0 && allowed.size > 0) {
+        conversation.push({ role: AiMessageRole.User, content: queryInstruction(input.allowedQueries, input.catalog, rounds) });
+        const requestSchema = queryRequestSchema(input.allowedQueries);
+        for (let round = 0; round < rounds; round += 1) {
+            if (input.budgetMs && now() - startedAt > input.budgetMs)
+                break;
+            roundsRun += 1;
+            const res = await input.provider.send({
+                messages: conversation,
+                ...(input.model ? { model: input.model } : {}),
+                ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}),
+                ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+                responseFormat: { type: 'json_schema', schema: requestSchema, schemaName: 'QueryRequest' },
+            });
+            if (!res.ok)
+                return res;
+            const parsed = parseQueryRequest(res.value.content);
+            if (!parsed || parsed.done || parsed.queries.length === 0)
+                break;
+            const resultLines = [];
+            for (const q of parsed.queries.slice(0, perRound)) {
+                if (!allowed.has(q.name)) {
+                    queries.push({ name: q.name, args: q.args, ok: false, result: 'refused: not in the allowed query list' });
+                    resultLines.push(`- ${q.name}: REFUSED (not permitted)`);
+                    continue;
+                }
+                try {
+                    const out = await input.executeQuery(q.name, q.args);
+                    queries.push({ name: q.name, args: q.args, ok: true, result: out.content });
+                    for (const e of out.entities)
+                        gathered.add(e);
+                    resultLines.push(`- ${q.name}(${JSON.stringify(q.args)}):\n${out.content}`);
+                }
+                catch (e) {
+                    queries.push({ name: q.name, args: q.args, ok: false, result: `error: ${e.message}` });
+                    resultLines.push(`- ${q.name}: ERROR ${e.message}`);
+                }
+            }
+            conversation.push({
+                role: AiMessageRole.User,
+                content: `Query results:\n${resultLines.join('\n')}\n\nRequest more facts (done:false) or set done:true to answer now.`,
+            });
+        }
+    }
+    conversation.push({ role: AiMessageRole.User, content: input.finalInstruction });
+    const finalRes = await input.provider.send({
+        messages: conversation,
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.maxTokens ? { maxTokens: input.maxTokens } : {}),
+        ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+        ...(input.finalResponseFormat ? { responseFormat: input.finalResponseFormat } : {}),
+    });
+    if (!finalRes.ok)
+        return finalRes;
+    return ok({
+        content: finalRes.value.content,
+        model: finalRes.value.model,
+        ...(finalRes.value.usage ? { usage: finalRes.value.usage } : {}),
+        roundsRun,
+        queries,
+        gatheredEntities: [...gathered],
+        degraded: queries.length === 0,
+    });
+}

package/dist/index.d.ts

@@ -11,4 +11,7 @@ export * from './llm-hints.js';
 export * from './llm-recommendations.js';
 export * from './delegate/delegate-edit-schema.js';
 export * from './delegate/parse-delegate-edit.js';
+export * from './delegate/delegate-analysis-schema.js';
+export * from './delegate/parse-delegate-analysis.js';
+export * from './delegate/query-loop.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,oCAAoC,CAAC;AACnD,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,wCAAwC,CAAC;AACvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -11,3 +11,6 @@ export * from "./llm-hints.js";
 export * from "./llm-recommendations.js";
 export * from "./delegate/delegate-edit-schema.js";
 export * from "./delegate/parse-delegate-edit.js";
+export * from "./delegate/delegate-analysis-schema.js";
+export * from "./delegate/parse-delegate-analysis.js";
+export * from "./delegate/query-loop.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/ai",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.28",
   "description": "SharkCraft local LLM provider abstraction: Ollama (HTTP) + llama.cpp (in-process) + multi-pass enhancement pipeline.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,8 +43,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.26",
-    "@shrkcrft/context": "^0.1.0-alpha.26",
+    "@shrkcrft/core": "^0.1.0-alpha.28",
+    "@shrkcrft/context": "^0.1.0-alpha.28",
     "node-llama-cpp": "^3.16.0"
   },
   "publishConfig": {