@nomix-ai/nomix-harness 0.2.5 → 0.2.6

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

@@ -13,15 +13,21 @@
  * way down: switching models mid-reply takes effect on the next step, never
  * inside the one in flight.
  *
- * Credentials stay outside that collection. The harness resolves a route's key
- * through its own seam and passes it as the request's `apiKey` option, which
- * pi-ai treats as the highest-priority auth override — so `Models` never holds
- * a credential store and the harness keeps its fail-loud reference semantics.
+ * A route naming a credential reference still resolves it through the harness
+ * seam and passes it as the request's `apiKey` option, which pi-ai treats as
+ * the highest-priority auth override — that is what keeps the fail-loud
+ * reference semantics. Everything that override does not cover reaches pi-ai
+ * through the collection's own auth: the credential store holds the records a
+ * login wrote and a refresh rotates, and the auth context answers the ambient
+ * questions a provider asks while resolving. Both are stable across snapshots,
+ * so a configuration change rebuilds the collection without forgetting who is
+ * signed in.
  *
  * @module nomix-llm-pi-ai/adapter
  */
+import type { AuthContext, CredentialStore } from '@earendil-works/pi-ai';
 import { LlmAdapter } from '../../../llm/lib/index.js';
-import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from '../../../llm/lib/index.js';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, ResolvedRetryPolicy, StreamChunk } from '../../../llm/lib/index.js';
 import type { AttachmentStore } from '../../../attachment/lib/index.js';
 import type { ResolvedPiAiProviderProfile } from './config.ts';
 /** Constructor options for {@link PiAiAdapter}: the two resolution hooks the plugin owns. */
