@parcha/agentrun-pi 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/host-addendum.d.ts

@@ -0,0 +1,4 @@
+import { type AuthorHostAddendum } from '@parcha/agentrun-dsl';
+/** What this extension adds to the shared workflow language: its commands, tools and unavailable transports.
+ *  The packaged skill is rendered with it, and `describe` returns it as `authoring.host`. */
+export declare const PI_HOST_ADDENDUM: AuthorHostAddendum;

package/dist/host-addendum.js

@@ -0,0 +1,20 @@
+import { WORKFLOW_NODE_KINDS } from '@parcha/agentrun-dsl';
+/** What this extension adds to the shared workflow language: its commands, tools and unavailable transports.
+ *  The packaged skill is rendered with it, and `describe` returns it as `authoring.host`. */
+export const PI_HOST_ADDENDUM = Object.freeze({
+    name: 'Pi extension',
+    nodeKinds: WORKFLOW_NODE_KINDS.filter(kind => kind !== 'artifact'),
+    rules: [
+        'Call agentrun with action describe first, then inspect the complete workflow with its input, then dry-run it (action dry-run, without a workflow argument), then run without a workflow argument.',
+        'A dry run runs the inspected workflow on synthetic values, or the input you give it, with no model, Jev or tool call. Its status is passed, not_run (a check could not run; skipped says why, and it proves nothing) or failed (problems say why). Report not_run as not run, never as passed.',
+        'Use exactly the tools describe returns. Without host-configured tools these are the active read-only built-ins (read, grep, find, ls), and bash, edit and write exist only in a trusted run; a host that configures its tools offers only those, including in trusted runs. The search tool reads fictional demo sources only.',
+        'Code nodes and mutating tools run only after the user issues /agentrun run --trusted for that run. Trusted execution is local and unsandboxed. A dry run of a workflow with code nodes is not_run until the user issues /agentrun dry-run --trusted.',
+        'A call uses via tool with a tool describe returns. Shell and executor calls and artifact delivery are unavailable.',
+        'This extension supplies no SOP text: do not run a workflow with sopSection here; it needs an SDK host that supplies the authoritative SOP.',
+        'Custom extension tools and outer permission hooks are not inherited, including in trusted runs.',
+        'A preview, procedure edit or input change does not authorize execution: inspect it, report Inspected — not run, and execute only when requested.',
+        'Use /agentrun to inspect the current graph, /agentrun input to change input, /agentrun save and /agentrun load for named definition revisions, /agentrun history for retained receipts, /agentrun run to restart, and /agentrun stop to request cancellation; closing the inspector does not stop a run.',
+        'Saving retains the definition without input or execution permission; loading rechecks current host capabilities and never resumes an interrupted run.',
+        'The structural limits describe returns bound node count, map concurrency and parallel branches.',
+    ],
+});

package/dist/host-session.js

@@ -1,5 +1,6 @@
 import { Agent } from '@earendil-works/pi-agent-core';
 import { createPiRunner } from './runner.js';
