@oxy.so/contracts 1.3.0 → 1.5.0

package/dist/esm/index.js

@@ -138,7 +138,7 @@ export {
 priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
 export { 
 // The six distinct catalogue objects + the customer-safe projection.
-inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
+inferenceModalitySchema, reasoningEffortSchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
 export { 
 // Routing policy: every control, plus the refinement that rejects a policy
 // no route could ever satisfy.
@@ -155,7 +155,7 @@ export {
 modelDistributionMethodSchema, modelSystemicRiskTierSchema, trainingComputeFlopsSchema, SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS, modelDownstreamDocumentationSchema, modelGpaiDocumentationSchema, modelLineDeclarationSchema, modelReleaseIngestionRequestSchema, modelReleaseIngestionResultSchema, modelDocumentationSchema, } from './inference/modelDocumentation.js';
 export { 
 // The normalized Oxy→data-plane request envelope.
-inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request.js';
+inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, inferenceReasoningSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request.js';
 export { 
 // Normalized SSE events.
 inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceAudioMediaTypeSchema, MAX_INFERENCE_AUDIO_BYTES, inferenceStreamAudioEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents.js';
@@ -178,3 +178,5 @@ export { AUTONOMY_LEVELS, CAPABILITY_PACKAGES, autonomyLevelSchema, capabilityPa
 export { emailContextAddressSchema, emailContextMailboxSchema, emailContextMessageSchema, emailAgentContextSchema, } from './emailAgentContext.js';
 export { inboxComposeRequestSchema, inboxDailyBriefRequestSchema, inboxNaturalSearchRequestSchema, inboxMessageInferenceParamsSchema, inboxInferenceTextResponseSchema, inboxNaturalSearchResponseSchema, inboxSmartRepliesResponseSchema, inboxThreadSummaryResponseSchema, inboxInferenceStreamEventSchema, } from './inference/inbox.js';
 export * from './externalIdentity.js';
+export * from './linkedAccounts.js';
+export * from './notifications.js';

package/dist/esm/inference/catalogue.js

@@ -40,6 +40,15 @@ export const inferenceModalitySchema = z.enum([
     'video',
     'embedding',
 ]);
+/**
+ * How hard a reasoning model is asked to think before it answers.
+ *
+ * A closed, provider-neutral vocabulary: Kaana translates each value into the
+ * serving provider's own control. A model advertises the subset it accepts in
+ * `modelCapabilitiesSchema.reasoningEfforts`, and Oxy refuses a request for an
+ * effort the resolved model does not advertise rather than dropping it.
+ */
+export const reasoningEffortSchema = z.enum(['low', 'medium', 'high']);
 /**
  * What a model can do, in the terms a caller has to decide against before
  * sending a request: can it call tools, does it accept images, will it honour a
@@ -54,6 +63,13 @@ export const modelCapabilitiesSchema = z
     structuredOutput: z.boolean(),
     jsonMode: z.boolean(),
     reasoning: z.boolean(),
+    /**
+     * The reasoning efforts a request may name for this model, in the order
+     * low → high. Empty means the model takes no effort control at all (it may
+     * still reason: `reasoning` answers that). Added in contract set 3.1.0;
+     * absent on the wire from an older producer, it parses as `[]`.
+     */
+    reasoningEfforts: z.array(reasoningEffortSchema).default([]),
     streaming: z.boolean(),
     promptCaching: z.boolean(),
     maxContextTokens: z.number().int().positive().safe(),
@@ -469,6 +485,12 @@ export const modelCatalogueEntrySchema = z.object({
     provenance: modelProvenanceSchema,
     knowledgeCutoff: inferenceDateSchema.optional(),
     releasedOn: inferenceDateSchema.optional(),
+    /**
+     * When the upstream provider first published this model, as that provider
+     * reports it. Present only when a provider reported it; never an Oxy or Kaana
+     * observation time. Lets a picker order models newest first.
+     */
+    releasedAt: inferenceTimestampSchema.optional(),
     regions: z.array(inferenceRegionSchema).default([]),
     servingProviders: z.array(catalogueServingProviderSummarySchema).default([]),
     dataPolicy: inferenceDataPolicySchema,

package/dist/esm/inference/request.js

@@ -25,7 +25,7 @@
  */
 import { z } from "zod";
 import { inferenceAttributionSchema } from "./attribution.js";
-import { inferenceModalitySchema } from "./catalogue.js";
+import { inferenceModalitySchema, reasoningEffortSchema } from "./catalogue.js";
 import { idempotencyKeySchema, inferenceTimestampSchema } from "./identifiers.js";
 import { authorizedRouteSchema, routingPolicyReferenceSchema, routingTargetSchema, } from "./routingPolicy.js";
 /* -------------------------------------------------------------------------- */
@@ -260,6 +260,16 @@ export const responseFormatSchema = z.discriminatedUnion("type", [
     })
         .strict(),
 ]);
+/**
+ * The caller's reasoning control. Strict, like every leaf: a provider-specific
+ * knob (`budget_tokens`, `summary`) is refused rather than silently dropped.
+ *
+ * Oxy forwards it only after checking the resolved model advertises the effort
+ * in its catalogue `reasoningEfforts`; Kaana translates it per provider.
+ */
+export const inferenceReasoningSchema = z
+    .object({ effort: reasoningEffortSchema })
+    .strict();
 /* -------------------------------------------------------------------------- */
 /*  Client metadata                                                           */
 /* -------------------------------------------------------------------------- */
@@ -336,6 +346,8 @@ export const inferenceRequestSchema = z
     stream: z.boolean(),
     maxOutputTokens: z.number().int().positive().safe().optional(),
     sampling: samplingParametersSchema,
+    /** Absent means the route's own default reasoning behaviour. */
+    reasoning: inferenceReasoningSchema.optional(),
     speech: inferenceSpeechParametersSchema.optional(),
     tools: z.array(toolDefinitionSchema).default([]),
     toolChoice: toolChoiceSchema.optional(),

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '3.0.0';
+export const INFERENCE_CONTRACT_VERSION = '3.1.0';

package/dist/esm/linkedAccounts.js

@@ -0,0 +1,90 @@
+/**
+ * Wire contract for Oxy linked accounts — external accounts (any Mastodon-API
+ * server, Bluesky) a LOCAL Oxy user has proven they own by completing an OAuth
+ * authorization there.
+ *
+ * Every response schema is `.strict()` and carries no field a third-party token
+ * could occupy: Oxy uses the OAuth flow only to learn which account authorized
+ * it, then discards the token. See `docs/identity/linked-accounts.md`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+export const LINKED_ACCOUNT_NETWORKS = ['activitypub', 'atproto'];
+export const linkedAccountNetworkSchema = z.enum(LINKED_ACCOUNT_NETWORKS);
+/**
+ * `POST /linked-accounts/:network/start`.
+ *
+ * - `instance` (activitypub): `mastodon.social`, `https://mastodon.social` or
+ *   `@user@mastodon.social`.
+ * - `handle` (atproto): a handle (`alice.bsky.social`) or a DID.
+ * - `returnTo` + `clientId`: where the browser lands afterwards, with
+ *   `?link_code=` or `?link_error=`. `returnTo` must exactly match a redirect
+ *   URI registered on the TRUSTED (first-party) application `clientId` names.
+ */
+export const startLinkedAccountRequestSchema = z
+    .object({
+    instance: z.string().trim().min(1).max(320).optional(),
+    handle: z.string().trim().min(1).max(320).optional(),
+    clientId: z.string().trim().min(1).max(256),
+    returnTo: z.string().trim().min(1).max(2048),
+})
+    .strict();
+export const startLinkedAccountResponseSchema = z
+    .object({
+    authorizeUrl: z.string().url(),
+    expiresAt: z.string().datetime(),
+})
+    .strict();
+/**
+ * `POST /linked-accounts/complete`, with the session of the user who STARTED
+ * the flow: `code` is the one-time `link_code` the callback appended to
+ * `returnTo`. It expires five minutes after the callback. Presented by any
+ * other user it is refused (403) and burned.
+ */
+export const completeLinkedAccountRequestSchema = z
+    .object({ code: z.string().trim().min(1).max(256) })
+    .strict();
+/** One live linked account, as its owner sees it. */
+export const linkedAccountSchema = z
+    .object({
+    id: z.string().min(1),
+    network: linkedAccountNetworkSchema,
+    /** `username@domain` for ActivityPub; the DID for atproto. */
+    accountKey: z.string().min(1),
+    /** ActivityPub actor id, or the DID for atproto. */
+    actorUri: z.string().min(1),
+    handle: z.string().min(1),
+    host: z.string().min(1),
+    proofMethod: z.literal('oauth'),
+    verifiedAt: z.string().datetime(),
+    createdAt: z.string().datetime(),
+})
+    .strict();
+export const completeLinkedAccountResponseSchema = z
+    .object({ linkedAccount: linkedAccountSchema })
+    .strict();
+export const linkedAccountListResponseSchema = z
+    .object({ linkedAccounts: z.array(linkedAccountSchema) })
+    .strict();
+/**
+ * `GET /linked-accounts/by-user/:userId` (service token with the privileged
+ * `linked-accounts:read`). Adds `federatedUserId`: the FEDERATED shadow user Oxy
+ * already holds for that external account, if any — the anchor for adopting
+ * content Oxy federated in before the account was linked.
+ */
+export const serviceLinkedAccountSchema = linkedAccountSchema
+    .extend({ federatedUserId: z.string().min(1).nullable() })
+    .strict();
+export const serviceLinkedAccountListResponseSchema = z
+    .object({ userId: z.string().min(1), linkedAccounts: z.array(serviceLinkedAccountSchema) })
+    .strict();
+/**
+ * Error codes the callback appends as `?link_error=<code>` to `returnTo`. An
+ * account already linked to someone else is reported by `/complete` (409).
+ */
+export const LINKED_ACCOUNT_CALLBACK_ERRORS = [
+    'access_denied',
+    'verification_failed',
+    'provider_unavailable',
+];

package/dist/esm/notifications.js

@@ -0,0 +1,78 @@
+/**
+ * The closed set of Oxy in-app notification types — owned here so the API's
+ * CHECK constraint (`notifications.type`), its request validation and the SDK
+ * all read one tuple.
+ *
+ * `system` is a message from an Oxy service about the recipient's OWN account
+ * (Oxy Move's "your migration finished"): the actor is the recipient, and the
+ * entity is their profile or an `app` id. It is the only type an actor does not
+ * cause.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+export const OXY_NOTIFICATION_TYPES = [
+    'like',
+    'reply',
+    'mention',
+    'follow',
+    'repost',
+    'quote',
+    'welcome',
+    'system',
+];
+/**
+ * What a notification's `entityId` names.
+ *
+ * `app` means `entityId` is an OPAQUE id in the notifying application's own
+ * namespace (Oxy Move's migration job id). Oxy never resolves it; it exists so
+ * a `system` notification about something that is not a post or a profile does
+ * not have to pretend to be one. Valid only with `type: 'system'`.
+ */
+export const OXY_NOTIFICATION_ENTITY_TYPES = ['post', 'reply', 'profile', 'app'];
+/** Length caps on the text a `system` notification carries (enforced by CHECKs too). */
+export const OXY_SYSTEM_NOTIFICATION_TITLE_MAX = 120;
+export const OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX = 500;
+export const OXY_NOTIFICATION_URL_MAX = 2048;
+/**
+ * `POST /notifications` (service token with `notifications:write`).
+ *
+ * Only a `system` notification carries text: `title` and `message` are REQUIRED
+ * for it and stored, and `url` is an optional deep link (https, or a custom
+ * scheme registered as a redirect URI on the calling application). For every
+ * other type the client renders from `type` + entity, and `title` / `message` /
+ * `data` are accepted but discarded, as they always were.
+ *
+ * `system` notifications share the duplicate guard (recipient, actor, type,
+ * entityId): use a caller-unique `entityId` (a job id) for each distinct event.
+ */
+export const createOxyNotificationRequestSchema = z
+    .object({
+    recipientId: z.string().min(1),
+    actorId: z.string().min(1),
+    type: z.enum(OXY_NOTIFICATION_TYPES),
+    entityId: z.string().min(1),
+    entityType: z.enum(OXY_NOTIFICATION_ENTITY_TYPES),
+    title: z.string().trim().min(1).max(OXY_SYSTEM_NOTIFICATION_TITLE_MAX).optional(),
+    message: z.string().trim().min(1).max(OXY_SYSTEM_NOTIFICATION_MESSAGE_MAX).optional(),
+    url: z.string().trim().min(1).max(OXY_NOTIFICATION_URL_MAX).optional(),
+    data: z.record(z.string(), z.unknown()).optional(),
+})
+    .superRefine((value, context) => {
+    if (value.type === 'system') {
+        if (value.actorId !== value.recipientId)
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['actorId'], message: 'a system notification is from the recipient\'s own account' });
+        if (!value.title)
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['title'], message: 'title is required for a system notification' });
+        if (!value.message)
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['message'], message: 'message is required for a system notification' });
+    }
+    else {
+        if (value.url !== undefined) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['url'], message: 'url is only stored for a system notification' });
+        }
+        if (value.entityType === 'app') {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ['entityType'], message: "entityType 'app' is only valid for a system notification" });
+        }
+    }
+});