@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/llm-pi-ai/lib/types/config.d.ts

@@ -14,12 +14,26 @@
  * @module nomix-llm-pi-ai/config
  */
 import type { CacheRetention, ModelThinkingLevel, Provider, ThinkingBudgets, Transport } from '@earendil-works/pi-ai';
-import z from '@nomix-ai/schemastery';
+import z from '../../../schemastery/lib/index.mjs';
 import type { CredentialRef } from '../../../credentials/lib/index.js';
 import type { ResolvedRetryPolicy, RetryPolicyConfig } from '../../../llm/lib/index.js';
 import type { PiAiCompatProfile, PiAiModality, PiAiModelOverride, PiAiModelProfile } from './catalog.ts';
 /** Default maximum idle interval while an adapter stream read is outstanding. */
 export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/**
+ * Default request-level bound on base64-encoded image payload. Every image in
+ * history is re-encoded into every request body, so an unbounded conversation
+ * eventually exceeds a provider or gateway request-size cap and the session
+ * can never complete another request. The 20MiB default admits fifteen 1MiB
+ * request versions after base64 expansion and reserves request capacity for
+ * system prompts, history, tools, and JSON.
+ * Deployments behind stricter gateways lower it per route.
+ */
+export declare const DEFAULT_MAX_REQUEST_IMAGE_BYTES: number;
+/** Default total-pixel budget preserves the complete 2048px normalized attachment. */
+export declare const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET: number;
+/** Default raw encoded-byte cap before inline base64 expansion. */
+export declare const DEFAULT_REQUEST_IMAGE_MAX_BYTES: number;
 /** Context capacity assumed for a model neither configuration nor the catalog sizes. */
 export declare const DEFAULT_CONTEXT_WINDOW = 262144;
 /** Output capability assumed for a model neither configuration nor the catalog sizes. */
@@ -66,10 +80,11 @@ export interface PiAiProviderProfile {
      */
     modelOverrides?: Record<string, PiAiModelOverride>;
     /**
-     * Reasoning-dispatch switches for every `openai-completions` model on this
-     * route; each model's own `compat` overrides per field. What neither sets
-     * keeps the installed catalog entry's value, then pi-ai's baseURL-derived
-     * detection.
+     * pi-ai wire-compatibility switches defaulting every model on this route
+     * whose protocol declares them; each model's own `compat` overrides per
+     * field. What neither sets keeps the installed catalog entry's value, then
+     * pi-ai's own detection. A switch no model on the route could read is
+     * refused rather than left looking applied.
      */
     compat?: PiAiCompatProfile;
     /**
@@ -111,7 +126,18 @@ export interface PiAiProviderProfile {
     websocketConnectTimeoutMs?: number;
     /** Maximum provider idle time while one stream read is outstanding. */
     streamIdleTimeoutMs?: number;
-    /** Provider-owned model-request retry policy; omission uses normal defaults. */
+    /**
+     * Maximum base64-encoded image payload per request. When a request's
+     * accumulated images exceed it, the oldest images are replaced by text
+     * placeholders until the request fits, so a long session keeps completing
+     * requests instead of being rejected by a request-size cap.
+     */
+    maxRequestImageBytes?: number;
+    /** Total-pixel budget for each deterministic inline request version. */
+    requestImagePixelBudget?: number;
+    /** Raw encoded-byte cap for each deterministic inline request version. */
+    requestImageMaxBytes?: number;
+    /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
     retryPolicy?: RetryPolicyConfig;
 }
 /** Validated profile with its route stamped and every adapter-owned default resolved. */
@@ -124,6 +150,12 @@ export interface ResolvedPiAiProviderProfile extends Omit<PiAiProviderProfile, '
     apiKeyEnv?: CredentialRef;
     /** Positive finite provider-idle interval after defaulting. */
     streamIdleTimeoutMs: number;
