@polpo-ai/server 0.15.81 → 0.15.83

package/dist/routes/completions/client-tools.d.ts

@@ -0,0 +1,46 @@
+import { jsonSchema } from "ai";
+type RequestClientTool = {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
+type RequestToolChoice = "auto" | "none" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+type ModelToolCall = {
+    toolCallId?: string;
+    toolName?: string;
+    input?: unknown;
+};
+export declare class RequestClientToolError extends Error {
+    readonly code: "tool_name_conflict" | "parallel_client_tool_calls_returned";
+    readonly toolName?: string;
+    constructor(code: RequestClientToolError["code"], message: string, toolName?: string);
+}
+/**
+ * Convert request-declared OpenAI function tools into AI SDK tools without an
+ * execute handler. They can be selected by the model and returned to the
+ * caller, but can never cross the server execution boundary.
+ */
+export declare function createRequestClientTools(tools: RequestClientTool[] | undefined): Record<string, {
+    description?: string;
+    strict?: boolean;
+    inputSchema: ReturnType<typeof jsonSchema>;
+}>;
+export declare function assertRequestClientToolNamesAvailable(requestTools: RequestClientTool[] | undefined, occupiedNames: Iterable<string>): void;
+export declare function requestToolChoiceToAI(choice: RequestToolChoice | undefined): unknown | undefined;
+/**
+ * A request-scoped client tool ends the server turn. Executing any sibling
+ * call before returning would make the result order-dependent, so mixed or
+ * parallel calls fail before a server tool is dispatched.
+ */
+export declare function selectRequestClientToolCall<T extends ModelToolCall>(calls: T[], clientToolNames: ReadonlySet<string>): T | undefined;
+export {};
+//# sourceMappingURL=client-tools.d.ts.map

package/dist/routes/completions/client-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.d.ts","sourceRoot":"","sources":["../../../src/routes/completions/client-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAEhC,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH,CAAC;AAEF,KAAK,iBAAiB,GAClB,MAAM,GACN,MAAM,GACN,UAAU,GACV;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAErD,KAAK,aAAa,GAAG;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAQF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,qCAAqC,CAAC;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGzB,IAAI,EAAE,sBAAsB,CAAC,MAAM,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM;CAOpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,iBAAiB,EAAE,GAAG,SAAS,GACrC,MAAM,CAAC,MAAM,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;CAAE,CAAC,CASxG;AAED,wBAAgB,qCAAqC,CACnD,YAAY,EAAE,iBAAiB,EAAE,GAAG,SAAS,EAC7C,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC9B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,GAAG,SAAS,GACpC,OAAO,GAAG,SAAS,CAGrB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,aAAa,EACjE,KAAK,EAAE,CAAC,EAAE,EACV,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,GACnC,CAAC,GAAG,SAAS,CAYf"}

package/dist/routes/completions/client-tools.js

@@ -0,0 +1,60 @@
+import { jsonSchema } from "ai";
+const EMPTY_PARAMETERS = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+export class RequestClientToolError extends Error {
+    code;
+    toolName;
+    constructor(code, message, toolName) {
+        super(message);
+        this.name = "RequestClientToolError";
+        this.code = code;
+        this.toolName = toolName;
+    }
+}
+/**
+ * Convert request-declared OpenAI function tools into AI SDK tools without an
+ * execute handler. They can be selected by the model and returned to the
+ * caller, but can never cross the server execution boundary.
+ */
+export function createRequestClientTools(tools) {
+    return Object.fromEntries((tools ?? []).map((tool) => [
+        tool.function.name,
+        {
+            ...(tool.function.description ? { description: tool.function.description } : {}),
+            ...(tool.function.strict !== undefined ? { strict: tool.function.strict } : {}),
+            inputSchema: jsonSchema(tool.function.parameters ?? EMPTY_PARAMETERS),
+        },
+    ]));
+}
+export function assertRequestClientToolNamesAvailable(requestTools, occupiedNames) {
+    const occupied = new Set([...occupiedNames].map((name) => name.toLocaleLowerCase("en-US")));
+    for (const tool of requestTools ?? []) {
+        const name = tool.function.name;
+        if (!occupied.has(name.toLocaleLowerCase("en-US")))
+            continue;
+        throw new RequestClientToolError("tool_name_conflict", `Request tool name conflicts with an effective runtime tool: ${name}`, name);
+    }
+}
+export function requestToolChoiceToAI(choice) {
+    if (choice === undefined || typeof choice === "string")
+        return choice;
+    return { type: "tool", toolName: choice.function.name };
+}
+/**
+ * A request-scoped client tool ends the server turn. Executing any sibling
+ * call before returning would make the result order-dependent, so mixed or
+ * parallel calls fail before a server tool is dispatched.
+ */
+export function selectRequestClientToolCall(calls, clientToolNames) {
+    const clientCalls = calls.filter((call) => typeof call.toolName === "string" && clientToolNames.has(call.toolName));
+    if (clientCalls.length === 0)
+        return undefined;
+    if (calls.length !== 1 || clientCalls.length !== 1) {
+        throw new RequestClientToolError("parallel_client_tool_calls_returned", "A client-side tool call cannot be combined with another tool call in the same turn");
+    }
+    return clientCalls[0];
+}
+//# sourceMappingURL=client-tools.js.map

package/dist/routes/completions/client-tools.js.map

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

package/dist/routes/completions/client-tools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-tools.test.d.ts.map

package/dist/routes/completions/client-tools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-tools.test.d.ts","sourceRoot":"","sources":["../../../src/routes/completions/client-tools.test.ts"],"names":[],"mappings":""}

package/dist/routes/completions/client-tools.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { RequestClientToolError, assertRequestClientToolNamesAvailable, createRequestClientTools, requestToolChoiceToAI, selectRequestClientToolCall, } from "./client-tools.js";
+const requestTool = (name = "configure_site_module") => ({
+    type: "function",
+    function: {
+        name,
+        description: "Open the module configuration UI.",
+        parameters: {
+            type: "object",
+            properties: {
+                module: { type: "string" },
+            },
+            required: ["module"],
+            additionalProperties: false,
+        },
+        strict: true,
+    },
+});
+function capturedError(run) {
+    try {
+        run();
+    }
+    catch (error) {
+        if (error instanceof RequestClientToolError)
+            return error;
+        throw error;
+    }
+    throw new Error("Expected RequestClientToolError");
+}
+describe("request-scoped client tools", () => {
+    it("maps OpenAI function tools to return-only AI SDK tools", () => {
+        const tools = createRequestClientTools([requestTool()]);
+        expect(Object.keys(tools)).toEqual(["configure_site_module"]);
+        expect(tools.configure_site_module).toMatchObject({
+            description: "Open the module configuration UI.",
+            strict: true,
+            inputSchema: {
+                jsonSchema: {
+                    type: "object",
+                    properties: { module: { type: "string" } },
+                    required: ["module"],
+                    additionalProperties: false,
+                },
+            },
+        });
+        expect(tools.configure_site_module).not.toHaveProperty("execute");
+    });
+    it("uses a closed empty object schema for parameterless functions", () => {
+        const tools = createRequestClientTools([{
+                type: "function",
+                function: { name: "open_dialog" },
+            }]);
+        expect(tools.open_dialog.inputSchema).toMatchObject({
+            jsonSchema: {
+                type: "object",
+                properties: {},
+                additionalProperties: false,
+            },
+        });
+    });
+    it("rejects collisions with any effective tool name case-insensitively", () => {
+        const error = capturedError(() => assertRequestClientToolNamesAvailable([requestTool("Configure_Site_Module")], ["configure_site_module", "bash"]));
+        expect(error).toMatchObject({
+            code: "tool_name_conflict",
+            toolName: "Configure_Site_Module",
+        });
+    });
+    it("accepts request tools that do not overlap the effective palette", () => {
+        expect(() => assertRequestClientToolNamesAvailable([requestTool()], ["bash", "tool_search", "ask_user_question"])).not.toThrow();
+    });
+    it.each([
+        ["auto", "auto"],
+        ["none", "none"],
+        ["required", "required"],
+        [
+            { type: "function", function: { name: "configure_site_module" } },
+            { type: "tool", toolName: "configure_site_module" },
+        ],
+    ])("maps OpenAI tool_choice %# to AI SDK tool choice", (choice, expected) => {
+        expect(requestToolChoiceToAI(choice)).toEqual(expected);
+    });
+    it("returns the only client-side call without executing it", () => {
+        const call = {
+            toolCallId: "call_1",
+            toolName: "configure_site_module",
+            input: { module: "commerce" },
+        };
+        expect(selectRequestClientToolCall([call], new Set([call.toolName]))).toBe(call);
+    });
+    it("returns undefined when the turn contains no client-side call", () => {
+        expect(selectRequestClientToolCall([
+            { toolCallId: "call_1", toolName: "bash", input: {} },
+        ], new Set(["configure_site_module"]))).toBeUndefined();
+    });
+    it("fails closed when a client-side call is mixed with another call", () => {
+        const error = capturedError(() => selectRequestClientToolCall([
+            { toolCallId: "call_1", toolName: "configure_site_module", input: {} },
+            { toolCallId: "call_2", toolName: "bash", input: {} },
+        ], new Set(["configure_site_module"])));
+        expect(error).toMatchObject({
+            code: "parallel_client_tool_calls_returned",
+        });
+    });
+});
+//# sourceMappingURL=client-tools.test.js.map

package/dist/routes/completions/client-tools.test.js.map

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

package/dist/routes/completions/continuation.d.ts

@@ -0,0 +1,10 @@
+export declare function continuationFingerprint(input: {
+    sessionId: string;
+    agent: string;
+    loop: string;
+    user?: string;
+    toolCallId: string;
+    expectedSessionVersion: number;
+    result: unknown;
+}): string;
+//# sourceMappingURL=continuation.d.ts.map

package/dist/routes/completions/continuation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.d.ts","sourceRoot":"","sources":["../../../src/routes/completions/continuation.ts"],"names":[],"mappings":"AAaA,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,MAAM,CAET"}

package/dist/routes/completions/continuation.js

@@ -0,0 +1,18 @@
+import { createHash } from "node:crypto";
+function stableJson(value) {
+    if (value === undefined)
+        return "null";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    return `{${Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
+        .join(",")}}`;
+}
+export function continuationFingerprint(input) {
+    return createHash("sha256").update(stableJson(input)).digest("hex");
+}
+//# sourceMappingURL=continuation.js.map

package/dist/routes/completions/continuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.js","sourceRoot":"","sources":["../../../src/routes/completions/continuation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACxE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SACxD,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC;SAC1C,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;SACpE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAQvC;IACC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC"}

package/dist/routes/completions/continuation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=continuation.test.d.ts.map

package/dist/routes/completions/continuation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.test.d.ts","sourceRoot":"","sources":["../../../src/routes/completions/continuation.test.ts"],"names":[],"mappings":""}

package/dist/routes/completions/continuation.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import { continuationFingerprint } from "./continuation.js";
+describe("continuationFingerprint", () => {
+    it("is stable across nested JSON key ordering", () => {
+        const base = {
+            sessionId: "session-1",
+            agent: "leo",
+            loop: "build",
+            toolCallId: "call-1",
+            expectedSessionVersion: 2,
+        };
+        expect(continuationFingerprint({
+            ...base,
+            result: { site: { id: "1", mode: "edit" }, accepted: true },
+        })).toBe(continuationFingerprint({
+            ...base,
+            result: { accepted: true, site: { mode: "edit", id: "1" } },
+        }));
+    });
+    it("changes for a different session boundary or result", () => {
+        const base = {
+            sessionId: "session-1",
+            agent: "leo",
+            loop: "build",
+            toolCallId: "call-1",
+            expectedSessionVersion: 2,
+            result: "ok",
+        };
+        expect(continuationFingerprint(base)).not.toBe(continuationFingerprint({
+            ...base,
+            sessionId: "session-2",
+        }));
+        expect(continuationFingerprint(base)).not.toBe(continuationFingerprint({
+            ...base,
+            result: "different",
+        }));
+    });
+});
+//# sourceMappingURL=continuation.test.js.map

package/dist/routes/completions/continuation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"continuation.test.js","sourceRoot":"","sources":["../../../src/routes/completions/continuation.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACnD,MAAM,IAAI,GAAG;YACX,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,KAAK;YACZ,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,QAAQ;YACpB,sBAAsB,EAAE,CAAC;SAC1B,CAAC;QACF,MAAM,CAAC,uBAAuB,CAAC;YAC7B,GAAG,IAAI;YACP,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;SAC5D,CAAC,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC;YAC/B,GAAG,IAAI;YACP,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;SAC5D,CAAC,CAAC,CAAC;IACN,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,IAAI,GAAG;YACX,SAAS,EAAE,WAAW;YACtB,KAAK,EAAE,KAAK;YACZ,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,QAAQ;YACpB,sBAAsB,EAAE,CAAC;YACzB,MAAM,EAAE,IAAI;SACb,CAAC;QACF,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC;YACrE,GAAG,IAAI;YACP,SAAS,EAAE,WAAW;SACvB,CAAC,CAAC,CAAC;QACJ,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,uBAAuB,CAAC;YACrE,GAAG,IAAI;YACP,MAAM,EAAE,WAAW;SACpB,CAAC,CAAC,CAAC;IACN,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/routes/completions/conversation-turn.d.ts

@@ -45,6 +45,10 @@ export interface PrepareConversationTurnOptions {
     /** Trusted surface identity. Omit for ordinary HTTP/API agent calls. */
     runtime?: CompletionRuntimeInvocation;
     signal?: AbortSignal;
+    continuation?: {
+        idempotencyKey: string;
+        fingerprint: string;
+    };
 }
 export interface RunConversationTurnInput extends PrepareConversationTurnOptions {
     body: CompletionRequestBody;

package/dist/routes/completions/conversation-turn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation-turn.d.ts","sourceRoot":"","sources":["../../../src/routes/completions/conversation-turn.ts"],"names":[],"mappings":"AACA,OAAO,EAuBL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAE3B,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EACV,mBAAmB,EACnB,2BAA2B,EAE5B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAe1D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAOjE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAanC,KAAK,aAAa,GAAG;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QAAE,KAAK,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACnE,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,GAAG,CAAC;IACjB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,UAAU,EAAE,GAAG,EAAE,CAAC;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,YAAY,EAAE,uBAAuB,CAAC;IACtC,YAAY,EAAE,GAAG,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,cAAc,CAAC,EAAE,wBAAwB,CAAC;IAC1C,iBAAiB,CAAC,EAAE,2BAA2B,CAAC;IAChD,cAAc,CAAC,EAAE,sBAAsB,CAAC;IACxC,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,aAAa,GAAG,mBAAmB,GAAG,YAAY,CAAC;AAE1F,MAAM,WAAW,8BAA8B;IAC7C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,wEAAwE;IACxE,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,wBAAyB,SAAQ,8BAA8B;IAC9E,IAAI,EAAE,qBAAqB,CAAC;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CACvD;AAED,MAAM,MAAM,sBAAsB,GAAG,oBAAoB,GAAG;IAC1D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAwOF,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,IAAI,EAAE,qBAAqB,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,2BAA2B,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GAAG,qBAAqB,CAexB;AA6ED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,qBAAqB,EAC3B,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,wBAAwB,CAAC,CAgkBnC;AAED,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,sBAAsB,CAAC,CA4BjC"}
+{"version":3,"file":"conversation-turn.d.ts","sourceRoot":"","sources":["../../../src/routes/completions/conversation-turn.ts"],"names":[],"mappings":"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"}

package/dist/routes/completions/conversation-turn.js

@@ -1,8 +1,10 @@
 import { nanoid } from "nanoid";
 import { agentMemoryScope, createToolInvocationContext, createRuntimePromptContextSegment, compileExecutionRouteManifest, createExecutionRouteResolvedEvent, createExplicitExecutionRoute, createRuntimePlanResolvedEvent, executionRouteRuntimePlanFields, normalizeRuntimeContextTrustMode, normalizeRuntimePlan, renderRuntimePromptContextSegment, renderRuntimePromptContextSegments, renderRuntimeContextPrompt, replacesLegacyAgentMemory, replacesLegacySharedMemory, resolveRuntimeContext, resolveExecutionRoute, resolveLoopSelection, validateExecutionRouterConfig, } from "@polpo-ai/core";
 import { normalizeChatInteractionSettings, resolveChatInteractionCapabilities, } from "@polpo-ai/core/chat-interactions";
-import { convertMessages, extractText } from "./message-mapping.js";
+import { convertMessages, extractText, sessionMessagesToCompletionMessages, } from "./message-mapping.js";
+import { SessionContinuationError } from "@polpo-ai/core/session-continuation";
 import { clientSideToolsForCapabilities, toAIToolChoice, } from "./tool-mapping.js";
+import { RequestClientToolError, assertRequestClientToolNamesAvailable, createRequestClientTools, requestToolChoiceToAI, } from "./client-tools.js";
 import { createGuardedCompletionToolExecutor, } from "./tool-guardrails.js";
 import { assertCompletionMessageContent, assertModelPreflightValue, assertRuntimeContextResolution, } from "./preflight-validation.js";
 import { agentConfigForModelPrimary, modelSelectionForAgent, modelSelectionForResolvedModel, } from "./agent-step-runner.js";
@@ -23,6 +25,16 @@ function completionError(message, status, code, type = "invalid_request_error")
         },
     };
 }
