indusagi-coding-agent 0.1.42 → 0.1.43

package/guides/INDUSVX_OBSERVE_FULL_INTEGRATION_REPORT.md

@@ -0,0 +1,543 @@
+# Use `indusvx-screth` locally as `indusagi` and get full Observe in `indusagi-screth`
+
+Date: 2026-03-30
+
+## What this document is about
+
+This report is **not** about copying all `indusvx-screth` source code into `indusagi-screth`.
+
+This report is about this exact goal:
+
+- keep `indusagi-screth` as the app repo
+- keep app imports like `indusagi/agent`, `indusagi/ai`, `indusagi/tui`
+- **replace the installed npm `indusagi` package with local `../indusvx-screth`**
+- then use **`indusvx-screth` Observe** inside `indusagi-screth` through normal imports
+- get as much of the full observability power as possible **without copying the whole codebase**
+
+---
+
+# Final answer
+
+## Yes, this is the right approach
+
+If your goal is:
+
+- do **not** move all `indusvx-screth` code into `indusagi-screth`
+- do **not** rewrite `indusagi-screth` into an `indusvx` repo
+- keep using imports named `indusagi/...`
+- but actually use your local `indusvx-screth` package and its Observe stack
+
+then the correct direction is:
+
+## 1) install local `indusvx-screth` under the dependency name `indusagi`
+
+In `indusagi-screth/package.json`, use:
+
+```json
+{
+  "dependencies": {
+    "indusagi": "file:../indusvx-screth"
+  }
+}
+```
+
+That means:
+
+- `indusagi-screth` still writes imports like `import { Agent } from "indusagi/agent"`
+- but npm resolves that dependency from your local `../indusvx-screth`
+- so at runtime/build time, `indusagi-screth` is actually using local `indusvx-screth`
+
+## 2) use Observe from normal package imports
+
+Inside `indusagi-screth`, import like this:
+
+```ts
+import {
+  createObserve,
+  ObserveClient,
+  InMemoryObserveServer,
+  FileObserveControlPlaneStore,
+  FileObserveArtifactContentStore,
+  ObserveHttpServer,
+} from "indusagi/observe";
+```
+
+So the app still looks like it uses `indusagi`, but the implementation comes from local `indusvx-screth`.
+
+---
+
+# Very important clarification
+
+## We should NOT do this
+
+Do **not**:
+
+- copy `src/observe/**` from `indusvx-screth` into `indusagi-screth`
+- copy `agent`, `ai`, `mcp`, `tui` source trees into `indusagi-screth`
+- maintain two duplicated implementations
+
+That would create:
+
+- drift
+- harder upgrades
+- more bugs
+- messy ownership
+
+## We SHOULD do this
+
+- keep `indusvx-screth` as the package implementation source
+- keep `indusagi-screth` as the application/shell repo
+- connect them through the package dependency named `indusagi`
+- wire Observe in `indusagi-screth` by importing from `indusagi/observe`
+
+That is the cleanest path.
+
+---
+
+# Main architecture idea
+
+## Desired setup
+
+### `indusvx-screth`
+Owns:
+
+- `agent`
+- `ai`
+- `mcp`
+- `tui`
+- `observe`
+- low-level runtime instrumentation
+
+### `indusagi-screth`
+Owns:
+
+- coding-agent app shell
+- CLI / modes
+- settings
+- auth
+- extension runtime
+- hooks
+- session orchestration
+- app-specific wiring
+
+So the app shell stays in `indusagi-screth`, but its engine comes from local `indusvx-screth`.
+
+---
+
+# How `indusagi-screth` should use Observe
+
+## Core idea
+
+After local package replacement, `indusagi-screth` should use Observe like any normal package feature:
+
+```ts
+import { createObserve } from "indusagi/observe";
+```
+
+No source copy needed.
+
+---
+
+# Recommended package setup
+
+## Best local-dev package change
+
+In `indusagi-screth/package.json` change:
+
+```json
+"indusagi": "^0.12.22"
+```
+
+to:
+
+```json
+"indusagi": "file:../indusvx-screth"
+```
+
+## Why this is the best option
+
+Because it gives you all of this:
+
+- existing imports stay the same
+- no mass refactor of source files
+- `indusagi-screth` still feels like an `indusagi` app
+- actual implementation comes from your local repo
+- Observe can be imported from `indusagi/observe`
+
+---
+
+# Build/install flow
+
+## Required flow
+
+Whenever you want `indusagi-screth` to use the latest local `indusvx-screth`:
+
+### 1. Build local package
+
+In `indusvx-screth`:
+
+```bash
+npm run build
+```
+
+### 2. Reinstall or refresh dependency in app repo
+
+In `indusagi-screth`:
+
+```bash
+npm install
+```
+
+### 3. Build app repo
+
+```bash
+npm run build
+```
+
+### 4. Test
+
+```bash
+npm test
+```
+
+---
+
+# How to use full Observe power in `indusagi-screth`
+
+## Goal
+
+Use these `indusvx-screth` Observe pieces via `indusagi/observe`:
+
+- `ObserveRuntime`
+- `ObserveClient`
+- `InMemoryObserveServer`
+- `FileObserveControlPlaneStore`
+- `FileObserveArtifactContentStore`
+- `ObserveHttpServer`
+- `ObservePanel`
+- privacy controls
+
+---
+
+# Recommended integration points in `indusagi-screth`
+
+## 1. Bootstrap Observe once in app startup
+
+### File
+- `app/main.ts`
+
+### What to do
+Create one Observe stack at startup.
+
+Example shape:
+
+```ts
+import {
+  createObserve,
+  ObserveClient,
+  InMemoryObserveServer,
+  FileObserveControlPlaneStore,
+  FileObserveArtifactContentStore,
+  ObserveHttpServer,
+} from "indusagi/observe";
+```
+
+Then initialize:
+
+- runtime exporter
+- control-plane store
+- artifact store
+- query backend
+- optional dashboard server
+- observe client
+
+### Why here
+This lets all app modes share one observability setup.
+
+---
+
+## 2. Pass Observe into runtime session creation
+
+### File
+- `app/runtime/sdk.ts`
+
+### What to add
+Extend session creation options so the app can pass Observe handles down.
+
+Example direction:
+
+```ts
+observe?: {
+  runtime: ReturnType<typeof createObserve>;
+  client?: ObserveClient;
+  server?: InMemoryObserveServer;
+}
+```
+
+### Why this matters
+This is the main handoff point between app shell and low-level engine.
+
+---
+
+## 3. Use Observe in the real agent/model flow
+
+### File
+- `app/runtime/sdk.ts`
+
+### Important functions
+- `createAgentInstance(...)`
+- `createStreamWithHooks(...)`
+- `createAgentSession(...)`
+
+### What to do
+Use Observe there so real runs produce:
+
+- trace
+- spans
+- events
+- tool metadata
+- model-generation metadata
+- errors
+
+If `Agent` in the local package supports `observe`, pass it directly.
+If not, wrap around it at the app layer first.
+
+---
+
+## 4. Instrument session lifecycle in the app shell
+
+### File
+- `app/runtime/agent-session.ts`
+
+### High-value targets
+- `prompt(...)`
+- `newSession(...)`
+- `switchSession(...)`
+- `fork(...)`
+- `compact(...)`
+- `executeBash(...)`
+- MCP registration/reconnect
+- memory enable/disable
+
+### Why
+This is how you get full app-level observability, not just model-call logging.
+
+---
+
+## 5. Turn on dashboard and API
+
+### Use from package import
+
+```ts
+import { ObserveHttpServer } from "indusagi/observe";
+```
+
+### Result
+`indusagi-screth` can expose:
+
+- health endpoint
+- stats endpoint
+- records endpoint
+- control-plane endpoints
+- dashboard HTML UI
+
+So you get a Langfuse-like local inspection surface without copying code.
+
+---
+
+## 6. Use artifact and control-plane features
+
+### Package imports
+
+```ts
+import {
+  ObserveClient,
+  FileObserveControlPlaneStore,
+  FileObserveArtifactContentStore,
+} from "indusagi/observe";
+```
+
+### Use for
+- prompts
+- traces
+- datasets
+- experiments
+- scores
+- artifacts
+- persisted snapshots
+
+This gives the app richer observability than simple log files.
+
+---
+
+## 7. Use TUI Observe helpers from package import
+
+### Package imports
+
+```ts
+import {
+  ObservePanel,
+  buildObservePanelSnapshot,
+  createObservePanelOverlayMetadata,
+} from "indusagi/observe";
+```
+
+### Integrate in
+- `app/interfaces/terminal-ui/interactive-mode.ts`
+
+### Result
+You can show:
+
+- live stats
+- trace counters
+- errors
+- recent spans/events
+- dashboard URL
+
+Again: no source copy, only package usage.
+
+---
+
+# Full-potential observability path
+
+If you want "full potential" observability in `indusagi-screth`, the package-based path should look like this:
+
+## Step 1
+Make `indusagi-screth` consume local `indusvx-screth` as dependency `indusagi`.
+
+## Step 2
+Import and bootstrap Observe from `indusagi/observe`.
+
+## Step 3
+Pass Observe through the app runtime so real agent runs use it.
+
+## Step 4
+Enable:
+
+- file exporter or custom exporter
+- control-plane store
+- artifact store
+- HTTP observe server
+- privacy config
+- TUI panel
+
+## Step 5
+Add app-level instrumentation in `sdk.ts` and `agent-session.ts`.
+
+That is the correct way to get near-full power while keeping clean boundaries.
+
+---
+
+# Practical answer
+
+For this plan, the direction is simple:
+
+1. keep `indusagi-screth` app code where it is
+2. do **not** copy `indusvx-screth` source into it
+3. point dependency `indusagi` to local `../indusvx-screth`
+4. import Observe from `indusagi/observe`
+5. wire Observe into `app/main.ts`, `app/runtime/sdk.ts`, and `app/runtime/agent-session.ts`
+6. use the dashboard, control-plane store, artifact store, privacy controls, and TUI helpers from package imports
+
+That is the architecture this document recommends.
+
+---
+
+# Best recommendation
+
+## If the priority is observability first
+
+Do this:
+
+1. keep `indusagi-screth` app code where it is
+2. do **not** copy `indusvx-screth` source into it
+3. point dependency `indusagi` to local `../indusvx-screth`
+4. import Observe from `indusagi/observe`
+5. wire Observe into `app/main.ts`, `app/runtime/sdk.ts`, and `app/runtime/agent-session.ts`
+6. use the full Observe stack through package imports
+
+That gives you the right architecture.
+
+---
+
+# Example mental model
+
+## Wanted model
+
+`indusagi-screth` says:
+
+```ts
+import { Agent } from "indusagi/agent";
+import { createObserve } from "indusagi/observe";
+```
+
+But because `package.json` points `indusagi` to:
+
+```json
+"file:../indusvx-screth"
+```
+
+those imports actually use your local `indusvx-screth` implementation.
+
+That is exactly the package-level swap you want.
+
+---
+
+# Testing checklist
+
+After switching the dependency to local `indusvx-screth`:
+
+## In `indusvx-screth`
+
+```bash
+npm run build
+npm test
+```
+
+## In `indusagi-screth`
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Then validate observability
+
+- start app flow
+- confirm `indusagi/observe` imports work
+- confirm traces/spans/events are emitted
+- confirm dashboard server starts
+- confirm artifacts/control-plane files are written
+- confirm TUI still works
+- confirm privacy redaction works
+
+---
+
+# One-line conclusion
+
+## Correct direction
+
+**Do not copy `indusvx-screth` code into `indusagi-screth`. Instead, make `indusagi-screth` use local `indusvx-screth` as the installed `indusagi` package, then import and wire full observability from `indusagi/observe`.**
+
+---
+
+# What I would do next
+
+If you want, next I can update the actual code for this package-based approach in one of these ways:
+
+## Option 1 — docs/package only
+- change `indusagi-screth/package.json` to local `file:../indusvx-screth`
+- document the local build/install flow
+
+## Option 2 — real Observe wiring
+- keep imports as `indusagi/...`
+- wire `indusagi/observe` into:
+  - `app/main.ts`
+  - `app/runtime/sdk.ts`
+  - `app/runtime/agent-session.ts`
+
+## Option 3 — compat path
+- create a minimal local compat package strategy so memory imports do not break
+
+If you want, I can do **Option 2 next** and keep everything package-based, no source-copy approach.