@@ -37,6 +43,15 @@ export interface PiAiAdapterOptions {
      * `MISSING_CREDENTIAL` rather than falling back.
      */
     resolveApiKey: (provider: string, profile: ResolvedPiAiProviderProfile) => Promise<string | undefined>;
+    /**
+     * How every collection this adapter builds resolves auth the request-level
+     * `apiKey` override does not cover. Required rather than optional: a
+     * collection built without them gets pi-ai's in-memory default store, which
+     * is empty at every boot and discarded on every configuration change, so a
+     * route whose only method is a login would report itself unconfigured on
+     * every request no matter how often the human signed in.
+     */
+    auth: PiAiAuthInjection;
     /** Resolve the optional durable attachment service at request time. */
     resolveAttachments?: () => AttachmentStore | undefined;
     /**
@@ -49,6 +64,13 @@ export interface PiAiAdapterOptions {
         reason: string;
     }) => void;
 }
+/** The two auth injectables a pi-ai collection is built with. */
+export interface PiAiAuthInjection {
+    /** Durable storage for credentials pi-ai itself writes: logins, and the refreshes it runs under its own lock. */
+    credentials: CredentialStore;
+    /** Ambient lookups a provider performs while resolving its own auth. */
+    authContext: AuthContext;
+}
 /**
  * pi-ai-backed multi-provider adapter. Each operation reads the current
  * profiles, so a configuration change reaches the next request without a
@@ -73,6 +95,9 @@ export declare class PiAiAdapter extends LlmAdapter {
     providerRetryPolicy(provider: string): ResolvedRetryPolicy | undefined;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
     resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    private modelInfo;
+    prepareCall(provider: string, model: string, _signal?: AbortSignal): Promise<PreparedAdapterCall>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private streamWithSnapshot;
 }
 //# sourceMappingURL=adapter.d.ts.map

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

@@ -13,10 +13,15 @@
  * way down: switching models mid-reply takes effect on the next step, never
  * inside the one in flight.
  *
- * Credentials stay outside that collection. The harness resolves a route's key
- * through its own seam and passes it as the request's `apiKey` option, which
- * pi-ai treats as the highest-priority auth override — so `Models` never holds
- * a credential store and the harness keeps its fail-loud reference semantics.
+ * A route naming a credential reference still resolves it through the harness
+ * seam and passes it as the request's `apiKey` option, which pi-ai treats as
+ * the highest-priority auth override — that is what keeps the fail-loud
+ * reference semantics. Everything that override does not cover reaches pi-ai
+ * through the collection's own auth: the credential store holds the records a
+ * login wrote and a refresh rotates, and the auth context answers the ambient
+ * questions a provider asks while resolving. Both are stable across snapshots,
+ * so a configuration change rebuilds the collection without forgetting who is
+ * signed in.
  *
  * @module nomix-llm-pi-ai/adapter
  */
@@ -182,7 +187,7 @@ export class PiAiAdapter extends LlmAdapter {
         const profiles = this.config.profiles();
         if (this.snapshot?.profiles === profiles)
             return this.snapshot;
-        const models = createModels();
+        const models = createModels(this.config.auth);
         for (const profile of profiles.values())
             models.setProvider(profile.piProvider);
         this.snapshot = { profiles, models };
@@ -229,24 +234,37 @@ export class PiAiAdapter extends LlmAdapter {
     resolveModel(provider, model, _signal) {
         return Promise.resolve().then(() => {
             const snapshot = this.current();
-            const profile = this.profileOf(snapshot, provider);
-            const resolvedModel = this.modelOf(snapshot, provider, model);
-            const defaultLevel = describableReasoningLevel(resolvedModel, profile.reasoning);
-            // Only a cap the deployment configured is a request default; the
-            // catalog's `maxTokens` sizes the model and stops there.
-            const configuredMaxTokens = profile.configuredMaxTokens.get(model);
-            return {
-                provider,
-                id: model,
-                name: resolvedModel.name,
-                inputModalities: [...resolvedModel.input],
-                context: { contextWindow: resolvedModel.contextWindow },
-                ...configuredMaxTokens === undefined ? {} : { defaultMaxTokens: configuredMaxTokens },
-                ...reasoningInfo(resolvedModel, defaultLevel),
-            };
+            return this.modelInfo(snapshot, provider, model);
+        });
+    }
+    modelInfo(snapshot, provider, model) {
+        const profile = this.profileOf(snapshot, provider);
+        const resolvedModel = this.modelOf(snapshot, provider, model);
+        const defaultLevel = describableReasoningLevel(resolvedModel, profile.reasoning);
+        // Only a cap the deployment configured is a request default; the
+        // catalog's `maxTokens` sizes the model and stops there.
+        const configuredMaxTokens = profile.configuredMaxTokens.get(model);
+        return {
+            provider,
+            id: model,
+            name: resolvedModel.name,
+            inputModalities: [...resolvedModel.input],
+            context: { contextWindow: resolvedModel.contextWindow },
+            ...configuredMaxTokens === undefined ? {} : { defaultMaxTokens: configuredMaxTokens },
+            ...reasoningInfo(resolvedModel, defaultLevel),
+        };
+    }
+    prepareCall(provider, model, _signal) {
+        const snapshot = this.current();
+        return Promise.resolve({
+            model: this.modelInfo(snapshot, provider, model),
+            stream: options => this.streamWithSnapshot(options, snapshot),
         });
     }
-    async *stream(options) {
+    stream(options) {
+        return this.streamWithSnapshot(options, this.current());
+    }
+    async *streamWithSnapshot(options, snapshot) {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
             if (options.stop !== undefined) {
@@ -257,7 +275,6 @@ export class PiAiAdapter extends LlmAdapter {
             // snapshot, and the credential freezes with them. A configuration change
             // mid-request builds a separate snapshot, so this request finishes under
             // the one it started with and the next call picks up the new one.
-            const snapshot = this.current();
             const profile = this.profileOf(snapshot, options.provider);
             const model = this.modelOf(snapshot, options.provider, options.model);
             const reasoning = resolveReasoningLevel(model, options.reasoningEffort ?? profile.reasoning);
@@ -282,7 +299,10 @@ export class PiAiAdapter extends LlmAdapter {
                 };
                 const context = attachments === undefined
                     ? toPiContext(options, undefined, onReplayDegrade)
-                    : await toPiContext(options, attachments, onReplayDegrade);
+                    : await toPiContext({ ...options, signal: watchdog.signal }, attachments, onReplayDegrade, profile.maxRequestImageBytes, {
+                        maxPixels: profile.requestImagePixelBudget,
+                        maxBytes: profile.requestImageMaxBytes,
+                    });
                 const events = snapshot.models.streamSimple(model, context, {
                     ...profileOptions(profile, reasoning, apiKey),
                     ...options.temperature === undefined ? {} : { temperature: options.temperature },

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

@@ -0,0 +1,60 @@
+/**
+ * The three adapters between pi-ai's auth model and the harness credential
+ * plane. Every pi-ai-specific concept stays on this side of them: the harness
+ * seams they consume — `ctx.credentials` records and `ctx.authorization` flows —
+ * name nothing from this library, so another adapter family can arrive with a
+ * different auth model and share the same two seams.
+ *
+ * @module nomix-llm-pi-ai/auth
+ */
+import type { AuthContext, CredentialStore } from '@earendil-works/pi-ai';
+import type { Context } from '../../../cordis/lib/index.js';
+import type { CredentialKey } from '../../../credentials/lib/index.js';
+/**
+ * The record scope every credential this adapter family stores is written
+ * under. It is the plugin's registered name, which is what tells a later
+ * reader — a configuration UI, or a second adapter family serving the same
+ * provider name — that this plugin owns the format inside the record.
+ */
+export declare const RECORD_SCOPE = "llm-pi-ai";
+/**
+ * The record address for one pi-ai provider id.
+ * @param providerId - pi-ai's own provider id, which is also the harness route key.
+ * @returns the scoped credential key this adapter family reads and writes.
+ */
+export declare function recordKeyFor(providerId: string): CredentialKey;
+/**
+ * A pi-ai `CredentialStore` over the harness credential records.
+ *
+ * pi-ai runs OAuth refresh *inside* `modify()`, so this store's exclusion has
+ * to cover a network round trip rather than a file rename — which is why the
+ * record write path takes a wait limit of its own rather than the short one a
+ * local write would need.
+ *
+ * pi-ai asks this store about every provider in the collection, hand-declared
+ * routes included, and a route key is an arbitrary settings dict key while a
+ * record id is not. An id outside the record grammar can never have stored a
+ * record, so reads answer "nothing stored" and a delete has nothing to remove;
+ * only `modify` refuses it, because a write that cannot land must not report
+ * that it did.
+ * @param ctx - the plugin context carrying the optional `ctx.credentials`.
+ * @returns the store to hand `createModels()`.
+ */
+export declare function credentialStoreFrom(ctx: Context): CredentialStore;
+/**
+ * A pi-ai `AuthContext` over the harness credential plane and the host
+ * filesystem.
+ *
+ * `env()` answers from the credential seam first, so a value a deployment
+ * stored through the harness is found by a provider's own ambient discovery —
+ * without this, that discovery reads only the process environment and a stored
+ * `AWS_ACCESS_KEY_ID` is invisible to it. `fileExists()` answers about the host
+ * process's own filesystem rather than the workspace `ctx.fs` seam, because the
+ * paths it is asked about (`~/.aws/credentials`, application-default
+ * credentials) are facts about where this process runs, not about the project
+ * under edit.
+ * @param ctx - the plugin context carrying the optional `ctx.credentials`.
+ * @returns the auth context to hand `createModels()`.
+ */
+export declare function authContextFrom(ctx: Context): AuthContext;
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1,196 @@
+/**
+ * The three adapters between pi-ai's auth model and the harness credential
+ * plane. Every pi-ai-specific concept stays on this side of them: the harness
+ * seams they consume — `ctx.credentials` records and `ctx.authorization` flows —
+ * name nothing from this library, so another adapter family can arrive with a
+ * different auth model and share the same two seams.
+ *
+ * @module nomix-llm-pi-ai/auth
+ */
+import { homedir } from 'node:os';
+import { access } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
+import { credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName, } from '../../../credentials/lib/index.js';
+import { launchEnvironmentOf } from '../../../launch-environment/lib/index.js';
+import { LlmError } from '../../../llm/lib/index.js';
+/**
+ * The record scope every credential this adapter family stores is written
+ * under. It is the plugin's registered name, which is what tells a later
+ * reader — a configuration UI, or a second adapter family serving the same
+ * provider name — that this plugin owns the format inside the record.
+ */
+export const RECORD_SCOPE = 'llm-pi-ai';
+/**
+ * The record address for one pi-ai provider id.
+ * @param providerId - pi-ai's own provider id, which is also the harness route key.
+ * @returns the scoped credential key this adapter family reads and writes.
+ */
+export function recordKeyFor(providerId) {
+    return credentialKey(RECORD_SCOPE, providerId);
+}
+/**
+ * Translate a stored record into the credential pi-ai expects.
+ *
+ * An `api-key` record is structural on both sides, so it is rebuilt field by
+ * field. A `grant` payload is pi-ai's own OAuth credential, stored verbatim:
+ * the seam treats it as opaque JSON precisely so a library that owns a token
+ * format keeps owning it, refresh fields and all.
+ * @param record - the stored record, or undefined when nothing is stored.
+ * @returns the pi-ai credential, or undefined for an absent record.
+ */
+function toPiCredential(record) {
+    if (record === undefined)
+        return undefined;
+    if (record.kind === 'api-key') {
+        return {
+            type: 'api_key',
+            ...record.key === undefined ? {} : { key: record.key },
+            ...record.env === undefined ? {} : { env: { ...record.env } },
+        };
+    }
+    return record.payload;
+}
+/**
+ * Translate a pi-ai credential into the record to store.
+ * @param credential - what a login or refresh produced.
+ * @returns the record to commit, in the union the credential seam stores.
+ */
+function toRecord(credential) {
+    if (credential.type === 'api_key') {
+        return {
+            kind: 'api-key',
+            ...credential.key === undefined ? {} : { key: credential.key },
+            ...credential.env === undefined ? {} : { env: { ...credential.env } },
+        };
+    }
+    return { kind: 'grant', payload: credential };
+}
+/**
+ * The credential service, or the failure that names what is missing. Reads
+ * answer "nothing stored" without a service, because a composition with no
+ * credential plane genuinely holds no credential; writes refuse, because a
+ * login whose grant silently evaporated would report success and then fail
+ * every request.
+ * @param ctx - the plugin context.
+ * @returns the live service.
+ * @throws {LlmError} code `NO_CREDENTIAL_STORE` when none is mounted.
+ */
+function writableStore(ctx) {
+    const credentials = ctx.get('credentials');
+    if (credentials === undefined) {
+        throw new LlmError('llm-pi-ai: this composition mounts no credentials service, so there is nowhere to store the'
+            + ' credential a sign-in produces; mount one (nomix-credentials-local) to sign in', 'NO_CREDENTIAL_STORE');
+    }
+    return credentials;
+}
+/**
+ * A pi-ai `CredentialStore` over the harness credential records.
+ *
+ * pi-ai runs OAuth refresh *inside* `modify()`, so this store's exclusion has
+ * to cover a network round trip rather than a file rename — which is why the
+ * record write path takes a wait limit of its own rather than the short one a
+ * local write would need.
+ *
+ * pi-ai asks this store about every provider in the collection, hand-declared
+ * routes included, and a route key is an arbitrary settings dict key while a
+ * record id is not. An id outside the record grammar can never have stored a
+ * record, so reads answer "nothing stored" and a delete has nothing to remove;
+ * only `modify` refuses it, because a write that cannot land must not report
+ * that it did.
+ * @param ctx - the plugin context carrying the optional `ctx.credentials`.
+ * @returns the store to hand `createModels()`.
+ */
+export function credentialStoreFrom(ctx) {
+    return {
+        async read(providerId) {
+            const credentials = ctx.get('credentials');
+            if (credentials === undefined)
+                return undefined;
+            if (!isCredentialKeySegment(providerId))
+                return undefined;
+            return toPiCredential(await credentials.readRecord(recordKeyFor(providerId)));
+        },
+        async list() {
+            const stored = await ctx.get('credentials')?.listRecords() ?? [];
+            const mine = [];
+            for (const entry of stored) {
+                // Records another plugin owns are not this collection's to report:
+                // their payloads are written in a format pi-ai never agreed to.
+                if (credentialKeyScope(entry.key) !== RECORD_SCOPE)
+                    continue;
+                mine.push({
+                    providerId: credentialKeyId(entry.key),
+                    type: entry.kind === 'api-key' ? 'api_key' : 'oauth',
+                });
+            }
+            return mine;
+        },
+        async modify(providerId, mutate) {
+            if (!isCredentialKeySegment(providerId)) {
+                throw new LlmError(`llm-pi-ai: provider id "${providerId}" cannot address a stored credential record (a record id is a`
+                    + ' lowercase hyphenated identifier); authenticate this route through apiKeyEnv instead of a stored'
+                    + ' credential', 'UNSTORABLE_PROVIDER_ID');
+            }
+            const stored = await writableStore(ctx).modifyRecord(recordKeyFor(providerId), async (current) => {
+                const next = await mutate(toPiCredential(current));
+                return next === undefined ? undefined : toRecord(next);
+            });
+            return toPiCredential(stored);
+        },
+        // `async` so a missing service reaches the caller as a rejection: pi-ai's
+        // store contract is promise-returning, and a synchronous throw would
+        // escape the `ModelsError` wrapper every other storage failure gets.
+        async delete(providerId) {
+            if (!isCredentialKeySegment(providerId))
+                return;
+            await writableStore(ctx).deleteRecord(recordKeyFor(providerId));
+        },
+    };
+}
+/**
+ * A pi-ai `AuthContext` over the harness credential plane and the host
+ * filesystem.
+ *
+ * `env()` answers from the credential seam first, so a value a deployment
+ * stored through the harness is found by a provider's own ambient discovery —
+ * without this, that discovery reads only the process environment and a stored
+ * `AWS_ACCESS_KEY_ID` is invisible to it. `fileExists()` answers about the host
+ * process's own filesystem rather than the workspace `ctx.fs` seam, because the
+ * paths it is asked about (`~/.aws/credentials`, application-default
+ * credentials) are facts about where this process runs, not about the project
+ * under edit.
+ * @param ctx - the plugin context carrying the optional `ctx.credentials`.
+ * @returns the auth context to hand `createModels()`.
+ */
+export function authContextFrom(ctx) {
+    return {
+        async env(name) {
+            // pi-ai asks about arbitrary provider-declared names; one that is not a
+            // POSIX identifier can never have been stored as a reference, and asking
+            // the seam would throw instead of answering "not set".
+            if (isCredentialRefName(name)) {
+                const credentials = ctx.get('credentials');
+                const hit = await credentials?.resolve(credentialRef(name));
+                if (hit !== undefined)
+                    return hit.value;
+            }
+            return launchEnvironmentOf(ctx).get(name)?.value;
+        },
+        async fileExists(path) {
+            const expanded = path.startsWith('~/') || path === '~'
+                ? resolvePath(homedir(), path.slice(1).replace(/^\//, ''))
+                : path;
+            try {
+                await access(expanded);
+                return true;
+            }
+            catch {
+                // Absent, unreadable, or a broken symlink — every one of which means
+                // this ambient credential source cannot be used, which is the only
+                // distinction the caller makes.
+                return false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=auth.js.map