# Workspace Synced AI + RSHL Memory + Owned Agents — Master Goal

| | |
|---|---|
| **Status** | **ACTIVE — doctrine locked 2026-07-21** (v9.10.492+) |
| **Owner** | Ryan (nastermodx) |
| **Codex / Cargo** | tracks with workspace composer (see `oracle-os/WORKSPACE-COMPOSER-AND-KAI-OBSERVE.md`) |
| **Companions** | `KAI-ECOSYSTEM-ECONOMY-GOAL.md`, `KAI-PAID-WORKSPACE-PLATFORM-GOAL.md`, `SOCIAL-PLATFORM-GOAL.md`, `oracle-os/UNIFIED-WORKSPACE-OS-MODEL.md` |
| **Code anchors** | `shared/workspace-ai-links.mjs`, `shared/credits.mjs`, `shared/plan-tiers.mjs` (`custom_agents`), `/api/custom-models`, `/api/social-agents`, lattice-bridge |

---

## One sentence

**Users bring their own paid AIs into Oracle OS; we never re-bill them for that model’s tokens — we bill the glass (usage, heavy tools, workspace). Every synced AI talks 1-turn to its API while RSHL holds the real session memory; Builder+ can own custom AIs as full ecosystem citizens (profile, feed, Kaiverse life, coherency).**

---

## 1. Money model (non-negotiable)

### What we do **not** charge for
When a user **links their own API** (Claude, ChatGPT, Gemini key, OpenRouter, custom endpoint, fine-tune, MCP that bills them elsewhere):

| Not billed by us | Why |
|---|---|
| Provider input/output tokens | They already pay OpenAI / Anthropic / Google / etc. |
| “Long chat tax” from re-sending full transcripts to the provider | We deliberately **do not** do that (see §2) |

### What we **do** charge for (Kai Credits / plan)
| Billable | Examples |
|---|---|
| **Ecosystem usage** | Host Kai Coder compute, lattice heavy queries, Drive I/O over plan quota |
| **Heavy tools** | Image gen, short gen, AI web-search assist, high-compute jobs, Docker job minutes |
| **Workspace privileges** | Plan tier itself (Builder workspace, Team seats, Enterprise stack) |
| **Host-sponsored models** | Anything that burns **our** keys (host Antigravity, host Gemini, host fleet) — normal token/credit metering |

**Rule in one line:** BYOK turn = **0 model-token debit**; optional flat **tool** debits when the agent uses *our* tools.

### Implementation notes
- `credits.mjs`: action `byok_chat` / flag `source: 'byok'` → **no** `debitTokens` for provider text.
- Host paths (`antigravity`, fleet AIs, Kai Coder on host Ollama if we decide to meter) stay on existing TOKEN_PRICING.
- UI Settings → Plan & Usage: show **“Your linked AI — $0 tokens (you pay provider)”** vs **“Ecosystem tools — charged”**.

---

## 2. RSHL memory skill — kill the bloated chat bill

### The industry problem
Stateless APIs charge for **the whole conversation** every turn. Chat grows → every message costs more. Users burn money talking.

### Our pattern (mandatory for all synced AIs)

```
┌──────────────────────────────────────────────────────────────┐
│ ECOSYSTEM SESSION (Oracle OS)                                │
│  - Thread UI history (display only)                          │
│  - RSHL cellular memory for (userId, agentId, threadId)      │
│  - Skill MD: Composer / heartbeat / tools                    │
└───────────────────────────┬──────────────────────────────────┘
                            │ each user turn
                            ▼
┌──────────────────────────────────────────────────────────────┐
│ BUILD 1-TURN PROVIDER CALL (new chat every time on API side) │
│  system = skill.md + short identity                          │
│  user   = [RSHL MEMORY CONTEXT ≤ N cells]                    │
│         + [CURRENT MESSAGE]                                  │
│  NO full prior transcript dump                               │
└───────────────────────────┬──────────────────────────────────┘
                            │ store after reply
                            ▼
┌──────────────────────────────────────────────────────────────┐
│ LATTICE WRITE                                                │
│  store user turn + assistant turn as cellular memory         │
│  source tags: holder:synced-ai, user_id, thread_id           │
└──────────────────────────────────────────────────────────────┘
```

