메뉴
AX project architecture and coding skills - use sub-skills for specific subsystems (agent, host, cli, providers, etc.)
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Use when modifying logging, error handling, or diagnostic messages — logger setup, transports, error diagnosis patterns in src/logger.ts and src/errors.ts
Use when modifying the trusted host process — server orchestration, message routing, IPC handler, request lifecycle, event streaming, file handling, plugin loading, or agent delegation in src/host/
Use when modifying the sandboxed agent process — runner, IPC client, local/IPC tools, tool catalog, prompt building, or identity loading in src/agent/
Use when modifying agent sandbox isolation -- Docker, Apple Container (macOS), or k8s providers in src/providers/sandbox/
Use when modifying IPC protocol between host and agent — schemas, actions, length-prefix framing, or Zod validation in ipc-schemas.ts and ipc-server.ts
Use this skill when the user asks for a capability the agent doesn't yet have — a new integration (Linear, GitHub, Notion, Slack, etc.), a new workflow, a new tool, or "can you check our team's X" where X is a service the agent has no existing connector for. Creates a proper AX skill under .ax/skills/<name>/ with the right frontmatter, credentials, and domain allowlist so the capability becomes permanent after admin approval. Use this skill whenever you'd otherwise be tempted to improvise with one-off scripts, `npm install`, or `execute_script` to reach an external service.
| name | ax |
| description | AX project architecture and coding skills - use sub-skills for specific subsystems (agent, host, cli, providers, etc.) |
This is the parent skill group for all AX project-specific architecture and coding skills. Use the appropriate sub-skill for the subsystem you're working on.
AX uses a provider contract pattern. The trusted host process (src/host/) orchestrates sandboxed agent processes (src/agent/) via IPC, with a plugin system (src/plugins/) for extensibility. Every subsystem is a TypeScript interface with pluggable implementations, loaded from a static allowlist in src/host/provider-map.ts (SC-SEC-002).
Agent isolation uses a unified container model with three sandbox providers:
| Provider | Platform | IPC Transport | Notes |
|---|---|---|---|
docker | Any | Unix socket | Container isolation via Docker |
apple | macOS | Unix socket (reverse bridge) | Apple Container framework |
k8s | Kubernetes | HTTP (IPC + work dispatch) | Session-long pods with HTTP-based IPC |
Old Linux-specific sandbox providers (seatbelt, nsjail, bwrap) and the subprocess dev fallback have been removed. The k8s provider uses HTTP for all communication — IPC (HttpIPCClient → POST /internal/ipc) and work dispatch (GET /internal/work). Session-long pods are managed by SessionPodManager and reused across turns. Pods cannot share a filesystem with the host.
Outbound HTTP via Web Proxy: Agents can optionally make outbound HTTP/HTTPS requests (npm install, pip install, curl, git clone) through a controlled forward proxy on the host. Opt-in via config.web_proxy (disabled by default). Containers keep --network=none — agents reach the proxy via a TCP bridge over a mounted Unix socket. The proxy enforces private IP blocking (SSRF), canary token scanning, and audit logging. K8s pods connect directly via a k8s Service (ax-web-proxy).
In k8s mode, all communication uses HTTP:
src/agent/http-ipc-client.ts → POST /internal/ipc route on host (src/host/server-k8s.ts)src/host/llm-proxy-core.ts → /internal/llm-proxy HTTP routeSessionPodManager.queueWork(); pods fetch via GET /internal/worksrc/providers/eventbus/postgres.ts (PostgreSQL-backed pub/sub for events)HTTP for all payloads: IPC requests use HTTP POST to /internal/ipc. Work dispatch uses SessionPodManager (in-process queue). NetworkPolicy allows sandbox pods egress to host on port 8080. Workspace persistence uses git-based providers (git-http for k8s, git-local for local dev).
The MCP fast path (src/host/inprocess.ts) runs the LLM orchestration loop directly in the host process — no pods, no IPC, no proxy, no GCS sync. Used for lightweight tool-calling tasks via MCP providers (database-backed). Key files: inprocess.ts (LLM loop), tool-router.ts (tool routing with per-turn limits), sandbox-manager.ts (cross-turn sandbox escalation). See src/providers/mcp/ for the McpProvider interface: listTools(), callTool(), credentialStatus(), storeCredential(). Implementations: none (no-op), database (per-agent HTTP/SSE MCP servers stored in DB with circuit breakers). Unified MCP routing via McpConnectionManager (src/plugins/mcp-manager.ts).
src/plugins/ now contains only the MCP connection manager — the per-agent registry that discovers tools and routes calls across all configured MCP servers. Skills and MCP servers reach it through the git-native skill flow (.ax/skills/<name>/SKILL.md → reconciler → admin approval → mcp-applier.ts → McpConnectionManager.addServer()).
Key files:
src/plugins/mcp-manager.ts — McpConnectionManager: unified MCP tool discovery and routing across skill-declared, database-backed, and default providerssrc/plugins/mcp-client.ts — HTTP client for querying remote MCP serverssrc/plugins/startup.ts — Bootstrap MCP servers from the database + config at startupThere is no longer a legacy install/uninstall/list_cowork IPC surface or ax plugin/ax mcp CLI. Third-party provider plugins (for LLM/memory/channel etc.) are still managed with ax provider add|remove|list|verify.
Session-scoped catalog built from each agent's active skill snapshot at turn start, shipped to the agent as a compact one-liner listing in the system prompt. Agents dispatch via two meta-tools rather than having every MCP/OpenAPI tool wired up as a first-class SDK tool.
src/types/catalog.ts — CatalogTool shape (discriminated union of mcp / openapi dispatch kinds) + Zod validator.src/host/tool-catalog/ — registry, MCP adapter, OpenAPI adapter, jq-based _select projection, per-session cache keyed on (agentId, HEAD-sha).src/host/skills/catalog-population.ts — iterates frontmatter.mcpServers[] + frontmatter.openapi[] from the skill snapshot, builds the catalog. Emits Diagnostic entries for populate failures + wide-surface advisories.src/host/ipc-handlers/describe-tools.ts — schema lookup by catalog name (describe_tools([]) lists the whole directory).src/host/ipc-handlers/call-tool.ts — single dispatcher: MCP via callToolOnServer, OpenAPI via makeDefaultOpenApiDispatcher (path/query/header/body routing, 4 auth schemes, URL rewrites, response parsing, _select projection, auto-spill on large responses).src/host/diagnostics.ts — per-turn ring-buffered collector; emitted as named SSE events (event: diagnostic) at end-of-turn so chat UI renders a banner.Skills declare REST APIs via openapi[] frontmatter (spec URL or workspace path + baseUrl + optional auth + include/exclude globs); the adapter emits one CatalogTool per operation with inputSchema derived from params + requestBody. MCP servers remain the first-class integration for vendors that publish one. Previous codegen pipeline (src/host/toolgen/, tool_batch IPC, execute_script + ax.callTool) was fully removed in the Phase 6 migration; the catalog + meta-tools replace that surface.
There are 15 provider categories in the static allowlist (src/host/provider-map.ts): llm, memory, channel, web_fetch, web_extract, web_search, credentials, audit, sandbox, scheduler, database, storage, eventbus, workspace, mcp, auth. Credentials is database-only. Workspace has git-http and git-local implementations. The mcp category has none and database implementations.