109 lines
5.1 KiB
Markdown
109 lines
5.1 KiB
Markdown
# AI Workspace Config Contract
|
|
|
|
This contract keeps topology differences in env/config instead of product-code branches.
|
|
|
|
## URL Classes
|
|
|
|
- Worker-facing URL: returned to or used by the Codex worker. It must be reachable from the machine that executes Codex.
|
|
- Backend-internal URL: used by app backends, Platform Assistant, Hub, Gateway, and service-to-service calls.
|
|
- Browser URL: used by user-facing UI.
|
|
- Downstream app URL: used by an adapter service to mutate/read its owned app backend.
|
|
|
|
Do not mix these classes. A URL reachable from the Mac browser is not automatically reachable from a remote Codex worker.
|
|
|
|
## Current Profiles
|
|
|
|
`local/remote-worker-relay`:
|
|
|
|
- Tasker UI: `http://task.local.nodedc`
|
|
- Platform Assistant: `http://127.0.0.1:18082`
|
|
- Local Hub process: `http://127.0.0.1:18081`
|
|
- Default worker-facing Hub relay: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
|
|
- Default Assistant-to-relay control URL: `https://ai-hub.nodedc.ru`
|
|
- Assistant action relay id: `local-dev`
|
|
- Assistant action gateway returned to worker: `https://ai-hub.nodedc.ru/api/ai-workspace/hub/v1/assistant-relays/local-dev/actions`
|
|
- Ops entitlement adapter: `http://host.docker.internal:4100/api/internal/v1/ai-workspace/entitlements` when deliberately enabled
|
|
- Ops Gateway downstream Tasker: `http://task.local.nodedc`
|
|
- The deployed AI Hub is allowed only as transport. Launcher, Engine, Ops, Authentik, task manager, and downstream app calls must stay local.
|
|
- The remote worker must not call product apps directly. Assistant actions must route back through the local AI Workspace Assistant.
|
|
|
|
`local-seo/deployed-hub-control-plane`:
|
|
|
|
- SEO frontend: `http://127.0.0.1:5177`
|
|
- SEO backend: `http://127.0.0.1:4100`
|
|
- SEO AI Workspace profile: `deployed-hub`
|
|
- SEO backend Assistant-compatible control-plane URL: `SEO_AI_WORKSPACE_CONTROL_URL=https://ai-hub.nodedc.ru`
|
|
- SEO backend control-plane token: `SEO_AI_WORKSPACE_CONTROL_TOKEN`, accepted by the public Hub server-side API.
|
|
- Worker-facing Hub: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
|
|
- Public Hub exposes only token-gated Assistant control-plane proxy endpoints required by SEO model-provider setup, probe, thread dispatch, and message polling.
|
|
- Public Hub must proxy those calls to internal Platform Assistant with server-side internal token. Browser clients and remote workers must not receive the Hub internal token or Assistant token.
|
|
- This profile is for local SEO development against the deployed AI Workspace service plane. It is not the same as `local`, and it must not silently fall back to localhost or product app URLs.
|
|
|
|
`synology/prod-public`:
|
|
|
|
- Browser Launcher: `https://hub.nodedc.ru`
|
|
- Browser Ops: `https://ops.nodedc.ru`
|
|
- Worker-facing Hub: `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
|
|
- Platform Assistant internal: `http://ai-workspace-assistant:18082`
|
|
- Platform to Ops entitlement: `http://172.22.0.222:18190/api/internal/v1/ai-workspace/entitlements`
|
|
- Ops Gateway worker-facing MCP: `https://ops-agents.nodedc.ru/mcp`
|
|
- Ops Gateway downstream Tasker: `http://172.22.0.222:18090`
|
|
- This is the preferred controlled runtime e2e target.
|
|
|
|
`tailscale/tunnel-local-e2e`:
|
|
|
|
- Allowed only as an explicit profile.
|
|
- All worker-facing URLs must be reachable from the executing Codex worker through Tailscale or a named tunnel.
|
|
- No product code should auto-fallback from localhost to Tailscale to public domains.
|
|
|
|
## Required Rule
|
|
|
|
New apps must join AI Workspace through app manifests/config/adapters:
|
|
|
|
- app id and surface id;
|
|
- context schema;
|
|
- entitlement adapter URL/token;
|
|
- MCP/tool pack URL and worker-facing public URL;
|
|
- smoke test contract;
|
|
- owner repo/service.
|
|
|
|
Do not add app-specific address logic to the agent installer, Engine, Ops, or Platform Assistant runtime flow.
|
|
|
|
### NDC SEO Mode
|
|
|
|
`seo-mode` is a first-class AI Workspace surface, not `global`.
|
|
|
|
Local SEO testing should keep SEO app/backend on fixed local ports while using the configured AI Workspace transport/profile:
|
|
|
|
- SEO frontend: `http://127.0.0.1:5177`
|
|
- SEO backend: `http://127.0.0.1:4100`
|
|
- SEO model-provider surface: `seo-mode`
|
|
- SEO model task mode: `seo-model-task`
|
|
- Worker-facing transport: public AI Hub relay when selected by profile, normally `wss://ai-hub.nodedc.ru/api/ai-workspace/hub`
|
|
- SEO task payload: sanitized `seo-model-task` contract only
|
|
|
|
The SEO backend must select profiles through env/config, not code edits. Local and deploy-host may use different Assistant URLs, executor ids, setup commands, model defaults, and app grants, but the request contract stays the same.
|
|
|
|
Remote Codex for SEO must not receive Wordstat/Yandex credentials, product app tokens, unrestricted repo access, rewrite/apply actions, or destructive actions. Wordstat/SERP collection remains SEO-backend-owned.
|
|
|
|
## Verification
|
|
|
|
Before changing worker, Assistant, Hub, or app adapter routing, run:
|
|
|
|
```sh
|
|
sh infra/scripts/check-local-test-system.sh
|
|
```
|
|
|
|
For a live local remote-worker test, require the relay topology explicitly:
|
|
|
|
```sh
|
|
REQUIRE_REMOTE_WORKER_RELAY=1 sh infra/scripts/check-local-test-system.sh
|
|
```
|
|
|
|
Security audit and test matrix:
|
|
|
|
```text
|
|
docs/AI_WORKSPACE_SECURITY_AUDIT_2026-06-20.md
|
|
docs/AI_WORKSPACE_TEST_MATRIX.md
|
|
```
|