SILVER
/
NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
NODEDC_PLATFORM/docs/AI_WORKSPACE_CONFIG_CONTRAC...

5.1 KiB
Raw Permalink Blame History

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 infra/scripts/check-local-test-system.sh

For a live local remote-worker test, require the relay topology explicitly:

REQUIRE_REMOTE_WORKER_RELAY=1 sh infra/scripts/check-local-test-system.sh

Security audit and test matrix:

docs/AI_WORKSPACE_SECURITY_AUDIT_2026-06-20.md
docs/AI_WORKSPACE_TEST_MATRIX.md