Feat/pi deferred extension model resolution (#1509)

* feat(pi): support extension-registered provider models via deferred resolution

Extension providers (e.g. pi-provider-kiro) register their models on
the ModelRegistry during session.bindExtensions(), not during the
initial modelRegistry.find() call. The previous approach threw
immediately when find() returned undefined, blocking extension models.

New flow:
1. modelRegistry.find() checks static catalog + models.json (step 3)
2. If found: pass to createAgentSession, fail-fast auth as before
3. If not found: log info, skip auth (extension providers manage their
   own credentials), create session without model
4. After bindExtensions() (step 4g): retry modelRegistry.find() — now
   extension-registered models are discoverable — and call
   session.setModel() to switch to the resolved model
5. If still not found after bindExtensions(): throw with a hint about
   installing the provider extension with enableExtensions: true

This preserves all existing behavior for built-in providers and
models.json custom models while adding support for extension-registered
providers like pi-provider-kiro (Kiro API — 20 free models including
Claude, DeepSeek, Qwen, etc.).

Changes:
- provider.ts: deferred model resolution after bindExtensions();
  conditional model arg to createAgentSession; conditional auth
  fail-fast; session.setModel() for extension-resolved models
- provider.test.ts: add setModel mock; update model-not-found tests
  for two-phase find() behavior

* test: add archon-test-pi example workflow for Kiro extension validation

Simple two-node workflow that verifies the Pi provider works with
extension-registered models (e.g. pi-provider-kiro). Node 1 asks a
factual question, node 2 validates the answer.

Tested with kiro/claude-sonnet-4-6 and kiro/minimax-m2-5.

* docs: add Pi/Kiro prerequisites and setup to examples README

* fix(pi): load models.json custom providers and surface SDK error messages

- Switch ModelRegistry.inMemory() to ModelRegistry.create() so custom
  providers from ~/.pi/agent/models.json (ollama, LM Studio, etc.)
  resolve correctly. Both return the same mutable class supporting
  registerProvider() for extensions.
- Surface Pi's AssistantMessage.errorMessage in the result chunk errors
  array so dag-executor shows actual errors instead of generic
  'SDK returned error'.
- Add ollama/qwen3.5 node to archon-test-pi workflow to validate both
  extension (kiro) and models.json (ollama) provider paths.

* fix(pi): address Wirasm PR review — comment clarity, session cleanup, test mock alignment

- event-bridge: document intentional design of yielding error chunks (isError:true
  propagates in chunk, not via throw); fix event name to pi.result_chunk_error;
  remove noisy model field from error log
- provider: replace verbose multi-paragraph step-numbered comments with concise
  WHY explanations; fix stale ModelRegistry.inMemory() reference (code uses create());
  add session.dispose() on model-not-found throw and setModel() failure to close
  the session cleanup gap
- provider.test: align mock from ModelRegistry.inMemory → ModelRegistry.create to
  match actual provider code (was already broken on the branch); update test
  description and comments to describe behavior rather than step numbers

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* test(pi): add happy-path test for deferred extension model resolution

Verifies that when find() returns undefined on the first call (static catalog miss)
and a model on the second call (after bindExtensions()), session.setModel() is
invoked with the resolved model and no error is returned.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: jhegeman-ds <joel.hegeman@deepseas.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

.archon/workflows/archon-test-pi.yaml

@@ -0,0 +1,34 @@
+name: archon-test-pi
+description: |
+  Simple test workflow to verify the pi provider works with Archon.
+  Triggers: "test pi", "test pi provider".
+
+provider: pi
+model: kiro/minimax-m2-5
+
+nodes:
+  - id: hello
+    prompt: |
+      Who won the 1984 Major League Baseball World Series? Answer in one sentence.
+
+  - id: hello-ollama
+    model: ollama/qwen3.5
+    prompt: |
+      Who won the 1984 Major League Baseball World Series? Answer in one sentence.
+
+  - id: verify
+    prompt: |
+      The extension model node said:
+
+      $hello.output
+
+      The ollama node said:
+
+      $hello-ollama.output
+
+      If both answers mention the Detroit Tigers, say "Pi provider verified ✅ (extension + ollama)".
+      If only the extension model is correct, say "Pi extension verified ✅, ollama FAILED ❌".
+      If only ollama is correct, say "Pi ollama verified ✅, extension FAILED ❌".
+      If neither is correct, say "Pi provider FAILED ❌ — both wrong".
+      Say nothing else.
+    depends_on: [hello, hello-ollama]

examples/workflows/README.md

@@ -0,0 +1,20 @@
+# Prerequisites
+
+## Install Pi
+
+```bash
+npm install -g @mariozechner/pi-coding-agent
+```
+
+## Install Kiro provider and dependencies
+
+```bash
+pi install npm:pi-provider-kiro
+npm install -g @mariozechner/pi-tui @mariozechner/pi-ai
+```
+
+## Install MCP for Pi
+
+```bash
+pi install npm:pi-mcp-adapter
+```

examples/workflows/archon-test-pi.yaml

@@ -0,0 +1,35 @@
+name: archon-test-pi
+description: |
+  Simple test workflow to verify the pi provider works with Archon.
+  Triggers: "test pi", "test pi provider".
+
+provider: pi
+model: kiro/minimax-m2-5
+
+nodes:
+  - id: hello
+    model: kiro/minimax-m2-5
+    prompt: |
+      Who won the 1984 Major League Baseball World Series? Answer in one sentence.
+
+  - id: hello-ollama
+    model: ollama/qwen3.5
+    prompt: |
+      Who won the 1984 Major League Baseball World Series? Answer in one sentence.
+
+  - id: verify
+    prompt: |
+      The extension model node said:
+
+      $hello.output
+
+      The ollama node said:
+
+      $hello-ollama.output
+
+      If both answers mention the Detroit Tigers, say "Pi provider verified ✅ (extension + ollama)".
+      If only the extension model is correct, say "Pi extension verified ✅, ollama FAILED ❌".
+      If only ollama is correct, say "Pi ollama verified ✅, extension FAILED ❌".
+      If neither is correct, say "Pi provider FAILED ❌ — both wrong".
+      Say nothing else.
+    depends_on: [hello, hello-ollama]

packages/providers/src/community/pi/event-bridge.ts

@@ -179,6 +179,15 @@ export function buildResultChunk(messages: readonly unknown[]): MessageChunk {
         }
       : {}),
   };
