Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 4 additions & 70 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@ name: CI
# Required check names:
# - Typecheck, Test & Build
# - Client bundle carries no secrets
# - Inference Ledger (Postgres)
# - Dependency audit

on:
Expand Down Expand Up @@ -110,14 +109,10 @@ jobs:
include-hidden-files: true
retention-days: 14

# Golden-path e2e (apex A3): drives the real built app — spawn Investor
# shell → blocks render → wires live → mock-LLM Think streams → persists
# across reload. The LLM is the OMNI_E2E server double (no keys needed).
# This guards the UI wiring layer where unit tests can't see.
#
# The harness is `next start`, not the Worker: the Worker bundle compiles
# demo mode in (vite.config.ts `define`), which turns /api/llm into a 503
# and so cannot run this path. Nothing deploys `.next`; it is a test rig.
# Golden-path e2e (apex A3): drives the built app — spawn Investor shell →
# blocks render → wires live → Think explains AI is off → persists across
# reload. This guards the UI wiring layer where unit tests can't see.
# Nothing deploys `.next`; it is a test rig.
- name: Build the e2e harness (Next server)
run: npm run build:next

Expand Down Expand Up @@ -203,67 +198,6 @@ jobs:
- name: Scan client bundle
run: npm run scan:bundle

# ============================================
# The inference ledger against a real Postgres.
#
# Its own job so the main gate stays dependency-free: `npm test` skips the
# integration file unless OMNI_TEST_DATABASE_URL is set. This is the only
# place the CHECK constraints, the foreign keys, the cascade, the recursive
# lineage walk and the migration runner are actually executed rather than
# asserted about.
# ============================================
ledger:
name: Inference Ledger (Postgres)
runs-on: ubuntu-24.04
timeout-minutes: 15

services:
postgres:
image: postgres:16
env:
POSTGRES_USER: omni
POSTGRES_PASSWORD: omni
POSTGRES_DB: omni_test
ports:
- 5432:5432
options: >-
--health-cmd pg_isready
--health-interval 10s
--health-timeout 5s
--health-retries 5

env:
OMNI_TEST_DATABASE_URL: postgres://omni:omni@localhost:5432/omni_test

steps:
- name: Checkout
uses: actions/checkout@v7.0.1

- name: Setup Node
uses: actions/setup-node@v7.1.0
with:
node-version-file: .nvmrc
cache: npm

- name: Install dependencies
run: npm ci

# Proves the runner and the migrations themselves, not just the SQL text.
- name: Migrate
run: npm run db:migrate
env:
DATABASE_URL: postgres://omni:omni@localhost:5432/omni_test

# Re-running must be a no-op: migrations are IF NOT EXISTS, constraint
# adds are guarded on pg_constraint, and applied files are recorded.
- name: Migrate again (idempotent)
run: npm run db:migrate
env:
DATABASE_URL: postgres://omni:omni@localhost:5432/omni_test

- name: Test (integration included)
run: npm test

# ============================================
# Dependency audit.
#
Expand Down
50 changes: 21 additions & 29 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,20 @@ Rules for agents (and people) changing OmniOS. Read `README.md` first,

## The product

- **The canvas is the product.** Blocks pull live data, wires say what feeds what,
personas answer from what their wires carry.
- **A persona's context is its inbound wires.** Nothing else may enter a persona
turn silently. If a source informed an answer, the user can point at the wire.
- **The canvas is the product.** Blocks pull live data, wires say what feeds what.
Personas sit on the canvas, but the public preview gives no AI answers.
- **Keep only what the live deployment reaches.** This repo is the public preview
at omni.syberlabs.io (`DEPLOYMENT.md`). A path no live deployment can reach is
dead and gets deleted (`APEX_PLAN.md` §7).
- **No second product surface.** The agent surface moved to `SyberLabs/omni-agent`
and the Garden was deleted (2026-09-01). Do not add a parallel app to this repo.
- Local-first and single-user. LLM and built-in data-provider keys are read
server-side from `process.env`. A credential you enter for a compiled API lives
- Local-first and single-user, with no server secrets. A credential you enter for a compiled API lives
in browser memory for the session (`src/core/capabilities/secrets.ts`) and is
attached to the capability's own request. It is persisted only if the person
turns on "Remember keys on this device": then it is sealed with AES-GCM under a
non-extractable browser key in its own IndexedDB database
(`src/core/capabilities/keyVault.ts`), never in a canvas or account backup and
never on a server. A deployed
instance goes on a private network (`DEPLOYMENT.md`).
never on a server.

