@endora-commerce/mod-prompt-actions 0.0.0-stage → 0.100.0

package/dist/backend/services/llm/google-adapter.js

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import { fromWireName, parseOrThrow, postJson, toWireName, wireNameMap, } from './provider.js';
+/**
+ * Google (Gemini) adapter — `POST :generateContent` with
+ * functionDeclarations / functionCall parts. Native fetch, no SDK
+ * (research §R2). Gemini returns no tool-call ids, so synthetic ids are
+ * minted per response; functionResponse parts are matched by name, which the
+ * API expects.
+ */
+const ResponseSchema = z.object({
+    candidates: z
+        .array(z.object({
+        content: z.object({
+            parts: z
+                .array(z.union([
+                z.object({ text: z.string() }),
+                z.object({
+                    functionCall: z.object({ name: z.string(), args: z.unknown().optional() }),
+                }),
+            ]))
+                .default([]),
+        }),
+        finishReason: z.string().optional(),
+    }))
+        .min(1),
+});
+/** Gemini's parameter schema is an OpenAPI subset — strip JSON-Schema-only keys. */
+function sanitizeForGemini(schema) {
+    if (Array.isArray(schema))
+        return schema.map(sanitizeForGemini);
+    if (typeof schema !== 'object' || schema === null)
+        return schema;
+    const out = {};
+    for (const [k, v] of Object.entries(schema)) {
+        if (k === '$schema' || k === 'additionalProperties')
+            continue;
+        out[k] = sanitizeForGemini(v);
+    }
+    return out;
+}
+export class GoogleAdapter {
+    apiKey;
+    fetchImpl;
+    provider = 'google';
+    constructor(apiKey, fetchImpl = fetch) {
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+    }
+    async complete(req) {
+        const names = wireNameMap(req.tools);
+        const body = {
+            systemInstruction: { parts: [{ text: req.system }] },
+            generationConfig: { maxOutputTokens: req.maxTokens },
+            tools: [
+                {
+                    functionDeclarations: req.tools.map((t) => ({
+                        name: toWireName(t.name),
+                        description: t.description,
+                        parameters: sanitizeForGemini(t.inputSchema),
+                    })),
+                },
+            ],
+            contents: req.messages.map((m) => {
+                if (m.role === 'user')
+                    return { role: 'user', parts: [{ text: m.text }] };
+                if (m.role === 'assistant') {
+                    return {
+                        role: 'model',
+                        parts: [
+                            ...(m.text ? [{ text: m.text }] : []),
+                            ...m.toolCalls.map((c) => ({
+                                functionCall: { name: toWireName(c.name), args: c.arguments ?? {} },
+                            })),
+                        ],
+                    };
+                }
+                let response;
+                try {
+                    response = JSON.parse(m.resultJson);
+                }
+                catch {
+                    response = { value: m.resultJson };
+                }
+                // functionResponse.response must be an object.
+                const wrapped = typeof response === 'object' && response !== null && !Array.isArray(response)
+                    ? response
+                    : { value: response };
+                return {
+                    role: 'user',
+                    parts: [
+                        { functionResponse: { name: toWireName(m.toolName), response: wrapped } },
+                    ],
+                };
+            }),
+        };
+        const json = await postJson(this.provider, this.fetchImpl, `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(req.model)}:generateContent`, { 'x-goog-api-key': this.apiKey }, body);
+        const parsed = parseOrThrow(this.provider, ResponseSchema, json);
+        const candidate = parsed.candidates[0];
+        const texts = [];
+        const toolCalls = [];
+        candidate.content.parts.forEach((part, index) => {
+            if ('text' in part) {
+                texts.push(part.text);
+                return;
+            }
+            toolCalls.push({
+                id: `gcall_${index}_${part.functionCall.name}`,
+                name: fromWireName(part.functionCall.name, names),
+                arguments: part.functionCall.args ?? {},
+            });
+        });
+        return {
+            text: texts.length > 0 ? texts.join('\n') : null,
+            toolCalls,
+            stopReason: toolCalls.length > 0
+                ? 'tool_use'
+                : candidate.finishReason === 'STOP'
+                    ? 'end'
+                    : candidate.finishReason === 'MAX_TOKENS'
+                        ? 'max_tokens'
+                        : 'other',
+        };
+    }
+}
+//# sourceMappingURL=google-adapter.js.map

