@skelm/pi 0.4.1 → 0.4.3

package/README.md

@@ -1,6 +1,6 @@
 # @skelm/pi
 
-> Pi coding-agent backend for [skelm](https://github.com/scottgl9/skelm) — integrates [`@mariozechner/pi-coding-agent`](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) with full permission enforcement.
+> Pi coding-agent backend for [skelm](https://github.com/scottgl9/skelm) — integrates [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) with full permission enforcement.
 
 [![npm](https://img.shields.io/npm/v/@skelm/pi)](https://www.npmjs.com/package/@skelm/pi)
 
@@ -10,10 +10,10 @@ Two backends are available:
 
 | | `createPiBackend` (RPC) | `createPiSdkBackend` (SDK) |
 |---|---|---|
-| **How it works** | Spawns `pi --mode rpc` per call | Uses `@mariozechner/pi-coding-agent` SDK directly |
+| **How it works** | Spawns `pi --mode rpc` per call | Uses `@earendil-works/pi-coding-agent` SDK directly |
 | **Tool enforcement** | Advisory (skelm intercepts after the fact) | Native (pi hard-enforces the allowlist) |
 | **System prompt** | Not controllable | Pi's default; `req.system` appended; optional full replace |
-| **Peer dependency** | `pi` CLI on `$PATH` | `@mariozechner/pi-coding-agent` installed |
+| **Peer dependency** | `pi` CLI on `$PATH` | `@earendil-works/pi-coding-agent` installed |
 
 Use the **SDK backend** for new work — it gives you hard tool enforcement and real system prompt control. The RPC backend exists for environments where the SDK peer dependency can't be installed.
 
@@ -26,13 +26,13 @@ npm install @skelm/pi
 **RPC backend** additionally requires the `pi` CLI on `$PATH`:
 
 ```bash
-npm install -g @mariozechner/pi-coding-agent   # installs the `pi` binary
+npm install -g @earendil-works/pi-coding-agent   # installs the `pi` binary
 ```
 
 **SDK backend** additionally requires the SDK as a peer dependency:
 
 ```bash
-npm install @mariozechner/pi-coding-agent
+npm install @earendil-works/pi-coding-agent
 ```
 
 ## SDK backend (recommended)
@@ -63,7 +63,7 @@ export default defineConfig({
 A workflow that reviews a PR using a **skill** that encodes your team's style guide:
 
 ```ts
-// workflows/review-pr.workflow.ts
+// workflows/review-pr.workflow.mts
 import { agent, pipeline } from 'skelm'
 import { z } from 'zod'
 

package/dist/backend.js

@@ -5,8 +5,8 @@
 // concurrency semaphore to avoid spawning unlimited processes.
 //
 // Pi does NOT speak ACP; this backend uses the native pi RPC protocol
-// documented in @mariozechner/pi-coding-agent/docs/rpc.md.
-import { PermissionDeniedError, createConcurrencySemaphore, loadSkillBodies } from '@skelm/core';
+// documented in @earendil-works/pi-coding-agent/docs/rpc.md.
+import { PermissionDeniedError, createConcurrencySemaphore, extractPromptText, loadSkillBodies, } from '@skelm/core';
 import { PiRpcClient } from './rpc-client.js';
 /** Custom error types exposed from @skelm/pi */
 export class PiBackendError extends Error {
@@ -44,6 +44,10 @@ export function createPiBackend(options = {}) {
         mcp: false, // pi manages its own tools; no external MCP wiring
         skills: true,
         modelSelection: options.model !== undefined,
+        // RPC mode forwards prompts as text to a subprocess; image bytes
+        // cannot cross that boundary, so vision is explicitly off. Callers
+        // wanting multimodal must use the pi-sdk backend.
+        vision: false,
         // RPC mode runs pi in a subprocess; skelm cannot intercept tool_call events
         // mid-run, so it cannot enforce allowedTools, allowedExecutables,
         // fsRead/fsWrite, allowedMcpServers, or allowedSkills. The new gateway
@@ -112,7 +116,7 @@ export function createPiBackend(options = {}) {
             catch (err) {
                 if (err instanceof Error) {
                     if (err.message.includes('ENOENT') || err.message.includes('EACCES')) {
-                        throw new PiBackendAuthenticationError('pi binary not found or not executable. Install it: npm install -g @mariozechner/pi-coding-agent', err);
+                        throw new PiBackendAuthenticationError('pi binary not found or not executable. Install it: npm install -g @earendil-works/pi-coding-agent', err);
                     }
                     if (err.message.includes('timed out')) {
                         throw new PiBackendTimeoutError(err.message, err);
@@ -185,6 +189,6 @@ function buildPrompt(req, skillBodies = []) {
         systemParts.push(body);
     if (systemParts.length > 0)
         parts.push(`[System: ${systemParts.join('\n\n---\n\n')}]`);
-    parts.push(req.prompt);
+    parts.push(extractPromptText(req.prompt));
     return parts.join('\n\n');
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @skelm/pi - Pi coding agent backend for skelm
  *
- * Integration with the Pi coding agent (@mariozechner/pi-coding-agent) via
+ * Integration with the Pi coding agent (@earendil-works/pi-coding-agent) via
  * RPC mode. Spawns `pi --mode rpc` per call, uses the documented JSONL
  * protocol to stream the response.
  */

package/dist/index.js

@@ -1,7 +1,7 @@
 /**
  * @skelm/pi - Pi coding agent backend for skelm
  *
- * Integration with the Pi coding agent (@mariozechner/pi-coding-agent) via
+ * Integration with the Pi coding agent (@earendil-works/pi-coding-agent) via
  * RPC mode. Spawns `pi --mode rpc` per call, uses the documented JSONL
  * protocol to stream the response.
  */

package/dist/provider.js

@@ -15,7 +15,7 @@ export class PiProvider extends ProviderPluginBase {
             id: 'pi',
             name: 'Pi Coding Agent',
             version: '1.0.0',
-            description: 'Pi coding agent provider (@mariozechner/pi-coding-agent)',
+            description: 'Pi coding agent provider (@earendil-works/pi-coding-agent)',
             logLevel: options?.logLevel ?? 'info',
         });
     }
@@ -59,7 +59,7 @@ export class PiProvider extends ProviderPluginBase {
             execSync(`${this._cmd} --version`, { stdio: 'ignore' });
         }
         catch {
-            throw new Error(`Pi binary not found: '${this._cmd}'. Install: npm install -g @mariozechner/pi-coding-agent`);
+            throw new Error(`Pi binary not found: '${this._cmd}'. Install: npm install -g @earendil-works/pi-coding-agent`);
         }
     }
     async healthCheck() {

package/dist/sdk-backend.d.ts

@@ -27,13 +27,6 @@ export declare class PiSdkBackendAuthenticationError extends PiSdkBackendError {
 }
 export declare class PiSdkBackendTimeoutError extends PiSdkBackendError {
 }
-/**
- * Create a pi coding agent backend using the pi SDK.
- *
- * This backend builds an explicit tool allowlist from the skelm permission
- * policy so pi itself enforces which tools the agent may use. This provides
- * native enforcement rather than the advisory enforcement of the RPC backend.
- */
 export declare function createPiSdkBackend(options?: PiSdkBackendOptions): SkelmBackend;
 /**
  * Derive a pi tool allowlist from a skelm permission policy.

package/dist/sdk-backend.js

@@ -16,7 +16,41 @@
  *   fsWrite.size > 0                             → 'write', 'edit'
  *   undefined policy                             → no override (pi defaults)
  */
-import { assertEgressEnforceable as assertEgressEnforceableCore, createConcurrencySemaphore, loadSkillBodies, } from '@skelm/core';
+import { assertEgressEnforceable as assertEgressEnforceableCore, createConcurrencySemaphore, extractPromptText, loadSkillBodies, } from '@skelm/core';
+/**
+ * Extract image parts from a prompt for forwarding to pi's `session.prompt`
+ * via its `images` option. Pi's ImageContent (`{type:'image', data, mimeType}`)
+ * matches skelm's image ContentPart shape one-for-one.
+ */
+function extractPromptImages(prompt) {
+    if (typeof prompt === 'string' || prompt === undefined)
+        return [];
+    return prompt
+        .filter((p) => p.type === 'image')
+        .map((p) => ({ mimeType: p.mimeType, data: p.data }));
+}
+/**
+ * Collect image parts from all `role: 'user'` messages in an `InferRequest`.
+ *
+ * Intentionally first-turn-only: pi's `session.prompt(text, { images })` is
+ * turn-scoped — it sends the supplied images alongside `text` as one user
+ * message and starts the agent loop. Multi-turn conversations that resubmit
+ * prior-turn imagery would either re-attach the same bytes (wasteful) or
+ * silently drop history images here; the simpler behavior is to bundle every
+ * image into the single outgoing turn and let pi's session history persist
+ * what the model already saw. Assistant/tool messages don't carry images on
+ * the skelm side, so filtering on `role: 'user'` is sufficient.
+ */
+function gatherImagesFromMessages(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'user') {
+            for (const img of extractPromptImages(m.content))
+                out.push(img);
+        }
+    }
+    return out;
+}
 import { PiSdkClient, PiSdkUpstreamError } from './sdk-client.js';
 const assertEgressEnforceable = (policy) => assertEgressEnforceableCore(policy, 'pi-sdk');
 export class PiSdkBackendError extends Error {
@@ -38,7 +72,81 @@ export class PiSdkBackendTimeoutError extends PiSdkBackendError {
  * policy so pi itself enforces which tools the agent may use. This provides
  * native enforcement rather than the advisory enforcement of the RPC backend.
  */
+/**
+ * Resolve provider/model/baseUrl/apiKey from explicit options, falling back to
+ * OPENAI_* env vars when present. Returns `undefined` when there's nothing to
+ * override — preserving the prior behavior of deferring to
+ * `~/.pi/agent/models.json`. Per finding-119.
+ *
+ * Called once at `createPiSdkBackend()` time — env vars are snapshotted at
+ * backend construction. Mutating `OPENAI_BASE_URL` (or its siblings) after
+ * the backend exists has no effect on subsequent calls; construct a fresh
+ * backend if you need to switch endpoints at runtime. This matches how every
+ * other skelm backend reads env vars at construction.
+ */
+/**
+ * Placeholder forwarded to the underlying provider when the operator has
+ * pointed pi at a local OpenAI-compatible endpoint but supplied no real
+ * key (or the sentinel `'unused'`). `@earendil-works/pi-coding-agent`
+ * v0.75+ rejects `apiKey: undefined | '' | 'unused'` at provider-define
+ * time with `"apiKey" or "oauth" is required` — see finding-129. Local
+ * servers (llamacpp, sglang, vLLM, ollama) ignore the auth header, so
+ * we forward a non-empty placeholder when the caller's intent is "no
+ * authentication needed."
+ */
+const NO_AUTH_PLACEHOLDER = 'sk-no-key-required';
+function isMissingApiKey(apiKey) {
+    return apiKey === undefined || apiKey === '' || apiKey === 'unused';
+}
+function resolveProviderOverride(options) {
+    const provider = options.provider ?? process.env.OPENAI_PROVIDER;
+    const model = options.model ?? process.env.OPENAI_MODEL;
+    const baseUrl = options.baseUrl ?? process.env.OPENAI_BASE_URL;
+    const rawApiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+    // Only override when the caller has actually said something — either an
+    // explicit option or a non-empty env var. A bare `provider`/`model` without
+    // any endpoint hint defaults to provider='openai' for parity with the rest
+    // of skelm's OpenAI-compatible backends.
+    if (provider === undefined &&
+        model === undefined &&
+        baseUrl === undefined &&
+        rawApiKey === undefined) {
+        return undefined;
+    }
+    if (model === undefined) {
+        // No model id at all → cannot register a model entry; let pi pick its
+        // built-in default. Pi's default is OpenAI cloud `gpt-5.4`.
+        return undefined;
+    }
+    // Promote missing/sentinel apiKey to a placeholder when we're routing to
+    // a non-default endpoint — finding-129. Without this the provider library
+    // throws before we ever reach the wire.
+    const apiKey = isMissingApiKey(rawApiKey) ? NO_AUTH_PLACEHOLDER : rawApiKey;
+    return {
+        provider: provider ?? 'openai',
+        model,
+        ...(baseUrl !== undefined && { baseUrl }),
+        apiKey,
+        contextWindow: options.contextWindow ?? 131_072,
+        maxTokens: options.maxTokens ?? 4096,
+    };
+}
+function assertProviderConfigured(providerOverride, action) {
+    if (providerOverride === undefined) {
+        // Finding-131: refuse to dispatch when no provider/model/baseUrl/apiKey
+        // is configured. Without this, pi-coding-agent falls back to its
+        // built-in default (OpenAI cloud) and any request silently traverses
+        // an undeclared upstream — a security concern (prompts /
+        // tool-arguments / file content sent off-host without consent). The
+        // word "AuthenticationError" appears in the message so external
+        // harnesses that pattern-match on auth failure shapes still recognise
+        // it. To intentionally rely on ~/.pi/agent/models.json, pass an
+        // explicit `provider` + `model` to `createPiSdkBackend`.
+        throw new PiSdkBackendAuthenticationError(`pi-sdk ${action} refused: no provider/model/baseUrl/apiKey configured. Set OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL, or pass {baseUrl, apiKey, model} to createPiSdkBackend(). (AuthenticationError)`);
+    }
+}
 export function createPiSdkBackend(options = {}) {
+    const providerOverride = resolveProviderOverride(options);
     const capabilities = {
         prompt: true,
         streaming: true,
@@ -47,6 +155,15 @@ export function createPiSdkBackend(options = {}) {
         skills: true,
         modelSelection: false,
         toolPermissions: 'native',
+        // Pi natively supports multimodal user-message content via its
+        // `session.prompt(text, { images })` knob; image parts are forwarded as
+        // pi-ai's ImageContent (same shape as skelm's). Whether the configured
+        // pi model can actually process images depends on `~/.pi/agent/models.json`
+        // (the `input` field on the Model entry); non-vision models surface their
+        // own error which the backend propagates. Set `vision: false` to flip on
+        // the framework's vision gate for deployments pinned to a text-only pi
+        // model.
+        vision: options.vision ?? true,
     };
     const { acquire, release } = createConcurrencySemaphore(options.maxConcurrent ?? 4);
     return {
@@ -57,6 +174,7 @@ export function createPiSdkBackend(options = {}) {
             // Fail-closed before acquiring the concurrency slot — see comment on
             // assertEgressEnforceable.
             assertEgressEnforceable(context.permissions);
+            assertProviderConfigured(providerOverride, 'inference');
             await acquire();
             try {
                 const cwd = options.cwd;
@@ -69,12 +187,14 @@ export function createPiSdkBackend(options = {}) {
                     ...(options.noExtensions !== undefined && { noExtensions: options.noExtensions }),
                     ...(options.noSkills !== undefined && { noSkills: options.noSkills }),
                     ...(options.noContextFiles !== undefined && { noContextFiles: options.noContextFiles }),
+                    ...(providerOverride !== undefined && { providerOverride }),
                     ...(request.system !== undefined && {
                         system: request.system,
                         replaceSystemPrompt: false,
                     }),
                 });
-                const result = await client.prompt(promptText, context.signal, options.timeout ?? 300_000, context.onPartial);
+                const inferImages = gatherImagesFromMessages(request.messages);
+                const result = await client.prompt(promptText, context.signal, options.timeout ?? 300_000, context.onPartial, inferImages.length > 0 ? inferImages : undefined);
                 const response = {
                     ...(result.usage !== undefined && {
                         usage: {
@@ -103,6 +223,7 @@ export function createPiSdkBackend(options = {}) {
             // Fail-closed before acquiring the concurrency slot — see comment on
             // assertEgressEnforceable.
             assertEgressEnforceable(policy);
+            assertProviderConfigured(providerOverride, 'agent execution');
             await acquire();
             try {
                 const toolAllowlist = derivePiToolAllowlist(policy);
@@ -116,13 +237,15 @@ export function createPiSdkBackend(options = {}) {
                     ...(options.noExtensions !== undefined && { noExtensions: options.noExtensions }),
                     ...(options.noSkills !== undefined && { noSkills: options.noSkills }),
                     ...(options.noContextFiles !== undefined && { noContextFiles: options.noContextFiles }),
+                    ...(providerOverride !== undefined && { providerOverride }),
                     // System prompt: inject content and indicate whether to replace pi's base
                     ...(systemContent !== undefined && {
                         system: systemContent,
                         replaceSystemPrompt: options.systemPrompt !== undefined,
                     }),
                 });
-                const result = await client.prompt(request.prompt, context.signal, options.timeout ?? 300_000, context.onPartial);
+                const agentImages = extractPromptImages(request.prompt);
+                const result = await client.prompt(extractPromptText(request.prompt), context.signal, options.timeout ?? 300_000, context.onPartial, agentImages.length > 0 ? agentImages : undefined);
                 return {
                     text: result.text,
                     stopReason: result.stopReason,
@@ -151,7 +274,7 @@ function classifyPiSdkError(err, action) {
     }
     if (err instanceof Error) {
         if (err.message.includes('ENOENT') || err.message.includes('not installed')) {
-            return new PiSdkBackendAuthenticationError('pi SDK not available. Install it: npm install @mariozechner/pi-coding-agent', err);
+            return new PiSdkBackendAuthenticationError('pi SDK not available. Install it: npm install @earendil-works/pi-coding-agent', err);
         }
         if (err.message.includes('timed out')) {
             return new PiSdkBackendTimeoutError(err.message, err);
@@ -217,11 +340,20 @@ function buildSystemContent(systemBase, req, skillBodies) {
  * histories we serialize the conversation into a labeled transcript.
  */
 function buildInferPrompt(req) {
+    // Pi does not support image content; collapse any multimodal messages to
+    // their text parts. Callers needing vision should route to a vision-capable
+    // backend (anthropic / openai).
+    const asText = (content) => typeof content === 'string'
+        ? content
+        : content
+            .filter((p) => p.type === 'text')
+            .map((p) => p.text)
+            .join('');
     if (req.messages.length === 1 && req.messages[0]?.role === 'user') {
-        return req.messages[0].content;
+        return asText(req.messages[0].content);
     }
     return req.messages
-        .map((m) => `${m.role === 'user' ? 'User' : m.role === 'assistant' ? 'Assistant' : m.role}: ${m.content}`)
+        .map((m) => `${m.role === 'user' ? 'User' : m.role === 'assistant' ? 'Assistant' : m.role}: ${asText(m.content)}`)
         .join('\n\n');
 }
 /**

package/dist/sdk-client.d.ts

@@ -49,6 +49,28 @@ export interface PiSdkClientOptions {
      * Default: false — project context files are useful and safe.
      */
     noContextFiles?: boolean;
+    /**
+     * Provider configuration applied to pi's `ModelRegistry` at session start.
+     * When set, the named provider is (re-)registered with the supplied
+     * `baseUrl`/`apiKey`/`model`, overriding whatever `~/.pi/agent/models.json`
+     * declares for the lifetime of this session. Allows pi-sdk to be pointed
+     * at a local OpenAI-compatible endpoint via `OPENAI_BASE_URL` /
+     * `OPENAI_API_KEY` / `OPENAI_MODEL` without touching the user's pi
+     * config (finding-119).
+     *
+     * Either all four fields are honored together, or none of them — the
+     * backend resolves env-var defaults and only forwards a populated object.
+     */
+    providerOverride?: {
+        provider: string;
+        model: string;
+        baseUrl?: string;
+        apiKey?: string;
+        /** Metadata declared on the registered model entry; see PiSdkBackendOptions. */
+        contextWindow?: number;
+        /** Metadata declared on the registered model entry; see PiSdkBackendOptions. */
+        maxTokens?: number;
+    };
 }
 export interface PiSdkResponse {
     text: string;
@@ -79,6 +101,9 @@ export declare class PiSdkUpstreamError extends Error {
 export declare class PiSdkClient {
     private readonly opts;
     constructor(opts?: PiSdkClientOptions);
-    prompt(text: string, signal?: AbortSignal, timeoutMs?: number, onPartial?: (delta: string) => void): Promise<PiSdkResponse>;
+    prompt(text: string, signal?: AbortSignal, timeoutMs?: number, onPartial?: (delta: string) => void, images?: ReadonlyArray<{
+        mimeType: string;
+        data: string;
+    }>): Promise<PiSdkResponse>;
     private _run;
 }

package/dist/sdk-client.js

@@ -30,17 +30,49 @@ export class PiSdkClient {
     constructor(opts = {}) {
         this.opts = opts;
     }
-    async prompt(text, signal, timeoutMs, onPartial) {
-        // Dynamic import keeps @mariozechner/pi-coding-agent optional at runtime
-        const pi = await import('@mariozechner/pi-coding-agent').catch(() => {
-            throw new Error('pi SDK not installed. Add @mariozechner/pi-coding-agent to your project: npm install @mariozechner/pi-coding-agent');
+    async prompt(text, signal, timeoutMs, onPartial, images) {
+        // Dynamic import keeps @earendil-works/pi-coding-agent optional at runtime
+        const pi = await import('@earendil-works/pi-coding-agent').catch(() => {
+            throw new Error('pi SDK not installed. Add @earendil-works/pi-coding-agent to your project: npm install @earendil-works/pi-coding-agent');
         });
         const { createAgentSessionServices, createAgentSessionFromServices, SessionManager } = pi;
         const cwd = this.opts.cwd ?? process.cwd();
-        const systemPromptOverride = this.opts.system !== undefined
-            ? (base) => this.opts.replaceSystemPrompt
-                ? this.opts.system
-                : [base, this.opts.system].filter(Boolean).join('\n\n')
+        // Issue #193: pi's built-in coding-agent system prompt (~13 KB, "You are
+        // an expert coding assistant operating inside pi …") strongly biases the
+        // model toward file/code workflows and away from visual reasoning. When
+        // the caller threads image content but supplies no system override of
+        // their own, qwen35-VL / GPT-4V / Claude-Vision reliably reply "I cannot
+        // view or analyze images" — even though pi-coding-agent itself correctly
+        // packs the image into the chat-completions `image_url` content part.
+        // The image bytes reach the wire; the model just disengages because the
+        // system prompt told it it's a coding tool.
+        //
+        // Fix: when this turn contains images, append a short vision-enable hint
+        // to whichever base+user system prompt would otherwise be sent. The hint
+        // does NOT override pi's coding-agent prompt — it augments it — so
+        // coding-on-screenshot pipelines still get coding-agent capabilities AND
+        // visual reasoning.
+        const hasImages = images !== undefined && images.length > 0;
+        const userSystem = this.opts.system;
+        const replace = this.opts.replaceSystemPrompt === true;
+        const visionHint = 'The user has attached one or more images to their message. ' +
+            'You have vision capability — look at the image(s) and address what you see when answering.';
+        const systemPromptOverride = userSystem !== undefined || hasImages
+            ? (base) => {
+                // Caller fully replaces pi's prompt — they own the whole shape.
+                // Trust the caller covered image guidance themselves; don't
+                // double-inject the vision hint.
+                if (replace && userSystem !== undefined)
+                    return userSystem;
+                const parts = [];
+                if (!replace && base !== undefined && base.length > 0)
+                    parts.push(base);
+                if (userSystem !== undefined)
+                    parts.push(userSystem);
+                if (hasImages)
+                    parts.push(visionHint);
+                return parts.length > 0 ? parts.join('\n\n') : undefined;
+            }
             : undefined;
         const services = await createAgentSessionServices({
             cwd,
@@ -51,20 +83,49 @@ export class PiSdkClient {
                 ...(systemPromptOverride !== undefined && { systemPromptOverride }),
             },
         });
+        // Apply provider/model override before the session is created so the
+        // registered model overrides whatever ~/.pi/agent/models.json declares.
+        // The override is registered with `openai-completions` as the API since
+        // every local OpenAI-compatible server (sglang, vLLM, llama.cpp, ollama)
+        // implements that surface but rarely the newer Responses API.
+        const override = this.opts.providerOverride;
+        // Pi-coding-agent doesn't re-export Model<Api> at its package root, so
+        // we let TypeScript infer the type from `services.modelRegistry.find()`.
+        let pickedModel;
+        if (override !== undefined) {
+            services.modelRegistry.registerProvider(override.provider, {
+                ...(override.baseUrl !== undefined && { baseUrl: override.baseUrl }),
+                ...(override.apiKey !== undefined && { apiKey: override.apiKey }),
+                models: [
+                    {
+                        id: override.model,
+                        name: override.model,
+                        api: 'openai-completions',
+                        reasoning: false,
+                        input: ['text', 'image'],
+                        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+                        contextWindow: override.contextWindow ?? 131_072,
+                        maxTokens: override.maxTokens ?? 4096,
+                    },
+                ],
+            });
+            pickedModel = services.modelRegistry.find(override.provider, override.model);
+        }
         const { session } = await createAgentSessionFromServices({
             services,
             sessionManager: SessionManager.inMemory(),
             ...(this.opts.tools !== undefined && { tools: this.opts.tools }),
             ...(this.opts.noTools !== undefined && { noTools: this.opts.noTools }),
+            ...(pickedModel !== undefined && { model: pickedModel }),
         });
         try {
-            return await this._run(session, text, signal, timeoutMs ?? 300_000, onPartial);
+            return await this._run(session, text, signal, timeoutMs ?? 300_000, onPartial, images);
         }
         finally {
             session.dispose();
         }
     }
-    _run(session, text, signal, timeoutMs, onPartial) {
+    _run(session, text, signal, timeoutMs, onPartial, images) {
         return new Promise((resolve, reject) => {
             let settled = false;
             const settle = (fn) => {
@@ -160,7 +221,16 @@ export class PiSdkClient {
                     });
                 }
             });
-            session.prompt(text).catch((err) => {
+            const promptOpts = images !== undefined && images.length > 0
+                ? {
+                    images: images.map((img) => ({
+                        type: 'image',
+                        data: img.data,
+                        mimeType: img.mimeType,
+                    })),
+                }
+                : undefined;
+            session.prompt(text, promptOpts).catch((err) => {
                 unsub();
                 settle(() => reject(err));
             });

package/dist/types.d.ts

@@ -38,6 +38,68 @@ export interface PiSdkBackendOptions {
      * Default: false — project context files are useful and safe.
      */
     noContextFiles?: boolean;
+    /**
+     * Advertise `capabilities.vision`. Defaults to `true`: image parts in the
+     * prompt are forwarded to pi via `session.prompt(text, { images })`. Whether
+     * the configured pi model actually accepts images depends on its
+     * `~/.pi/agent/models.json` entry (the model's `input` field). Set
+     * `vision: false` to flip on the framework's vision gate for deployments
+     * pinned to a text-only pi model.
+     */
+    vision?: boolean;
+    /**
+     * Provider name to register with pi's `ModelRegistry` at session start.
+     * Defaults to `process.env.OPENAI_PROVIDER ?? 'openai'`. Pass an explicit
+     * value to pin a different provider (e.g. `'anthropic'`).
+     *
+     * Together with `model` / `baseUrl` / `apiKey`, this lets pi-sdk be pointed
+     * at a local OpenAI-compatible server (sglang, vLLM, llama.cpp, ollama)
+     * without hand-editing `~/.pi/agent/models.json`. Per finding-119 the env
+     * vars are honored automatically so pi-sdk reaches the same endpoint as
+     * every other skelm backend in the same config.
+     *
+     * `OPENAI_PROVIDER` is a pi-sdk-specific addition (the cross-backend
+     * convention is just `OPENAI_BASE_URL` / `OPENAI_API_KEY` / `OPENAI_MODEL`).
+     * It exists because pi's ModelRegistry is keyed by provider name; if you
+     * want to register the override against a non-`openai` provider (e.g.
+     * `'anthropic'`) without an explicit option, this is the knob.
+     */
+    provider?: string;
+    /**
+     * Model id used when registering the provider above. Defaults to
+     * `process.env.OPENAI_MODEL` when set, otherwise pi's own default
+     * (`gpt-5.4` at time of writing). Explicit value overrides env.
+     */
+    model?: string;
+    /**
+     * Base URL of the OpenAI-compatible endpoint. Defaults to
+     * `process.env.OPENAI_BASE_URL` when set. Trailing `/v1` is preserved
+     * verbatim — the pi SDK does not append it itself.
+     */
+    baseUrl?: string;
+    /**
+     * API key for the configured provider. Defaults to
+     * `process.env.OPENAI_API_KEY` when set. Local servers that ignore auth
+     * still need a non-empty value (e.g. `"unused"`); pass an explicit string
+     * to override.
+     */
+    apiKey?: string;
+    /**
+     * Optional `contextWindow` (in tokens) declared on the registered model
+     * entry. Defaults to 131_072 — a permissive ceiling that works for most
+     * modern local-LLM servers (sglang qwen3-coder, vLLM llama-3.1, …) and
+     * matches pi's built-in qwen/gpt defaults. Override when pinning pi-sdk
+     * at a small-context model (e.g. llama.cpp serving a 4K-context variant)
+     * so pi's own context-tracking math stays honest. The value is metadata —
+     * pi does not use it for hard truncation today, but downstream tooling may.
+     */
+    contextWindow?: number;
+    /**
+     * Optional `maxTokens` (in tokens) declared on the registered model
+     * entry. Defaults to 4096. Same metadata-only role as `contextWindow`;
+     * override when targeting a model with a tighter (or looser) output cap.
+     */
+    maxTokens?: number;
 }
 export interface PiBackendOptions {
     /** Backend id (default: 'pi') */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skelm/pi",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Pi coding-agent backend for skelm with full permission enforcement",
   "license": "MIT",
   "author": "Scott Glover <scottgl@gmail.com>",
@@ -26,7 +26,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "files": [
@@ -45,17 +45,17 @@
     "clean": "rm -rf dist tsconfig.tsbuildinfo"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=0.73.0",
-    "@skelm/core": "^0.4.1"
+    "@earendil-works/pi-coding-agent": ">=0.75.0",
+    "@skelm/core": "^0.4.3"
   },
   "peerDependenciesMeta": {
-    "@mariozechner/pi-coding-agent": {
+    "@earendil-works/pi-coding-agent": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.73.0",
-    "@skelm/core": "^0.4.1",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@skelm/core": "^0.4.3",
     "@types/node": "^20.10.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"