indusagi-coding-agent 0.1.42 → 0.1.44

package/guides/CLAUDE_CODEX_CLI_INTEGRATION_PLAN.md

@@ -0,0 +1,321 @@
+# 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
+- **indusagi-coding-agent 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 **indusagi-coding-agent 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`

package/guides/{PI_MONO_MIT_REMOVAL_GUIDE.md → INDUSAGI_MONO_MIT_REMOVAL_GUIDE.md}

@@ -1,8 +1,8 @@
-# PI Mono MIT Removal Guide for `indusagi-screth`
+# Indusagi Mono MIT Removal Guide for `indusagi-screth`
 
 
 
-> **Important:** This is a technical provenance-cleanup guide, **not legal advice**. If you want to make a strong public claim like _"`indusagi-screth` contains no PI Mono derived code"_, you should still do a final legal/provenance review.
+> **Important:** This is a technical provenance-cleanup guide, **not legal advice**. If you want to make a strong public claim like _"`indusagi-screth` contains no Indusagi Mono derived code"_, you should still do a final legal/provenance review.
 
 
 
@@ -10,21 +10,21 @@
 
 
 
-If the goal is to make `indusagi-screth` **PI Mono MIT-free**, the safe standard is:ß
+If the goal is to make `indusagi-screth` **Indusagi Mono MIT-free**, the safe standard is:ß
 
 
 
-1. No copied PI Mono source files remain.
+1. No copied Indusagi Mono source files remain.
 
-2. No adapted/derived PI Mono files remain unless you are willing to keep MIT attribution.
+2. No adapted/derived Indusagi Mono files remain unless you are willing to keep MIT attribution.
 
 3. Third-party vendor assets are either:
 
    - replaced by direct upstream package installation/build steps, or
 
-   - kept with their own proper attribution, independent of PI Mono.
+   - kept with their own proper attribution, independent of Indusagi Mono.
 
-4. Documentation, package metadata, and marketing text do not imply PI Mono-derived implementation if that is no longer true.
+4. Documentation, package metadata, and marketing text do not imply Indusagi Mono-derived implementation if that is no longer true.
 
 
 
@@ -34,7 +34,7 @@ If the goal is to make `indusagi-screth` **PI Mono MIT-free**, the safe standard
 
 Compared repos:
 
-- `@pi-mono/packages/coding-agent/`
+- `@indusagi-mono/packages/coding-agent/`
 
 - `@indusagi-screth/`
 
@@ -50,7 +50,7 @@ Current overlap snapshot:
 
 
 
-That means `indusagi-screth` is **not** currently in a position where it is safe to say _"PI Mono copyright does not apply"_. There is still enough exact and likely-derived overlap that a cleanup pass is required.
+That means `indusagi-screth` is **not** currently in a position where it is safe to say _"Indusagi Mono copyright does not apply"_. There is still enough exact and likely-derived overlap that a cleanup pass is required.
 
 
 
@@ -70,7 +70,7 @@ Before rewriting anything, follow these rules:
 
 
 
-- Do **not** use PI Mono files as copy-paste sources during the rewrite.
+- Do **not** use Indusagi Mono files as copy-paste sources during the rewrite.
 
 - Rewrite from behavior/specification, not from line-by-line adaptation.
 
@@ -82,7 +82,7 @@ Before rewriting anything, follow these rules:
 
   - `kept and MIT attribution retained`
 
-- If a file is still PI Mono-derived after cleanup, keep MIT attribution for that file/subtree.
+- If a file is still Indusagi Mono-derived after cleanup, keep MIT attribution for that file/subtree.
 
 
 
@@ -94,7 +94,7 @@ Before rewriting anything, follow these rules:
 
 
 
-These are the highest-risk files because they currently match PI Mono exactly.
+These are the highest-risk files because they currently match Indusagi Mono exactly.
 
 
 
@@ -118,7 +118,7 @@ These are the highest-risk files because they currently match PI Mono exactly.
 
 ### P1-B. Exact vendor / asset files to replace properly
 
-These should not stay as copied repo assets if the goal is "PI Mono MIT-free provenance".
+These should not stay as copied repo assets if the goal is "Indusagi Mono MIT-free provenance".
 
 
 
@@ -136,7 +136,7 @@ For each file above, do one of:
 
 - full independent rewrite, or
 
-- replace from original upstream package/source with proper direct attribution, not via PI Mono copy.
+- replace from original upstream package/source with proper direct attribution, not via Indusagi Mono copy.
 
 ### P1 status update
 
@@ -308,7 +308,7 @@ These should **not** be hand-edited.
 - new control-flow shape
 - new intermediate data model
 - same behavior implemented through a different code path
-- vendor assets replaced from direct upstream instead of PI Mono copies
+- vendor assets replaced from direct upstream instead of Indusagi Mono copies
 
 
 
@@ -410,7 +410,7 @@ These files are not byte-identical, but they share the same path and likely shar
 
 ### Why P2 is critical
 
-If these remain structurally PI Mono-derived, then even rewriting surface docs or utilities will not materially change provenance risk.
+If these remain structurally Indusagi Mono-derived, then even rewriting surface docs or utilities will not materially change provenance risk.
 
 ### Focused P2 plan for the currently requested files
 
@@ -418,7 +418,7 @@ If these remain structurally PI Mono-derived, then even rewriting surface docs o
 
 ### Focused P2 post-rewrite recheck (approximate)
 
-**Method note:** the percentages below are an approximate **post-P2** recheck against `@pi-mono/packages/coding-agent/`, using a `git diff --no-index --word-diff=porcelain` unchanged-text ratio. These numbers are meant for provenance prioritization, not as a legal or plagiarism determination.
+**Method note:** the percentages below are an approximate **post-P2** recheck against `@indusagi-mono/packages/coding-agent/`, using a `git diff --no-index --word-diff=porcelain` unchanged-text ratio. These numbers are meant for provenance prioritization, not as a legal or plagiarism determination.
 
 | File | Post-P2 similarity | Post-P2 difference |
 |---|---:|---:|
@@ -440,7 +440,7 @@ If these remain structurally PI Mono-derived, then even rewriting surface docs o
 
 ### Focused P2 post-rewrite takeaway
 
-This recheck suggests the biggest previously high-similarity P2 files have moved materially away from PI Mono structure in this batch. In particular:
+This recheck suggests the biggest previously high-similarity P2 files have moved materially away from Indusagi Mono structure in this batch. In particular:
 
 - `src/core/prompt-templates.ts` moved from the earlier near-match risk zone to `30.9%` similarity / `69.1%` difference.
 - `src/core/session-manager.ts` moved from the earlier near-match risk zone to `15.2%` similarity / `84.8%` difference.
@@ -495,7 +495,7 @@ The files you called out are spread across bootstrap, CLI parsing, runtime orche
 
 **Minimal but meaningful rewrite:**
 - move MCP log suppression into named helper(s)
-- avoid top-level anonymous patch structure copied from PI Mono style
+- avoid top-level anonymous patch structure copied from Indusagi Mono style
 - introduce a `bootstrapCli()` wrapper that owns process-title + logger patch + main invocation
 
 **Suggested rewrite shape:**
@@ -526,7 +526,7 @@ The files you called out are spread across bootstrap, CLI parsing, runtime orche
 - separate package-root detection from exported path helpers
 - centralize env var resolution and tilde expansion
 - group asset path helpers vs user config path helpers vs metadata exports
-- reduce structural resemblance to current PI Mono layout even if behavior stays the same
+- reduce structural resemblance to current Indusagi Mono layout even if behavior stays the same
 
 **Suggested rewrite shape:**
 - `resolvePackageRoot()`
@@ -1050,7 +1050,7 @@ Validation after the P3 rewrite pass:
 
 ### Focused P3 post-rewrite recheck (approximate)
 
-**Method note:** the percentages below are an approximate **post-P3** recheck against `@pi-mono/packages/coding-agent/`, using a `git diff --no-index --word-diff=porcelain` unchanged-text ratio. These numbers are meant for provenance prioritization, not as a legal or plagiarism determination.
+**Method note:** the percentages below are an approximate **post-P3** recheck against `@indusagi-mono/packages/coding-agent/`, using a `git diff --no-index --word-diff=porcelain` unchanged-text ratio. These numbers are meant for provenance prioritization, not as a legal or plagiarism determination.
 
 | File | Post-P3 similarity | Post-P3 difference |
 |---|---:|---:|
@@ -1097,7 +1097,7 @@ So unlike the focused P2 batch, the focused P3 batch is **not yet all below `40%
 
 
 