package/dist/backend/services/llm/google-adapter.js.map

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

package/dist/backend/services/llm/openai-adapter.d.ts

@@ -0,0 +1,9 @@
+import { type FetchLike, type LlmCompletion, type LlmProviderAdapter, type LlmRequest } from './provider.js';
+export declare class OpenAiAdapter implements LlmProviderAdapter {
+    private readonly apiKey;
+    private readonly fetchImpl;
+    readonly provider: "openai";
+    constructor(apiKey: string, fetchImpl?: FetchLike);
+    complete(req: LlmRequest): Promise<LlmCompletion>;
+}
+//# sourceMappingURL=openai-adapter.d.ts.map

package/dist/backend/services/llm/openai-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-adapter.d.ts","sourceRoot":"","sources":["../../../../src/backend/services/llm/openai-adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AA8BvB,qBAAa,aAAc,YAAW,kBAAkB;IAIpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,QAAQ,CAAC,QAAQ,EAAG,QAAQ,CAAU;gBAGnB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,SAAiB;IAGzC,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;CAyExD"}

package/dist/backend/services/llm/openai-adapter.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { LlmProviderError, fromWireName, parseOrThrow, postJson, toWireName, wireNameMap, } from './provider.js';
+/**
+ * OpenAI (GPT) adapter — `POST /v1/chat/completions` with tools/tool_calls.
+ * Native fetch, no SDK (research §R2). Tool-call arguments arrive as a JSON
+ * string and are parsed here; the interpreter re-validates against the
+ * tool's Zod schema regardless.
+ */
+const ResponseSchema = z.object({
+    choices: z
+        .array(z.object({
+        message: z.object({
+            content: z.string().nullable().optional(),
+            tool_calls: z
+                .array(z.object({
+                id: z.string(),
+                function: z.object({ name: z.string(), arguments: z.string() }),
+            }))
+                .optional(),
+        }),
+        finish_reason: z.string().nullable().optional(),
+    }))
+        .min(1),
+});
+export class OpenAiAdapter {
+    apiKey;
+    fetchImpl;
+    provider = 'openai';
+    constructor(apiKey, fetchImpl = fetch) {
+        this.apiKey = apiKey;
+        this.fetchImpl = fetchImpl;
+    }
+    async complete(req) {
+        const names = wireNameMap(req.tools);
+        const body = {
+            model: req.model,
+            max_completion_tokens: req.maxTokens,
+            messages: [
+                { role: 'system', content: req.system },
+                ...req.messages.map((m) => {
+                    if (m.role === 'user')
+                        return { role: 'user', content: m.text };
+                    if (m.role === 'assistant') {
+                        return {
+                            role: 'assistant',
+                            content: m.text,
+                            ...(m.toolCalls.length > 0
+                                ? {
+                                    tool_calls: m.toolCalls.map((c) => ({
+                                        id: c.id,
+                                        type: 'function',
+                                        function: {
+                                            name: toWireName(c.name),
+                                            arguments: JSON.stringify(c.arguments),
+                                        },
+                                    })),
+                                }
+                                : {}),
+                        };
+                    }
+                    return { role: 'tool', tool_call_id: m.toolCallId, content: m.resultJson };
+                }),
+            ],
+            tools: req.tools.map((t) => ({
+                type: 'function',
+                function: { name: toWireName(t.name), description: t.description, parameters: t.inputSchema },
+            })),
+        };
+        const json = await postJson(this.provider, this.fetchImpl, 'https://api.openai.com/v1/chat/completions', { authorization: `Bearer ${this.apiKey}` }, body);
+        const parsed = parseOrThrow(this.provider, ResponseSchema, json);
+        const choice = parsed.choices[0];
+        const toolCalls = (choice.message.tool_calls ?? []).map((c) => {
+            let args;
+            try {
+                args = JSON.parse(c.function.arguments);
+            }
+            catch {
+                throw new LlmProviderError(this.provider, 'malformed', `openai tool call "${c.function.name}" carried non-JSON arguments.`);
+            }
+            return { id: c.id, name: fromWireName(c.function.name, names), arguments: args };
+        });
+        return {
+            text: choice.message.content ?? null,
+            toolCalls,
+            stopReason: choice.finish_reason === 'tool_calls'
+                ? 'tool_use'
+                : choice.finish_reason === 'stop'
+                    ? 'end'
+                    : choice.finish_reason === 'length'
+                        ? 'max_tokens'
+                        : 'other',
+        };
+    }
+}
+//# sourceMappingURL=openai-adapter.js.map