+  if (isError) {
+    // Intentional design: error chunks are yielded, not thrown. isError:true in the chunk
+    // is the signal — callers (bridgeSession, dag-executor) check result.isError to classify
+    // failures and still receive full token/stopReason context from the same chunk.
+    getLog().error(
+      { stopReason: last.stopReason, errorMessage: last.errorMessage },
+      'pi.result_chunk_error'
+    );
+  }
   return chunk;
 }
 

packages/providers/src/community/pi/provider.test.ts

@@ -43,13 +43,15 @@ const mockSetFlagValue = mock((_name: string, _value: boolean | string) => undef
 const mockExtensionRunner = {
   setFlagValue: mockSetFlagValue,
 };
+const mockSetModel = mock(async (_model: unknown) => undefined);
 const mockSession = {
   subscribe: mockSubscribe,
   prompt: mockPrompt,
   abort: mockAbort,
   dispose: mockDispose,
   bindExtensions: mockBindExtensions,
   extensionRunner: mockExtensionRunner,
+  setModel: mockSetModel,
   isStreaming: false,
   sessionId: 'mock-session-uuid',
 };
@@ -188,6 +190,7 @@ describe('PiProvider', () => {
     mockDispose.mockClear();
     mockSubscribe.mockClear();
     mockBindExtensions.mockClear();
+    mockSetModel.mockClear();
     mockSetFlagValue.mockClear();
     mockResourceLoaderReload.mockClear();
     mockCreateAgentSession.mockClear();
@@ -281,11 +284,9 @@ describe('PiProvider', () => {
   });
 
   test('ModelRegistry.create receives the AuthStorage instance', async () => {
-    // Headline-fix wiring: ModelRegistry.create must receive the same
-    // AuthStorage instance returned by AuthStorage.create(), so registry
-    // lookups can resolve user-configured custom models from
-    // ~/.pi/agent/models.json (LM Studio, ollama, llamacpp, etc.). Without
-    // this wiring the registry only sees the static built-in catalog.
+    // ModelRegistry.create must receive the same AuthStorage instance
+    // returned by AuthStorage.create(), so extension providers can resolve
+    // credentials and register models during bindExtensions().
     process.env.GEMINI_API_KEY = 'sk-test';
     resetScript(scriptedAgentEnd());
 
@@ -327,33 +328,32 @@ describe('PiProvider', () => {
   });
 
   test('Pi model not found includes models.json load error when registry reports one', async () => {
-    // ModelRegistry swallows models.json parse/validation errors into an
-    // internal loadError. When find() returns undefined we surface that
-    // error in both the structured log and the throw message so users
-    // debugging a custom-provider config see the actual reason.
     process.env.GEMINI_API_KEY = 'sk-test';
+    // find() is called twice — first on the static catalog, then again after bindExtensions()
+    // resolves extension providers. Both must return undefined to trigger the error.
+    mockModelRegistryFind.mockImplementationOnce(() => undefined);
     mockModelRegistryFind.mockImplementationOnce(() => undefined);
     mockModelRegistryCreate.mockImplementationOnce(() => ({
       find: mockModelRegistryFind,
       getError: () => 'Provider lm-studio: "baseUrl" is required when defining custom models.',
     }));
 
+    resetScript(scriptedAgentEnd());
     const { error } = await consume(
       new PiProvider().sendQuery('hi', '/tmp', undefined, {
         model: 'lm-studio/some-model',
       })
     );
 
     expect(error?.message).toContain('Pi model not found');
-    expect(error?.message).toContain('models.json failed to load');
-    expect(error?.message).toContain('"baseUrl" is required');
-    expect(mockLogger.error).toHaveBeenCalledWith(
+    expect(error?.message).toContain('provider extension');
+    expect(mockLogger.warn).toHaveBeenCalledWith(
       expect.objectContaining({
         piProvider: 'lm-studio',
         modelId: 'some-model',
         loadError: expect.stringContaining('"baseUrl" is required'),
       }),
-      'pi.model_not_found'
+      'pi.model_registry_load_error'
     );
   });
 
@@ -407,17 +407,43 @@ describe('PiProvider', () => {
 
   test('throws when ModelRegistry.find returns undefined', async () => {
     process.env.GEMINI_API_KEY = 'sk-test';
-    // 'nonexistent' is handled in mockModelRegistryFind to return undefined, but
-    // the adapter rejects unknown providers. To exercise
-    // the not-found branch, use a known provider but unknown modelId by
-    // temporarily swapping mockModelRegistryFind to always return undefined.
+    // find() is called twice — first on the static catalog, then again after bindExtensions()
+    // resolves extension providers. Both must return undefined to trigger the error.
+    mockModelRegistryFind.mockImplementationOnce(() => undefined);
     mockModelRegistryFind.mockImplementationOnce(() => undefined);
+    resetScript(scriptedAgentEnd());
     const { error } = await consume(
       new PiProvider().sendQuery('hi', '/tmp', undefined, {
         model: 'google/unknown-model-id',
       })
     );
     expect(error?.message).toContain('Pi model not found');
+    expect(error?.message).toContain('provider extension');
+  });
+
+  test('deferred resolution: calls session.setModel when find() resolves after bindExtensions', async () => {
+    // Phase 1: model not in static catalog (extension provider path).
+    // Phase 2: extension registers the model during bindExtensions() and find() succeeds.
+    mockModelRegistryFind.mockImplementationOnce(() => undefined);
+    mockModelRegistryFind.mockImplementationOnce(() => ({
+      id: 'custom-model',
+      provider: 'extension-provider',
+      name: 'extension-provider/custom-model',
+    }));
+    resetScript(scriptedAgentEnd());
+
+    const { error } = await consume(
+      new PiProvider().sendQuery('hi', '/tmp', undefined, {
+        model: 'extension-provider/custom-model',
+      })
+    );
+
+    expect(error).toBeUndefined();
+    expect(mockModelRegistryFind).toHaveBeenCalledTimes(2);
+    expect(mockSetModel).toHaveBeenCalledTimes(1);
+    expect(mockSetModel).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'custom-model', provider: 'extension-provider' })
+    );
   });
 
   test('request env (codebase env vars) overrides process.env via setRuntimeApiKey', async () => {