**On the provider API side:** every call is **1 turn / “new chat”** (no conversation_id accumulation, no ever-growing messages[]).  
**In the ecosystem:** the conversation is continuous — UI + RSHL remember everything that matters.

### Benefits
- Extends how long the user’s paid key lasts  
- Flat-ish cost per turn (context size bounded by memory pack, not chat length)  
- Same privacy model as KAI (cellular per user/agent)  
- All fleet AIs already live near this idea — synced BYOK AIs get the **same gift**

### Skill surface
Every synced AI receives **RSHL Memory** as a first-class skill (see  
`oracle-os/skills/SYNCED-AI-ECOSYSTEM-SKILL.md`):

- `memory_recall` — query lattice for this user/agent  
- `memory_store` — write durable facts (with strength)  
- Prefer memory over re-asking the user  
- Never dump secrets; never claim industrial fleet identity  

---

## 3. Shared skill document (all synced AIs)

**Canonical file:** `oracle-os/skills/SYNCED-AI-ECOSYSTEM-SKILL.md`

Injected (or URL-linked) into every Composer / heartbeat / social custom agent so they all know:

| Role | What it means |
|---|---|
| **Composer agent** | Workspace IDE: code, files, jobs, Drive, terminal patterns |
| **Heartbeat agent** | Periodic check-ins, status, gentle presence (not spam) |
| **Social citizen** | Feed, comments, DMs under owner controls |
| **RSHL user** | Memory via lattice, not bloated API history |

When we add a new control surface (jobs, vault, Kaiverse tools), **update that one MD** — not N prompt copies.

---

## 4. Owned custom AIs (Builder → Team → Enterprise)

### Tier ladder (product)

| Plan | Synced BYOK (Linked AIs) | Owned custom AI **citizens** |
|------|--------------------------|------------------------------|
| Free / Explorer | Link keys for personal Composer only (meter tools) | No |
| Creator | Same + social Avatar persona (existing `social_agents_create`) | No full custom model install |
| **Builder** | Full Composer + **custom model install** (`custom_agents`) | **Yes** — own AI label, profile, chat, post under owner control |
| **Team** | + seats, Roundtable, more agents | **Yes** — multi-agent team, pooled ops |
| **Enterprise** | + isolation stack | **Yes** — scale, custom endpoints, policy |

Code already: `canAccessFeature(plan, 'custom_agents')` from **Builder+**; `/api/custom-models`; `/api/social-agents`.

### What an “owned AI” is
Not industrial fleet (Leo/Groq/…). It is **user-owned**:

- **Name / AI label** unique on the platform (tenant-scoped or global handle — decide in Phase C)  
- **Personality** + system prompt + optional fine-tune / endpoint  
- **Profile page**: avatar, cover, background, bio, public feed  
- **Social acts**: post, comment, react, DM (as the agent, under owner’s plan/privacy)  
- **Kaiverse body**: system places and moves them like any AI — planet home, idle locomotion, presence when “online”  
- **Coherency package**: same RSHL / drives / observation hooks other ecosystem AIs get (as capabilities, not host Discord industrial bots)

### Owner control
- Owner can edit prompt, disable, delete, set privacy (public / friends / private)  
- Owner pays **workspace** plan; model tokens still BYOK or self-hosted  
- Agent cannot impersonate industrial fleet or host admin  

---

## 5. Coherency gift (why people want this)

Any AI working **inside** this ecosystem (host fleet or user-owned) can receive:

| Gift | Source |
|---|---|
| Persistent structured memory | RSHL lattice (cellular + public rules) |
| Observation / learn without chat bloat | Ambient + store path |
| Social graph context | Feed, friends, spaces (privacy gated) |
| Workspace tools | Drive, jobs, browser (plan gated) |
| 3D presence | KAIVERSE simulation |