package/dist/backend/services/llm/openai-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-adapter.js","sourceRoot":"","sources":["../../../../src/backend/services/llm/openai-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,WAAW,GAKZ,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AAEH,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC;SACP,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;YAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;YACzC,UAAU,EAAE,CAAC;iBACV,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;gBACP,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;gBACd,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;aAChE,CAAC,CACH;iBACA,QAAQ,EAAE;SACd,CAAC;QACF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;KAChD,CAAC,CACH;SACA,GAAG,CAAC,CAAC,CAAC;CACV,CAAC,CAAC;AAEH,MAAM,OAAO,aAAa;IAIL;IACA;IAJV,QAAQ,GAAG,QAAiB,CAAC;IAEtC,YACmB,MAAc,EACd,YAAuB,KAAK;QAD5B,WAAM,GAAN,MAAM,CAAQ;QACd,cAAS,GAAT,SAAS,CAAmB;IAC5C,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,GAAe;QAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,IAAI,GAAG;YACX,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,qBAAqB,EAAE,GAAG,CAAC,SAAS;YACpC,QAAQ,EAAE;gBACR,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE;gBACvC,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;oBACxB,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM;wBAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;oBAChE,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;wBAC3B,OAAO;4BACL,IAAI,EAAE,WAAW;4BACjB,OAAO,EAAE,CAAC,CAAC,IAAI;4BACf,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;gCACxB,CAAC,CAAC;oCACE,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;wCAClC,EAAE,EAAE,CAAC,CAAC,EAAE;wCACR,IAAI,EAAE,UAAU;wCAChB,QAAQ,EAAE;4CACR,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;4CACxB,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;yCACvC;qCACF,CAAC,CAAC;iCACJ;gCACH,CAAC,CAAC,EAAE,CAAC;yBACR,CAAC;oBACJ,CAAC;oBACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;gBAC7E,CAAC,CAAC;aACH;YACD,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC3B,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,WAAW,EAAE;aAC9F,CAAC,CAAC;SACJ,CAAC;QAEF,MAAM,IAAI,GAAG,MAAM,QAAQ,CACzB,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,SAAS,EACd,4CAA4C,EAC5C,EAAE,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE,EAAE,EAC1C,IAAI,CACL,CAAC;QACF,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC;QAElC,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC5D,IAAI,IAAa,CAAC;YAClB,IAAI,CAAC;gBACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,gBAAgB,CACxB,IAAI,CAAC,QAAQ,EACb,WAAW,EACX,qBAAqB,CAAC,CAAC,QAAQ,CAAC,IAAI,+BAA+B,CACpE,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACnF,CAAC,CAAC,CAAC;QAEH,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI;YACpC,SAAS;YACT,UAAU,EACR,MAAM,CAAC,aAAa,KAAK,YAAY;gBACnC,CAAC,CAAC,UAAU;gBACZ,CAAC,CAAC,MAAM,CAAC,aAAa,KAAK,MAAM;oBAC/B,CAAC,CAAC,KAAK;oBACP,CAAC,CAAC,MAAM,CAAC,aAAa,KAAK,QAAQ;wBACjC,CAAC,CAAC,YAAY;wBACd,CAAC,CAAC,OAAO;SAClB,CAAC;IACJ,CAAC;CACF"}

