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
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,17 @@ providers/transport → `deep-dive-providers.md`; reload/restart →
package version, `server/` thin HTTP adapters, `coordinator/` +
`coordinator/streaming/` (`coordinator.rs`, `execution.rs`, `terminal.rs`,
`timeout.rs`, `types.rs`, `diagnostics.rs` behind `mod.rs`) request lifecycle,
`agent_orchestration.rs` finite hosted tool execution, `request/` admission,
`request/` admission,
`wire/` protocol codecs, `routing/` + `accounts/` +
`catalog/` + `quota/` + `health/` selection, `model_router.rs` affinity,
`identity.rs` + `web_session.rs` + `user_budget.rs` + `instance_budget.rs` +
`model_policy.rs` + `tool_policy.rs` on-prem user access, `providers/` transport,
`model_policy.rs` on-prem user access, `providers/` transport,
`runtime_lifecycle/` generations + `reload.rs` +
`task_supervisor.rs`, `operations/` local lifecycle, `db/` +
`rust/assets/db/migrations/` v1–v65 immutable.
- Reusable policy crates: `rust/crates/eggpool-model-routing/` (neutral validation/compilation only; selector execution and affinity cache stay in `rust/src/`), `rust/crates/eggpool-client-config/` (portable Codex/OpenCode projection, profiles, `epc1` tokens, V1/V2 renderers, TOML/JSONC-preserving mutation; EggPool `Config`/catalog/DB/key/endpoint/CLI/file IO stays in `rust/src/operations/integrations.rs`), `rust/crates/eggpool-provider-profile/` (secret-free sans-I/O provider-profile contract plus the canonical bundled asset at `assets/_provider_profiles.toml`; `rust/src/provider_profile.rs` is the only EggPool reader), `rust/crates/eggpool-wire/` (neutral sans-I/O wire kernel; execution stays in `rust/src/`), `rust/crates/eggpool-connect/` (narrow `eggpool-connect` binary: plan/install/verify/backups/restore/remove with byte-exact backups, atomic writes, automatic rollback; no Axum/SQLite/Eggress, no proxy/agent/daemon).
- Tooling only (never a runtime fallback): repo-root `pyproject.toml`, `scripts/`, `tests/tooling/`. `scripts/qualification_sbc.py` is the sole physical-SBC runner (loopback-only, aggregate-only, non-CI). Native tests live in `rust/tests/` (serial; there is no `coordinator_c012`; streaming files are `coordinator.rs`, `execution.rs`, `terminal.rs`, `timeout.rs`, `types.rs`, `diagnostics.rs`).
- Config resolution: `--config` > `$EGGPOOL_CONFIG` > `~/.config/eggpool/config.toml` > `./config.toml`. Provider/upstream keys come from environment/`.env`, never committed; the server key lives under `[server]` (`api_key` via `eggpool newkey`, or `api_key_env`). Examples: `rust/config.example.toml`, `rust/config.sbc.example.toml`.
- Config resolution: `--config` > `$EGGPOOL_CONFIG` > `~/.config/eggpool/config.toml` > `./config.toml`. Provider/upstream keys come from environment/`.env`, never committed; the server key lives under `[server]` (`api_key` via `eggpool newkey`, or `api_key_env`). Examples: `rust/config.example.toml`, `rust/config.local.example.toml`, `rust/config.sbc.example.toml`.
- Plans: `plans/` is append-only (`plans/README.md`, `plans/registry.md` is the control surface; pre-251 flat `001-*`…`250-*` are immutable history). See the `plan` skill before adding one. Past plan numbers in this file go stale — link the registry, never paste plan history here.

## Commands (run from repo root)
Expand Down
4 changes: 4 additions & 0 deletions architecture/deep-dive-observability.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,10 @@ owner through a bounded indexed repository and excludes internal selector
children from logical-request views. Routine metrics, routing traces, and
diagnostics still omit user IDs, credential IDs, scopes, prompts, and tokens.

