indusagi-coding-agent 0.1.59 → 0.1.60

package/guides/INDUSVX_OBSERVE_FULL_INTEGRATION_REPORT.md

@@ -1,543 +0,0 @@
-# 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/react-ink/interactive-mode.tsx`
-
-### 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.