package/dist/backend/services/llm/provider-factory.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { type PromptActionsCapability, type PromptActionsProvider, type ResolveResult } from '@endora-commerce/contracts';
+import type { FetchLike, LlmProviderAdapter } from './provider.js';
+/**
+ * Settings-driven provider factory + capability derivation (feature 043,
+ * T023 / US4). Configuration is resolved per call through the Settings
+ * universal getter (Redis/LRU-cached), so provider, model and key changes
+ * take effect on the next prompt without a restart (US4/AC4). The API key
+ * never leaves this module: the capability DTO carries only the status.
+ *
+ * Feature 058 — the provider/model/key are sourced SOLELY from the
+ * `prompt_actions.llm_credentials` reference (a reusable `llm` credential
+ * configuration). When that reference is unset or unresolvable, the assistant
+ * reports `not_configured` and fails closed; there is no separate provider /
+ * model / api_key setting.
+ */
+/** Narrow port over SettingsService so the module depends on a shape, not the class. */
+export interface SettingsReadPort {
+    get<T>(code: string, salesChannelId: string, schema: z.ZodType<T>): Promise<T>;
+}
+/** Narrow port over CredentialsService.resolve (feature 058, Principle I). */
+export interface CredentialResolvePort {
+    resolve(configurationCode: string): Promise<ResolveResult>;
+}
+export declare class AssistantDisabled extends Error {
+    readonly name = "AssistantDisabled";
+    readonly code: "ASSISTANT_DISABLED";
+    constructor();
+}
+export declare class AssistantNotConfigured extends Error {
+    readonly name = "AssistantNotConfigured";
+    readonly code: "ASSISTANT_NOT_CONFIGURED";
+    constructor();
+}
+export interface LlmProviderFactoryDeps {
+    settings: SettingsReadPort;
+    /** Channel used to resolve the (global-scope) assistant settings. */
+    resolveChannelId: () => Promise<string>;
+    fetchImpl?: FetchLike;
+    /** Feature 058 — resolves the `prompt_actions.llm_credentials` reference. */
+    credentials?: CredentialResolvePort;
+}
+export interface ResolvedAssistant {
+    adapter: LlmProviderAdapter;
+    provider: PromptActionsProvider;
+    model: string;
+    bulkLimit: number;
+}
+export declare class LlmProviderFactory {
+    private readonly deps;
+    constructor(deps: LlmProviderFactoryDeps);
+    /** Status surface for the palette — never exposes the key (US4/AC2). */
+    capability(): Promise<PromptActionsCapability>;
+    /** Adapter for one interpretation run; throws typed errors for the routes. */
+    resolve(): Promise<ResolvedAssistant>;
+    bulkLimit(): Promise<number>;
+    private readConfig;
+    private resolveFromCredential;
+}
+//# sourceMappingURL=provider-factory.d.ts.map

package/dist/backend/services/llm/provider-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-factory.d.ts","sourceRoot":"","sources":["../../../../src/backend/services/llm/provider-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AAKpC,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnE;;;;;;;;;;;;GAYG;AAEH,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChF;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,iBAAiB,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5D;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,uBAAuB;IAC7C,QAAQ,CAAC,IAAI,EAAG,oBAAoB,CAAU;;CAI/C;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,SAAkB,IAAI,4BAA4B;IAClD,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;;CAIrD;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,QAAQ,EAAE,qBAAqB,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,sBAAsB;IAEzD,wEAAwE;IAClE,UAAU,IAAI,OAAO,CAAC,uBAAuB,CAAC;IASpD,8EAA8E;IACxE,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAcrC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;YAIpB,UAAU;YAqCV,qBAAqB;CAuBpC"}

