@oxy.so/contracts 4.6.0 → 4.7.0

package/dist/cjs/agency.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizedAppEventSchema = exports.catalogRegistrationSchema = exports.appCapabilityCatalogSchema = exports.catalogEventSchema = exports.catalogToolSchema = exports.auditEventSchema = exports.auditResultSchema = exports.policyDecisionSchema = exports.capabilityTicketClaimsSchema = exports.automationDefinitionSchema = exports.automationDataFlowSchema = exports.automationActorSelectionSchema = exports.automationTriggerSchema = exports.delegationGrantSchema = exports.capabilityCoordinatorSchema = exports.executionAuthorizationRefSchema = exports.capabilityCatalogBindingSchema = exports.grantLimitSchema = exports.toolGrantOverrideSchema = exports.resourceRefSchema = exports.actorRefSchema = exports.capabilityPackageSchema = exports.CAPABILITY_PACKAGES = exports.autonomyLevelSchema = exports.AUTONOMY_LEVELS = void 0;
 const zod_1 = require("zod");
+const capabilityInvocation_1 = require("./capabilityInvocation");
 const nonEmptyStringSchema = zod_1.z.string().trim().min(1);
 const identifierSchema = zod_1.z.string().trim().min(1).max(255);
 const limitKeySchema = zod_1.z.string().regex(/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$/, 'limit keys must be dot-separated input property names').max(255);
@@ -349,6 +350,42 @@ exports.catalogToolSchema = zod_1.z.object({
             path: ['invocation', 'method'],
         });
     }