+async function cleanupFailedPreparation(cleanup) {
+    if (!cleanup)
+        return;
+    try {
+        await cleanup();
+    }
+    catch {
+        // Preserve the deterministic preflight error; cleanup is best-effort here.
+    }
+}
 function preflightError(error) {
     const guardrail = guardrailErrorEnvelope(error);
     if (guardrail) {
@@ -313,7 +325,8 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
     let executionRoute;
     let activatedSkills = [];
     let deferredAgentTools = false;
-    const completionId = options.completionId ?? `chatcmpl-${nanoid(24)}`;
+    let completionId = options.completionId ?? `chatcmpl-${nanoid(24)}`;
+    const sessionStore = deps.getSessionStore();
     const invocation = completionInvocation(options.runtime);
     const interactionSettings = normalizeChatInteractionSettings(initialAgentConfig?.chat);
     const interactionCapabilities = resolveChatInteractionCapabilities({
@@ -321,12 +334,26 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
         settings: interactionSettings,
         client: body.polpo?.capabilities,
     });
-    const clientSideTools = clientSideToolsForCapabilities(interactionCapabilities);
+    const builtInClientSideTools = clientSideToolsForCapabilities(interactionCapabilities);
+    try {
+        assertRequestClientToolNamesAvailable(body.tools, Object.keys(builtInClientSideTools));
+    }
+    catch (error) {
+        if (error instanceof RequestClientToolError) {
+            return completionError(error.message, 400, error.code);
+        }
+        throw error;
+    }
+    const requestClientSideTools = createRequestClientTools(body.tools);
+    const clientSideTools = {
+        ...builtInClientSideTools,
+        ...requestClientSideTools,
+    };
     const clientSideToolNames = new Set(Object.keys(clientSideTools));
     const contextTrust = normalizeRuntimeContextTrustMode(deps.getConfig()?.settings?.contextTrust);
     const converted = convertMessages(body.messages, contextTrust);
     let { aiMessages, extraSystemParts, promptContextSegments, } = converted;
-    const callerSystemParts = contextTrust === "enforce" && promptContextSegments.length > 0
+    let callerSystemParts = contextTrust === "enforce" && promptContextSegments.length > 0
         ? [renderRuntimePromptContextSegments(promptContextSegments)]
         : extraSystemParts;
     if (agentMode) {
@@ -388,6 +415,56 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
             }
         }
         resolvedAgentConfig = agentConfig;
+        const continuation = body.polpo?.continuation;
+        if (continuation) {
+            if (!projectLoopRuntime) {
+                return completionError("The selected loop is not available as a Project Loop", 422, "loop_not_available");
+            }
+            if (!options.sessionId || !options.continuation) {
+                return completionError("Client-tool continuation requires an existing session and Idempotency-Key", 400, "invalid_continuation_request");
+            }
+            if (!sessionStore?.prepareContinuation) {
+                return completionError("Session continuation is not supported by the configured store", 501, "session_continuation_unavailable");
+            }
+            const toolResult = body.messages[0];
+            try {
+                const prepared = await sessionStore.prepareContinuation({
+                    sessionId: options.sessionId,
+                    agent: body.agent,
+                    user: options.runtime?.user ?? body.user,
+                    ...(options.runtime?.scope ? { scope: options.runtime.scope } : {}),
+                    toolCallId: continuation.tool_call_id,
+                    result: toolResult.content,
+                    expectedSessionVersion: continuation.expected_session_version,
+                    idempotencyKey: options.continuation.idempotencyKey,
+                    fingerprint: options.continuation.fingerprint,
+                    runId: completionId,
+                });
+                completionId = prepared.runId;
+                const canonicalMessages = sessionMessagesToCompletionMessages(prepared.messages);
+                body = { ...body, messages: canonicalMessages };
+                const canonical = convertMessages(body.messages, contextTrust);
+                aiMessages = canonical.aiMessages;
+                extraSystemParts = canonical.extraSystemParts;
+                promptContextSegments = canonical.promptContextSegments;
+                callerSystemParts = contextTrust === "enforce" && promptContextSegments.length > 0
+                    ? [renderRuntimePromptContextSegments(promptContextSegments)]
+                    : extraSystemParts;
+                options.setHeader?.("x-polpo-run-id", completionId);
+                options.setHeader?.("x-session-version", String(prepared.sessionVersion + 1));
+            }
+            catch (error) {
+                if (error instanceof SessionContinuationError) {
+                    const status = error.code === "session_not_found"
+                        ? 404
+                        : error.code === "continuation_scope_mismatch"
+                            ? 403
+                            : 409;
+                    return completionError(error.message, status, error.code);
+                }
+                throw error;
+            }
+        }
         if (requestedSkills.length > 0) {
             const assignedSkills = new Set(Array.isArray(agentConfig.skills)
                 ? agentConfig.skills.filter((skill) => typeof skill === "string")
@@ -555,7 +632,6 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
     if (projectLoopRuntime && isStructuredResponseFormat(body.response_format)) {
         return completionError("response_format is not supported with project loop execution", 400, "unsupported_response_format");
     }
-    const sessionStore = deps.getSessionStore();
     let sessionId = options.sessionId ?? null;
     if (sessionStore) {
         if (!sessionId) {
@@ -565,14 +641,20 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
             sessionId = await sessionStore.create({
                 title: sessionTitle,
                 agent: agentScope ?? undefined,
-                user: body.user,
+                user: options.runtime?.user ?? body.user,
                 metadata: body.metadata,
+                ...(options.runtime?.scope ? { scope: options.runtime.scope } : {}),
             });
         }
         const lastUserMsg = [...body.messages].reverse().find((message) => message.role === "user");
-        if (lastUserMsg && sessionId) {
+        if (!body.polpo?.continuation && lastUserMsg && sessionId) {
             await sessionStore.addMessage(sessionId, "user", lastUserMsg.content);
         }
+        if (!body.polpo?.continuation && sessionId && sessionStore.getSession) {
+            const current = await sessionStore.getSession(sessionId);
+            if (current)
+                options.setHeader?.("x-session-version", String(Number(current.version ?? 0) + 1));
+        }
     }
     if (deferredAgentTools) {
         const toolInvocation = createCompletionToolInvocation({
@@ -589,6 +671,21 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
         extraAiTools = resolvedTools.extraAiTools;
     }
     if (!projectLoopRuntime) {
+        try {
+            assertRequestClientToolNamesAvailable(body.tools, [
+                ...effectiveTools
+                    .map((tool) => tool?.name)
+                    .filter((name) => typeof name === "string"),
+                ...Object.keys(extraAiTools ?? {}),
+            ]);
+        }
+        catch (error) {
+            if (error instanceof RequestClientToolError) {
+                await cleanupFailedPreparation(onResponseFinished);
+                return completionError(error.message, 400, error.code);
+            }
+            throw error;
+        }
         effectiveToolExecutor = createGuardedCompletionToolExecutor({
             executor: effectiveToolExecutor,
             tools: effectiveTools,
@@ -615,6 +712,18 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
                 maxLoadBatch: toolDisclosure.maxLoadBatch,
                 maxSearchResults: toolDisclosure.maxSearchResults,
             });
+            try {
+                assertRequestClientToolNamesAvailable(body.tools, pool.tools
+                    .map((tool) => tool?.name)
+                    .filter((name) => typeof name === "string"));
+            }
+            catch (error) {
+                if (error instanceof RequestClientToolError) {
+                    await cleanupFailedPreparation(onResponseFinished);
+                    return completionError(error.message, 400, error.code);
+                }
+                throw error;
+            }
             const alwaysActive = [
                 ...Object.keys(extraAiTools ?? {}),
                 ...clientSideToolNames,
@@ -649,6 +758,9 @@ export async function prepareChatCompletionExecution(deps, body, options = {}) {
             activatedSkills,
         };
     }
+    if (body.tool_choice !== undefined) {
+        modelToolChoice = requestToolChoiceToAI(body.tool_choice);
+    }
     const execution = {
         deps,
         body,