`eggpool audit export` and `GET /api/admin/audit/export` are a projection
of existing administration and logical request rows. They are not a new
telemetry pipeline, and they do not store prompts or tool payloads.

## Verification

```bash
Expand Down
10 changes: 5 additions & 5 deletions architecture/deep-dive-on-prem-user-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,16 @@ history.

## Ownership boundary

The subsystem is six flat runtime modules plus two HTTP adapter surfaces:
The subsystem is five flat runtime modules plus two HTTP adapter surfaces.
EggPool does not execute tools. Client-executed tool calls stay in the
wire codecs, and the content-free gateway audit export is a read of the
existing administration and request tables.

| Path | Owns |
|---|---|
| `rust/src/identity.rs` | Local user records, password hashes, personal API credentials, the administrative audit trail, and the request-attribution types |
| `rust/src/identity.rs` | Local user records, password hashes, personal API credentials, the administrative audit trail, request attribution, and the content-free gateway audit export |
| `rust/src/web_session.rs` | Opaque browser sessions, the CSRF digest, and bounded local login throttling |
| `rust/src/model_policy.rs` | Versioned, user-specific model authorization (profiles, exact rules, per-user overrides, instance denials) |
| `rust/src/tool_policy.rs` | Default-deny Eggsearch discovery/invocation authorization, explicit credential scopes, exact profile/user rules, instance denials, and content-free audit mutations |
| `rust/src/server/tools.rs` | Disabled-by-default authenticated MCP JSON POST gateway; bounded backend operations, per-request grant rechecks, and user-bound downstream sessions |
| `rust/src/server/hosted.rs` | Disabled-by-default finite hosted operation; bounded model/tool sequencing, content-free parent attribution, and grant/catalog rechecks |
| `rust/src/user_budget.rs` | Durable per-user budget rules, admission holds, attempt usage, and settled usage windows |
| `rust/src/instance_budget.rs` | The instance-global budget scope intersected with the per-user rules |
| `rust/src/server/auth.rs` | Browser login, session cookies, CSRF forms, and forwarded-HTTPS validation |
Expand Down
18 changes: 8 additions & 10 deletions architecture/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,7 @@ fail closed on validation, commit, or ownership ambiguity.
re-exports the CLI/config/error boundary. `rust/src/cli.rs` owns the Clap
command tree (36 commands: `serve`, `connect`, `logout`, `check-config`, `edit`, `getkey`,
`newkey`, `configsetup`, `configremote`, `deploy`, `accounts`, `dashboard`, `db`, `models`,
`modelinfo`, `stats`, `tools`, `users`, `onboard`, `croncheck`, `ensure-running`, `migrate`,
`modelinfo`, `stats`, `audit`, `users`, `onboard`, `croncheck`, `ensure-running`, `migrate`,
`stop`, `restart`, `init-config`, `help`, `recover`, `uninstall`, `update`,
`install-provenance`, `set`, `rehash`, `runtime-status`, `status`, `backup`, `version`).
`rust/src/runtime.rs` adapts each command to `operations/*`, `config`, and
Expand All @@ -98,7 +98,7 @@ Deep dive: [Core](deep-dive-core.md).
`rust/src/config.rs` is the typed TOML contract (`Config`, `ServerConfig`,
`UpstreamConfig`, `DatabaseConfig`, `RoutingConfig`, `ModelsConfig`,
`ProviderConfig`, `DashboardConfig`, `SecurityConfig`, `MetricsConfig`,
`BackupConfig`, `ModelRouterConfig`, `IntegrationsConfig` (`[integrations].advertise_base_url`), `ToolBackendConfig` (`[tools]`, explicit diagnostics, optional gateway, and disabled-by-default hosted execution),
`BackupConfig`, `ModelRouterConfig`, `IntegrationsConfig` (`[integrations].advertise_base_url`), `ToolBackendConfig` (`[tools]` switches that fail closed when execution is enabled),
transcoder/model-info policies) with
`from_toml`/`validate` and proxy/model-router compilation. Resolution order is
explicit `--config` > `$EGGPOOL_CONFIG` > `$XDG_CONFIG_HOME`-aware
Expand Down Expand Up @@ -159,7 +159,8 @@ managed-user at `/login`, `/logout`, `/account`, `/account/landing`,
`/account/tokens/revoke`, `/usage`, `/api/user-budget`; dashboard pages at
`/`, `/accounts`, `/models`, `/models/{*model_id}`, `/latency`, `/events`,
`/timeseries`, `/bandwidth`, `/pings`, `/reliability`, `/routing`,
`/traces`, `/runtime`, `/cache`, `/users`, `/profiles`, `/admin/audit`;
`/traces`, `/runtime`, `/cache`, `/users`, `/profiles`, `/admin/audit`,
`/api/admin/audit/export`;
admin actions at `/admin/users/create`, `/admin/users/state`,
`/admin/users/password`, `/admin/users/token`, `/admin/users/revoke-tokens`,
`/admin/users/profile`, `/admin/users/override`,
Expand Down Expand Up @@ -506,13 +507,10 @@ observability JSON (`/api/stats/transcoding`, `/api/stats/cache-observability`,
observational only.
- On-prem user access: local downstream identities with Argon2id passwords and
revocable per-user agent tokens (`eggpool users …`), browser login behind a
session/CSRF boundary, versioned per-user model policy, default-deny Eggsearch
tool grants and explicit per-token tool scopes, a disabled-by-default
authenticated Eggsearch MCP gateway at `POST /api/tools/v1/mcp`, and a separate
finite hosted operation at `POST /api/agent/v1/run`; per-user and instance-global
daily/monthly budgets remain owned by their current authorities. Hosted model
turns remain coordinator calls, while tool calls reauthorize through the
gateway's internal bounded invocation service.
session/CSRF boundary, versioned per-user model policy, and per-user and
instance-global daily/monthly budgets. Tool calls on the inference APIs are
returned to the client. `GET /api/admin/audit/export` and `eggpool audit export`
project content-free administration and inference facts for an administrator.
The admin and member surfaces are the
`/admin/*`, `/users`, `/profiles`, `/account*`, `/my-account*`, and `/usage`
routes; see [On-prem user access](deep-dive-on-prem-user-access.md).
Expand Down
32 changes: 7 additions & 25 deletions docs/agent-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,11 @@ Codex and OpenCode additionally support a managed lifecycle that installs a gene

`eggpool configremote` is the headless companion: on the EggPool host it exports a small secret-free `epc1` connection profile for Codex/OpenCode running on other machines. Local `configsetup` writes the local filesystem; `configremote` never touches a desktop filesystem and never mutates EggPool config to manufacture a setup.

## Optional EggPool MCP tools

The tools gateway is a separate, disabled-by-default MCP endpoint. Configure
the agent's Streamable HTTP MCP client to use
`http://<eggpool-host>:11300/api/tools/v1/mcp` (or the HTTPS URL of the
operator-managed reverse proxy) and provide a personal EggPool token through
the agent's secret/environment mechanism. The token needs the
`tools:discover:eggsearch` scope for listing and `tools:invoke:eggsearch` for
calling, and an administrator must grant the specific tools. The route
supports MCP `2025-03-26` initialize, list, and call over JSON POST; clients
that require downstream GET/SSE streams, resources, prompts, or resumable
sessions are not supported. Ordinary inference tool declarations remain
client-executed. See the [gateway security and protocol guide](tool-gateway.md).

## Optional finite hosted execution

`POST /api/agent/v1/run` is a distinct EggPool-specific finite operation, not
part of the generated Codex/OpenCode provider profile. It runs only when the
operator enables hosted execution and lists an exact qualified model ID. The
request chooses an explicit subset of Eggsearch tools, and the managed token
needs inference plus current per-user tool scopes and grants. It has no
conversation persistence or streaming/resume support. See the
[hosted orchestration guide](hosted-tool-orchestration.md).
## Tool calls

Generated provider profiles use EggPool for model calls. The client
executes tool calls. EggPool does not expose an MCP gateway or a hosted
tool runner. See [Tool execution](tool-gateway.md).

## Supported Targets

Expand Down Expand Up @@ -289,5 +271,5 @@ operation. Managed-user model policy applies to the submitted model exactly as
it does to other inference routes; a permitted chat model is not necessarily
embedding-enabled. The operator must explicitly qualify that model/provider
pair as described in [providers](providers.md).
For the PrivateGPT-style deployment pattern and its user-isolation limits, see
[external retrieval interoperability](retrieval-interoperability.md).
EggPool does not retrieve private documents. See
[Retrieval](retrieval-interoperability.md).
40 changes: 15 additions & 25 deletions docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,31 +168,21 @@ enforces the same rules even when a client submits a hidden model manually.
The integration profile's ETag includes the policy revision so client caches
refresh after an administrator changes model access.

Personal credentials may be issued with separate `tools:discover:eggsearch`
and `tools:invoke:eggsearch` scopes. Existing credentials keep their original
scopes. Tool grants are independently default-deny and do not affect model
authorization. With `[tools].enabled = true` and
`[tools].gateway_enabled = true`, the managed-user-only
`POST /api/tools/v1/mcp` route exposes authorized Eggsearch tools using MCP
`2025-03-26`. It supports JSON POST requests for `initialize`,
`notifications/initialized`, `tools/list`, and `tools/call`; it rejects
JSON-RPC batches and other methods, does not implement downstream GET/SSE
streams, resources, prompts, or session resumption, and does not change
Chat/Responses/Messages tool execution semantics. Request bodies are capped at
128 KiB, tool arguments at 32 KiB, backend responses at 1 MiB, concurrent
backend operations at 16, and sessions at 1,024 with a 30-minute idle expiry.
Only the configured loopback Eggsearch 0.4.3 service is contacted. Credentials
are never forwarded; trust labels and structured tool results are preserved.
See the [MCP gateway guide](tool-gateway.md) for the security model and setup.

With `[tools].enabled = true` and `[tools].hosted_execution_enabled = true`,
managed agent tokens may use the finite EggPool-specific
`POST /api/agent/v1/run` operation. It requires an operator-qualified exact
model ID and current per-user Eggsearch invocation grants. The endpoint is
stateless, non-streaming, and bounded; it does not alter client-executed tool
calls on the standard inference APIs. See the
[hosted orchestration guide](hosted-tool-orchestration.md) for its DTO,
resource caps, and configuration.
EggPool does not execute tools. Chat Completions, Responses, Messages, and
compact return tool calls to the client. `POST /api/tools/v1/mcp` and
`POST /api/agent/v1/run` are not routed. New personal tokens are not issued
tool-execution scopes. See [Tool execution](tool-gateway.md).

`GET /api/admin/audit/export` is an administrator browser-session read.
It returns JSON lines, schema version 1, newest first. Each of the
administration and inference sections includes at most `limit` rows
(default 500, maximum 2000). A final `kind` of `export` reports
`truncated` and `limit`. Fields are identifiers, action names, model id,
protocol, status, token counts, latency, a bounded reason code when one
is already stored, and timestamps. The export does not contain prompts,
tool arguments, tool results, or credentials. Personal API tokens and
member sessions are denied. EggUI transcripts and CodeGG sessions stay
in those applications. The same projection is `eggpool audit export`.

`GET /api/user-budget` is available to personal tokens and browser sessions.
Members can read only their own rules and rollups; an active admin may select a
Expand Down
Loading
Loading