+    // The invocation template is how a coordinator turns arguments into a
+    // request (`resolveCatalogInvocation`). A `{param}` the input schema does
+    // not declare as a REQUIRED property can never be filled, and a GET input
+    // that is not a scalar has no query-string form — both are refused here so
+    // the builder never has to guess.
+    const declared = typeof tool.inputSchema.properties === 'object'
+        && tool.inputSchema.properties !== null
+        && !Array.isArray(tool.inputSchema.properties)
+        ? tool.inputSchema.properties
+        : {};
+    const required = Array.isArray(tool.inputSchema.required) ? tool.inputSchema.required : [];
+    const parameters = (0, capabilityInvocation_1.catalogInvocationPathParameters)(tool.invocation.path);
+    requireUnique(parameters, 'invocation.path parameters');
+    for (const parameter of parameters) {
+        if (!Object.prototype.hasOwnProperty.call(declared, parameter) || !required.includes(parameter)) {
+            context.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: `Path parameter {${parameter}} must be a required input property`,
+                path: ['invocation', 'path'],
+            });
+        }
+    }
+    if (tool.invocation.method === 'GET') {
+        for (const [key, property] of Object.entries(declared)) {
+            const type = typeof property === 'object' && property !== null
+                ? property.type
+                : undefined;
+            if (type !== 'string' && type !== 'number' && type !== 'integer' && type !== 'boolean') {
+                context.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    message: `GET input ${key} must be a string, number, integer or boolean`,
+                    path: ['inputSchema', 'properties', key],
+                });
+            }
+        }
+    }
 });
 exports.catalogEventSchema = zod_1.z.object({
     type: identifierSchema,
@@ -416,6 +453,18 @@ exports.appCapabilityCatalogSchema = zod_1.z.object({
         }
         names.add(tool.name);
     }
+    // Matching an incoming request back to its tool must have ONE answer that
+    // does not depend on the order tools are listed in — see
+    // `matchCatalogInvocation`. Two templates that one request could satisfy
+    // (`/messages/{id}` beside `/messages/unread`) make that impossible.
+    for (const [left, right] of (0, capabilityInvocation_1.findOverlappingCatalogInvocations)(catalog.tools)) {
+        context.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            message: `Tools ${left.name} and ${right.name} have overlapping invocations `
+                + `(${left.invocation.method} ${left.invocation.path} / ${right.invocation.method} ${right.invocation.path})`,
+            path: ['tools'],
+        });
+    }
     const eventTypes = new Set();
     for (const [index, event] of catalog.events.entries()) {
         if (eventTypes.has(event.type)) {

package/dist/cjs/capabilityInvocation.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * How a catalog tool call travels over HTTP, in both directions.
+ *
+ * A capability catalog names each tool's `invocation` as a method plus a path
+ * template (`/email/messages/{emailId}`). Two parties have to agree on what
+ * that means: the coordinator that BUILDS the request from the model's
+ * arguments (Alia), and the app that MATCHES an incoming request back to the
+ * one tool its ticket was signed for (the Inbox capability middleware). Each
+ * used to carry its own copy of the rules, and the matcher walked the tool list
+ * in array order, so a literal segment (`/messages/unread`) and a parameter
+ * (`/messages/{id}`) in the same position resolved to whichever tool happened to
+ * be declared first. Both halves live here now, next to the catalog schema that
+ * refuses a catalog whose templates could ever match the same request — so a
+ * match is unique by construction, not by ordering.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catalogInvocationPathParameters = catalogInvocationPathParameters;
+exports.catalogInvocationsOverlap = catalogInvocationsOverlap;
+exports.catalogInvocationTemplatesEquivalent = catalogInvocationTemplatesEquivalent;
+exports.findOverlappingCatalogInvocations = findOverlappingCatalogInvocations;
+exports.matchCatalogInvocation = matchCatalogInvocation;
+exports.resolveCatalogInvocation = resolveCatalogInvocation;
+const PARAMETER_SEGMENT = /^\{([A-Za-z][A-Za-z0-9_]*)\}$/;
+function pathSegments(path) {
+    return path.split('/').filter(Boolean);
+}
+/** The `{name}` placeholders of a path template, in order. */
+function catalogInvocationPathParameters(path) {
+    return pathSegments(path).flatMap((segment) => {
+        const parameter = PARAMETER_SEGMENT.exec(segment)?.[1];
+        return parameter ? [parameter] : [];
+    });
+}
+/**
+ * Whether one concrete request could match BOTH templates.
+ *
+ * Same method, same number of segments, and at every position either the same
+ * literal or a parameter on at least one side. `/messages/{id}` and
+ * `/messages/unread` overlap (the request `/messages/unread` fits both);
+ * `/messages/{id}` and `/messages/{id}/thread` do not.
+ */
+function catalogInvocationsOverlap(left, right) {
+    if (left.method.toUpperCase() !== right.method.toUpperCase())
+        return false;
+    const leftSegments = pathSegments(left.path);
+    const rightSegments = pathSegments(right.path);
+    if (leftSegments.length !== rightSegments.length)
+        return false;
+    return leftSegments.every((segment, index) => {
+        const other = rightSegments[index] ?? '';
+        return segment === other || PARAMETER_SEGMENT.test(segment) || PARAMETER_SEGMENT.test(other);
+    });
+}
+/**
+ * Whether two templates name the same ADDRESS: same method, and at every
+ * position the same literal or a parameter on both sides — parameter names do
+ * not matter (`/messages/{id}` and `/messages/{emailId}` are one address;
+ * `/messages/{id}` and `/messages/bundled` are not, though they overlap).
+ * Used to say which documented REST operation shares its address with a tool.
+ */
+function catalogInvocationTemplatesEquivalent(left, right) {
+    if (left.method.toUpperCase() !== right.method.toUpperCase())
+        return false;
+    const leftSegments = pathSegments(left.path);
+    const rightSegments = pathSegments(right.path);
+    if (leftSegments.length !== rightSegments.length)
+        return false;
+    return leftSegments.every((segment, index) => {
+        const other = rightSegments[index] ?? '';
+        const leftIsParameter = PARAMETER_SEGMENT.test(segment);
+        return leftIsParameter ? PARAMETER_SEGMENT.test(other) : segment === other;
+    });
+}
+/** Every pair of tools whose invocations overlap — empty for a valid catalog. */
+function findOverlappingCatalogInvocations(tools) {
+    const overlaps = [];
+    for (let left = 0; left < tools.length; left += 1) {
+        for (let right = left + 1; right < tools.length; right += 1) {
+            const a = tools[left];
+            const b = tools[right];
+            if (a && b && catalogInvocationsOverlap(a.invocation, b.invocation))
+                overlaps.push([a, b]);
+        }
+    }
+    return overlaps;
+}
+function matchTemplate(template, method, requestSegments) {
+    if (template.method.toUpperCase() !== method.toUpperCase())
+        return null;
+    const templateSegments = pathSegments(template.path);
+    if (templateSegments.length !== requestSegments.length)
+        return null;
+    const params = {};
+    for (const [index, templateSegment] of templateSegments.entries()) {
+        const requestSegment = requestSegments[index];
+        if (!requestSegment)
+            return null;
+        const parameter = PARAMETER_SEGMENT.exec(templateSegment)?.[1];
+        if (!parameter) {
+            if (templateSegment !== requestSegment)
+                return null;
+            continue;
+        }
+        try {
+            params[parameter] = decodeURIComponent(requestSegment);
+        }
+        catch {
+            return null;
+        }
+    }
+    return params;
+}
+/**
+ * The ONE tool whose invocation matches `method` + `path` (the full app-local
+ * path, e.g. `/email/messages/abc`), or null.
+ *
+ * Every tool is tried, not the first hit, so the answer cannot depend on the
+ * order the catalog lists its tools in. A second hit means the catalog should
+ * never have validated — `appCapabilityCatalogSchema` refuses overlapping
+ * templates — so it throws rather than guessing which tool the ticket meant.
+ */
+function matchCatalogInvocation(tools, method, path) {
+    const requestSegments = pathSegments(path);
+    const matches = [];
+    for (const tool of tools) {
+        const params = matchTemplate(tool.invocation, method, requestSegments);
+        if (params)
+            matches.push({ tool, params });
+    }
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous catalog invocation ${method} ${path}: ${matches.map(({ tool }) => tool.name).join(', ')}`);
+    }
+    return matches[0] ?? null;
+}
+/**
+ * Build the HTTP request for a tool call from the model's arguments.
+ *
+ * Path parameters are substituted (and removed from the remaining arguments);
+ * GET sends the rest as query parameters, everything else as a JSON body. A GET
+ * argument that is not a scalar is refused instead of being stringified into
+ * `[object Object]` — the catalog schema only lets GET tools declare scalar
+ * inputs, so reaching that branch means the arguments did not come from the
+ * tool's own schema. The resolved URL must stay on `internalBaseUrl`'s origin.
+ */
+function resolveCatalogInvocation(catalog, tool, args) {
+    const remaining = { ...args };
+    const path = tool.invocation.path.replace(/\{(\w+)\}/g, (_match, parameter) => {
+        const value = Object.prototype.hasOwnProperty.call(remaining, parameter) ? remaining[parameter] : undefined;
+        delete remaining[parameter];
+        if (value === undefined || value === null || value === '') {
+            throw new Error(`Missing required path parameter: ${parameter}`);
+        }
+        return encodeURIComponent(String(value));
+    });
+    const baseUrl = new URL(catalog.internalBaseUrl);
+    const url = new URL(path, `${baseUrl.origin}/`);
+    if (url.origin !== baseUrl.origin) {
+        throw new Error(`Catalog invocation for ${tool.name} escapes its registered app origin`);
+    }
+    const method = tool.invocation.method.toUpperCase();
+    if (method !== 'GET')
+        return { method, url, body: remaining };
+    for (const [key, value] of Object.entries(remaining)) {
+        if (value === undefined || value === null)
+            continue;
+        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+            throw new Error(`GET argument ${key} of ${tool.name} must be a string, number or boolean`);
+        }
+        url.searchParams.set(key, String(value));
+    }
+    return { method, url };
+}

package/dist/cjs/index.js

@@ -37,7 +37,7 @@ exports.MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH = exports.inferenceStreamEventSch
 exports.realtimeTextDeltaEventSchema = exports.realtimeTranscriptDoneEventSchema = exports.realtimeTranscriptDeltaEventSchema = exports.realtimeTranscriptSourceSchema = exports.realtimeOutputAudioDoneEventSchema = exports.realtimeOutputAudioDeltaEventSchema = exports.realtimeResponseCreatedEventSchema = exports.realtimeInputAudioClearedEventSchema = exports.realtimeInputAudioCommittedEventSchema = exports.realtimeSpeechStoppedEventSchema = exports.realtimeSpeechStartedEventSchema = exports.realtimeItemTruncatedEventSchema = exports.realtimeItemDeletedEventSchema = exports.realtimeItemDoneEventSchema = exports.realtimeItemAddedEventSchema = exports.realtimeCommandAcceptedEventSchema = exports.realtimeSessionResumedEventSchema = exports.realtimeSessionUpdatedEventSchema = exports.realtimeSessionCreatedEventSchema = exports.realtimeClientCommandSchema = exports.realtimeSessionCloseCommandSchema = exports.realtimeSessionResumeCommandSchema = exports.realtimeResponseCancelCommandSchema = exports.realtimeResponseCreateCommandSchema = exports.realtimeInputAudioClearCommandSchema = exports.realtimeInputAudioCommitCommandSchema = exports.realtimeInputAudioAppendCommandSchema = exports.realtimeItemTruncateCommandSchema = exports.realtimeItemDeleteCommandSchema = exports.realtimeItemCreateCommandSchema = exports.realtimeSessionUpdateCommandSchema = exports.realtimeResponseParametersSchema = exports.realtimeConversationItemSchema = exports.realtimeContentPartSchema = exports.realtimeSessionRequestSchema = exports.realtimeClientMetadataSchema = exports.realtimeSessionLimitsSchema = exports.realtimeSessionConfigUpdateSchema = exports.realtimeSessionConfigSchema = exports.realtimeTranslationSchema = exports.realtimeInputTranscriptionSchema = exports.realtimeTurnDetectionSchema = exports.realtimeOutputModalitySchema = exports.realtimeAudioFormatSchema = exports.realtimeResponseIdSchema = exports.realtimeItemIdSchema = exports.realtimeCommandIdSchema = exports.MAX_REALTIME_RESUME_WINDOW_MS = exports.MAX_REALTIME_SESSION_AUDIO_BYTES = exports.MAX_REALTIME_SESSION_DURATION_MS = void 0;
 exports.BILLING_INVOICE_STATUSES = exports.accountBillingStateSchema = exports.billingProfileSchema = exports.autoRechargeSchema = exports.billingProfileStatusSchema = exports.BILLING_PROFILE_STATUSES = exports.billingModeSchema = exports.BILLING_MODES = exports.providerConnectionSchema = exports.providerConnectionStatusSchema = exports.providerConnectionValidationSchema = exports.providerCredentialCustodyStateSchema = exports.providerCredentialValidationDeploymentSchema = exports.providerCredentialValidationOperationSchema = exports.kaanaCredentialValidationOutcomeSchema = exports.kaanaCredentialValidationFailureCodeSchema = exports.kaanaCredentialValidationOutcomeStateSchema = exports.kaanaCredentialValidationTaskSchema = exports.kaanaCredentialOutcomeSchema = exports.kaanaCredentialConflictOutcomeSchema = exports.kaanaCredentialAppliedOutcomeSchema = exports.kaanaCredentialOutcomeRequestSchema = exports.kaanaCredentialRevokeOutcomeRequestSchema = exports.kaanaCredentialRotateOutcomeRequestSchema = exports.kaanaCredentialCreateOutcomeRequestSchema = exports.kaanaCredentialMutationSchema = exports.kaanaCredentialRevokeMutationSchema = exports.kaanaCredentialRotateMutationSchema = exports.kaanaCredentialCreateMutationSchema = exports.kaanaCredentialIdentitySchema = exports.kaanaCredentialOperationActionSchema = exports.kaanaCredentialOperationIdSchema = exports.kaanaCredentialHandleSchema = exports.providerConnectionScopeSchema = exports.usageRefundSchema = exports.usageRefundReasonSchema = exports.usageRefundSubjectSchema = exports.usageReceiptSchema = exports.normalizedUsageReportSchema = exports.inferenceRequestOutcomeSchema = exports.usageReservationSchema = exports.usageReservationStatusSchema = exports.usageReservationRequestSchema = exports.realtimeServerEventSchema = exports.realtimeSessionClosedEventSchema = exports.realtimeSessionCloseReasonSchema = exports.realtimeErrorEventSchema = exports.realtimeResponseDoneEventSchema = exports.realtimeResponseStatusSchema = exports.realtimeToolCallEventSchema = void 0;
 exports.catalogEventSchema = exports.catalogToolSchema = exports.auditEventSchema = exports.auditResultSchema = exports.policyDecisionSchema = exports.capabilityTicketClaimsSchema = exports.automationDefinitionSchema = exports.automationDataFlowSchema = exports.automationActorSelectionSchema = exports.automationTriggerSchema = exports.delegationGrantSchema = exports.capabilityCoordinatorSchema = exports.executionAuthorizationRefSchema = exports.capabilityCatalogBindingSchema = exports.grantLimitSchema = exports.toolGrantOverrideSchema = exports.resourceRefSchema = exports.actorRefSchema = exports.capabilityPackageSchema = exports.autonomyLevelSchema = exports.CAPABILITY_PACKAGES = exports.AUTONOMY_LEVELS = exports.productEntitlementSchema = exports.costCenterSpendSchema = exports.costCenterSchema = exports.costCenterStatusSchema = exports.COST_CENTER_STATUSES = exports.payAsYouGoEntitlementSchema = exports.productPlanSchema = exports.planAllowanceSchema = exports.LIVE_PRODUCT_PLAN_STATUSES = exports.productPlanStatusSchema = exports.PRODUCT_PLAN_STATUSES = exports.reconciliationReportSchema = exports.reconciliationRunSchema = exports.reconciliationDiscrepancySchema = exports.reconciliationRunStatusSchema = exports.RECONCILIATION_RUN_STATUSES = exports.reconciliationDiscrepancyKindSchema = exports.RECONCILIATION_DISCREPANCY_KINDS = exports.autoRechargeAttemptSchema = exports.autoRechargeStatusSchema = exports.AUTO_RECHARGE_STATUSES = exports.externalPaymentSchema = exports.externalPaymentKindSchema = exports.EXTERNAL_PAYMENT_KINDS = exports.externalPaymentProviderSchema = exports.EXTERNAL_PAYMENT_PROVIDERS = exports.billingInvoiceSchema = exports.billingInvoiceStatusSchema = void 0;
-exports.inboxInferenceStreamEventSchema = exports.inboxThreadSummaryResponseSchema = exports.inboxSmartRepliesResponseSchema = exports.inboxNaturalSearchResponseSchema = exports.inboxInferenceTextResponseSchema = exports.inboxMessageInferenceParamsSchema = exports.inboxNaturalSearchRequestSchema = exports.inboxDailyBriefRequestSchema = exports.inboxComposeRequestSchema = exports.emailAgentContextSchema = exports.emailContextMessageSchema = exports.emailContextMailboxSchema = exports.emailContextAddressSchema = exports.normalizedAppEventSchema = exports.catalogRegistrationSchema = exports.appCapabilityCatalogSchema = void 0;
+exports.decisionAnswersMatch = exports.decisionFitsGateway = exports.decisionInputBudget = exports.decisionFailureSchema = exports.decisionSuccessSchema = exports.decisionResultSchema = exports.decisionAnswerSchema = exports.decisionRequestSchema = exports.decisionInputSchema = exports.decisionQuestionSchema = exports.decisionEffortSchema = exports.inboxInferenceStreamEventSchema = exports.inboxThreadSummaryResponseSchema = exports.inboxSmartRepliesResponseSchema = exports.inboxNaturalSearchResponseSchema = exports.inboxInferenceTextResponseSchema = exports.inboxMessageInferenceParamsSchema = exports.inboxNaturalSearchRequestSchema = exports.inboxDailyBriefRequestSchema = exports.inboxComposeRequestSchema = exports.emailAgentContextSchema = exports.emailContextMessageSchema = exports.emailContextMailboxSchema = exports.emailContextAddressSchema = exports.resolveCatalogInvocation = exports.matchCatalogInvocation = exports.findOverlappingCatalogInvocations = exports.catalogInvocationTemplatesEquivalent = exports.catalogInvocationsOverlap = exports.catalogInvocationPathParameters = exports.normalizedAppEventSchema = exports.catalogRegistrationSchema = exports.appCapabilityCatalogSchema = void 0;
 var accountGraph_1 = require("./accountGraph");
 Object.defineProperty(exports, "ACCOUNT_KINDS", { enumerable: true, get: function () { return accountGraph_1.ACCOUNT_KINDS; } });
 Object.defineProperty(exports, "accountKindSchema", { enumerable: true, get: function () { return accountGraph_1.accountKindSchema; } });
@@ -753,6 +753,13 @@ Object.defineProperty(exports, "catalogEventSchema", { enumerable: true, get: fu
 Object.defineProperty(exports, "appCapabilityCatalogSchema", { enumerable: true, get: function () { return agency_1.appCapabilityCatalogSchema; } });
 Object.defineProperty(exports, "catalogRegistrationSchema", { enumerable: true, get: function () { return agency_1.catalogRegistrationSchema; } });
 Object.defineProperty(exports, "normalizedAppEventSchema", { enumerable: true, get: function () { return agency_1.normalizedAppEventSchema; } });
+var capabilityInvocation_1 = require("./capabilityInvocation");
+Object.defineProperty(exports, "catalogInvocationPathParameters", { enumerable: true, get: function () { return capabilityInvocation_1.catalogInvocationPathParameters; } });
+Object.defineProperty(exports, "catalogInvocationsOverlap", { enumerable: true, get: function () { return capabilityInvocation_1.catalogInvocationsOverlap; } });
+Object.defineProperty(exports, "catalogInvocationTemplatesEquivalent", { enumerable: true, get: function () { return capabilityInvocation_1.catalogInvocationTemplatesEquivalent; } });
+Object.defineProperty(exports, "findOverlappingCatalogInvocations", { enumerable: true, get: function () { return capabilityInvocation_1.findOverlappingCatalogInvocations; } });
+Object.defineProperty(exports, "matchCatalogInvocation", { enumerable: true, get: function () { return capabilityInvocation_1.matchCatalogInvocation; } });
+Object.defineProperty(exports, "resolveCatalogInvocation", { enumerable: true, get: function () { return capabilityInvocation_1.resolveCatalogInvocation; } });
 var emailAgentContext_1 = require("./emailAgentContext");
 Object.defineProperty(exports, "emailContextAddressSchema", { enumerable: true, get: function () { return emailAgentContext_1.emailContextAddressSchema; } });
 Object.defineProperty(exports, "emailContextMailboxSchema", { enumerable: true, get: function () { return emailAgentContext_1.emailContextMailboxSchema; } });
@@ -774,3 +781,15 @@ __exportStar(require("./federationInstanceFetch"), exports);
 __exportStar(require("./notifications"), exports);
 __exportStar(require("./email/messages"), exports);
 __exportStar(require("./stickers"), exports);
+var decisions_1 = require("./inference/decisions");
+Object.defineProperty(exports, "decisionEffortSchema", { enumerable: true, get: function () { return decisions_1.decisionEffortSchema; } });
+Object.defineProperty(exports, "decisionQuestionSchema", { enumerable: true, get: function () { return decisions_1.decisionQuestionSchema; } });
+Object.defineProperty(exports, "decisionInputSchema", { enumerable: true, get: function () { return decisions_1.decisionInputSchema; } });
+Object.defineProperty(exports, "decisionRequestSchema", { enumerable: true, get: function () { return decisions_1.decisionRequestSchema; } });
+Object.defineProperty(exports, "decisionAnswerSchema", { enumerable: true, get: function () { return decisions_1.decisionAnswerSchema; } });
+Object.defineProperty(exports, "decisionResultSchema", { enumerable: true, get: function () { return decisions_1.decisionResultSchema; } });
+Object.defineProperty(exports, "decisionSuccessSchema", { enumerable: true, get: function () { return decisions_1.decisionSuccessSchema; } });
+Object.defineProperty(exports, "decisionFailureSchema", { enumerable: true, get: function () { return decisions_1.decisionFailureSchema; } });
+Object.defineProperty(exports, "decisionInputBudget", { enumerable: true, get: function () { return decisions_1.decisionInputBudget; } });
+Object.defineProperty(exports, "decisionFitsGateway", { enumerable: true, get: function () { return decisions_1.decisionFitsGateway; } });
+Object.defineProperty(exports, "decisionAnswersMatch", { enumerable: true, get: function () { return decisions_1.decisionAnswersMatch; } });

package/dist/cjs/inference/catalogue.js

@@ -58,7 +58,8 @@ exports.reasoningEffortSchema = zod_1.z.enum(['low', 'medium', 'high']);
  * 3.4.0). Ordered cheapest first; `auto` asks Oxy to pick the cheapest level
  * that suffices for the request.
  *
- * - `instant` — very cheap, fast small models; no reasoning effort requested
+ * - `instant` — very cheap, fast small models; the least reasoning each model
+ *   accepts (`low` on a reasoning model, nothing on one without effort control)
  * - `medium` — mid-size models, low reasoning effort
  * - `high` — strong models, medium reasoning effort
  * - `xhigh` — strong models, high reasoning effort
@@ -96,6 +97,7 @@ exports.inferenceApiFormatSchema = zod_1.z.enum([
     'responses',
     'chat_completions',
     'embeddings',
+    'decisions',
     'images_generations',
     'audio_transcriptions',
     'audio_speech',
@@ -583,7 +585,9 @@ exports.routingProfileSchema = zod_1.z.object({
     powerLevel: exports.powerLevelSchema.optional(),
     /**
      * The reasoning effort a power level asks for when the request names none,
-     * applied only on a model that advertises it. Absent: none is requested.
+     * clamped to the nearest effort the chosen model accepts (the lowest at or
+     * above it, else the highest). Absent: the level asks for no reasoning, sent
+     * as the least effort a reasoning model accepts.
      */
     reasoningEffort: exports.reasoningEffortSchema.optional(),
 });

package/dist/cjs/inference/decisions.js

@@ -0,0 +1,245 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionSuccessSchema = exports.decisionFailureSchema = exports.decisionResultSchema = exports.decisionAnswerSchema = exports.decisionRequestSchema = exports.decisionInputSchema = exports.decisionQuestionSchema = exports.decisionEffortSchema = void 0;
+exports.decisionInputBudget = decisionInputBudget;
+exports.decisionFitsGateway = decisionFitsGateway;
+exports.decisionAnswersMatch = decisionAnswersMatch;
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+const identifiers_1 = require("./identifiers");
+const money_1 = require("./money");
+const routingPolicy_1 = require("./routingPolicy");
+const usage_1 = require("./usage");
+const probability = zod_1.z.number().finite().min(0).max(1);
+const text = zod_1.z.string().min(1).max(65536);
+const id = zod_1.z.string().min(1).max(128);
+const tolerance = 1e-6;
+exports.decisionEffortSchema = zod_1.z.enum([
+    "instant",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+]);
+const common = { id, question: text, criteria: text.optional() };
+exports.decisionQuestionSchema = zod_1.z.discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        ...common,
+        kind: zod_1.z.literal("choice"),
+        options: zod_1.z.array(text).min(2).max(255),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        ...common,
+        kind: zod_1.z.literal("score"),
+        levels: zod_1.z.array(text).min(2).max(10),
+    })
+        .strict(),
+    zod_1.z.object({ ...common, kind: zod_1.z.literal("noul") }).strict(),
+]);
+const payloadFields = {
+    state: zod_1.z.string().max(65536),
+    instructions: text.optional(),
+    questions: zod_1.z.array(exports.decisionQuestionSchema).min(1).max(255),
+    effort: exports.decisionEffortSchema.optional(),
+};
+/**
+ * Conservative serialized input accounting, including escaping and structure.
+ * Measures both the normalized payload and the provider's structured-question
+ * representation. Common instructions repeat per question there. A 255-byte
+ * model identity and 4096-byte gateway-policy allowance bound adapter metadata.
+ * Kaana must also check its final serialized body before sending it.
+ */
+function decisionInputBudget(payload) {
+    const bytes = (value) => new TextEncoder().encode(JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`)).length;
+    const model = "x".repeat(255);
+    const measure = (questions) => {
+        const wireQuestions = Object.fromEntries(questions.map((q) => [q.id, {
+                type: q.kind,
+                instructions: {
+                    question: q.question,
+                    ...(payload.instructions === undefined ? {} : { instructions: payload.instructions }),
+                    ...(q.criteria === undefined ? {} : { criteria: q.criteria }),
+                },
+                ...(q.kind === "choice" ? { criteria: Object.fromEntries(q.options.map((label) => [label, null])) } :
+                    q.kind === "score" ? { criteria: q.levels } : {}),
+            }]));
+        return Math.max(bytes({ ...payload, model, questions }), bytes({ model, state: payload.state, questions: wireQuestions, ...(payload.effort === undefined ? {} : { effort: payload.effort }) }));
+    };
+    const total = measure(payload.questions);
+    return { total, context: Math.max(...payload.questions.map((q) => measure([q]))), gateway: total + 4096 };
+}
+/** OpenRouter's TOTAL limit is separate from direct state-plus-longest context. */
+function decisionFitsGateway(payload) {
+    return decisionInputBudget(payload).gateway <= 32000;
+}
+function validateInput(payload, ctx) {
+    if (new Set(payload.questions.map((q) => q.id)).size !==
+        payload.questions.length)
+        ctx.addIssue({
+            code: "custom",
+            path: ["questions"],
+            message: "Question IDs must be unique.",
+        });
+    for (const [index, question] of payload.questions.entries()) {
+        const labels = question.kind === "choice"
+            ? question.options
+            : question.kind === "score"
+                ? question.levels
+                : [];
+        if (new Set(labels).size !== labels.length)
+            ctx.addIssue({
+                code: "custom",
+                path: ["questions", index],
+                message: "Options and levels must be unique.",
+            });
+    }
+    const budget = decisionInputBudget(payload);
+    if (budget.total > 64000 || budget.context > 32000)
+        ctx.addIssue({
+            code: "custom",
+            path: ["state"],
+            message: "Decisions exceed the serialized 64000-byte total or 32000-byte per-question context budget.",
+        });
+}
+exports.decisionInputSchema = zod_1.z
+    .object(payloadFields)
+    .strict()
+    .superRefine(validateInput);
+exports.decisionRequestSchema = zod_1.z
+    .object({
+    model: identifiers_1.modelReferenceSchema.refine((model) => model.includes("@"), "Decisions require a revision-pinned model."),
+    ...payloadFields,
+})
+    .strict()
+    .superRefine(validateInput);
+exports.decisionAnswerSchema = zod_1.z
+    .discriminatedUnion("kind", [
+    zod_1.z
+        .object({
+        id,
+        kind: zod_1.z.literal("choice"),
+        /** Actual provider-selected option. Never reconstructed from probabilities. */
+        reply: text,
+        /** Provider-returned confidence, not a correctness probability. */
+        confidence: probability,
+        probabilities: zod_1.z.array(probability).min(2).max(255),
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        id,
+        kind: zod_1.z.literal("score"),
+        /** Actual provider score. Kept separate from the validated expected index. */
+        reply: zod_1.z.number().finite().min(0).max(9),
+        confidence: probability,
+        mean: zod_1.z.number().finite().min(0).max(9),
+        distribution: zod_1.z.array(probability).min(2).max(10),
+    })
+        .strict(),
+    zod_1.z.object({ id, kind: zod_1.z.literal("noul"), probability }).strict(),
+])
+    .superRefine((answer, ctx) => {
+    if (answer.kind === "noul")
+        return;
+    if (answer.kind === "score" && Math.abs(answer.reply - answer.mean) > tolerance) {
+        ctx.addIssue({ code: "custom", path: ["reply"], message: "Provider score must match the expected level index." });
+    }
+    const distribution = answer.kind === "choice" ? answer.probabilities : answer.distribution;
+    if (Math.abs(distribution.reduce((sum, value) => sum + value, 0) - 1) >
+        tolerance)
+        ctx.addIssue({
+            code: "custom",
+            message: "Probabilities must sum to one.",
+        });
+    if (answer.kind === "score" &&
+        Math.abs(distribution.reduce((sum, value, index) => sum + index * value, 0) -
+            answer.mean) > tolerance)
+        ctx.addIssue({
+            code: "custom",
+            path: ["mean"],
+            message: "Mean must equal the expected zero-based level index.",
+        });
+});
+const resultFields = {
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    model: identifiers_1.modelReferenceSchema.refine((model) => model.includes("@"), "Decisions require an immutable model revision."),
+    data: zod_1.z.array(exports.decisionAnswerSchema).min(1).max(255),
+};
+function uniqueAnswers(result, ctx) {
+    if (new Set(result.data.map((answer) => answer.id)).size !== result.data.length)
+        ctx.addIssue({
+            code: "custom",
+            path: ["data"],
+            message: "Answer IDs must be unique.",
+        });
+}
+exports.decisionResultSchema = zod_1.z
+    .object({ ...resultFields, usage: usage_1.normalizedUsageReportSchema })
+    .strict()
+    .superRefine(uniqueAnswers)
+    .superRefine((result, ctx) => {
+    if (result.usage.requestId !== result.requestId ||
+        result.usage.resolvedModelReference !== result.model ||
+        result.usage.outcome !== "completed") {
+        ctx.addIssue({
+            code: "custom",
+            path: ["usage"],
+            message: "Decision usage must describe this completed request and immutable model.",
+        });
+    }
+});
+/**
+ * Kaana's typed decisions failure. `usage` is present only when the provider
+ * measured something before failing; its absence means nothing was measured,
+ * never that the cost was zero. A failure carrying usage did execute.
+ */
+exports.decisionFailureSchema = zod_1.z
+    .object({
+    schemaVersion: zod_1.z.literal(1),
+    requestId: identifiers_1.requestIdSchema,
+    error: errors_1.inferenceErrorSchema,
+    usage: usage_1.normalizedUsageReportSchema.optional(),
+})
+    .strict()
+    .superRefine((failure, ctx) => {
+    if (failure.error.requestId !== failure.requestId) {
+        ctx.addIssue({ code: "custom", path: ["error", "requestId"], message: "The error must answer this request." });
+    }
+    if (failure.usage !== undefined &&
+        (failure.usage.requestId !== failure.requestId || failure.usage.outcome === "completed")) {
+        ctx.addIssue({ code: "custom", path: ["usage"], message: "Failure usage must describe this request and an incomplete outcome." });
+    }
+});
+exports.decisionSuccessSchema = zod_1.z
+    .object({
+    ...resultFields,
+    usage: zod_1.z.array(money_1.usageQuantitySchema),
+    routingPolicy: routingPolicy_1.routingPolicyReferenceSchema,
+})
+    .strict()
+    .superRefine(uniqueAnswers);
+/** Bind output to the exact request. Provider order is not semantic. */
+function decisionAnswersMatch(input, answers) {
+    if (answers.length !== input.questions.length ||
+        new Set(answers.map((a) => a.id)).size !== answers.length)
+        return false;
+    return input.questions.every((question) => {
+        const answer = answers.find((candidate) => candidate.id === question.id);
+        if (!answer ||
+            !exports.decisionAnswerSchema.safeParse(answer).success ||
+            answer.kind !== question.kind)
+            return false;
+        if (question.kind === "choice" && answer.kind === "choice") {
+            const index = question.options.indexOf(answer.reply);
+            return question.options.length === answer.probabilities.length && index >= 0 &&
+                answer.probabilities[index] + tolerance >= Math.max(...answer.probabilities);
+        }
+        if (question.kind === "score" && answer.kind === "score")
+            return question.levels.length === answer.distribution.length;
+        return question.kind === "noul";
+    });
+}