-These files are many, but they are important because the TUI layer is highly expressive and likely to preserve PI Mono structure even after edits. Rewrite after P2/P3.
+These files are many, but they are important because the TUI layer is highly expressive and likely to preserve Indusagi Mono structure even after edits. Rewrite after P2/P3.
 
 
 
@@ -1680,7 +1680,7 @@ That materially changes the repository-wide overlap picture: there are no longer
 
 
 
-These files exist in `indusagi-screth` but not in PI Mono, so they are **not immediate PI Mono overlap evidence** based on path comparison alone:
+These files exist in `indusagi-screth` but not in Indusagi Mono, so they are **not immediate Indusagi Mono overlap evidence** based on path comparison alone:
 
 
 
@@ -1716,7 +1716,7 @@ These files exist in `indusagi-screth` but not in PI Mono, so they are **not imm
 
 
 
-These still deserve provenance review, but they are **not first priority** for PI Mono separation.
+These still deserve provenance review, but they are **not first priority** for Indusagi Mono separation.
 
 
 
@@ -1756,7 +1756,7 @@ These still deserve provenance review, but they are **not first priority** for P
 
 ## Phase 4 — Final cleanup
 
-8. Re-run repo comparison against PI Mono.
+8. Re-run repo comparison against Indusagi Mono.
 
 9. Confirm there are no exact-match code files left.
 
@@ -1774,13 +1774,13 @@ These still deserve provenance review, but they are **not first priority** for P
 
 
 
-You can make a much stronger statement like _"`indusagi-screth` is no longer PI Mono-derived"_ only when all of the following are true:
+You can make a much stronger statement like _"`indusagi-screth` is no longer Indusagi Mono-derived"_ only when all of the following are true:
 
 
 
-- [ ] No exact identical PI Mono code files remain.
+- [ ] No exact identical Indusagi Mono code files remain.
 
-- [ ] No copied PI Mono vendor assets remain unless separately sourced and attributed.
+- [ ] No copied Indusagi Mono vendor assets remain unless separately sourced and attributed.
 
 - [ ] High-risk core files have been independently rewritten.
 
@@ -1858,7 +1858,7 @@ These percentages are **approximate line-based estimates**, not legal determinat
 
 Method used:
 
-- compare the PI Mono file and the `indusagi-screth` file at the same relative path
+- compare the Indusagi Mono file and the `indusagi-screth` file at the same relative path
 
 - use line counts plus `git diff --no-index --numstat` style added/deleted line counts