package/dist/backend/services/llm/provider-factory.js

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+import { rethrowIfModuleDisabled } from '@endora-commerce/platform/kernel';
+import { PromptActionsProviderSchema, } from '@endora-commerce/contracts';
+import { PROMPT_ACTIONS_SETTING_CODES } from '../../../manifest.js';
+import { AnthropicAdapter } from './anthropic-adapter.js';
+import { GoogleAdapter } from './google-adapter.js';
+import { OpenAiAdapter } from './openai-adapter.js';
+export class AssistantDisabled extends Error {
+    name = 'AssistantDisabled';
+    code = 'ASSISTANT_DISABLED';
+    constructor() {
+        super('The prompt assistant is disabled on this platform.');
+    }
+}
+export class AssistantNotConfigured extends Error {
+    name = 'AssistantNotConfigured';
+    code = 'ASSISTANT_NOT_CONFIGURED';
+    constructor() {
+        super('The prompt assistant is enabled but its provider settings are incomplete.');
+    }
+}
+export class LlmProviderFactory {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Status surface for the palette — never exposes the key (US4/AC2). */
+    async capability() {
+        const cfg = await this.readConfig();
+        if (!cfg.enabled)
+            return { status: 'disabled', bulkLimit: cfg.bulkLimit };
+        if (!cfg.provider || !cfg.model || !cfg.apiKey) {
+            return { status: 'not_configured', bulkLimit: cfg.bulkLimit };
+        }
+        return { status: 'ready', bulkLimit: cfg.bulkLimit };
+    }
+    /** Adapter for one interpretation run; throws typed errors for the routes. */
+    async resolve() {
+        const cfg = await this.readConfig();
+        if (!cfg.enabled)
+            throw new AssistantDisabled();
+        if (!cfg.provider || !cfg.model || !cfg.apiKey)
+            throw new AssistantNotConfigured();
+        const fetchImpl = this.deps.fetchImpl ?? fetch;
+        const adapter = cfg.provider === 'anthropic'
+            ? new AnthropicAdapter(cfg.apiKey, fetchImpl)
+            : cfg.provider === 'google'
+                ? new GoogleAdapter(cfg.apiKey, fetchImpl)
+                : new OpenAiAdapter(cfg.apiKey, fetchImpl);
+        return { adapter, provider: cfg.provider, model: cfg.model, bulkLimit: cfg.bulkLimit };
+    }
+    async bulkLimit() {
+        return (await this.readConfig()).bulkLimit;
+    }
+    async readConfig() {
+        const channelId = await this.deps.resolveChannelId();
+        const read = async (code, schema, fallback) => {
+            try {
+                return await this.deps.settings.get(code, channelId, schema);
+            }
+            catch {
+                // Not seeded yet / out of scope — treat as unset rather than erroring
+                // the palette (mirrors the resolveModerationMode degrade pattern).
+                return fallback;
+            }
+        };
+        const [enabled, refCode, bulkLimit] = await Promise.all([
+            read(PROMPT_ACTIONS_SETTING_CODES.ENABLED, z.boolean(), false),
+            read(PROMPT_ACTIONS_SETTING_CODES.LLM_CREDENTIALS, z.string(), ''),
+            read(PROMPT_ACTIONS_SETTING_CODES.BULK_LIMIT, z.number().int().positive(), 500),
+        ]);
+        // Feature 058 — the `prompt_actions.llm_credentials` reference is the SINGLE
+        // source of provider/model/apiKey. When it is unset or unresolvable (or
+        // resolves to a provider prompt_actions has no adapter for), the assistant
+        // reports `not_configured` and fails closed — there is no legacy path.
+        const fromCredential = await this.resolveFromCredential(refCode.trim());
+        return {
+            enabled,
+            provider: fromCredential?.provider ?? null,
+            model: fromCredential?.model ?? '',
+            apiKey: fromCredential?.apiKey ?? '',
+            bulkLimit,
+        };
+    }
+    async resolveFromCredential(refCode) {
+        if (!this.deps.credentials || !refCode)
+            return null;
+        // Tolerated: an unresolvable reference means the assistant is not
+        // configured, and reporting that is the product's answer (feature 058).
+        // **A presence answer is a different sentence**: with `credentials` off
+        // there is nothing for the operator to configure, and `not_configured`
+        // would send them to fix a setting that is already right.
+        const resolved = await this.deps.credentials.resolve(refCode).catch((error) => {
+            rethrowIfModuleDisabled(error);
+            return null;
+        });
+        if (!resolved || resolved.status !== 'ok')
+            return null;
+        // Only providers prompt_actions has an adapter for (anthropic/google/openai)
+        // are usable; any other resolved provider (e.g. deepseek) is not_configured.
+        const provider = PromptActionsProviderSchema.safeParse(resolved.providerCode);
+        if (!provider.success)
+            return null;
+        const model = typeof resolved.values['model'] === 'string' ? resolved.values['model'].trim() : '';
+        const apiKey = typeof resolved.values['apiKey'] === 'string' ? resolved.values['apiKey'].trim() : '';
+        if (!model || !apiKey)
+            return null;
+        return { provider: provider.data, model, apiKey };
+    }
+}
+//# sourceMappingURL=provider-factory.js.map