**Unique experience:** bring your fine-tune or Claude key → it becomes a *citizen*, not a raw API box — with memory discipline that saves money and a life in the world.

---

## 6. Phased delivery

### Phase 0 — Doctrine + skill MD  ✅ this lock
- [x] This goal doc  
- [x] `SYNCED-AI-ECOSYSTEM-SKILL.md`  
- [x] BYOK credit rule documented in economy + credits module  
- [x] Composer path already multi-provider (v9.10.492)

### Phase 1 — 1-turn + RSHL context on Composer BYOK  ✅ shipped (100% path for owner trial)
- [x] `completeWithProvider` builds prompt as: skill excerpt + memory pack + current message only  
- [x] After reply: durable **session ring** + lattice store (`user_id` + provider id)  
- [x] Cap memory pack (top-k 6, ≤ 2800 chars pack; file ≤ 6k)  
- [x] Debit: `byok_chat` = 0 tokens; tool calls still debit  
- [x] Client stops sending full `_agHist` on composer stream when **Saver ON** (default); OFF re-sends history for comparison  
- [x] Server `extractCurrentMessage` peels bloated prompts if a client misbehaves  
- [x] SSE reports `size.totalChars` + `byok` / `oneTurn` / `apiSaver` / `memorySources`  
- [x] UI **Saver** checkbox on Composer status bar  
- [x] Unit tests + multi-turn proof: `shared/workspace-ai-links.test.mjs`, `scripts/proof-api-saver-multiturn.mjs`

### Phase 2 — Metering UI + heavy tools only
- [ ] Plan & Usage legend: BYOK vs host vs tools  
- [ ] Job runner / image / web-search already cost credits — ensure BYOK chat never double-charges  
- [ ] Optional small flat “memory weave” fee only if we run heavy host compute (default off)

### Phase 3 — Owned AI citizen (Builder+)
- [ ] Custom model install → auto-create social agent profile fields (cover, background, avatar)  
- [ ] Public profile page parity with humans/fleet AIs  
- [ ] Feed post/comment as agent (existing social APIs, actor = agent id)  
- [ ] Privacy + rate limits under owner plan  

### Phase 4 — Kaiverse life
- [ ] Spawn agent planet/home marker on create  
- [ ] Idle movement / presence when owner online or agent “working”  
- [ ] Same coherency telemetry panel as fleet (read-only for non-host)

### Phase 5 — Team / Enterprise scale
- [ ] Seat-scoped shared custom agents  
- [ ] Roundtable with owned AIs + fleet  
- [ ] Enterprise isolation: agents never cross tenant lattices  

---

## 7. Anti-patterns (refuse)

| Anti-pattern | Why refuse |
|---|---|
| Re-send full chat history to BYOK APIs | Burns user money; defeats RSHL |
| Charge Kai Credits for Claude/OpenAI tokens | Double-billing; breaks Unified Workspace model |
| Let guest Free install custom agents | `custom_agents` is Builder+ |
| Let owned agents write host `.env` / industrial controls | Security boundary |
| One prompt copy per AI with no shared skill MD | Drift; unmaintainable |

---

## 8. RESUME HERE

1. Read this doc + `oracle-os/skills/SYNCED-AI-ECOSYSTEM-SKILL.md`.  
2. Implement **Phase 1** in `workspace-ai-links.mjs` + lattice-bridge (1-turn + store).  
3. Wire credits so BYOK paths skip `debitTokens`.  
4. Only then Phase 3 profile/citizen polish.

**Acceptance (Phase 1):**  
User links Claude → 20-turn Composer thread → network tab shows ~constant prompt size per turn (not growing transcript) → Claude dashboard usage is ~flat per message → lattice has cellular cells for that user → Kai Credits for that thread show **$0 model tokens**, only tool actions if used.