+    /** Positive request-level base64 image payload bound after defaulting. */
+    maxRequestImageBytes: number;
+    /** Positive total-pixel request-version budget after defaulting. */
+    requestImagePixelBudget: number;
+    /** Positive raw request-version byte cap after defaulting. */
+    requestImageMaxBytes: number;
     /** Immutable retry policy captured with this provider route. */
     retryPolicy: ResolvedRetryPolicy;
     /**

package/dist/kernel/llm-pi-ai/lib/types/config.js

@@ -13,14 +13,28 @@
  *
  * @module nomix-llm-pi-ai/config
  */
-import z from '@nomix-ai/schemastery';
+import z from '../../../schemastery/lib/index.mjs';
 import { credentialRef } from '../../../credentials/lib/index.js';
 import { MAX_TIMER_DELAY_MS } from '../../../timeout/lib/index.js';
 import { resolveRetryPolicy, RetryPolicySchema } from '../../../llm/lib/index.js';
-import { MODALITIES, resolveRouteModels, SUPPORTED_THINKING_FORMATS, THINKING_LEVELS } from "./catalog.js";
+import { CACHE_CONTROL_FORMATS, CHAT_TEMPLATE_VARS, MAX_TOKENS_FIELDS, MODALITIES, resolveRouteModels, SUPPORTED_THINKING_FORMATS, THINKING_LEVELS, } from "./catalog.js";
 import { buildProvider, supportedProtocols } from "./provider.js";
 /** Default maximum idle interval while an adapter stream read is outstanding. */
 export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000;
+/**
+ * Default request-level bound on base64-encoded image payload. Every image in
+ * history is re-encoded into every request body, so an unbounded conversation
+ * eventually exceeds a provider or gateway request-size cap and the session
+ * can never complete another request. The 20MiB default admits fifteen 1MiB
+ * request versions after base64 expansion and reserves request capacity for
+ * system prompts, history, tools, and JSON.
+ * Deployments behind stricter gateways lower it per route.
+ */
+export const DEFAULT_MAX_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Default total-pixel budget preserves the complete 2048px normalized attachment. */
+export const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 2048 * 2048;
+/** Default raw encoded-byte cap before inline base64 expansion. */
+export const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
 /** Context capacity assumed for a model neither configuration nor the catalog sizes. */
 export const DEFAULT_CONTEXT_WINDOW = 262_144;
 /** Output capability assumed for a model neither configuration nor the catalog sizes. */
@@ -42,9 +56,42 @@ const thinkingBudgets = z.object({
     medium: z.number(),
     high: z.number(),
 });
+/**
+ * One `chat_template_kwargs` value. The `$var` member is pi-ai's placeholder
+ * for a value dispatch fills from the request's thinking state, which is what
+ * makes a chat-template gateway configurable without restating its template.
+ */
+const chatTemplateKwarg = z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.const(null),
+    z.object({
+        $var: z.union(CHAT_TEMPLATE_VARS).required(),
+        omitWhenOff: z.boolean(),
+    }),
+]);
 const compatProfile = z.object({
-    thinkingFormat: z.union(SUPPORTED_THINKING_FORMATS),
+    supportsStore: z.boolean(),
+    supportsDeveloperRole: z.boolean(),
     supportsReasoningEffort: z.boolean(),
+    supportsUsageInStreaming: z.boolean(),
+    maxTokensField: z.union(MAX_TOKENS_FIELDS),
+    requiresToolResultName: z.boolean(),
+    requiresAssistantAfterToolResult: z.boolean(),
+    requiresThinkingAsText: z.boolean(),
+    requiresReasoningContentOnAssistantMessages: z.boolean(),
+    thinkingFormat: z.union(SUPPORTED_THINKING_FORMATS),
+    chatTemplateKwargs: z.dict(chatTemplateKwarg),
+    supportsStrictMode: z.boolean(),
+    cacheControlFormat: z.union(CACHE_CONTROL_FORMATS),
+    supportsLongCacheRetention: z.boolean(),
+    supportsEagerToolInputStreaming: z.boolean(),
+    supportsCacheControlOnTools: z.boolean(),
+    supportsTemperature: z.boolean(),
+    forceAdaptiveThinking: z.boolean(),
+    allowEmptySignature: z.boolean(),
+    supportsStrictTools: z.boolean(),
 });
 /**
  * Keys are the offered levels, values their wire spellings. A valueless key
@@ -97,6 +144,9 @@ const profile = z.object({
     timeoutMs: z.natural(),
     websocketConnectTimeoutMs: z.natural(),
     streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+    maxRequestImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_REQUEST_IMAGE_BYTES),
+    requestImagePixelBudget: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET),
+    requestImageMaxBytes: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_MAX_BYTES),
     retryPolicy: RetryPolicySchema,
 });
 /** Runtime schema for {@link Config}. */