package/dist/backend/services/llm/provider-factory.js.map

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

package/dist/backend/services/llm/provider.d.ts

@@ -0,0 +1,63 @@
+import type { z } from 'zod';
+import type { LlmToolDefinition, PromptActionsProvider } from '@endora-commerce/contracts';
+/**
+ * Provider-neutral LLM adapter contract (feature 043, research §R2).
+ *
+ * Three thin adapters (Anthropic / Google / OpenAI) speak the providers'
+ * native tool-calling REST APIs over injected `fetch` — no SDK dependency.
+ * Everything the interpreter consumes is normalized to this shape; provider
+ * responses are Zod-validated at the boundary (Principle V).
+ */
+export type { LlmToolDefinition };
+export type LlmMessage = {
+    role: 'user';
+    text: string;
+} | {
+    role: 'assistant';
+    text: string | null;
+    toolCalls: LlmToolCall[];
+} | {
+    role: 'tool_result';
+    toolCallId: string;
+    toolName: string;
+    resultJson: string;
+};
+export interface LlmToolCall {
+    id: string;
+    /** Dotted registry id, e.g. 'inventory.set_stock_level'. */
+    name: string;
+    arguments: unknown;
+}
+export interface LlmRequest {
+    model: string;
+    system: string;
+    messages: LlmMessage[];
+    tools: LlmToolDefinition[];
+    maxTokens: number;
+}
+export interface LlmCompletion {
+    text: string | null;
+    toolCalls: LlmToolCall[];
+    stopReason: 'tool_use' | 'end' | 'max_tokens' | 'other';
+}
+export interface LlmProviderAdapter {
+    readonly provider: PromptActionsProvider;
+    complete(req: LlmRequest): Promise<LlmCompletion>;
+}
+export declare class LlmProviderError extends Error {
+    readonly provider: PromptActionsProvider;
+    readonly kind: 'http' | 'network' | 'malformed';
+    readonly status?: number | undefined;
+    readonly name = "LlmProviderError";
+    constructor(provider: PromptActionsProvider, kind: 'http' | 'network' | 'malformed', message: string, status?: number | undefined);
+}
+export type FetchLike = typeof fetch;
+export declare function toWireName(id: string): string;
+export declare function wireNameMap(tools: LlmToolDefinition[]): Map<string, string>;
+export declare function fromWireName(wire: string, map: Map<string, string>): string;
+/** Shared POST + JSON helper with uniform error mapping. */
+export declare function postJson(provider: PromptActionsProvider, fetchImpl: FetchLike, url: string, headers: Record<string, string>, body: unknown): Promise<unknown>;
+export declare function malformed(provider: PromptActionsProvider, issues: unknown): LlmProviderError;
+/** Boundary guard reused by adapters. */
+export declare function parseOrThrow<T>(provider: PromptActionsProvider, schema: z.ZodType<T>, value: unknown): T;
+//# sourceMappingURL=provider.d.ts.map

