indusagi-coding-agent 0.1.59 → 0.1.61

package/guides/CLAUDE_CODEX_CLI_INTEGRATION_PLAN.md

@@ -1,321 +0,0 @@
-# Claude CLI / Codex CLI / Indusagi CLI Integration Plan for `indusagi-screth`
-
-## Goal
-
-Add support for CLI-backed providers in `indusagi-screth`, including:
-
-- Claude CLI / Claude Agent runtime
-- Codex CLI / Codex app-server runtime
-- **@varun1213213123132/indus1-test CLI** as another provider runtime
-
-so they can be integrated similarly to how `t3code` wires provider adapters.
-
----
-
-## Short Answer
-
-You have 3 practical paths:
-
-1. **Fast path**: custom providers via `registerProvider(..., { streamSimple })` and shell out to CLI.
-2. **Better path**: still custom provider, but run `indusagi` in `--mode rpc` for persistent subprocess + streaming events.
-3. **Full t3-style path**: build a provider adapter subsystem (session lifecycle + canonical runtime events).
-
-If you want parity with `t3code`, use **Path 3**.
-
----
-
-## Important Architecture Reality (Current Code)
-
-`indusagi-screth` is currently **model-centric**:
-
-- provider/model registration:
-  - `app/runtime/model-registry.ts`
-- extension provider registrations are queued and applied through:
-  - `app/runtime/plugins/loader.ts`
-  - `app/main.ts`
-  - `app/runtime/plugins/runner.ts`
-- runtime calls route through `indusagi/ai` provider API (`streamSimple`):
-  - `app/runtime/sdk.ts`
-
-### Why this matters
-
-Claude/Codex/Indusagi CLIs are **agent runtimes**, not plain model endpoints.
-
-Current architecture expects model providers to look like API adapters that produce assistant/tool-call events. So a CLI integration can work quickly, but full parity needs provider session orchestration.
-
----
-
-## Current Capability You Already Have
-
-You already support custom providers via extension/runtime registration:
-
-- `registerProvider(name, config)` API in extensions:
-  - `app/runtime/plugins/types.ts`
-- runtime queue + application:
-  - `app/runtime/plugins/loader.ts`
-  - `app/main.ts`
-  - `app/runtime/plugins/runner.ts`
-- custom stream handler support:
-  - `streamSimple` in `ProviderConfigInput` (`app/runtime/model-registry.ts`)
-
-This is enough for a strong PoC.
-
----
-
-## Path 1 — Fast Integration (Spawn CLI per turn)
-
-## Best for
-
-- quickest implementation
-- proving provider UX
-- validating prompt/output quality
-
-## Provider IDs to use
-
-- `claude-cli`
-- `codex-cli`
-- `indusagi-cli`
-
-## Implementation
-
-### 1) Add extension registration file
-
-Create:
-
-- `.indusagi/extensions/cli-providers.ts`
-
-Register 3 providers with model list + `streamSimple`.
-
-### 2) Implement stream handlers by spawning CLI
-
-Use `createAssistantMessageEventStream()` + `createAssistantMessageOutput()` from `indusagi/ai` and map process stdout into text deltas.
-
-Minimal skeleton:
-
-```ts
-import {
-  createAssistantMessageEventStream,
-  createAssistantMessageOutput,
-  type Model,
-  type Context,
-  type SimpleStreamOptions,
-} from "indusagi/ai";
-import { spawn } from "node:child_process";
-
-function streamSimpleCli(
-  bin: string,
-  args: string[],
-  model: Model<any>,
-  context: Context,
-  options?: SimpleStreamOptions,
-) {
-  const stream = createAssistantMessageEventStream();
-  const output = createAssistantMessageOutput(model);
-
-  stream.pushStart(output);
-  stream.pushTextStart(0, output);
-
-  const prompt = "...convert context.messages to prompt...";
-  const child = spawn(bin, [...args, prompt], {
-    stdio: ["ignore", "pipe", "pipe"],
-    env: process.env,
-  });
-
-  child.stdout.on("data", (buf) => {
-    const delta = String(buf);
-    const prev = (output.content[0] as any)?.text ?? "";
-    output.content[0] = { type: "text", text: prev + delta };
-    stream.pushTextDelta(0, delta, output);
-  });
-
-  child.on("close", (code) => {
-    const text = (output.content[0] as any)?.text ?? "";
-    stream.pushTextEnd(0, text, output);
-    stream.pushDone(code === 0 ? "stop" : "length", output);
-  });
-
-  child.on("error", (err) => {
-    output.stopReason = "error";
-    output.errorMessage = err instanceof Error ? err.message : String(err);
-    stream.pushError("error", output);
-  });
-
-  return stream;
-}
-```
-
-### 3) CLI command strategy
-
-- Claude: `claude -p`
-- Codex: start with a non-session command path for PoC (if available in your environment)
-- indusagi: `indusagi --mode text -p` (or `--mode json` and parse)
-
-### 4) Register model metadata
-
-Use placeholder model metadata in provider config (`contextWindow`, `maxTokens`, `cost`) until you have exact values.
-
-### 5) Auth gating note
-
-Current validation in `model-registry` requires `apiKey` or `oauth` when `models` are provided.
-
-- quick workaround: provide dummy `apiKey` in config and ignore it
-- cleaner fix: in `app/runtime/model-registry.ts`, relax rule when `streamSimple` is present
-
-Suggested rule:
-
-- if `models` exists AND `streamSimple` exists => allow without `apiKey/oauth`.
-
-## Limitations
-
-- no persistent provider session lifecycle
-- no native provider thread IDs/recovery
-- approvals/tool events from external agent are hard to map cleanly
-
----
-
-## Path 2 — Better Integration for `indusagi-cli` (RPC mode subprocess)
-
-## Best for
-
-- integrating **@varun1213213123132/indus1-test as a provider** with persistent process state
-- better streaming/event mapping than one-shot print mode
-
-`indusagi-screth` already has RPC client support:
-
-- `app/interfaces/service-api/rpc-client.ts`
-
-You can run subprocess:
-
-- `indusagi --mode rpc`
-
-and bridge RPC events into `AssistantMessageEventStream`.
-
-### Why this is useful
-
-Compared to one-shot `--mode text/-p`:
-
-- persistent subprocess
-- better event visibility
-- easier to add interrupt + model switching hooks
-
-### Suggested mapping
-
-- `message` events (assistant) -> `text_delta` / `text_end`
-- error event -> `pushError(...)`
-- completed/idle -> `pushDone(...)`
-
----
-
-## Path 3 — Full `t3code`-Style Provider Runtime (Recommended)
-
-## Best for
-
-- production-quality CLI providers
-- parity with Codex/Claude adapter design from `t3code`
-- extensibility to more runtimes
-
-## High-level design
-
-Add a provider subsystem inside `indusagi-screth`, e.g.:
-
-- `app/runtime/providers/Services/ProviderAdapter.ts`
-- `app/runtime/providers/Services/ProviderService.ts`
-- `app/runtime/providers/Layers/ProviderAdapterRegistry.ts`
-- `app/runtime/providers/Layers/ClaudeCliAdapter.ts`
-- `app/runtime/providers/Layers/CodexCliAdapter.ts`
-- `app/runtime/providers/Layers/IndusagiCliAdapter.ts`
-
-### Core responsibilities
-
-1. **ProviderAdapter**
-   - `startSession(threadId, config)`
-   - `sendTurn(threadId, input)`
-   - `interrupt/stop/listSessions`
-   - `streamEvents`
-
-2. **Adapter registry**
-   - provider key -> adapter
-
-3. **Provider service**
-   - route calls to adapter
-   - persist resume/binding state
-
-4. **Event normalization**
-   - provider raw events -> canonical runtime/session events
-
-5. **Session integration**
-   - in `AgentSession`, route selected providers (`claude-cli`, `codex-cli`, `indusagi-cli`) through provider service instead of direct `streamSimple`.
-
----
-
-## Concrete File-Level Plan (Updated)
-
-## Phase 1: Fast PoC
-
-1. Create extension file:
-   - `.indusagi/extensions/cli-providers.ts`
-2. Register 3 providers:
-   - `claude-cli`
-   - `codex-cli`
-   - `indusagi-cli`
-3. Implement `streamSimple` wrappers for all 3
-4. Validate:
-   - `indusagi --extension .indusagi/extensions/cli-providers.ts --list-models`
-
-## Phase 2: Validation + UX Cleanup
-
-1. Relax `model-registry` auth validation for `streamSimple` providers
-2. Add CLI binary existence checks (e.g. `--version`) and friendly startup errors
-3. Add tests for provider registration and selection
-
-## Phase 3: Full Adapter Runtime
-
-1. Build provider adapter/service layers
-2. Implement adapters:
-   - `ClaudeCliAdapter`
-   - `CodexCliAdapter`
-   - `IndusagiCliAdapter`
-3. Route session engine by provider type
-4. Add event mapping + resume semantics + interrupt handling
-
----
-
-## Test Checklist (Updated)
-
-- Provider registration
-  - all 3 providers visible in model list
-- Selection
-  - `/model` can switch to `claude-cli` / `codex-cli` / `indusagi-cli`
-- Streaming
-  - deltas arrive incrementally
-- Interrupt
-  - cancellation works consistently
-- Error handling
-  - missing CLI binary gives clear message
-- Session
-  - resume behavior predictable
-- RPC bridge (if Path 2)
-  - subprocess startup/shutdown stable
-  - events mapped correctly
-
----
-
-## Recommendation
-
-- **Immediate**: implement Path 1 for all three providers.
-- **Next**: move `indusagi-cli` to Path 2 (RPC) for better process/session behavior.
-- **Production**: adopt Path 3 provider runtime (t3-style adapters).
-
----
-
-## Optional Next Step
-
-If you want, next I can generate this file directly:
-
-- `.indusagi/extensions/cli-providers.ts`
-
-with starter registrations + scaffolding for:
-
-- `claude-cli`
-- `codex-cli`
-- `indusagi-cli`