@@ -159,6 +209,18 @@ export function resolveProfiles(providers) {
             || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
             throw new Error(`llm-pi-ai: provider "${provider}" streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
         }
+        const maxRequestImageBytes = source.maxRequestImageBytes ?? DEFAULT_MAX_REQUEST_IMAGE_BYTES;
+        if (!Number.isInteger(maxRequestImageBytes) || maxRequestImageBytes <= 0) {
+            throw new Error(`llm-pi-ai: provider "${provider}" maxRequestImageBytes must be a positive integer`);
+        }
+        const requestImagePixelBudget = source.requestImagePixelBudget ?? DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET;
+        if (!Number.isSafeInteger(requestImagePixelBudget) || requestImagePixelBudget <= 0) {
+            throw new Error(`llm-pi-ai: provider "${provider}" requestImagePixelBudget must be a positive safe integer`);
+        }
+        const requestImageMaxBytes = source.requestImageMaxBytes ?? DEFAULT_REQUEST_IMAGE_MAX_BYTES;
+        if (!Number.isSafeInteger(requestImageMaxBytes) || requestImageMaxBytes <= 0) {
+            throw new Error(`llm-pi-ai: provider "${provider}" requestImageMaxBytes must be a positive safe integer`);
+        }
         // Detached from the configuration object because pi-ai types `Model.input`
         // mutable. The schema's explicit default covers an absent key, so an empty
         // list here is always one someone typed — and unlike an entry's, nothing
@@ -190,6 +252,9 @@ export function resolveProfiles(providers) {
             displayName,
             ...apiKeyEnv === undefined ? {} : { apiKeyEnv: credentialRef(apiKeyEnv) },
             streamIdleTimeoutMs,
+            maxRequestImageBytes,
+            requestImagePixelBudget,
+            requestImageMaxBytes,
             retryPolicy: resolveRetryPolicy(retryPolicy, `llm-pi-ai: provider "${provider}" retryPolicy`),
             ...rest.headers === undefined ? {} : { headers: { ...rest.headers } },
             ...rest.thinkingBudgets === undefined ? {} : { thinkingBudgets: { ...rest.thinkingBudgets } },

package/dist/kernel/llm-pi-ai/lib/types/context.d.ts

@@ -4,7 +4,7 @@
  * @module nomix-llm-pi-ai/context
  */
 import type { GenerateOptions } from '../../../llm/lib/index.js';
-import type { AttachmentStore } from '../../../attachment/lib/index.js';
+import type { AttachmentStore, ImageRequestPolicy } from '../../../attachment/lib/index.js';
 import type { Context as PiContext } from '@earendil-works/pi-ai';
 /**
  * Convert text-only harness history to a synchronous pi-ai Context. Tool
@@ -17,11 +17,16 @@ import type { Context as PiContext } from '@earendil-works/pi-ai';
 export declare function toPiContext(options: GenerateOptions, attachments?: undefined, onReplayDegrade?: (reason: string) => void): PiContext;
 /**
  * Convert harness history to a pi-ai Context while resolving durable images.
- * Tool result names are recovered from preceding assistant tool calls.
+ * Tool result names are recovered from preceding assistant tool calls. When
+ * the accumulated base64 image payload exceeds `maxRequestImageBytes`, the
+ * oldest images are replaced by text placeholders until the request fits, so
+ * an image-heavy session keeps clearing gateway request-size caps.
  * @param options - the harness request; `options.system` maps to pi-ai's single `systemPrompt` slot.
  * @param attachments - durable byte resolver for image references.
  * @param onReplayDegrade - forwarded to {@link toPiAssistant} for each assistant message.
+ * @param maxRequestImageBytes - request-level bound on base64-encoded image payload; omission leaves every image in place.
+ * @param requestImagePolicy - route pixel and raw encoded-byte budgets.
  * @returns the asynchronously resolved pi-ai context.
  */
-export declare function toPiContext(options: GenerateOptions, attachments: AttachmentStore, onReplayDegrade?: (reason: string) => void): Promise<PiContext>;
+export declare function toPiContext(options: GenerateOptions, attachments: AttachmentStore, onReplayDegrade?: (reason: string) => void, maxRequestImageBytes?: number, requestImagePolicy?: ImageRequestPolicy): Promise<PiContext>;
 //# sourceMappingURL=context.d.ts.map

package/dist/kernel/llm-pi-ai/lib/types/context.js

@@ -3,8 +3,9 @@
  *
  * @module nomix-llm-pi-ai/context
  */
-import { CallId, contentHasImage, LlmError } from '../../../llm/lib/index.js';
+import { CallId, contentHasImage, LlmError, offloadRequestImagesWithPolicy, requestImageHandleText } from '../../../llm/lib/index.js';
 import { toPiAssistant } from "./replay.js";
+import { DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET } from "./config.js";
 /** Join the text blocks of a harness message. */
 function flattenText(message) {
     return message.content
@@ -18,7 +19,15 @@ function toolResultText(blocks) {
         ? block.text
         : block.type === 'tool-result' ? toolResultText(block.content) : '').join('');
 }
-async function userContent(blocks, attachments) {
+/** Reject image roles that pi-ai cannot replay before request-size offloading can replace them. */
+function assertSupportedImageRoles(messages) {
+    for (const message of messages) {
+        if (message.role !== 'user' && contentHasImage(message.content)) {
+            throw new LlmError(`pi-ai cannot represent an image in an in-history ${message.role} message`, 'UNSUPPORTED_CONTENT');
+        }
+    }
+}
+async function userContent(blocks, requestImages) {
     const content = [];
     for (const block of blocks) {
         switch (block.type) {
@@ -27,17 +36,18 @@ async function userContent(blocks, attachments) {
                     content.push({ type: 'text', text: block.text });
                 break;
             case 'image': {
-                const stored = await attachments.readImage(block.attachment);
+                const version = requestImages.get(block.attachment.attachmentId);
+                content.push({ type: 'text', text: requestImageHandleText(version) });
                 content.push({
                     type: 'image',
-                    data: Buffer.from(stored.data).toString('base64'),
-                    mimeType: stored.ref.mediaType,
+                    data: Buffer.from(version.data).toString('base64'),
+                    mimeType: version.mediaType,
                 });
                 break;
             }
             case 'tool-result':
                 {
-                    const nested = await userContent(block.content, attachments);
+                    const nested = await userContent(block.content, requestImages);
                     if (typeof nested === 'string') {
                         if (nested.length > 0)
                             content.push({ type: 'text', text: nested });
@@ -56,6 +66,26 @@ async function userContent(blocks, attachments) {
         return content.map(block => block.text).join('');
     return content;
 }
+function collectImageRefs(blocks, refs) {
+    for (const block of blocks) {
+        if (block.type === 'image')
+            refs.set(block.attachment.attachmentId, block.attachment);
+        else if (block.type === 'tool-result')
+            collectImageRefs(block.content, refs);
+    }
+}
+async function prepareRequestImages(messages, attachments, policy, signal) {
+    const refs = new Map();
+    for (const message of messages)
+        collectImageRefs(message.content, refs);
+    const orderedRefs = [...refs.values()];
+    const prepared = await Promise.all(orderedRefs.map(ref => attachments.readImageRequest(ref, policy, signal)));
+    const versions = new Map();
+    for (const [index, ref] of orderedRefs.entries()) {
+        versions.set(ref.attachmentId, prepared[index]);
+    }
+    return versions;
+}
 function toolsOf(options) {
     return options.tools?.map(tool => ({
         name: tool.name,
@@ -113,19 +143,33 @@ function textOnlyContext(options, onReplayDegrade) {
     }
     return piContext(options, messages);
 }
-export function toPiContext(options, attachments, onReplayDegrade) {
+export function toPiContext(options, attachments, onReplayDegrade, maxRequestImageBytes, requestImagePolicy) {
     return attachments === undefined
         ? textOnlyContext(options, onReplayDegrade)
-        : toPiContextWithImages(options, attachments, onReplayDegrade);
+        : toPiContextWithImages(options, attachments, onReplayDegrade, maxRequestImageBytes, requestImagePolicy);
 }
-async function toPiContextWithImages(options, attachments, onReplayDegrade) {
+async function toPiContextWithImages(options, attachments, onReplayDegrade, maxRequestImageBytes, requestImagePolicy = {
+    maxPixels: DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+    maxBytes: DEFAULT_REQUEST_IMAGE_MAX_BYTES,
+}) {
+    assertSupportedImageRoles(options.messages);
+    const requestMessages = offloadRequestImagesWithPolicy(options.messages, {
+        representation: 'base64',
+        ...maxRequestImageBytes === undefined ? {} : { maxBytes: maxRequestImageBytes },
+        byteQuantum: 1,
+        byteLength: ref => Math.min(ref.bytes, requestImagePolicy.maxBytes),
+    });
+    const requestImages = await prepareRequestImages(requestMessages, attachments, requestImagePolicy, options.signal);
+    const exactMessages = offloadRequestImagesWithPolicy(requestMessages, {
+        representation: 'base64',
+        ...maxRequestImageBytes === undefined ? {} : { maxBytes: maxRequestImageBytes },
+        byteQuantum: 1,
+        byteLength: ref => requestImages.get(ref.attachmentId).bytes,
+    });
     const toolNames = new Map();
     const messages = [];
-    for (const message of options.messages) {
+    for (const message of exactMessages) {
         if (message.role === 'system') {
-            if (contentHasImage(message.content)) {
-                throw new LlmError('pi-ai cannot represent an image in an in-history system message', 'UNSUPPORTED_CONTENT');
-            }
             // pi-ai has a single systemPrompt slot; in-history system messages are
             // folded into user messages to preserve order (rare in practice — the
             // harness sends the system prompt via options.system).
@@ -143,13 +187,13 @@ async function toPiContextWithImages(options, attachments, onReplayDegrade) {
         }
         // user role: text + tool results (each result becomes its own message).
         const regular = message.content.filter(block => block.type !== 'tool-result');
-        const content = await userContent(regular, attachments);
-        const results = message.content.filter(block => block.type === 'tool-result');
+        const content = await userContent(regular, requestImages);
+        const results = message.content.filter((block) => (block.type === 'tool-result'));
         if (content.length > 0 || results.length === 0) {
             messages.push({ role: 'user', content, timestamp: 0 });
         }
         for (const result of results) {
-            const resultContent = await userContent(result.content, attachments);
+            const resultContent = await userContent(result.content, requestImages);
             messages.push({
                 role: 'toolResult',
                 toolCallId: result.toolCallId,

package/dist/kernel/llm-pi-ai/lib/types/index.d.ts

@@ -54,12 +54,13 @@
  *
  * @module @nomix-ai/nomix-llm-pi-ai
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 import { Config } from './config.ts';
 export { PiAiAdapter } from './adapter.ts';
 export type { PiAiAdapterOptions } from './adapter.ts';
 export { Config } from './config.ts';
 export type { PiAiCompatProfile, PiAiModality, PiAiModelOverride, PiAiModelProfile, PiAiProviderProfile, PiAiReasoningEfforts, PiAiThinkingFormat, ResolvedPiAiProviderProfile, } from './config.ts';
+export { recordKeyFor } from './auth.ts';
 export { supportedProtocols } from './provider.ts';
 export declare const name = "llm-pi-ai";
 export declare const inject: string[];

package/dist/kernel/llm-pi-ai/lib/types/index.js

@@ -58,11 +58,14 @@ import { launchEnvironmentOf } from '../../../launch-environment/lib/index.js';
 import { assertUsableApiKey, LlmError } from '../../../llm/lib/index.js';
 import { deepEqualJson, installSettingsSection, settingsNamespace } from '../../../settings/lib/index.js';
 import { PiAiAdapter } from "./adapter.js";
-import { catalogProviderIds, catalogProviderTakesApiKey } from "./catalog.js";
+import { authContextFrom, credentialStoreFrom } from "./auth.js";
+import { catalogProviderIds } from "./catalog.js";
 import { assertServiceable, Config, resolveProfiles } from "./config.js";
 import { discoverModels } from "./discovery.js";
+import { registerPiAiFlows } from "./login.js";
 export { PiAiAdapter } from "./adapter.js";
 export { Config } from "./config.js";
+export { recordKeyFor } from "./auth.js";
 export { supportedProtocols } from "./provider.js";
 export const name = 'llm-pi-ai';
 export const inject = ['llm'];
@@ -85,15 +88,10 @@ function registrationFacts(profiles) {
         .sort((left, right) => left.provider.localeCompare(right.provider));
 }
 /**
- * The configurable-provider directory: every installed catalog route this
- * adapter can authenticate, plus every route the current profiles declare. A
- * hand-declared route has no catalog entry, so without this union it would
- * have no settings address and configuration surfaces could neither show nor
- * edit it.
- *
- * The profile half is unconditional, which is what keeps a route already
- * stored against a withheld provider editable and deletable rather than
- * stranded in the settings document with nothing on the page to remove it.
+ * The configurable-provider directory: every installed catalog route, plus
+ * every route the current profiles declare. A hand-declared route has no
+ * catalog entry, so without this union it would have no settings address and
+ * configuration surfaces could neither show nor edit it.
  * @param profiles - the currently resolved provider profiles.
  * @returns the directory entries in catalog order, declared routes last.
  */
@@ -112,15 +110,8 @@ function directoryEntries(profiles) {
             declared: !catalog.has(provider),
         });
     };
-    // A provider whose only native method is OAuth leaves this adapter nothing
-    // to authenticate with, so offering it would put a card on the settings page
-    // whose own posture — no key, credentials discovered by the provider — fails
-    // every request. Catalog *membership* is unaffected, so `declare` above still
-    // answers what pi-ai ships.
-    for (const provider of catalog) {
-        if (catalogProviderTakesApiKey(provider))
-            declare(provider, provider);
-    }
+    for (const provider of catalog)
+        declare(provider, provider);
     for (const [provider, profile] of profiles)
         declare(provider, profile.displayName);
     return [...entries.values()];
@@ -171,15 +162,26 @@ export function apply(ctx, config) {
             + ` set — store ${ref} through the credentials service (the web Models page writes it) or export it,`
             + ' and remove apiKeyEnv only if this provider should authenticate from pi-ai\'s own environment discovery', 'MISSING_CREDENTIAL');
     };
+    // One store and one ambient context for the whole plugin instance: both read
+    // through `ctx` per call, so they stay correct across the collection rebuilds
+    // a configuration change causes, and a sign-in survives one.
+    const auth = { credentials: credentialStoreFrom(ctx), authContext: authContextFrom(ctx) };
     const adapter = new PiAiAdapter({
         profiles,
         resolveApiKey,
+        auth,
         resolveAttachments: () => ctx.get('attachments'),
         onReplayDegrade: ({ provider, model, reason }) => {
             ctx.logger.warn(`llm-pi-ai: unusable replay state on assistant history for route "${provider}/${model}";`
                 + ` sending that message as provider-neutral content (${reason})`);
         },
     });
+    // Independent of the route set: signing in is what makes a route worth
+    // adding, so the flows are offered before any profile names their provider.
+    // Scoped to the authorization seam rather than injected outright, because a
+    // composition without it (headless, ACP) simply has no surface to sign in
+    // from, while everything else this plugin does still works.
+    ctx.inject(['authorization'], (authorized) => { registerPiAiFlows(authorized, auth); });
     // The full installed catalog is configurable from the moment the plugin
     // mounts — dormant or not — so configuration surfaces can offer every
     // pi-ai provider before any route exists. Hand-declared routes join it as

package/dist/kernel/llm-pi-ai/lib/types/invariant.d.ts

@@ -2,7 +2,7 @@
  * Package-owned invariant companion for `@nomix-ai/nomix-llm-pi-ai`.
  * @module @nomix-ai/nomix-llm-pi-ai/invariant
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "llm-pi-ai-invariant";
 /** Service required before the companion can reserve package ownership. */

package/dist/kernel/llm-pi-ai/lib/types/login.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Authorization flows for the pi-ai providers that ship a login. This is the
+ * whole of the translation between the harness's neutral notice/prompt
+ * vocabulary and pi-ai's `AuthInteraction`; nothing above it knows which
+ * library ran the conversation.
+ *
+ * @module nomix-llm-pi-ai/login
+ */
+import type { Context } from '../../../cordis/lib/index.js';
+import type { PiAiAuthInjection } from './adapter.ts';
+/**
+ * Register one authorization flow per installed provider that ships a login.
+ *
+ * Registration is unconditional on configuration: a provider has to be signed
+ * into before a route for it is worth adding, so the flow exists from the
+ * moment the plugin mounts rather than appearing once a profile does.
+ * @param ctx - the plugin context carrying `ctx.authorization`.
+ * @param auth - the injectables every collection here is built with.
+ */
+export declare function registerPiAiFlows(ctx: Context, auth: PiAiAuthInjection): void;
+//# sourceMappingURL=login.d.ts.map

package/dist/kernel/llm-pi-ai/lib/types/login.js

@@ -0,0 +1,154 @@
+/**
+ * Authorization flows for the pi-ai providers that ship a login. This is the
+ * whole of the translation between the harness's neutral notice/prompt
+ * vocabulary and pi-ai's `AuthInteraction`; nothing above it knows which
+ * library ran the conversation.
+ *
+ * @module nomix-llm-pi-ai/login
+ */
+import { createModels } from '@earendil-works/pi-ai';
+import { isCredentialKeySegment } from '../../../credentials/lib/index.js';
+import { catalogProvider, catalogProviderIds } from "./catalog.js";
+import { recordKeyFor } from "./auth.js";
+/**
+ * The login methods one catalog provider offers.
+ *
+ * A method appears only when pi-ai can actually run it: `oauth` always carries
+ * a `login`, while an api-key method has one only when the provider collects
+ * its key interactively — which every installed one currently does, so a key is
+ * typed into pi-ai's own prompt rather than into the settings form.
+ * @param provider - the installed catalog provider, if pi-ai ships one.
+ * @returns its methods, most preferred first; empty when it offers no login.
+ */
+function loginMethods(provider) {
+    const methods = [];
+    const oauth = provider?.auth.oauth;
+    if (oauth !== undefined)
+        methods.push({ id: 'oauth', label: oauth.loginLabel ?? oauth.name });
+    const apiKey = provider?.auth.apiKey;
+    if (apiKey?.login !== undefined)
+        methods.push({ id: 'api-key', label: apiKey.name });
+    return methods;
+}
+/**
+ * Restate one pi-ai login event in the seam's vocabulary.
+ *
+ * A device-code grant is the one event carrying two things the human needs at
+ * once — where to go and what to type there — which is why the neutral notice
+ * has a `code` beside its `url` rather than folding the code into the message.
+ * @param event - what pi-ai reported.
+ * @param session - the attempt to report it to.
+ */
+function relay(event, session) {
+    switch (event.type) {
+        case 'info': {
+            const link = event.links?.[0];
+            session.notify({ message: event.message, ...link === undefined ? {} : { url: link.url } });
+            return;
+        }
+        case 'auth_url':
+            session.notify({
+                message: event.instructions ?? 'Open this page to continue signing in.',
+                url: event.url,
+            });
+            return;
+        case 'device_code':
+            session.notify({
+                message: 'Enter this code on the verification page to finish signing in.',
+                url: event.verificationUri,
+                code: event.userCode,
+            });
+            return;
+        case 'progress':
+            session.notify({ message: event.message });
+            return;
+        default:
+            // pi-ai's event union is open to new members: a build that meets one it
+            // does not know still shows the human that something is happening rather
+            // than going silent mid-login.
+            session.notify({ message: 'Signing in…' });
+    }
+}
+/**
+ * Restate one pi-ai prompt in the seam's vocabulary.
+ *
+ * `manual_code` becomes a plain text question because the difference pi-ai
+ * draws — a code the human copies from a browser rather than a value they know
+ * — changes nothing a surface renders. Its own `signal` is carried through, and
+ * that is the part which matters: it is how a flow racing a typed code against
+ * a browser callback withdraws the losing question.
+ * @param prompt - what pi-ai asked.
+ * @returns the neutral prompt to put to the human.
+ */
+function restate(prompt) {
+    const signal = prompt.signal === undefined ? {} : { signal: prompt.signal };
+    switch (prompt.type) {
+        case 'select':
+            return { ...signal, kind: 'select', message: prompt.message, options: prompt.options };
+        case 'secret':
+            return {
+                ...signal,
+                kind: 'secret',
+                message: prompt.message,
+                ...prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder },
+            };
+        default:
+            return {
+                ...signal,
+                kind: 'text',
+                message: prompt.message,
+                ...prompt.placeholder === undefined ? {} : { placeholder: prompt.placeholder },
+            };
+    }
+}
+/**
+ * Register one authorization flow per installed provider that ships a login.
+ *
+ * Registration is unconditional on configuration: a provider has to be signed
+ * into before a route for it is worth adding, so the flow exists from the
+ * moment the plugin mounts rather than appearing once a profile does.
+ * @param ctx - the plugin context carrying `ctx.authorization`.
+ * @param auth - the injectables every collection here is built with.
+ */
+export function registerPiAiFlows(ctx, auth) {
+    for (const providerId of catalogProviderIds()) {
+        const provider = catalogProvider(providerId);
+        const [first, ...rest] = loginMethods(provider);
+        /* v8 ignore next 3 -- every id here names an installed provider and every
+           installed provider ships a login, so nothing is skipped today; the guard
+           is what keeps that from becoming a crash if either stops being true. */
+        if (provider === undefined || first === undefined)
+            continue;
+        /* v8 ignore next 7 -- every installed catalog id today is a lowercase
+           hyphenated identifier; the guard keeps a future upstream id outside the
+           record grammar (dotted or uppercase, as vendor ids elsewhere already
+           are) from throwing in `recordKeyFor` and failing the whole mount. */
+        if (!isCredentialKeySegment(providerId)) {
+            ctx.logger.warn('llm-pi-ai: catalog provider "%s" cannot address a credential record; its sign-in is not offered', providerId);
+            continue;
+        }
+        ctx.authorization.registerFlow({
+            key: recordKeyFor(providerId),
+            label: provider.name,
+            methods: [first, ...rest],
+            async run(session) {
+                // A collection of its own, holding only the provider being signed
+                // into: login is not serving requests, and the credential it produces
+                // lands in the shared store either way.
+                const models = createModels(auth);
+                models.setProvider(provider);
+                // Total over the two ids declared above, and the seam only ever hands
+                // back one a flow declared.
+                const type = session.method === 'oauth' ? 'oauth' : 'api_key';
+                // pi-ai persists what the login returns through that same store, which
+                // is what makes it the single writer of this record.
+                await models.login(providerId, type, {
+                    signal: session.signal,
+                    notify: (event) => { relay(event, session); },
+                    prompt: prompt => session.prompt(restate(prompt)),
+                });
+            },
+        });
+    }
+}
+//# sourceMappingURL=login.js.map

package/dist/kernel/llm-pi-ai/lib/types/stream.js

@@ -38,6 +38,10 @@ function classifyPiAiError(message) {
         return QUOTA_EXCEEDED_CODE;
     if (/\b429\b|rate.?limit/i.test(message))
         return 'RATE_LIMIT';
+    // A rejected request body (gateway or provider size cap): resending the
+    // same request cannot succeed, so it is invalid, not transient.
+    if (/\b413\b|failed to buffer the request body:\s*length limit exceeded|payload too large|request body too large/i.test(message))
+        return 'INVALID_REQUEST';
     if (/\b400\b|invalid.?request/i.test(message))
         return 'INVALID_REQUEST';
     if (/\b5\d\d\b/.test(message))