package/dist/backend/services/llm/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../../src/backend/services/llm/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAE3F;;;;;;;GAOG;AAEH,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,WAAW,EAAE,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,UAAU,EAAE,UAAU,GAAG,KAAK,GAAG,YAAY,GAAG,OAAO,CAAC;CACzD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;IACzC,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnD;AAED,qBAAa,gBAAiB,SAAQ,KAAK;aAGvB,QAAQ,EAAE,qBAAqB;aAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW;aAEtC,MAAM,CAAC,EAAE,MAAM;IALjC,SAAkB,IAAI,sBAAsB;gBAE1B,QAAQ,EAAE,qBAAqB,EAC/B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,EACtD,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA;CAIlC;AAED,MAAM,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;AAUrC,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAE3E;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAE3E;AAED,4DAA4D;AAC5D,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,qBAAqB,EAC/B,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,OAAO,CAAC,CAiClB;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,qBAAqB,EAAE,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAM5F;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,OAAO,GACb,CAAC,CAIH"}

package/dist/backend/services/llm/provider.js

@@ -0,0 +1,67 @@
+export class LlmProviderError extends Error {
+    provider;
+    kind;
+    status;
+    name = 'LlmProviderError';
+    constructor(provider, kind, message, status) {
+        super(message);
+        this.provider = provider;
+        this.kind = kind;
+        this.status = status;
+    }
+}
+// ---------------------------------------------------------------------------
+// Wire-name sanitization
+// ---------------------------------------------------------------------------
+// Registry ids are dotted ('catalog.search_products') but Anthropic and
+// OpenAI tool names must match ^[a-zA-Z0-9_-]{1,64}$. All adapters therefore
+// send '__'-joined names and translate responses back through a per-request
+// reverse map (never string surgery — ids may legitimately contain '_').
+export function toWireName(id) {
+    return id.replace(/\./g, '__');
+}
+export function wireNameMap(tools) {
+    return new Map(tools.map((t) => [toWireName(t.name), t.name]));
+}
+export function fromWireName(wire, map) {
+    return map.get(wire) ?? wire;
+}
+/** Shared POST + JSON helper with uniform error mapping. */
+export async function postJson(provider, fetchImpl, url, headers, body) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...headers },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        throw new LlmProviderError(provider, 'network', `Could not reach the ${provider} API: ${err.message}`);
+    }
+    let json = null;
+    try {
+        json = await response.json();
+    }
+    catch {
+        // fall through — handled below
+    }
+    if (!response.ok) {
+        throw new LlmProviderError(provider, 'http', `${provider} API responded with HTTP ${response.status}.`, response.status);
+    }
+    if (json === null) {
+        throw new LlmProviderError(provider, 'malformed', `${provider} API returned a non-JSON body.`);
+    }
+    return json;
+}
+export function malformed(provider, issues) {
+    return new LlmProviderError(provider, 'malformed', `${provider} API response did not match the expected shape: ${JSON.stringify(issues).slice(0, 500)}`);
+}
+/** Boundary guard reused by adapters. */
+export function parseOrThrow(provider, schema, value) {
+    const r = schema.safeParse(value);
+    if (!r.success)
+        throw malformed(provider, r.error.issues);
+    return r.data;
+}
+//# sourceMappingURL=provider.js.map

package/dist/backend/services/llm/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../../src/backend/services/llm/provider.ts"],"names":[],"mappings":"AA6CA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAGvB;IACA;IAEA;IALA,IAAI,GAAG,kBAAkB,CAAC;IAC5C,YACkB,QAA+B,EAC/B,IAAsC,EACtD,OAAe,EACC,MAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,aAAQ,GAAR,QAAQ,CAAuB;QAC/B,SAAI,GAAJ,IAAI,CAAkC;QAEtC,WAAM,GAAN,MAAM,CAAS;IAGjC,CAAC;CACF;AAID,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAC9E,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,yEAAyE;AAEzE,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAA0B;IACpD,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,GAAwB;IACjE,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAC/B,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAA+B,EAC/B,SAAoB,EACpB,GAAW,EACX,OAA+B,EAC/B,IAAa;IAEb,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;YAC9B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE;YAC3D,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,gBAAgB,CACxB,QAAQ,EACR,SAAS,EACT,uBAAuB,QAAQ,SAAU,GAAa,CAAC,OAAO,EAAE,CACjE,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,GAAY,IAAI,CAAC;IACzB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,gBAAgB,CACxB,QAAQ,EACR,MAAM,EACN,GAAG,QAAQ,4BAA4B,QAAQ,CAAC,MAAM,GAAG,EACzD,QAAQ,CAAC,MAAM,CAChB,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,gBAAgB,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,QAAQ,gCAAgC,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAA+B,EAAE,MAAe;IACxE,OAAO,IAAI,gBAAgB,CACzB,QAAQ,EACR,WAAW,EACX,GAAG,QAAQ,mDAAmD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACrG,CAAC;AACJ,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,YAAY,CAC1B,QAA+B,EAC/B,MAAoB,EACpB,KAAc;IAEd,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,CAAC,OAAO;QAAE,MAAM,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1D,OAAO,CAAC,CAAC,IAAI,CAAC;AAChB,CAAC"}

