diff --git a/.env.example b/.env.example index 828582ff..19c41ccf 100644 --- a/.env.example +++ b/.env.example @@ -98,7 +98,13 @@ PHONE_TRANSCRIBE_API_KEY= SUPERMEMORY_API_KEY= # Optional. Defaults to https://api.supermemory.ai. Self-hosted: http://localhost:6767 SUPERMEMORY_API_URL= +# Transactional auth email (verification and password reset). Leave blank and +# those flows report "belum tersedia" instead of failing at boot. +# Format: smtp://user:pass@host:587 or smtps://user:pass@host:465 SMTP_URL= +# Sender address for the emails above. Defaults to the SMTP_URL user when the +# URL carries credentials, so it is only required for credential-free relays. +SMTP_FROM= VAPID_PUBLIC_KEY= VAPID_PRIVATE_KEY= OTEL_EXPORTER_OTLP_ENDPOINT= diff --git a/.gitattributes b/.gitattributes index 2f57ad86..cf9eb7e0 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,7 +1,8 @@ * text=auto eol=lf + *.sh text eol=lf infra/sandboxes/computer/sentrabot-browser text eol=lf infra/sandboxes/computer/fluxbox.* text eol=lf -*.png filter=lfs diff=lfs merge=lfs -text -*.jpg filter=lfs diff=lfs merge=lfs -text -*.ico filter=lfs diff=lfs merge=lfs -text +*.png binary +*.jpg binary +*.ico binary diff --git a/README.md b/README.md index 208ba0be..189e5a86 100644 --- a/README.md +++ b/README.md @@ -1,863 +1,863 @@ -
-
-
- |
-
-
-### [`SENTRA / BOT`](https://sentrahai.com/)
-
-
- -The autonomous intelligence layer of Sentra Artificial Intelligence. - - - - PERCEIVE → REASON → VERIFY → HUMAN AUTHORITY → ACT
-
- |
-
-
-
-
-
-
-LAYER I · INTELLIGENCE
-
-Agent runtime, typed orchestration, routines, memory, search, connections, artifacts, and model access.
-
- |
-
-
-LAYER II · COMPUTERS
-
-Owned or remote execution surfaces: Docker, E2B, Daytona, Box, desktop, and deterministic fake providers for tests.
-
- |
-
-
-LAYER III · AUTHORITY
-
-Authentication, membership, secrets, auditability, explicit boundaries, and human review before consequential action.
-
- |
-
-
-THE HUMAN HOLDS THE KEY
-
-Machines propose; a human reviews, verifies, and acts. Nothing signs itself. In clinical paths, final authority is deliberately non-delegable.
-
- |
-
-
-READ-ONLY UNTIL PROVEN
-
-Clinical integrations begin strictly read-only. No write reaches a patient record until the read path has been verified end to end.
-
- |
-
-
-BRING YOUR OWN MODEL & COMPUTER
-
-Models and computer providers remain replaceable. Run locally, use a remote sandbox, or point clients at a central deployment without binding the system to one vendor.
-
- |
-
-
-SEPARABLE BY DESIGN
-
-Reasoning, memory, orchestration, computers, realtime, security, and persistence are independent surfaces that can be inspected or replaced without rewriting the whole system.
-
- |
-
-
-DURABLE STATE OVER EPHEMERAL COMPUTE
-
-A sandbox is where work runs, not where truth lives. Workspace state checkpoints back to durable storage; remote computers are runtime cache.
-
- |
-
-
-NO MAGIC WITHOUT VERIFICATION
-
-The system should expose where work runs, where state lives, what boundary applies, and which human or policy controls the next action.
-
- |
-
-
-
-
-
-
-
-
-
LIVE TOPOLOGY // CONTROL & EXECUTION PLANE
-
-APPLICATIONS
-
-- `apps/api` — HTTP API, auth, typed orchestration
-- `apps/web` — React + Vite client
-- `apps/desktop` — Electron shell for Sentra Bot
-- `apps/worker` — routines, wakeups, jobs, run continuation
-
- |
-
-
-CORE PACKAGES
-
-- `adapter-kit` — ports and interfaces
-- `adapters` — concrete execution + provider adapters
-- `contracts` — shared typed RPC contracts
-- `core` — pure domain logic
-- `db` — Prisma schema, migrations, repositories
-- `memory` — per-bot markdown memory
-
- |
-
-
-SHARED SURFACES
-
-- `auth` — Better Auth sessions + signup policy
-- `chat-ui` — cross-platform markdown rendering
-- `ui-tokens` — design tokens / theme primitives
-- `ui-web` — shared React UI components
-- `testkit` — topology, canary, computer E2E, performance
-
- |
-
-
-INFRASTRUCTURE
-
-- `infra/compose` — Docker Compose topologies, Caddy, deployment assets
-- `infra/sandboxes` — bot computer images + supervisor
-- `scripts` — backup / restore utilities
-
- |
-
REPOSITORY MAP // CANONICAL LAYOUT
-
-apps/api · PORT 3100-Hono + @orpc/server. Owns auth routes, typed RPC, trusted-origin CORS, health reporting, and wiring across database, realtime, jobs, sandboxes, secrets, memory, artifacts, runtime, and auth. - - |
-
-
-apps/web · PORT 5173-React + Vite SPA. Talks to the API over RPC; Compose proxies `/api` and `/rpc` to the API container. - - |
-
-
-apps/desktop-Electron shell with productName: "Sentra Bot". It is a client of the same API — not a second backend — and supports the trusted-host desktop sandbox path.
-
- |
-
-
-apps/worker-Long-running process that consumes the job queue, executes bot runs, reconciles scheduled routines, handles wakeups, and shares the same packages as the API. - - |
-
PRISMA · POSTGRESQL 16 · GRAPHILE · LISTEN/NOTIFY · DURABLE BOT STATE
-
-
-
-DATABASE
-
-**ORM:** Prisma
-**Schema:** `packages/db/prisma/schema.prisma`
-**Migrations:** `packages/db/prisma/migrations/`
-
-Core models include user, session, workspace, membership, bot, thread, message, run, event, routine, computer, lease, artifact, secret, model credential, connection, memory document, usage record, and deployment settings.
-
- |
-
-
-MEMORY & DURABLE STATE
-
-Per-bot markdown memory lives behind the memory package. Computer workspaces checkpoint back to `DATA_DIR`, keeping persistent state independent from ephemeral cloud sandboxes.
-
- |
-
-
-JOBS
-
-`WAKEUP_DRIVER=graphile` uses a Postgres-backed Graphile Worker queue.
-`WAKEUP_DRIVER=memory` swaps in an in-memory queue for tests and development.
-
- |
-
-
-REALTIME
-
-Thread events fan out through Postgres `LISTEN/NOTIFY` via `PostgresRealtimeFanout`, with an in-memory implementation when no pool exists.
-
- |
-
-
-
-
-
-
-
-
-LOCAL DEV
-
-`docker-compose.yml`
-
-Postgres, supervisor, computer image, data-init, API, worker, and web. Postgres is published on loopback only. The supervisor — not the API — owns the Docker socket.
-
- |
-
-
-SINGLE-VM PROD
-
-`docker-compose.prod.yml`
-
-Postgres + API + worker + web + Caddy. Hardened container posture with `no-new-privileges`, dropped capabilities, limits, internal network, and health checks.
-
- |
-
-
-CENTRAL + SUPABASE
-
-`docker-compose.supabase.yml`
-
-API + worker + web + Caddy, without a local Postgres container. End users need only the web URL or desktop client pointed at the central origin.
-
- |
-
EDGE & HOST POSTURE
-
-FULL LOCAL TOPOLOGY
-
-```bash
-cp .env.example .env
-# set BETTER_AUTH_SECRET, ENCRYPTION_KEY, OPENROUTER_API_KEY
-
-pnpm install
-pnpm sandbox:build
-
-docker compose --env-file .env \
- -f infra/compose/docker-compose.yml \
- up --build
-
-# open http://127.0.0.1:5173
-```
-
-The first registered user becomes the deployment owner.
-
- |
-
-
-SOURCE DEVELOPMENT
-
-```bash
-cp .env.example .env
-pnpm install
-pnpm sandbox:build
-pnpm dev
-
-# turbo: api + worker + web (+ supervisor)
-# open http://127.0.0.1:5173
-```
-
- |
-
-
-PRODUCTION
-
-```bash
-docker compose --env-file .env \
- -f infra/compose/docker-compose.prod.yml \
- up -d --build
-
-curl --fail https://app.example.com/health
-```
-
- |
-
-
-CENTRAL BACKEND
-
-1. Set pooled `DATABASE_URL` and direct `DIRECT_URL`.
-2. Deploy Prisma migrations.
-3. Start `docker-compose.supabase.yml`.
-
-```bash
-pnpm --filter @rakazo/db exec prisma migrate deploy
-
-docker compose --env-file .env \
- -f infra/compose/docker-compose.supabase.yml \
- up -d --build
-```
-
- |
-
-
-
-
-
-
-
PROMOTION LOGIC // BUILD → VERIFY → OPERATE
-
-WHO HOLDS AUTHORITY?
-
-The relevant human operator or reviewer. In clinical paths, the human boundary is terminal.
-
- |
-
-
-WHERE DOES STATE LIVE?
-
-Postgres and durable `DATA_DIR` — not an ephemeral cloud computer.
-
- |
-
-
-WHERE DOES WORK RUN?
-
-Inside the configured computer provider: Docker, E2B, Daytona, Box, desktop, or a fake test surface.
-
- |
-
-
-HOW IS IT VERIFIED?
-
-Typed contracts, deterministic tests, topology checks, canaries, runtime health, and explicit human review where consequences require it.
-
- |
-
|
-
- -Upstream open-source agent platform. - - |
-- -Sentra Bot is built on the shoulders of **Rakazo** — the upstream platform from which the repository inherits packaging, adapter architecture, and the persistent-bot engine. - -We thank the Rakazo authors and community. - -Everything Sentra-specific — **Sentra Bot branding, the clinical read-only direction, and the central Supabase deployment path** — is layered on top of that foundation. - - | -
ACTUAL REPOSITORY SURFACE · SENTRA BOT
-
-
-
-RUNTIME & APPLICATIONS-Node.js 22 · Hono · @orpc/server · React · Vite · Electron · background worker - - |
-
-
-DATA & REALTIME-PostgreSQL 16 · Supabase · Prisma · Graphile Worker · LISTEN/NOTIFY · durable DATA_DIR - - |
-
-
-AGENT & MEMORY-Pi runtime · scripted test runtime · per-bot markdown memory · routines · wakeups · artifacts · connectors - - |
-
-
-COMPUTER PROVIDERS-Docker · E2B · Daytona · Box · desktop host · fake test provider · supervisor API - - |
-
-
-SECURITY & AUTHORITY-Better Auth · membership enforcement · encryption key · secret store · read-only clinical boundary · host hardening · human authority - - |
-
-
-QUALITY & OPERATIONS-Biome · Vitest · Playwright · integration harness · topology tests · canary tests · computer E2E · performance checks · GitHub Actions - - |
-
- Sentra Bot · Intelligence for Autonomy.
- Part of the Sentra Artificial Intelligence ecosystem.
- // persistent intelligence. explicit authority.
-
+
+
+ |
+
+
+### [`SENTRA / BOT`](https://sentrahai.com/)
+
+
+ +The autonomous intelligence layer of Sentra Artificial Intelligence. + + + + PERCEIVE → REASON → VERIFY → HUMAN AUTHORITY → ACT
+
+ |
+
+
+
+
+
+
+LAYER I · INTELLIGENCE
+
+Agent runtime, typed orchestration, routines, memory, search, connections, artifacts, and model access.
+
+ |
+
+
+LAYER II · COMPUTERS
+
+Owned or remote execution surfaces: Docker, E2B, Daytona, Box, desktop, and deterministic fake providers for tests.
+
+ |
+
+
+LAYER III · AUTHORITY
+
+Authentication, membership, secrets, auditability, explicit boundaries, and human review before consequential action.
+
+ |
+
+
+THE HUMAN HOLDS THE KEY
+
+Machines propose; a human reviews, verifies, and acts. Nothing signs itself. In clinical paths, final authority is deliberately non-delegable.
+
+ |
+
+
+READ-ONLY UNTIL PROVEN
+
+Clinical integrations begin strictly read-only. No write reaches a patient record until the read path has been verified end to end.
+
+ |
+
+
+BRING YOUR OWN MODEL & COMPUTER
+
+Models and computer providers remain replaceable. Run locally, use a remote sandbox, or point clients at a central deployment without binding the system to one vendor.
+
+ |
+
+
+SEPARABLE BY DESIGN
+
+Reasoning, memory, orchestration, computers, realtime, security, and persistence are independent surfaces that can be inspected or replaced without rewriting the whole system.
+
+ |
+
+
+DURABLE STATE OVER EPHEMERAL COMPUTE
+
+A sandbox is where work runs, not where truth lives. Workspace state checkpoints back to durable storage; remote computers are runtime cache.
+
+ |
+
+
+NO MAGIC WITHOUT VERIFICATION
+
+The system should expose where work runs, where state lives, what boundary applies, and which human or policy controls the next action.
+
+ |
+
+
+
+
+
+
+
+
+
LIVE TOPOLOGY // CONTROL & EXECUTION PLANE
+
+APPLICATIONS
+
+- `apps/api` — HTTP API, auth, typed orchestration
+- `apps/web` — React + Vite client
+- `apps/desktop` — Electron shell for Sentra Bot
+- `apps/worker` — routines, wakeups, jobs, run continuation
+
+ |
+
+
+CORE PACKAGES
+
+- `adapter-kit` — ports and interfaces
+- `adapters` — concrete execution + provider adapters
+- `contracts` — shared typed RPC contracts
+- `core` — pure domain logic
+- `db` — Prisma schema, migrations, repositories
+- `memory` — per-bot markdown memory
+
+ |
+
+
+SHARED SURFACES
+
+- `auth` — Better Auth sessions + signup policy
+- `chat-ui` — cross-platform markdown rendering
+- `ui-tokens` — design tokens / theme primitives
+- `ui-web` — shared React UI components
+- `testkit` — topology, canary, computer E2E, performance
+
+ |
+
+
+INFRASTRUCTURE
+
+- `infra/compose` — Docker Compose topologies, Caddy, deployment assets
+- `infra/sandboxes` — bot computer images + supervisor
+- `scripts` — backup / restore utilities
+
+ |
+
REPOSITORY MAP // CANONICAL LAYOUT
+
+apps/api · PORT 3100+Hono + @orpc/server. Owns auth routes, typed RPC, trusted-origin CORS, health reporting, and wiring across database, realtime, jobs, sandboxes, secrets, memory, artifacts, runtime, and auth. + + |
+
+
+apps/web · PORT 5173+React + Vite SPA. Talks to the API over RPC; Compose proxies `/api` and `/rpc` to the API container. + + |
+
+
+apps/desktop+Electron shell with productName: "Sentra Bot". It is a client of the same API — not a second backend — and supports the trusted-host desktop sandbox path.
+
+ |
+
+
+apps/worker+Long-running process that consumes the job queue, executes bot runs, reconciles scheduled routines, handles wakeups, and shares the same packages as the API. + + |
+
PRISMA · POSTGRESQL 16 · GRAPHILE · LISTEN/NOTIFY · DURABLE BOT STATE
+
+
+
+DATABASE
+
+**ORM:** Prisma
+**Schema:** `packages/db/prisma/schema.prisma`
+**Migrations:** `packages/db/prisma/migrations/`
+
+Core models include user, session, workspace, membership, bot, thread, message, run, event, routine, computer, lease, artifact, secret, model credential, connection, memory document, usage record, and deployment settings.
+
+ |
+
+
+MEMORY & DURABLE STATE
+
+Per-bot markdown memory lives behind the memory package. Computer workspaces checkpoint back to `DATA_DIR`, keeping persistent state independent from ephemeral cloud sandboxes.
+
+ |
+
+
+JOBS
+
+`WAKEUP_DRIVER=graphile` uses a Postgres-backed Graphile Worker queue.
+`WAKEUP_DRIVER=memory` swaps in an in-memory queue for tests and development.
+
+ |
+
+
+REALTIME
+
+Thread events fan out through Postgres `LISTEN/NOTIFY` via `PostgresRealtimeFanout`, with an in-memory implementation when no pool exists.
+
+ |
+
+
+
+
+
+
+
+
+LOCAL DEV
+
+`docker-compose.yml`
+
+Postgres, supervisor, computer image, data-init, API, worker, and web. Postgres is published on loopback only. The supervisor — not the API — owns the Docker socket.
+
+ |
+
+
+SINGLE-VM PROD
+
+`docker-compose.prod.yml`
+
+Postgres + API + worker + web + Caddy. Hardened container posture with `no-new-privileges`, dropped capabilities, limits, internal network, and health checks.
+
+ |
+
+
+CENTRAL + SUPABASE
+
+`docker-compose.supabase.yml`
+
+API + worker + web + Caddy, without a local Postgres container. End users need only the web URL or desktop client pointed at the central origin.
+
+ |
+
EDGE & HOST POSTURE
+
+FULL LOCAL TOPOLOGY
+
+```bash
+cp .env.example .env
+# set BETTER_AUTH_SECRET, ENCRYPTION_KEY, OPENROUTER_API_KEY
+
+pnpm install
+pnpm sandbox:build
+
+docker compose --env-file .env \
+ -f infra/compose/docker-compose.yml \
+ up --build
+
+# open http://127.0.0.1:5173
+```
+
+The first registered user becomes the deployment owner.
+
+ |
+
+
+SOURCE DEVELOPMENT
+
+```bash
+cp .env.example .env
+pnpm install
+pnpm sandbox:build
+pnpm dev
+
+# turbo: api + worker + web (+ supervisor)
+# open http://127.0.0.1:5173
+```
+
+ |
+
+
+PRODUCTION
+
+```bash
+docker compose --env-file .env \
+ -f infra/compose/docker-compose.prod.yml \
+ up -d --build
+
+curl --fail https://app.example.com/health
+```
+
+ |
+
+
+CENTRAL BACKEND
+
+1. Set pooled `DATABASE_URL` and direct `DIRECT_URL`.
+2. Deploy Prisma migrations.
+3. Start `docker-compose.supabase.yml`.
+
+```bash
+pnpm --filter @rakazo/db exec prisma migrate deploy
+
+docker compose --env-file .env \
+ -f infra/compose/docker-compose.supabase.yml \
+ up -d --build
+```
+
+ |
+
+
+
+
+
+
+
PROMOTION LOGIC // BUILD → VERIFY → OPERATE
+
+WHO HOLDS AUTHORITY?
+
+The relevant human operator or reviewer. In clinical paths, the human boundary is terminal.
+
+ |
+
+
+WHERE DOES STATE LIVE?
+
+Postgres and durable `DATA_DIR` — not an ephemeral cloud computer.
+
+ |
+
+
+WHERE DOES WORK RUN?
+
+Inside the configured computer provider: Docker, E2B, Daytona, Box, desktop, or a fake test surface.
+
+ |
+
+
+HOW IS IT VERIFIED?
+
+Typed contracts, deterministic tests, topology checks, canaries, runtime health, and explicit human review where consequences require it.
+
+ |
+
|
+
+ +Upstream open-source agent platform. + + |
++ +Sentra Bot is built on the shoulders of **Rakazo** — the upstream platform from which the repository inherits packaging, adapter architecture, and the persistent-bot engine. + +We thank the Rakazo authors and community. + +Everything Sentra-specific — **Sentra Bot branding, the clinical read-only direction, and the central Supabase deployment path** — is layered on top of that foundation. + + | +
ACTUAL REPOSITORY SURFACE · SENTRA BOT
+
+
+
+RUNTIME & APPLICATIONS+Node.js 22 · Hono · @orpc/server · React · Vite · Electron · background worker + + |
+
+
+DATA & REALTIME+PostgreSQL 16 · Supabase · Prisma · Graphile Worker · LISTEN/NOTIFY · durable DATA_DIR + + |
+
+
+AGENT & MEMORY+Pi runtime · scripted test runtime · per-bot markdown memory · routines · wakeups · artifacts · connectors + + |
+
+
+COMPUTER PROVIDERS+Docker · E2B · Daytona · Box · desktop host · fake test provider · supervisor API + + |
+
+
+SECURITY & AUTHORITY+Better Auth · membership enforcement · encryption key · secret store · read-only clinical boundary · host hardening · human authority + + |
+
+
+QUALITY & OPERATIONS+Biome · Vitest · Playwright · integration harness · topology tests · canary tests · computer E2E · performance checks · GitHub Actions + + |
+
+ Sentra Bot · Intelligence for Autonomy.
+ Part of the Sentra Artificial Intelligence ecosystem.
+ // persistent intelligence. explicit authority.
+
- {avatarError} -
- ) : null} -