package/dist/cjs/inference/request.js

@@ -26,6 +26,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.inferenceRequestSchema = exports.inferenceAudioOutputParametersSchema = exports.inferenceSpeechParametersSchema = exports.clientRequestMetadataSchema = exports.inferenceReasoningSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
+const decisions_1 = require("./decisions");
 const zod_1 = require("zod");
 const attribution_1 = require("./attribution");
 const catalogue_1 = require("./catalogue");
@@ -198,6 +199,7 @@ exports.inferenceMessageSchema = zod_1.z
  * that both metering and provider translation depend on.
  */
 exports.inferenceInputSchema = zod_1.z.discriminatedUnion("format", [
+    zod_1.z.object({ format: zod_1.z.literal("decisions"), decisions: decisions_1.decisionInputSchema }).strict(),
     zod_1.z
         .object({
         format: zod_1.z.literal("messages"),
@@ -406,6 +408,17 @@ exports.inferenceRequestSchema = zod_1.z
     authorizedRoutes: zod_1.z.array(routingPolicy_1.authorizedRouteSchema).min(1).optional(),
 })
     .superRefine((request, ctx) => {
+    if (request.input.format === "decisions" || request.client.apiFormat === "decisions") {
+        const exactModel = request.target.kind === "model" && request.target.modelReference.includes('@');
+        const foreignRoute = request.authorizedRoutes?.some((route) => request.target.kind !== "model" || route.modelReference !== request.target.modelReference || route.substitution !== "same_model");
+        if (request.input.format !== "decisions" || request.client.apiFormat !== "decisions" ||
+            request.modality !== "text" || request.stream || !exactModel || foreignRoute ||
+            request.maxOutputTokens !== undefined || Object.keys(request.sampling).length > 0 ||
+            request.tools.length > 0 || request.toolChoice !== undefined || request.responseFormat !== undefined ||
+            request.reasoning !== undefined || request.speech !== undefined || request.audioOutput !== undefined) {
+            ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["input"], message: "Decisions require exact-model typed nonstreaming input without generation controls or model substitution." });
+        }
+    }
     const isSpeech = request.client.apiFormat === "audio_speech";
     if (isSpeech && request.speech !== undefined && (request.modality !== "audio" || request.input.format !== "text" || request.stream)) {
         ctx.addIssue({ code: zod_1.z.ZodIssueCode.custom, path: ["speech"], message: "speech requires audio modality, text input, parameters and non-streaming output" });

package/dist/cjs/inference/version.js

@@ -102,4 +102,4 @@ exports.INFERENCE_CONTRACT_VERSION = void 0;
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-exports.INFERENCE_CONTRACT_VERSION = '3.4.0';
+exports.INFERENCE_CONTRACT_VERSION = '3.5.0';