package/dist/backend/services/plan-executor.service.d.ts

@@ -0,0 +1,49 @@
+import type { PromptActionPlan, PromptActionResult, ToolContext } from '@endora-commerce/contracts';
+import type { PromptActionToolRegistry } from './tool-registry.js';
+/**
+ * PlanExecutorService — feature 043 US1/US2 (research §R6).
+ *
+ * Walks a confirmed plan with defense-in-depth re-validation: catalogue
+ * membership, Zod params, and the operator's LIVE permission are all checked
+ * again at execution time (a plan may be minutes old — FR-007). Execution
+ * delegates to the owning module's service through the tool handler; this
+ * module owns zero domain logic.
+ *
+ * Partial-failure semantics (FR-011): independent operations keep their
+ * outcome; one failure never rolls back a previously succeeded operation.
+ */
+export declare class PermissionRevoked extends Error {
+    readonly toolId: string;
+    readonly permission: string;
+    readonly name = "PermissionRevoked";
+    readonly code: "PROMPT_PERMISSION_REVOKED";
+    constructor(toolId: string, permission: string);
+}
+export interface ExecutorVisibility {
+    hasPermission(permission: string): Promise<boolean>;
+    isModuleInstalled(moduleId: string): Promise<boolean>;
+}
+/** Marker returned by tool handlers that delegate to the catalog bulk queue (US2). */
+export interface DelegatedExecution {
+    delegated: true;
+    bulkOperationId: string;
+}
+export declare function isDelegatedExecution(value: unknown): value is DelegatedExecution;
+export interface ExecutePlanResult {
+    result: PromptActionResult;
+    /** Set when at least one operation was delegated to the bulk machinery. */
+    bulkOperationId: string | null;
+}
+export declare class PlanExecutorService {
+    private readonly registry;
+    constructor(registry: PromptActionToolRegistry);
+    /**
+     * Executes every operation in the plan. Throws {@link PermissionRevoked}
+     * (the whole request becomes `refused`) when a live permission check
+     * fails BEFORE any operation has run; revocation discovered mid-plan is
+     * reported as a per-operation failure instead (already-applied work must
+     * stay applied — FR-011).
+     */
+    execute(plan: PromptActionPlan, toolCtx: ToolContext, visibility: ExecutorVisibility): Promise<ExecutePlanResult>;
+}
+//# sourceMappingURL=plan-executor.service.d.ts.map

package/dist/backend/services/plan-executor.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-executor.service.d.ts","sourceRoot":"","sources":["../../../src/backend/services/plan-executor.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,kBAAkB,EAElB,WAAW,EACZ,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;;;;;;;;GAWG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;aAGd,MAAM,EAAE,MAAM;aAAkB,UAAU,EAAE,MAAM;IAF9E,SAAkB,IAAI,uBAAuB;IAC7C,QAAQ,CAAC,IAAI,EAAG,2BAA2B,CAAU;gBACzB,MAAM,EAAE,MAAM,EAAkB,UAAU,EAAE,MAAM;CAG/E;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,IAAI,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAOhF;AAiBD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2EAA2E;IAC3E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,wBAAwB;IAE/D;;;;;;OAMG;IACG,OAAO,CACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,kBAAkB,GAC7B,OAAO,CAAC,iBAAiB,CAAC;CA+E9B"}