@opendatalabs/personal-server-ts-core 0.0.1-canary.00328bf

package/dist/derivatives/inference.js

@@ -0,0 +1,262 @@
+/**
+ * Inference provider adapter for the derivative compute layer.
+ *
+ * One implementation: OpenAI-compatible chat completions over `fetch`, so it
+ * runs unchanged in Node and in the browser (PS-Lite). In production the
+ * base URL is the Vana inference relay, which holds the provider key; the
+ * optional API key header exists for local development against a provider
+ * directly.
+ *
+ * RELAY AUTH: the Vana inference relay
+ * (`POST /v1/inference/chat/completions` on the data gateway) only forwards
+ * a request that is signed by the owner or by one of the owner's ACTIVE
+ * registered servers, with the same Web3Signed scheme the lineage read uses
+ * (`RequestSigner`, see ../signing/request-signer.ts). Pass `requestSigner`
+ * and every relay call carries `Authorization: Web3Signed ...` over the
+ * exact bytes that go on the wire. `apiKey` is the local-development
+ * alternative (direct provider, `Authorization: Bearer`) and wins when both
+ * are set: a bearer key means "not the relay".
+ *
+ * E2EE SEAM: the Phala confidential-inference E2EE v2 protocol encrypts each
+ * `messages[i].content` to the gateway's attested public key and adds the
+ * headers X-E2EE-Version, X-Client-Pub-Key, X-Model-Pub-Key, X-E2EE-Nonce
+ * and X-E2EE-Timestamp; the response content comes back encrypted to the
+ * client key. `InferenceRequestEncryption` below is the hook, implemented
+ * by `createPhalaE2eeEncryption` in ./e2ee. This module only knows the
+ * shape: encrypt the outgoing messages, decrypt the one response field.
+ */
+export const DEFAULT_INFERENCE_BASE_URL = "https://inference.phala.com/v1";
+export const DEFAULT_INFERENCE_MODEL = "z-ai/glm-5.3-flash";
+export const DEFAULT_INFERENCE_TIMEOUT_MS = 120_000;
+export const DEFAULT_INFERENCE_MAX_TOKENS = 2_048;
+export const DEFAULT_INFERENCE_REQUEST_FIELDS = {
+    provider: { aci_verified: true, zdr: true },
+};
+/** Thrown for a non-2xx or malformed provider reply. Carries no prompt text. */
+export class InferenceRequestError extends Error {
+    status;
+    /** OpenAI-style `error.type` of the rejection, when the body had one. */
+    errorType;
+    /**
+     * Explicit retry hint. When undefined the compute layer falls back to the
+     * status: no response, 429 or 5xx are retried.
+     */
+    retryable;
+    constructor(message, status, options = {}) {
+        super(message);
+        this.status = status;
+        this.name = "InferenceRequestError";
+        this.errorType = options.errorType ?? null;
+        this.retryable = options.retryable;
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readUsage(value) {
+    if (!isRecord(value))
+        return undefined;
+    const num = (v) => (typeof v === "number" ? v : undefined);
+    const usage = {
+        promptTokens: num(value.prompt_tokens),
+        completionTokens: num(value.completion_tokens),
+        totalTokens: num(value.total_tokens),
+    };
+    return usage;
+}
+function readContent(body) {
+    if (!isRecord(body) || !Array.isArray(body.choices))
+        return null;
+    const first = body.choices[0];
+    if (!isRecord(first) || !isRecord(first.message))
+        return null;
+    const index = typeof first.index === "number" ? first.index : 0;
+    const field = `choices.${index}.message.content`;
+    const id = typeof body.id === "string" ? body.id : "";
+    const content = first.message.content;
+    if (typeof content === "string")
+        return { content, field, id };
+    // Some providers return content parts.
+    if (Array.isArray(content)) {
+        const text = content
+            .map((part) => isRecord(part) && typeof part.text === "string" ? part.text : "")
+            .join("");
+        return { content: text, field, id };
+    }
+    return null;
+}
+/** OpenAI-style `{ error: { type } }` of a rejection; never its message. */
+async function readErrorType(response) {
+    try {
+        const body = await response.json();
+        if (isRecord(body) && isRecord(body.error)) {
+            return typeof body.error.type === "string" ? body.error.type : null;
+        }
+    }
+    catch {
+        // Not JSON: no type to report.
+    }
+    return null;
+}
+/**
+ * Sign one relay request. A signer that cannot sign (locked key, wallet
+ * gone) is a permanent failure: the request is never sent unsigned, and the
+ * compute layer must not retry it into a storm.
+ */
+async function signOrThrow(signer, params) {
+    try {
+        return await signer.signRequest(params);
+    }
+    catch (err) {
+        const name = err instanceof Error ? err.name : "Error";
+        throw new InferenceRequestError(`inference request could not be signed (${name})`, null, { errorType: "relay_signing_failed", retryable: false });
+    }
+}
+export function createOpenAiCompatibleInferenceProvider(options = {}) {
+    const base = (options.baseUrl ?? DEFAULT_INFERENCE_BASE_URL).replace(/\/+$/, "");
+    const defaultModel = options.model ?? DEFAULT_INFERENCE_MODEL;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_INFERENCE_TIMEOUT_MS;
+    const doFetch = options.fetch ?? fetch;
+    const requestFields = options.requestFields ?? DEFAULT_INFERENCE_REQUEST_FIELDS;
+    const encryption = options.encryption;
+    // A bearer key means the base URL is a provider, not the relay: the relay
+    // never takes one, so the key wins and no signature is produced.
+    const requestSigner = options.apiKey ? undefined : options.requestSigner;
+    const chatUrl = new URL(`${base}/chat/completions`);
+    /** One send; `rejected` reports a non-2xx so the caller may retry once. */
+    async function send(input) {
+        const headers = new Headers({ "Content-Type": "application/json" });
+        if (options.apiKey) {
+            headers.set("Authorization", `Bearer ${options.apiKey}`);
+        }
+        const model = input.model || defaultModel;
+        let messages = input.messages;
+        let encrypted = null;
+        if (encryption) {
+            encrypted = await encryption.encryptRequest({
+                model,
+                messages,
+                headers,
+            });
+            messages = encrypted.messages;
+        }
+        const body = {
+            ...requestFields,
+            model,
+            messages,
+            max_tokens: input.maxTokens ?? DEFAULT_INFERENCE_MAX_TOKENS,
+        };
+        // Serialized ONCE, after encryption: the bytes that are hashed into the
+        // signature are the bytes that go on the wire (ciphertext included).
+        const payload = JSON.stringify(body);
+        if (requestSigner) {
+            headers.set("Authorization", await signOrThrow(requestSigner, {
+                aud: chatUrl.origin,
+                method: "POST",
+                uri: `${chatUrl.pathname}${chatUrl.search}`,
+                body: new TextEncoder().encode(payload),
+            }));
+        }
+        let response;
+        try {
+            response = await doFetch(chatUrl.toString(), {
+                method: "POST",
+                headers,
+                body: payload,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (err) {
+            // Transport failure: no status, no body. The message is the error
+            // class name only; it never carries request contents.
+            const name = err instanceof Error ? err.name : "Error";
+            throw new InferenceRequestError(`inference request failed before a response (${name})`, null);
+        }
+        if (!response.ok) {
+            const errorType = await readErrorType(response);
+            const retry = (await encryption?.onRejected?.({
+                status: response.status,
+                errorType,
+                headers: response.headers,
+            })) === true;
+            return {
+                ok: false,
+                retry,
+                error: new InferenceRequestError(`inference request failed with status ${response.status}${errorType ? ` (${errorType})` : ""}`, response.status, { errorType }),
+            };
+        }
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            throw new InferenceRequestError("inference response was not JSON", response.status);
+        }
+        const choice = readContent(parsed);
+        if (choice === null) {
+            throw new InferenceRequestError("inference response carried no assistant content", response.status);
+        }
+        let content = choice.content;
+        if (encrypted) {
+            // Fail closed: a reply that is not valid ciphertext for this request
+            // is an error, never used as plaintext.
+            content = await encrypted.decryptResponse({
+                content,
+                field: choice.field,
+                id: choice.id,
+                headers: response.headers,
+            });
+        }
+        if (content.trim() === "") {
+            // An empty reply must never become a "ready" derivative.
+            throw new InferenceRequestError("inference response carried no assistant content", response.status);
+        }
+        const receiptId = response.headers.get("x-receipt-id") ?? undefined;
+        const aciIdentity = response.headers.get("x-aci-identity") ?? undefined;
+        return {
+            ok: true,
+            result: {
+                content,
+                usage: readUsage(isRecord(parsed) ? parsed.usage : undefined),
+                ...(receiptId ? { receiptId } : {}),
+                ...(aciIdentity ? { aciIdentity } : {}),
+            },
+        };
+    }
+    return {
+        defaultModel,
+        async chat(input) {
+            const first = await send(input);
+            if (first.ok)
+                return first.result;
+            if (!first.retry)
+                throw first.error;
+            // The encryption asked for one re-send (fresh key, fresh nonce).
+            const second = await send(input);
+            if (second.ok)
+                return second.result;
+            throw second.error;
+        },
+    };
+}
+/** Test double: records calls, answers with a fixed JSON object by default. */
+export function createFakeInferenceProvider(options = {}) {
+    const calls = [];
+    return {
+        defaultModel: options.model ?? "fake-model",
+        calls,
+        async chat(input) {
+            calls.push(input);
+            if (options.respond)
+                return options.respond(input, calls.length - 1);
+            return {
+                content: JSON.stringify({
+                    answer: "fake answer",
+                    evidence: "fake evidence",
+                }),
+                receiptId: "fake-receipt",
+            };
+        },
+    };
+}
+//# sourceMappingURL=inference.js.map

package/dist/derivatives/inference.js.map

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

package/dist/derivatives/prompt.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Prompt assembly for a question: the source scopes' latest local records,
+ * trimmed newest-first to a bounded number of items each, framed by a system
+ * prompt that pins the model to the provided data and to a JSON answer.
+ *
+ * Nothing here leaves the Personal Server except through the inference
+ * provider call the compute step makes.
+ */
+import { type AnswerShape } from "./answer-shape.js";
+import type { InferenceMessage } from "./inference.js";
+export declare const DEFAULT_MAX_SOURCE_ITEMS = 50;
+/** Upper bound on the serialized size of one source's trimmed data. */
+export declare const DEFAULT_MAX_SOURCE_CHARS = 200000;
+/**
+ * Newest first. Items that carry a timestamp sort by it; items that do not
+ * keep their relative order after the timestamped ones, reversed, on the
+ * assumption that a connector appends newest last. Stable.
+ */
+export declare function sortNewestFirst<T>(items: readonly T[]): T[];
+export interface TrimResult {
+    data: unknown;
+    /** Items kept / items present, summed over every array that was trimmed. */
+    kept: number;
+    total: number;
+    /** True when the char cap cut the serialization. */
+    truncated: boolean;
+}
+/**
+ * The trim rule. A record whose `data` is an array is trimmed to the newest
+ * `maxItems`; a record object trims every top-level array value the same
+ * way and keeps its other keys; reserved server keys are dropped. When the
+ * serialized result still exceeds `maxChars`, items are dropped from the
+ * old end until it fits (at least one is kept), and as a last resort the
+ * serialization itself is cut at `maxChars`.
+ */
+export declare function trimSourceData(data: unknown, options?: {
+    maxItems?: number;
+    maxChars?: number;
+}): TrimResult;
+export interface PromptSource {
+    scope: string;
+    collectedAt: string;
+    version: number;
+    data: unknown;
+    kept: number;
+    total: number;
+    truncated: boolean;
+}
+export declare const SYSTEM_PROMPT: string;
+/**
+ * The system prompt for a question that declared an answer shape: the same
+ * grounding, but `answer` is the declared object rather than prose. The
+ * prompt is not the boundary (the reply is validated against the compiled
+ * shape afterwards); it is what makes the model produce a matching reply
+ * on the first try.
+ */
+export declare function shapedSystemPrompt(shape: AnswerShape): string;
+/** Assemble the chat messages for one compute. */
+export declare function buildQuestionMessages(input: {
+    question: string;
+    sources: readonly PromptSource[];
+    answerShape?: AnswerShape | null;
+}): InferenceMessage[];
+/**
+ * The corrective turn after a reply that did not match the declared shape:
+ * the model's own reply back as context, then what was wrong with it. The
+ * issue list comes from zod and states constraints only, so nothing of the
+ * user data is restated here that the model did not already send.
+ */
+export declare function buildShapeRetryMessages(input: {
+    messages: readonly InferenceMessage[];
+    reply: string;
+    issues: readonly string[];
+    answerShape: AnswerShape;
+}): InferenceMessage[];
+export interface ParsedAnswer {
+    answer: string;
+    evidence: string | null;
+}
+/**
+ * Read the model's JSON answer. Tolerates a fenced code block or leading
+ * prose around the object; falls back to the whole text as the answer when
+ * no object can be parsed (the answer is still the model's, just unframed).
+ */
+export declare function parseAnswer(content: string): ParsedAnswer;
+export interface ParsedShapedAnswer {
+    /** The object to check against the compiled shape; never validated here. */
+    answer: Record<string, unknown>;
+    evidence: string | null;
+}
+/**
+ * Read the model's reply for a question that declared a shape. Returns
+ * every object worth checking, best first: the `answer` member of the
+ * envelope, then the envelope itself for a model that put the declared
+ * fields at the top level. Empty when nothing parsed as an object at all,
+ * which is a shape failure like any other.
+ */
+export declare function parseShapedAnswer(content: string): ParsedShapedAnswer[];
+//# sourceMappingURL=prompt.d.ts.map

package/dist/derivatives/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/derivatives/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAC3C,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,SAAU,CAAC;AAyChD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAW3D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACrD,UAAU,CAqDZ;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;CACpB;AAOD,eAAO,MAAM,aAAa,QAKd,CAAC;AAEb;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAW7D;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAClC,GAAG,gBAAgB,EAAE,CAiCrB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;CAC1B,GAAG,gBAAgB,EAAE,CAgBrB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAmBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAgBzD;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAkBvE"}

package/dist/derivatives/prompt.js

@@ -0,0 +1,281 @@
+/**
+ * Prompt assembly for a question: the source scopes' latest local records,
+ * trimmed newest-first to a bounded number of items each, framed by a system
+ * prompt that pins the model to the provided data and to a JSON answer.
+ *
+ * Nothing here leaves the Personal Server except through the inference
+ * provider call the compute step makes.
+ */
+import { describeAnswerShape } from "./answer-shape.js";
+export const DEFAULT_MAX_SOURCE_ITEMS = 50;
+/** Upper bound on the serialized size of one source's trimmed data. */
+export const DEFAULT_MAX_SOURCE_CHARS = 200_000;
+/** Keys a record commonly carries its own timestamp under, in priority order. */
+const TIMESTAMP_KEYS = [
+    "collectedAt",
+    "updatedAt",
+    "updated_at",
+    "update_time",
+    "createdAt",
+    "created_at",
+    "create_time",
+    "timestamp",
+    "time",
+    "date",
+    "publishedAt",
+    "published_at",
+];
+/** Server-stamped envelope keys that are not user data. */
+const RESERVED_KEYS = new Set(["$lineage", "$writtenBy", "$binary"]);
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function timestampOf(item) {
+    if (!isRecord(item))
+        return null;
+    for (const key of TIMESTAMP_KEYS) {
+        const value = item[key];
+        if (typeof value === "number" && Number.isFinite(value)) {
+            // Seconds vs milliseconds: anything below 1e12 is taken as seconds.
+            return value < 1e12 ? value * 1000 : value;
+        }
+        if (typeof value === "string") {
+            const parsed = Date.parse(value);
+            if (!Number.isNaN(parsed))
+                return parsed;
+        }
+    }
+    return null;
+}
+/**
+ * Newest first. Items that carry a timestamp sort by it; items that do not
+ * keep their relative order after the timestamped ones, reversed, on the
+ * assumption that a connector appends newest last. Stable.
+ */
+export function sortNewestFirst(items) {
+    const indexed = items.map((item, index) => ({
+        item,
+        index,
+        at: timestampOf(item),
+    }));
+    const dated = indexed
+        .filter((entry) => entry.at !== null)
+        .sort((a, b) => b.at - a.at || b.index - a.index);
+    const undated = indexed.filter((entry) => entry.at === null).reverse();
+    return [...dated, ...undated].map((entry) => entry.item);
+}
+/**
+ * The trim rule. A record whose `data` is an array is trimmed to the newest
+ * `maxItems`; a record object trims every top-level array value the same
+ * way and keeps its other keys; reserved server keys are dropped. When the
+ * serialized result still exceeds `maxChars`, items are dropped from the
+ * old end until it fits (at least one is kept), and as a last resort the
+ * serialization itself is cut at `maxChars`.
+ */
+export function trimSourceData(data, options = {}) {
+    const maxItems = Math.max(1, options.maxItems ?? DEFAULT_MAX_SOURCE_ITEMS);
+    const maxChars = Math.max(1, options.maxChars ?? DEFAULT_MAX_SOURCE_CHARS);
+    let kept = 0;
+    let total = 0;
+    const trimArray = (items, limit) => {
+        total += items.length;
+        const sorted = sortNewestFirst(items).slice(0, limit);
+        kept += sorted.length;
+        return sorted;
+    };
+    const build = (limit) => {
+        kept = 0;
+        total = 0;
+        if (Array.isArray(data))
+            return trimArray(data, limit);
+        if (isRecord(data)) {
+            // A stamped derivative also stores the caller lineage field the server
+            // consumed; it carries the same source data-point ids as `$lineage`
+            // and must not reach the prompt, or a question could echo them into
+            // an answer a grantee reads.
+            const stamped = "$lineage" in data;
+            const out = {};
+            for (const [key, value] of Object.entries(data)) {
+                if (RESERVED_KEYS.has(key))
+                    continue;
+                if (stamped && key === "lineage")
+                    continue;
+                out[key] = Array.isArray(value) ? trimArray(value, limit) : value;
+            }
+            return out;
+        }
+        return data;
+    };
+    let limit = maxItems;
+    let result = build(limit);
+    let text = JSON.stringify(result) ?? "null";
+    // Shrink the item budget while the serialization is over the cap. Each
+    // pass at least halves the budget, so this ends in O(log maxItems) steps.
+    while (text.length > maxChars && limit > 1) {
+        limit = Math.max(1, Math.floor(limit / 2));
+        result = build(limit);
+        text = JSON.stringify(result) ?? "null";
+    }
+    if (text.length > maxChars) {
+        return {
+            data: `${text.slice(0, maxChars)}...[truncated]`,
+            kept,
+            total,
+            truncated: true,
+        };
+    }
+    return { data: result, kept, total, truncated: false };
+}
+const GROUNDING = [
+    "You answer a question about a person using ONLY the user data provided in the message.",
+    "Do not use outside knowledge and do not guess; if the data does not support an answer, say so in the answer.",
+];
+export const SYSTEM_PROMPT = [
+    ...GROUNDING,
+    "Respond with a single JSON object and nothing else, with exactly these fields:",
+    '  "answer": string, the answer to the question, written for the person the data belongs to;',
+    '  "evidence": string, a short summary of which parts of the data support the answer.',
+].join("\n");
+/**
+ * The system prompt for a question that declared an answer shape: the same
+ * grounding, but `answer` is the declared object rather than prose. The
+ * prompt is not the boundary (the reply is validated against the compiled
+ * shape afterwards); it is what makes the model produce a matching reply
+ * on the first try.
+ */
+export function shapedSystemPrompt(shape) {
+    return [
+        ...GROUNDING,
+        "Respond with a single JSON object and nothing else, with exactly these fields:",
+        '  "answer": object, holding exactly the fields listed below and no others;',
+        '  "evidence": string, a short summary of which parts of the data support the answer.',
+        'The "answer" object holds:',
+        ...describeAnswerShape(shape),
+        "Use the declared type for every field: a number field is a JSON number, not a string.",
+        "Do not add fields, do not rename them and do not put prose outside them.",
+    ].join("\n");
+}
+/** Assemble the chat messages for one compute. */
+export function buildQuestionMessages(input) {
+    const sections = input.sources.map((source) => {
+        const note = source.total > source.kept
+            ? ` (newest ${source.kept} of ${source.total} items)`
+            : "";
+        const cut = source.truncated ? " (truncated)" : "";
+        return [
+            `### Scope: ${source.scope}${note}${cut}`,
+            `Collected at: ${source.collectedAt}`,
+            JSON.stringify(source.data),
+        ].join("\n");
+    });
+    const user = [
+        "## Question",
+        input.question,
+        "",
+        "## User data",
+        ...sections,
+        "",
+        input.answerShape
+            ? "Answer the question as a JSON object with the fields answer and evidence, where answer holds exactly the declared fields."
+            : "Answer the question as a JSON object with the fields answer and evidence.",
+    ].join("\n");
+    return [
+        {
+            role: "system",
+            content: input.answerShape
+                ? shapedSystemPrompt(input.answerShape)
+                : SYSTEM_PROMPT,
+        },
+        { role: "user", content: user },
+    ];
+}
+/**
+ * The corrective turn after a reply that did not match the declared shape:
+ * the model's own reply back as context, then what was wrong with it. The
+ * issue list comes from zod and states constraints only, so nothing of the
+ * user data is restated here that the model did not already send.
+ */
+export function buildShapeRetryMessages(input) {
+    return [
+        ...input.messages,
+        { role: "assistant", content: input.reply },
+        {
+            role: "user",
+            content: [
+                "That reply did not match the required answer shape:",
+                ...input.issues.map((issue) => `- ${issue}`),
+                "",
+                'Answer again as a single JSON object with the fields answer and evidence, where "answer" holds:',
+                ...describeAnswerShape(input.answerShape),
+                "Return the JSON object and nothing else.",
+            ].join("\n"),
+        },
+    ];
+}
+/**
+ * The framings a model wraps its JSON in: a fenced code block, the bare
+ * text, and the span between the first `{` and the last `}`. Deduplicated,
+ * because a bare object is all three at once.
+ */
+function jsonFramings(content) {
+    const candidates = [content.trim()];
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(content);
+    if (fenced?.[1])
+        candidates.unshift(fenced[1].trim());
+    const first = content.indexOf("{");
+    const last = content.lastIndexOf("}");
+    if (first !== -1 && last > first) {
+        candidates.push(content.slice(first, last + 1));
+    }
+    return [...new Set(candidates)];
+}
+/**
+ * Read the model's JSON answer. Tolerates a fenced code block or leading
+ * prose around the object; falls back to the whole text as the answer when
+ * no object can be parsed (the answer is still the model's, just unframed).
+ */
+export function parseAnswer(content) {
+    for (const candidate of jsonFramings(content)) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (isRecord(parsed) && typeof parsed.answer === "string") {
+                return {
+                    answer: parsed.answer,
+                    evidence: typeof parsed.evidence === "string" ? parsed.evidence : null,
+                };
+            }
+        }
+        catch {
+            // try the next framing
+        }
+    }
+    return { answer: content.trim(), evidence: null };
+}
+/**
+ * Read the model's reply for a question that declared a shape. Returns
+ * every object worth checking, best first: the `answer` member of the
+ * envelope, then the envelope itself for a model that put the declared
+ * fields at the top level. Empty when nothing parsed as an object at all,
+ * which is a shape failure like any other.
+ */
+export function parseShapedAnswer(content) {
+    const found = [];
+    for (const candidate of jsonFramings(content)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(parsed))
+            continue;
+        const evidence = typeof parsed.evidence === "string" ? parsed.evidence : null;
+        if (isRecord(parsed.answer)) {
+            found.push({ answer: parsed.answer, evidence });
+        }
+        found.push({ answer: parsed, evidence });
+    }
+    return found;
+}
+//# sourceMappingURL=prompt.js.map