indusagi-coding-agent 0.1.42 → 0.1.44

package/guides/OPTION3_PROVIDER_ADAPTER_RUNTIME_PLAN.md

@@ -0,0 +1,370 @@
+# Option 3 Plan: Full Provider Adapter Runtime (Claude CLI / Codex CLI / Indusagi CLI)
+
+## Objective
+
+Implement a **production-grade provider runtime layer** in `indusagi-screth` so CLI-backed providers behave as first-class runtimes, not just `streamSimple` wrappers.
+
+Target providers:
+
+- `claude-cli`
+- `codex-cli`
+- `indusagi-cli`
+
+---
+
+## Success Criteria
+
+1. Selecting any of the 3 providers routes execution through a dedicated adapter runtime.
+2. Session lifecycle is explicit: start, send turn, interrupt, shutdown, recover.
+3. Provider events are normalized into the existing `AssistantMessageEventStream` path.
+4. Session state persists enough metadata to resume reliably.
+5. Existing API providers keep working unchanged.
+
+---
+
+## Current Constraints in Codebase
+
+Relevant current flow:
+
+- Provider registration and model list:
+  - `app/runtime/model-registry.ts`
+- Stream execution path:
+  - `app/runtime/sdk.ts` (`createStreamWithHooks` -> `streamSimple(...)`)
+- Session orchestration and persistence:
+  - `app/runtime/agent-session.ts`
+  - `app/runtime/session-manager.ts`
+- Extension registration queue:
+  - `app/runtime/plugins/loader.ts`
+  - `app/runtime/plugins/runner.ts`
+  - `app/main.ts`
+- Existing RPC client (useful for `indusagi-cli` adapter):
+  - `app/interfaces/service-api/rpc-client.ts`
+
+Problem: current runtime assumes model API adapters. CLI runtimes require their own session/event lifecycle.
+
+---
+
+## Target Architecture
+
+## 1) New Provider Runtime Module
+
+Create a new module tree:
+
+- `app/runtime/providers/types.ts`
+- `app/runtime/providers/provider-adapter.ts`
+- `app/runtime/providers/provider-adapter-registry.ts`
+- `app/runtime/providers/provider-service.ts`
+- `app/runtime/providers/adapters/claude-cli-adapter.ts`
+- `app/runtime/providers/adapters/codex-cli-adapter.ts`
+- `app/runtime/providers/adapters/indusagi-cli-adapter.ts`
+
+## 2) Core Interfaces
+
+### `ProviderAdapter`
+
+```ts
+export interface ProviderAdapter {
+  readonly id: string;
+  supports(provider: string): boolean;
+
+  startSession(input: {
+    provider: string;
+    modelId: string;
+    sessionId: string;
+    cwd: string;
+  }): Promise<ProviderSessionHandle>;
+
+  streamTurn(input: {
+    handle: ProviderSessionHandle;
+    model: Model<Api>;
+    context: Context;
+    options?: SimpleStreamOptions;
+  }): AssistantMessageEventStream;
+
+  interrupt(handle: ProviderSessionHandle): Promise<void>;
+  stopSession(handle: ProviderSessionHandle): Promise<void>;
+  healthCheck?(): Promise<{ ok: boolean; reason?: string }>;
+}
+```
+
+### `ProviderSessionHandle`
+
+Contains adapter-managed runtime identity and metadata:
+
+- `adapterId`
+- `provider`
+- `modelId`
+- `runtimeSessionId` (thread/conversation/process id)
+- adapter-specific opaque payload
+
+## 3) `ProviderService`
+
+Responsibilities:
+
+- decide whether a model/provider should use adapter runtime
+- get or create adapter session handle for current agent session
+- stream one turn via adapter
+- interrupt/cleanup active runtime
+- persist runtime metadata for restore
+
+Internal state map:
+
+- `Map<agentSessionId, ProviderSessionHandle>`
+
+## 4) Adapter Registry
+
+Responsibilities:
+
+- register adapters
+- resolve by provider id
+- expose diagnostics for availability checks
+
+---
+
+## Integration Plan (File-Level)
+
+## Phase 0 — Scaffolding
+
+### Add new files
+
+- `app/runtime/providers/types.ts`
+- `app/runtime/providers/provider-adapter.ts`
+- `app/runtime/providers/provider-adapter-registry.ts`
+- `app/runtime/providers/provider-service.ts`
+
+### Add lightweight tests
+
+- `tests/runtime/providers/provider-adapter-registry.test.ts`
+- `tests/runtime/providers/provider-service.test.ts`
+
+---
+
+## Phase 1 — Runtime Routing in SDK
+
+### Modify `app/runtime/sdk.ts`
+
+1. Create `ProviderAdapterRegistry` during `createAgentSession()` bootstrap.
+2. Register built-in adapters (`claude-cli`, `codex-cli`, `indusagi-cli`).
+3. Create `ProviderService` and inject references:
+   - session id from `SessionManager`
+   - cwd
+4. Update `createStreamWithHooks(...)`:
+   - before `streamSimple(...)`, call provider service:
+     - if adapter exists for `model.provider`, use `providerService.streamTurn(...)`
+     - else fallback to existing `streamSimple(...)`
+
+Result: model/API providers unaffected; only targeted CLI providers reroute.
+
+---
+
+## Phase 2 — Provider Metadata + Validation
+
+### Modify `app/runtime/model-registry.ts`
+
+Add provider runtime metadata support in `ProviderConfigInput`:
+
+```ts
+runtime?: {
+  adapter: "claude-cli" | "codex-cli" | "indusagi-cli" | string;
+  authMode?: "apiKey" | "oauth" | "external-cli" | "none";
+}
+```
+
+Changes:
+
+1. Persist runtime config per provider in registry map.
+2. Add `getProviderRuntime(provider: string)` accessor.
+3. Relax validation for `models` when runtime auth is external:
+   - if `runtime.authMode` is `external-cli` or `none`, do not require `apiKey/oauth`.
+4. Keep existing validation for normal HTTP API providers.
+
+### Modify extension type surface
+
+- `app/runtime/plugins/types.ts`
+  - extend `ProviderConfig` with same `runtime` field.
+
+---
+
+## Phase 3 — Session Persistence for Adapter State
+
+### Modify `app/runtime/session-manager.ts`
+
+Use existing custom entry mechanism:
+
+- `appendCustomEntry("provider_runtime", data)`
+
+Persist after adapter session creation/update:
+
+```json
+{
+  "type": "custom",
+  "customType": "provider_runtime",
+  "data": {
+    "provider": "codex-cli",
+    "adapterId": "codex-cli",
+    "modelId": "gpt-5.4-1m",
+    "runtimeSessionId": "...",
+    "timestamp": "..."
+  }
+}
+```
+
+On startup, `ProviderService` should inspect latest relevant custom entry and attempt restore.
+
+---
+
+## Phase 4 — Adapter Implementations
+
+## 4.1 `IndusagiCliAdapter` (first, easiest)
+
+File:
+
+- `app/runtime/providers/adapters/indusagi-cli-adapter.ts`
+
+Implementation:
+
+- use existing `RpcClient` (`app/interfaces/service-api/rpc-client.ts`)
+- start subprocess in `--mode rpc`
+- set provider/model if needed
+- map incoming RPC events to `AssistantMessageEventStream` events
+- support interrupt/stop cleanly
+
+Why first: strong existing API and event stream already available.
+
+## 4.2 `CodexCliAdapter`
+
+File:
+
+- `app/runtime/providers/adapters/codex-cli-adapter.ts`
+
+Implementation approach:
+
+- mimic t3code `codex app-server` management pattern
+- manage process lifecycle per agent session
+- translate codex events -> normalized assistant stream
+- implement robust retry and “binary missing” errors
+
+## 4.3 `ClaudeCliAdapter`
+
+File:
+
+- `app/runtime/providers/adapters/claude-cli-adapter.ts`
+
+Implementation approach:
+
+- support preferred Claude CLI invocation/session mode available in your environment
+- parse streaming/stdout events to text deltas
+- add cancellation + process cleanup
+
+---
+
+## Phase 5 — Agent Session Hooks
+
+### Modify `app/runtime/agent-session.ts`
+
+Add lifecycle hooks to call provider service:
+
+1. On model change to non-adapter provider:
+   - stop old adapter session handle (if exists).
+2. On user interrupt/steer path:
+   - call `providerService.interrupt(...)` when current provider is adapter-backed.
+3. On session shutdown:
+   - `providerService.stopSession(...)`.
+
+Goal: no orphan subprocesses and predictable cancellation.
+
+---
+
+## Phase 6 — CLI UX and Login Surface
+
+### Modify `app/command-line/login-handler.ts`
+
+- include adapter providers only if they actually support login.
+- for `external-cli` auth mode, show clear message:
+  - “Authenticate using provider CLI command (e.g., `claude login`, `codex login`)”
+
+### Modify `app/command-line/list-models.ts` (optional enhancement)
+
+- show runtime-backed providers even without API keys when `authMode=external-cli` and health check passes.
+
+---
+
+## Phase 7 — Tests
+
+Add tests in:
+
+- `tests/runtime/providers/*.test.ts`
+- `tests/runtime/model-registry*.test.ts`
+- `tests/runtime/sdk*.test.ts`
+
+### Required coverage
+
+1. Routing: adapter provider uses `ProviderService`, others use `streamSimple`.
+2. Validation: runtime external providers do not require apiKey/oauth.
+3. Persistence: provider runtime custom entry is written and restored.
+4. Interrupt/shutdown: child process cleanup runs.
+5. Error handling: binary missing, startup failure, malformed stream.
+
+---
+
+## Phase 8 — Rollout Strategy
+
+1. Ship behind env flag:
+   - `INDUSAGI_ENABLE_PROVIDER_ADAPTERS=1`
+2. Enable only `indusagi-cli` adapter first.
+3. Then enable `codex-cli` and `claude-cli` after integration tests pass.
+4. Remove flag when stable.
+
+---
+
+## Event Normalization Rules
+
+All adapters must normalize to one contract:
+
+1. `pushStart(output)`
+2. `pushTextStart(index, output)` once
+3. `pushTextDelta(index, delta, output)` many times
+4. `pushTextEnd(index, finalText, output)` once
+5. `pushDone(stopReason, output)` once
+6. `pushError(...)` on failure path
+
+Non-text native events (approvals/tool telemetry) should be mapped to session custom entries first, then surfaced in UI incrementally.
+
+---
+
+## Risks and Mitigations
+
+1. **Provider protocol drift** (CLI output formats change)
+   - Mitigation: adapter-level parsers with golden tests.
+
+2. **Process leaks**
+   - Mitigation: strict stop/timeout/SIGKILL policy in provider service.
+
+3. **Auth ambiguity for external CLI**
+   - Mitigation: explicit `authMode=external-cli` + health checks + clear UX copy.
+
+4. **Session mismatch on restore**
+   - Mitigation: store adapter/model/provider in custom entry and validate before restore.
+
+---
+
+## Definition of Done
+
+- [ ] New provider runtime module exists with registry/service/adapters.
+- [ ] `sdk.ts` routes adapter providers through provider service.
+- [ ] `model-registry.ts` supports runtime metadata and external-cli auth mode.
+- [ ] Adapter session metadata persisted and restorable.
+- [ ] `indusagi-cli` adapter fully working via RPC.
+- [ ] `codex-cli` and `claude-cli` adapters pass smoke tests.
+- [ ] No regressions for existing API providers.
+
+---
+
+## Recommended Execution Order (Practical)
+
+1. Build shared runtime module + routing.
+2. Implement `indusagi-cli` adapter first (uses existing RPC client).
+3. Add persistence + interruption handling.
+4. Implement `codex-cli` adapter.
+5. Implement `claude-cli` adapter.
+6. Harden tests and remove feature flag.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "indusagi-coding-agent",
-  "version": "0.1.42",
-  "description": "Local TypeScript coding-agent workspace built around the sibling indusvx-screth_copy package.",
+  "version": "0.1.44",
+  "description": "Terminal-first TypeScript coding agent built on the published indusagi package.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,7 +33,11 @@
     "clean": "shx rm -rf dist",
     "sync:export-vendors": "node tasks/sync-export-vendors.mjs",
     "copy:export-assets": "node tasks/copy-export-assets.mjs",