## Authority boundaries

Expand All @@ -28,10 +27,7 @@ Rules for agents (and people) changing OmniOS. Read `README.md` first,
on 2026-10-08 (MasterMind `docs/contracts/account-saves-v1.md`). These are only
uploaded by Save to account, never synchronized automatically; restore crosses
vault validators and resets capability approvals. The backup exception does not
move live canvas authority. **Postgres owns only server-side run records**: inference
runs (`INFERENCE_LEDGER.md`) and the capability broker's execution rows
(`db/migrations/004_capability_execution.sql`). Do not move live canvas authority to a
server, and do not put canvas state in Postgres.
move live canvas authority. Do not move live canvas authority to a server.
- **A manifest never grants itself authority.** Compilers only propose a
`CapabilityManifest`. `installProposal` registers it, write and destructive
effects need `approveCapability`, and `executeCapability` is the one runtime.
Expand All @@ -53,13 +49,12 @@ Run all of these; each is a script in `package.json`. Node comes from `.nvmrc`.
npm run typecheck # tsc --noEmit, 0 errors
npm run lint # eslint, 0 errors (warnings are tracked debt)
npm test # vitest
npm run build # next build
npm run scan:bundle # no secret reached .next/static (needs build first)
npm run test:e2e # playwright golden path (needs build first)
npm run build # the Worker bundle that deploys
npm run scan:bundle # no secret reached dist/client (needs build first)
npm run build:next # the Next server the e2e harness drives
npm run test:e2e # playwright golden path (needs build:next first)
```

Postgres-backed tests are skipped unless `OMNI_TEST_DATABASE_URL` points at a
scratch database. They `TRUNCATE`, so never use the database in `.env`.
Docs-only changes still run the checks that a docs edit can break (at least
`typecheck` and `lint`), and every path or script a doc names must exist.

Expand Down Expand Up @@ -90,18 +85,15 @@ Docs-only changes still run the checks that a docs edit can break (at least

Stop and ask the owner instead of proceeding when a change would:

1. **Let model output mutate canvas state without the interaction engine's
admission.** LLM text, a persona answer, or a compiled manifest must not add,
move, delete, or wire blocks on its own.
2. **Cite a source that carried no data.** An empty array or an empty Memory pool
must produce no source chip (`FINDINGS.md`).
3. **Add new write-effect capability surface** (a new path that can run POST, PUT,
1. **Let generated output mutate canvas state without the interaction engine's
admission.** A compiled manifest must not add, move, delete, or wire blocks on
its own.
2. **Add new write-effect capability surface** (a new path that can run POST, PUT,
PATCH, or DELETE, or a new way to approve one) without an explicit product need.
This surface is frozen on the SyberLabs MasterMind 2026-09-29 recommendation,
pending an owner decision.
4. Put a secret, or a value derived from one, into `.next/static`, a log, or the
inference ledger.
5. Make the app public-facing without the checklist in `DEPLOYMENT.md`.
3. Put a secret, or a value derived from one, into `dist/client` or a log.
4. Serve anything from the public host that spends a key or reads shared data.

## Claim discipline

Expand All @@ -125,10 +117,10 @@ measurement exists. Do not write "works with any API" or
- `src/core/capabilities/` compilers, registry, execution, `DESIGN.md`
- `src/core/interaction/` command engine, speech grammar, push-to-talk
- `src/core/stores/` Zustand stores over the vault; `wireStore.ts` admits wires
- `src/core/services/` persona turns, wire context, LLM client; `server/` holds server-only code
- `src/core/services/` persona turns, cascade order, ports; `server/` holds the public data proxy
- `src/core/gateway/` `ApiGateway` and normalizers for the built-in data sources
- `src/app/api/` server routes (LLM proxy, capability broker, inference runs)
- `e2e/` Playwright specs; `db/migrations/` ledger schema
- `src/app/api/` the public data routes and the 503 stubs the deploy gate checks
- `e2e/` Playwright specs

## Cross-repo architecture

Expand Down
55 changes: 35 additions & 20 deletions APEX_PLAN.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# OmniOS roadmap

Reviewed 2026-09-26. OmniOS is a local-first canvas for connecting data blocks to
AI personas and seeing which sources informed each response.
Reviewed 2026-09-26. OmniOS is a local-first canvas for connecting data blocks.
Section 7 records what was cut on 2026-11-02; sections 3 and 6 are history and
name work that section removed.

## 1. Product core

- Shells save blocks, positions, and wires; built-in templates create working shells.
- Data blocks fetch and normalize public or configured provider data.
- Persona turns use active inbound wires, stream a response, and retain source
provenance. Optional Postgres records inference runs and their lineage.
- IndexedDB stores local canvas state. Provider calls that use credentials pass
through server routes.
- Personas sit on the canvas and say AI answers are off in the public preview.
- IndexedDB stores local canvas state. Keyless public data goes through server
routes; a key a person enters goes straight from the browser to that API.

## 2. Current boundaries

Expand All @@ -21,27 +21,16 @@ AI personas and seeing which sources informed each response.
`src/core/interaction/ports.ts`), and only the first input and first output
port are checked. An untyped output acts as `any`: it feeds `any` inputs
(personas) or string-sink schemas through a `text` projection, and typed
text/json inputs without a string sink refuse it. Persona context
(`aggregateWireContext`) ignores ports and projections; projections apply
only in capability execution (`wireInputs.ts`).
- **Mind-panel Think sees what the canvas shows.** `captureShellSnapshot`
(used by `think()`) keeps only blocks of the active shell that have a wire in
or out, or are pinned, plus only the wires between them and the pins on them.
It does not read the observations pool, so earlier answers do not reach the
prompt. With
nothing in scope, Think is refused unless the caller passes a question
(Quick Ask).
text/json inputs without a string sink refuse it. Projections apply only in
capability execution (`wireInputs.ts`).

## 3. Done (merged 2026-10-01)

1. **Block accessibility tree** (#75). dnd-kit's `attributes` and `listeners`
are spread on the grip only (`src/components/blocks/BlockCard.tsx`), so a
card is no longer a `role="button"` around its own controls. See
`FINDINGS.md`.
2. **Recorded inference lineage** (#72). `src/blocks/persona/RunLineage.tsx`
reads the runs behind a persona answer through
`GET /api/inference-runs/:id/lineage` and draws the tree from a toggle
under the answer.
2. **Recorded inference lineage** (#72). Removed in section 7.
3. **Persisted wires re-validated on load** (#74). Every load path runs the
same `admitWire` as the live canvas: shell restore and templates through
`replaceWiresForShell`, vault-hydrated wires through
Expand Down Expand Up @@ -106,3 +95,29 @@ this order:
with read-only scopes only. No live sign-in has been run (no client is
registered). The API index still counts Google APIs as unusable until it
is rebuilt (`npm run catalog:build`).

Items 1, 6, 7 and 8 were removed in section 7.

## 7. Reachability cut (2026-11-02)

Rule from the owner: a path is dead if no live deployed app can reach it. The one
live app is the Worker at omni.syberlabs.io, with demo mode on, no secret and no
database, so everything behind those facts went. Last present at `8a21350`:

- Model answers: the LLM client and route, persona prompts and engine, the Mind
engine, kernel, crystallize, run lineage, the Think result modal, markdown
rendering of answers. A turn now commits the preview's refusal.
- Postgres, migrations, the inference ledger, hosted OIDC auth.
- The capability broker's server side and data plant (house keys). A brokered
block still runs and shows the broker's 503.
- OAuth sign-in. A Google block still says sign-in is not set up.
- Remote speech (OpenAI Realtime). The browser recognizer remains.
- Jev and Kev persona suggestions and meaning search. Keyword search remains.
- MCP and async transports, manifest provenance: no production caller bound one.
- Tooling only those paths used: `forge:spec`, `eval:registry-jev`,
`metrics:line`, `db:migrate`, the speech field harness.

Kept because they build or guard the live artifact: `verify:curated` and the
nightly quality line (they write `public/curated-quality.json`, which search
shows), `catalog:build` (`public/api-index.json`), `scan:bundle`, the tests of
live code, and the 503 stubs the deploy gate checks.
Loading
Loading