+import { workflowToolContext } from './tool-context.js';
 export const PI_MODEL_SETUP_MESSAGE = 'AgentRun requires an active Pi model. Use /login to connect a provider, then /model to select it. Try /agentrun demo without model access.';
 function selectedModel(context) {
     const model = context.model;
@@ -16,6 +17,7 @@ function selectedModel(context) {
 export function createPiHostSessionFactory(context) {
     const model = selectedModel(context);
     const stream = context.modelRegistry.streamSimple.bind(context.modelRegistry);
+    const toolContext = workflowToolContext(context);
     return async (options) => {
         if (options.model !== model)
             throw new Error('The child session must use the captured active Pi model');
@@ -25,7 +27,7 @@ export function createPiHostSessionFactory(context) {
             name: tool.name, label: tool.label, description: tool.description,
             parameters: tool.parameters,
             async execute(id, args, signal, onUpdate) {
-                const result = await tool.execute(id, args, signal, onUpdate, context);
+                const result = await tool.execute(id, args, signal, onUpdate, toolContext);
                 if (tool.name === 'submit' && result.details?.accepted === true)
                     delivered = true;
                 return result;
@@ -72,9 +74,10 @@ export function createPiHostSessionFactory(context) {
 }
 export function createPiHostRunner(context, options = {}) {
     const model = selectedModel(context);
+    // The host session's thinking level is not a node's: a node that names none thinks at medium, unless the caller
+    // passes its own `thinkingLevel`.
     return createPiRunner({
         ...options, model, cwd: options.cwd ?? context.cwd,
-        thinkingLevel: options.thinkingLevel ?? context.thinkingLevel,
         sessionFactory: createPiHostSessionFactory(context),
     });
 }

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./runner.js";
-export * from "./author.js";
 export * from "./types.js";
 export { createPiHostRunner, createPiHostSessionFactory } from './host-session.js';
 export { WorkflowExtensionService } from './extension-service.js';
-export { loadPiAuthorSkillBundle } from './skill-bundle.js';
+export { PI_HOST_ADDENDUM } from './host-addendum.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 export * from "./runner.js";
-export * from "./author.js";
 export * from "./types.js";
 export { createPiHostRunner, createPiHostSessionFactory } from './host-session.js';
 export { WorkflowExtensionService } from './extension-service.js';
-export { loadPiAuthorSkillBundle } from './skill-bundle.js';
+export { PI_HOST_ADDENDUM } from './host-addendum.js';

package/dist/pi-host.d.ts

@@ -0,0 +1,7 @@
+export declare const SUPPORTED_PI_RANGE: string;
+export declare const NEWEST_TESTED_PI_VERSION = "1.3.0";
+/** Whether Pi `version` is in the supported range. As npm reads the range, a prerelease is not; nor is a version that
+ *  is not `x.y.z`. */
+export declare function isSupportedPi(version: string): boolean;
+/** The status line for Pi host `version`: the supported range, and for a host outside it the newest tested one. */
+export declare function piHostLine(version: string): string;

package/dist/pi-host.js

@@ -0,0 +1,22 @@
+// The Pi hosts this release supports: the range of its pi-durable and chord peers. `/agentrun status` flags a host
+// outside it, without blocking it, and names the newest version CI runs (the `pi-1-2` job) as the one to install.
+const FLOOR = [1, 0, 4];
+const CEILING = [1, 4, 0];
+export const SUPPORTED_PI_RANGE = `>=${FLOOR.join(".")} <${CEILING.join(".")}`;
+export const NEWEST_TESTED_PI_VERSION = "1.3.0";
+const compare = (a, b) => (a[0] - b[0]) || (a[1] - b[1]) || (a[2] - b[2]);
+/** Whether Pi `version` is in the supported range. As npm reads the range, a prerelease is not; nor is a version that
+ *  is not `x.y.z`. */
+export function isSupportedPi(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (!match)
+        return false;
+    const parsed = match.slice(1).map(Number);
+    return compare(parsed, FLOOR) >= 0 && compare(parsed, CEILING) < 0;
+}
+/** The status line for Pi host `version`: the supported range, and for a host outside it the newest tested one. */
+export function piHostLine(version) {
+    return isSupportedPi(version)
+        ? `Pi host: ${version} (supported: ${SUPPORTED_PI_RANGE})`
+        : `Pi host: ${version} (outside the supported range ${SUPPORTED_PI_RANGE}; the newest tested host: npm install -g @earendil-works/pi-coding-agent@${NEWEST_TESTED_PI_VERSION})`;
+}

package/dist/presentation.js

@@ -12,7 +12,7 @@ function lines(value, depth = 0) {
         }).concat(value.length > 30 ? [`… ${value.length - 30} more items in the structured result`] : []);
     const entries = Object.entries(value);
     return entries.slice(0, 30).flatMap(([key, item]) => {
-        const label = key.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/_/g, ' ');
+        const label = key.replace(/([a-z])([A-Z])/g, (_, first, upper) => `${first} ${upper.toLowerCase()}`).replace(/_/g, ' ');
         const children = lines(item, depth + 1);
         return children.length === 1 ? [`${label}: ${children[0]}`] : [`${label}:`, ...children.map(line => `  ${line}`)];
     }).concat(entries.length > 30 ? [`… ${entries.length - 30} more fields in the structured result`] : []);
@@ -30,5 +30,5 @@ export function formatRunReport(report, scripted = false) {
     const trace = report.traceTruncated ? `\nTrace retention is partial${report.trace ? ` (${report.trace.droppedEvents} valid events omitted, ${report.trace.rejectedEvents} rejected)` : ''}; this does not mean the output is truncated.` : '';
     const clipped = body.length > 12_000 ? `${body.slice(0, 12_000)}\n… Full output is in the structured result.` : body;
     const status = report.status === 'escalated' ? 'stopped — needs attention (escalated)' : report.status;
-    return cleanText(`${scripted ? 'Scripted demo' : 'Workflow'}: ${status}${report.error ? ` (${report.error.code})` : ''}\n\n${clipped}${recovery}${uncertain}${trace}\n\nWorkflow calls: ${report.calls.tool} direct tool call${report.calls.tool === 1 ? '' : 's'}, ${report.calls.judge} system one decision${report.calls.judge === 1 ? '' : 's'}, ${report.calls.agent} model step${report.calls.agent === 1 ? '' : 's'}.${scripted ? '\nScripted responses; no model calls. Replay: /agentrun run. Real models: /agentrun demo live.' : ''}`);
+    return cleanText(`${scripted ? 'Scripted demo' : 'Workflow'}: ${status}${report.error ? ` (${report.error.code})` : ''}\n\n${clipped}${recovery}${uncertain}${trace}\n\nWorkflow calls: ${report.calls.tool} direct tool call${report.calls.tool === 1 ? '' : 's'}, ${report.calls.judge} system one decision${report.calls.judge === 1 ? '' : 's'}, ${report.calls.agent} model step${report.calls.agent === 1 ? '' : 's'}.${scripted ? '\nScripted responses; no model calls. Replay: /agentrun run. Example modes: /agentrun help.' : ''}`);
 }

package/dist/run-error.d.ts

@@ -0,0 +1,6 @@
+export declare class PiRunError extends Error {
+    readonly reason: "aborted" | "timeout" | "turn_limit" | "submission_limit" | "no_submission" | "model_error";
+    readonly turns: number;
+    readonly submissions: number;
+    constructor(reason: "aborted" | "timeout" | "turn_limit" | "submission_limit" | "no_submission" | "model_error", turns: number, submissions: number);
+}

package/dist/run-error.js

@@ -0,0 +1,13 @@
+// Kept apart from runner.ts so the workflow service loads without a pi package installed.
+export class PiRunError extends Error {
+    reason;
+    turns;
+    submissions;
+    constructor(reason, turns, submissions) {
+        super(`Pi node did not deliver an accepted submission: ${reason} (${turns} turns, ${submissions} submissions)`);
+        this.reason = reason;
+        this.turns = turns;
+        this.submissions = submissions;
+        this.name = "PiRunError";
+    }
+}

package/dist/runner.d.ts

@@ -3,10 +3,5 @@ import type { PiRunnerOptions } from "./types.js";
 export type { PiRunnerOptions, PiSession, PiSessionFactory } from "./types.js";
 export type PiRunner = NonNullable<WorkflowDeps["runNode"]>;
 export type PiNodeRequest = Parameters<PiRunner>[0];
-export declare class PiRunError extends Error {
-    readonly reason: "aborted" | "timeout" | "turn_limit" | "submission_limit" | "no_submission" | "model_error";
-    readonly turns: number;
-    readonly submissions: number;
-    constructor(reason: "aborted" | "timeout" | "turn_limit" | "submission_limit" | "no_submission" | "model_error", turns: number, submissions: number);
-}
+export { PiRunError } from "./run-error.js";
 export declare function createPiRunner(options: PiRunnerOptions): PiRunner;

package/dist/runner.js

@@ -1,17 +1,8 @@
 import { Compile } from "typebox/compile";
 import { createAgentSession, DefaultResourceLoader, SessionManager, SettingsManager, ModelRuntime, } from "@earendil-works/pi-coding-agent";
-export class PiRunError extends Error {
-    reason;
-    turns;
-    submissions;
-    constructor(reason, turns, submissions) {
-        super(`Pi node did not deliver an accepted submission: ${reason} (${turns} turns, ${submissions} submissions)`);
-        this.reason = reason;
-        this.turns = turns;
-        this.submissions = submissions;
-        this.name = "PiRunError";
-    }
-}
+import { PiRunError } from "./run-error.js";
+import { nodeThinking } from "./thinking.js";
+export { PiRunError } from "./run-error.js";
 function positive(value, name) {
     if (!Number.isSafeInteger(value) || value < 1)
         throw new Error(`${name} must be a positive integer`);
@@ -70,6 +61,9 @@ export function createPiRunner(options) {
         for (const name of requested)
             if (!names.has(name))
                 throw new Error(`Pi tool was not explicitly registered: ${name}`);
+        // Every Pi node starts a fresh session, so there is no caller transcript to fork.
+        if (request.context === "fork")
+            throw new Error(`Pi node "${request.label}" asks for context: "fork", but the Pi runner starts every node in a fresh session and has no caller transcript to fork. Declare context: "fresh", or run it on a host that supports fork.`);
         const validator = Compile(request.schema);
         const parameters = submitParameters(request.schema);
         const envelopeValidator = Compile(parameters);
@@ -166,7 +160,7 @@ export function createPiRunner(options) {
             const sessionManager = SessionManager.inMemory(cwd);
             const prepared = {
                 cwd, model: options.model, modelRuntime: options.modelRuntime,
-                thinkingLevel: request.thinking ?? options.thinkingLevel ?? "low", maxTurns: maxTurns ?? undefined, resourceLoader, settingsManager,
+                thinkingLevel: nodeThinking(request.thinking, options.thinkingLevel), maxTurns: maxTurns ?? undefined, resourceLoader, settingsManager,
                 sessionManager,
                 tools: [...requested, "submit"],
                 customTools: [...(options.tools ?? []).filter(tool => requested.includes(tool.name)).map(tool => ({

package/dist/signin/index.d.ts

@@ -0,0 +1,9 @@
+export { checkKeys, checkSetupPrompt, JEV_KEYS } from "./spec.js";
+export type { CheckOptions, Choice, DemoSpec, EyesNeed, Key, KeyReport, ModelNeed, Package, Platform, Program, ReportItem, RunMode, SetupPromptReport } from "./spec.js";
+export { AGENT_NAME, CHATGPT_PROVIDER, consoleInteraction, signIn, SignInError } from "./signin.js";
+export type { ConsoleIo, SignedIn, SignInOptions } from "./signin.js";
+export { CHATGPT_UNSUPPORTED, resolveModel, ResolveError } from "./resolve.js";
+export type { EyesModel, ResolvedModel, ResolveOptions } from "./resolve.js";
+export { USAGE_LIMIT_CODE, UsageLimitError, usageLimitError } from "./limit.js";
+export { agentrunHome, AuthStoreError, FileCredentialStore, fileCredentialStore } from "./store.js";
+export type { FileCredentialStoreOptions } from "./store.js";

package/dist/signin/index.js

@@ -0,0 +1,7 @@
+// Sign in, pick a model, check keys: the shared piece every demo runs first. The only entry of this package that
+// reaches pi-ai, an optional peer; every other entry stays free of it.
+export { checkKeys, checkSetupPrompt, JEV_KEYS } from "./spec.js";
+export { AGENT_NAME, CHATGPT_PROVIDER, consoleInteraction, signIn, SignInError } from "./signin.js";
+export { CHATGPT_UNSUPPORTED, resolveModel, ResolveError } from "./resolve.js";
+export { USAGE_LIMIT_CODE, UsageLimitError, usageLimitError } from "./limit.js";
+export { agentrunHome, AuthStoreError, FileCredentialStore, fileCredentialStore } from "./store.js";

package/dist/signin/limit.d.ts

@@ -0,0 +1,10 @@
+export declare const USAGE_LIMIT_CODE = "subscription_sharing_usage_limit_exceeded";
+export declare class UsageLimitError extends Error {
+    readonly code = "USAGE_LIMIT";
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+/** The typed limit error when `value` (an error, an assistant message from a failed request, or its text) is the plan's
+ *  usage limit; undefined otherwise. */
+export declare function usageLimitError(value: unknown): UsageLimitError | undefined;

package/dist/signin/limit.js

@@ -0,0 +1,23 @@
+// The ChatGPT plan's usage limit (five hours on Plus, shared with every other app the user signed in to). OpenAI answers
+// a request past it with 429 `subscription_sharing_usage_limit_exceeded`, at the start or mid-stream. It resets after
+// hours, not seconds, so it is never retried: pi-ai sends a request once by default and classes the code as not
+// retryable, and this maps it to one typed error.
+export const USAGE_LIMIT_CODE = "subscription_sharing_usage_limit_exceeded";
+export class UsageLimitError extends Error {
+    code = "USAGE_LIMIT";
+    constructor(options) {
+        super("Your ChatGPT plan's usage limit is reached; wait, or set a provider key.", options);
+        this.name = "UsageLimitError";
+    }
+}
+/** The typed limit error when `value` (an error, an assistant message from a failed request, or its text) is the plan's
+ *  usage limit; undefined otherwise. */
+export function usageLimitError(value) {
+    if (value instanceof UsageLimitError)
+        return value;
+    const text = typeof value === "string" ? value
+        : value instanceof Error ? value.message
+            : value && typeof value === "object" && "errorMessage" in value ? String(value.errorMessage ?? "")
+                : "";
+    return text.includes(USAGE_LIMIT_CODE) ? new UsageLimitError({ cause: value }) : undefined;
+}

package/dist/signin/resolve.d.ts

@@ -0,0 +1,47 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { type SignInOptions } from "./signin.js";
+import type { DemoSpec } from "./spec.js";
+/** What Sign in with ChatGPT covers: streaming Responses calls with `store: false`, without these. */
+export declare const CHATGPT_UNSUPPORTED: readonly string[];
+export type ResolveOptions = Omit<SignInOptions, "home"> & {
+    provider?: string;
+    model?: string;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+    /** An explicit eyes model (`--eyes-model`); `model` defaults to the spec's eyes default. */
+    eyes?: {
+        provider: string;
+        model?: string;
+    };
+    signal?: AbortSignal;
+};
+type Resolved = {
+    model: Model<Api>;
+    /** The key valid now. Not enumerable, and left out of `toJSON`. */
+    readonly apiKey: string;
+    /** A key valid at the time of the call: a sign-in's token is refreshed under the store's lock when it is near expiry. */
+    getApiKey(): Promise<string>;
+    /** Only streaming Responses calls with `store: false`, without `unsupported`. */
+    responsesOnly: boolean;
+    unsupported: readonly string[];
+    toJSON(): Record<string, unknown>;
+};
+export type ResolvedModel = Resolved & {
+    source: "flag" | "chatgpt";
+    limit?: string;
+    eyes?: EyesModel;
+};
+export type EyesModel = Resolved & {
+    source: "flag" | "lead";
+};
+export declare class ResolveError extends Error {
+    readonly code: "FLAGS" | "UNKNOWN_PROVIDER" | "UNKNOWN_MODEL" | "MISSING_KEY" | "NEEDS" | "EYES" | "NO_MODEL" | "MODEL_LIST" | "SIGNED_OUT";
+    constructor(code: "FLAGS" | "UNKNOWN_PROVIDER" | "UNKNOWN_MODEL" | "MISSING_KEY" | "NEEDS" | "EYES" | "NO_MODEL" | "MODEL_LIST" | "SIGNED_OUT", message: string);
+}
+/**
+ * The model this run uses and the key to send, in the order above. The eyes model, when the spec has one, resolves the
+ * same way: an explicit eyes model with its provider's key, else the lead's model when it meets the eyes' needs, else
+ * a `ResolveError` ("EYES") naming the gap. The ChatGPT plan takes no video input.
+ */
+export declare function resolveModel(spec: DemoSpec, options?: ResolveOptions): Promise<ResolvedModel>;
+export {};

package/dist/signin/resolve.js

@@ -0,0 +1,163 @@
+import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
+import { USAGE_LIMIT_CODE, UsageLimitError } from "./limit.js";
+import { CHATGPT_PROVIDER, chatgptModels, consoleInteraction, signIn } from "./signin.js";
+import { agentrunHome, fileCredentialStore } from "./store.js";
+/** What Sign in with ChatGPT covers: streaming Responses calls with `store: false`, without these. */
+export const CHATGPT_UNSUPPORTED = Object.freeze(["temperature", "max_output_tokens", "previous_response_id", "hosted tools", "audio input", "video input"]);
+export class ResolveError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ResolveError";
+    }
+}
+const meets = (model, need) => need === "images" ? model.input.includes("image") : need !== "video";
+function resolved(model, apiKey, getApiKey, source, extra = {}) {
+    const responsesOnly = source === "chatgpt" || extra.responsesOnly === true;
+    const result = { model, source, responsesOnly, unsupported: responsesOnly ? CHATGPT_UNSUPPORTED : [], ...extra };
+    Object.defineProperty(result, "apiKey", { value: apiKey, enumerable: false });
+    Object.defineProperty(result, "getApiKey", { value: getApiKey, enumerable: false });
+    Object.defineProperty(result, "toJSON", {
+        enumerable: false,
+        value: () => {
+            const { model: _model, ...rest } = result;
+            return { provider: model.provider, model: model.id, ...rest, ...(rest.eyes ? { eyes: rest.eyes.toJSON() } : {}) };
+        },
+    });
+    return result;
+}
+/** The env key of `provider` set in `env`, and the names it was looked up under. Anthropic takes an API key only. */
+async function providerKey(provider, env, signal) {
+    if (provider.id === "anthropic")
+        return { key: env.ANTHROPIC_API_KEY || undefined, names: ["ANTHROPIC_API_KEY"] };
+    const names = [];
+    const result = await provider.auth.apiKey?.resolve({
+        ctx: { env: async (name) => { names.push(name); return env[name] || undefined; }, fileExists: async () => false },
+        signal,
+    });
+    return { key: result?.auth.apiKey, names };
+}
+/** The account's models (GET /v1/models), those it lists as visible. */
+async function accountModels(baseUrl, apiKey, signal) {
+    const response = await fetch(`${baseUrl}/models`, { headers: { authorization: `Bearer ${apiKey}` }, signal });
+    if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        if (body.includes(USAGE_LIMIT_CODE))
+            throw new UsageLimitError();
+        throw new ResolveError("MODEL_LIST", `GET ${baseUrl}/models answered ${response.status}`);
+    }
+    const data = (await response.json()).data ?? [];
+    return data
+        .filter((entry) => typeof entry?.id === "string" && (entry.visibility === undefined || entry.visibility === "list"))
+        .map((entry) => ({ id: entry.id, created: typeof entry.created === "number" ? entry.created : 0 }));
+}
+/** The preferred id when it is listed and capable, else the newest listed model pi-ai knows that meets `needs`. */
+function choose(provider, listed, needs, preferred) {
+    const known = new Map(provider.getModels().map((model) => [model.id, model]));
+    const capable = listed
+        .flatMap((entry) => { const model = known.get(entry.id); return model && needs.every((need) => meets(model, need)) ? [{ model, created: entry.created }] : []; })
+        .sort((a, b) => b.created - a.created || a.model.id.localeCompare(b.model.id));
+    const pick = capable.find((entry) => entry.model.id === preferred) ?? capable[0];
+    if (!pick)
+        throw new ResolveError("NO_MODEL", `The account lists ${listed.length} models, and none is a ${provider.name} model pi-ai knows that takes ${needs.join(", ")}.`);
+    return pick.model;
+}
+async function flagModel(providerId, modelId, needs, preferred, env, signal, flag) {
+    const provider = builtinProviders().find((entry) => entry.id === providerId);
+    if (!provider)
+        throw new ResolveError("UNKNOWN_PROVIDER", `${flag} ${providerId}: pi-ai has no provider with that id`);
+    const { key, names } = await providerKey(provider, env, signal);
+    if (!key)
+        throw new ResolveError("MISSING_KEY", `${flag} ${providerId} needs ${names.join(" or ") || "its key"} set`);
+    // Video cannot be read from pi-ai's catalog: an explicit model is trusted to read it.
+    const checked = needs.filter((need) => need !== "video");
+    let model;
+    if (modelId) {
+        model = provider.getModels().find((entry) => entry.id === modelId);
+        if (!model)
+            throw new ResolveError("UNKNOWN_MODEL", `${provider.name} has no model ${modelId} in pi-ai's catalog`);
+        const gap = checked.filter((need) => !meets(model, need));
+        if (gap.length)
+            throw new ResolveError("NEEDS", `${provider.name} ${modelId} does not take ${gap.join(" or ")} input, which this run needs`);
+    }
+    else if (providerId === CHATGPT_PROVIDER && provider.baseUrl) {
+        model = choose(provider, await accountModels(provider.baseUrl, key, signal), checked, preferred);
+    }
+    else {
+        const fallback = preferred ? provider.getModels().find((entry) => entry.id === preferred) : undefined;
+        if (!fallback || !checked.every((need) => meets(fallback, need)))
+            throw new ResolveError("FLAGS", `${flag} ${providerId} needs a model id too`);
+        model = fallback;
+    }
+    return { model, key };
+}
+/**
+ * The model this run uses and the key to send, in the order above. The eyes model, when the spec has one, resolves the
+ * same way: an explicit eyes model with its provider's key, else the lead's model when it meets the eyes' needs, else
+ * a `ResolveError` ("EYES") naming the gap. The ChatGPT plan takes no video input.
+ */
+export async function resolveModel(spec, options = {}) {
+    const env = options.env ?? process.env;
+    const signal = options.signal ?? new AbortController().signal;
+    const needs = spec.models.lead.needs;
+    let lead;
+    if (options.provider || options.model) {
+        if (!options.provider)
+            throw new ResolveError("FLAGS", "--model needs --provider");
+        const { model, key } = await flagModel(options.provider, options.model, needs, spec.models.lead.default, env, signal, "--provider");
+        lead = resolved(model, key, async () => key, "flag");
+    }
+    else {
+        const home = agentrunHome(options.home, env);
+        const store = fileCredentialStore(home);
+        if ((await store.read(CHATGPT_PROVIDER, { signal }))?.type !== "oauth") {
+            // The run's signal reaches the sign-in through its interaction, so a cancel ends the login and frees its port.
+            const interaction = options.interaction ?? consoleInteraction();
+            // Its calls are forwarded, not spread: an interaction's notify and prompt may be methods of its class.
+            const cancelled = options.signal ? {
+                signal: interaction.signal ? AbortSignal.any([interaction.signal, options.signal]) : options.signal,
+                notify: (event) => interaction.notify(event),
+                prompt: (prompt) => interaction.prompt(prompt),
+            } : interaction;
+            try {
+                await signIn({ ...options, home, env, interaction: cancelled });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason;
+                throw error;
+            }
+        }
+        const models = chatgptModels(store);
+        const getApiKey = async () => {
+            const key = (await models.getAuth(CHATGPT_PROVIDER, { signal }))?.auth.apiKey;
+            if (!key)
+                throw new ResolveError("SIGNED_OUT", "The ChatGPT sign-in is gone from auth.json; sign in again");
+            return key;
+        };
+        const key = await getApiKey();
+        const provider = models.getProvider(CHATGPT_PROVIDER);
+        const model = choose(provider, await accountModels(provider.baseUrl, key, signal), needs, spec.models.lead.default);
+        lead = resolved(model, key, getApiKey, "chatgpt", {
+            limit: `Model calls count toward your ChatGPT plan's usage limit (five hours on Plus, shared with your other apps); this run expects about ${spec.expectedCalls}.`,
+        });
+    }
+    const eyes = spec.models.eyes;
+    if (!eyes)
+        return lead;
+    if (options.eyes) {
+        const { model, key } = await flagModel(options.eyes.provider, options.eyes.model ?? eyes.default, eyes.needs, eyes.default, env, signal, "--eyes-model");
+        lead.eyes = resolved(model, key, async () => key, "flag");
+        return lead;
+    }
+    const gap = eyes.needs.filter((need) => !meets(lead.model, need));
+    if (gap.length) {
+        const reasons = gap.map((need) => need === "images" ? `the lead model ${lead.model.id} takes no image input`
+            : lead.source === "chatgpt" ? "the ChatGPT plan takes no video input"
+                : `pi-ai's catalog lists no video input for ${lead.model.provider} ${lead.model.id}`);
+        throw new ResolveError("EYES", `The run's eyes need ${gap.join(" and ")} input: ${reasons.join("; ")}. Name a model that reads it with --eyes-model and set its provider's key${gap.includes("video") ? ", or list images and let frames be extracted locally" : ""}.`);
+    }
+    lead.eyes = resolved(lead.model, lead.apiKey, lead.getApiKey, "lead", { responsesOnly: lead.responsesOnly });
+    return lead;
+}

package/dist/signin/signin.d.ts

@@ -0,0 +1,44 @@
+import type { AuthInteraction, MutableModels } from "@earendil-works/pi-ai";
+import { type FileCredentialStore } from "./store.js";
+export declare const AGENT_NAME = "AgentRun";
+/** pi-ai's provider id for OpenAI, whose OAuth method is Sign in with ChatGPT. */
+export declare const CHATGPT_PROVIDER = "openai";
+export type SignInOptions = {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    /** The app name OpenAI shows on the consent screen. Default "AgentRun". */
+    agentName?: string;
+    /** How the sign-in talks to the user. Default: the terminal (`consoleInteraction`). */
+    interaction?: AuthInteraction;
+};
+export type SignedIn = {
+    home: string;
+    provider: typeof CHATGPT_PROVIDER;
+    hostId: string;
+    expires: number;
+};
+export declare class SignInError extends Error {
+    readonly code: "PORT_IN_USE" | "APP_NAME_IGNORED";
+    constructor(code: "PORT_IN_USE" | "APP_NAME_IGNORED", message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A pi-ai collection with only OpenAI, whose credentials live in `store`. */
+export declare function chatgptModels(store: FileCredentialStore): MutableModels;
+/**
+ * Sign in once per install; the token refreshes on its own afterwards. The sign-in page must name this app: pi-ai
+ * before 1.1 ignores `agentName` and names pi, so a page that names anything else is never shown, and the sign-in fails
+ * with `SignInError` ("APP_NAME_IGNORED") before the browser opens.
+ */
+export declare function signIn(options?: SignInOptions): Promise<SignedIn>;
+export type ConsoleIo = {
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output?: NodeJS.WritableStream;
+    /** Opens the sign-in page; default the platform's opener, skipped when AGENTRUN_NO_BROWSER is set. */
+    open?: (url: string) => void;
+};
+/** The terminal: prints the sign-in page's address and opens it, then waits for the browser's callback or, on a
+ *  terminal, a pasted redirect address. The page address carries no token. */
+export declare function consoleInteraction(io?: ConsoleIo): AuthInteraction;