-    "build": "npm run sync:export-vendors && tsc -p tsconfig.build.json && npm run copy:export-assets && shx chmod +x dist/cli.js",
+    "build": "npm run build:observe-local && npm run sync:export-vendors && tsc -p tsconfig.build.json && npm run copy:export-assets && shx chmod +x dist/cli.js",
+    "build:observe-local": "node -e \"console.log('Using published indusagi@0.12.24')\"",
+    "observe:smoke": "npm run build && node dist/dev/observe-smoke.js",
+    "observe:smoke:serve": "npm run build && node dist/dev/observe-smoke.js --serve",
+    "observe:deep": "npm run build && node dist/dev/observe-deep.js",
     "test": "vitest --run",
     "verify": "npm run build && npm test"
   },
@@ -48,9 +52,12 @@
     "file-type": "^21.1.1",
     "glob": "^11.0.3",
     "highlight.js": "^11.11.1",
-    "indusagi": "^0.12.22",
+    "i": "^0.3.7",
+    "indusagi": "^0.12.24",
+    "indusagi-coding-agent": "^0.1.42",
     "marked": "^17.0.5",
     "minimatch": "^10.0.3",
+    "npm": "^11.12.0",
     "strip-ansi": "^7.1.2",
     "uuid": "^11.1.0"
   },