open-managed-agents 0.1.0

package/dist/src/types/json.js

@@ -0,0 +1,19 @@
+export function isJsonObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value));
+}
+export function isJsonValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (!isJsonObject(value))
+        return false;
+    return Object.values(value).every(isJsonValue);
+}

package/dist/src/types/sessions.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/managed-agents-console/README.md

@@ -0,0 +1,52 @@
+# Managed Agents Console
+
+The appliance's bundled operator UI. **The primary way to run it is not this
+directory** — the OMA server serves it at `/console`:
+
+```text
+http://127.0.0.1:4180/console
+```
+
+No build step: React + ReactDOM + Babel-standalone are vendored under
+`vendor/` (production UMD builds from the npm registry) and the JSX compiles
+in the browser. Nothing loads from a CDN, so the console works on air-gapped
+hosts.
+
+## Logging in
+
+The console asks for a key on load (unless the server runs with
+`OMA_AUTH_MODE=disabled`, in which case it browses `wrk_default` directly):
+
+- **Workspace key** (`oma_…`, e.g. the one printed on first boot) — read-only
+  browsing of that workspace's agents, sessions, events, spans, and files,
+  including authenticated file downloads.
+- **Admin key** (`OMA_ADMIN_KEY`) — everything above plus the Admin panel:
+  create workspaces, mint/list/revoke API keys. Minted plaintext is shown
+  once, with copy and a "browse as this workspace" shortcut. Setup:
+  [dev-deployment.md](../../docs/dev-deployment.md#the-admin-api-and-console-admin-mode).
+
+Keys live in page memory only — never `localStorage`, `sessionStorage`, or a
+cookie (enforced by `src/control-plane/__tests__/console-security.test.ts`).
+A reload asks again.
+
+Admin mutations (workspace/key CRUD) are live. `/v1` mutations — create
+agent/session, send message, interrupt, archive — remain deliberately
+disabled in this slice.
+
+## Dev server (optional)
+
+For UI work without a full appliance, a static server + `/v1` proxy:
+
+```bash
+npm run ui:dev            # http://127.0.0.1:4177/
+```
+
+It proxies `/v1/*` to `OMA_CONSOLE_API_BASE` (default the CWC example server
+on `http://127.0.0.1:40178`). Local development convenience only — do not
+expose it as a shared gateway; it forwards browser request headers to the
+configured API. Admin mode needs same-origin `/admin` routes, so use the
+appliance-served `/console` for that.
+
+Demo review mode with bundled fake data: append `?mode=demo` to either URL.
+If the API is unreachable, the console falls back to the same demo data with
+a warning banner.

package/dist/ui/managed-agents-console/docs/agents.md

@@ -0,0 +1,23 @@
+# Define your agent
+
+> [!NOTE] Status: **Shipped alpha.** Agents are versioned, workspace-scoped configuration objects.
+
+## Agent configuration
+
+An agent selects an exact provider and model, system instructions, built-in tool configuration, skills, MCP servers, metadata, and a default confirmation policy. The model must be enabled by the appliance and have configured credentials before it can run a provider-backed session.
+
+## Create an agent
+
+Create an agent from the console or `POST /v1/agents`. The API validates built-in tool names and policies before persistence. Use the model catalog to discover deployment-enabled, credential-ready choices rather than assuming a hosted model name will work locally.
+
+## Update semantics
+
+Updating an agent creates a new immutable version with optimistic version checks. Existing sessions keep their originally selected version. Use the versions endpoint or console detail to inspect history.
+
+## Agent lifecycle
+
+List active agents by default, include archived agents only when the API requests them, and archive an agent when it should no longer begin new work. Archiving is an API-backed lifecycle action, not a browser-only label.
+
+## What an agent does not define
+
+An agent does not grant network access, choose arbitrary images, or make a sandbox healthy. Those properties belong to the [environment](#docs=environments) and are exercised only when a session runs.

package/dist/ui/managed-agents-console/docs/console.md

@@ -0,0 +1,23 @@
+# Prototype in Console
+
+> [!NOTE] Status: **Shipped alpha.** The console is a local appliance UI, not a conversational agent builder.
+
+Use the console to exercise the same workspace-scoped API that your integration will use. It is available at the URL printed by `oma up`; sign in with a workspace key.
+
+The key is used once to establish a revocable console session. The browser never stores or can read the session token; the server stores only its hash. A workspace-key session is invalidated as soon as its source key is revoked. When admin mode is enabled, an admin can use the workspace selector to open any workspace directly; the selected workspace remains a separate `/v1` session, not implicit admin access.
+
+## Build an agent
+
+Create an agent, choose a credential-ready model, set instructions, and choose its tools and confirmation policy. Agent updates create immutable versions, so an existing session continues with the version it started with.
+
+## Test a session
+
+Create an immutable environment, then create a session with the selected agent and environment. Send a prompt and inspect persisted events, tool input and output, generated files, errors, and confirmation requests.
+
+## What the console does not do
+
+The alpha console does not generate agents from a chat, provision hosted infrastructure, or simulate writes that the server cannot perform. If an API capability is unavailable, the console leaves the action absent or explains the limitation.
+
+## Move to code
+
+Use the console to understand the workflow, then use the bundled [OpenAPI reference](/docs/) for request and response details. The API requires a workspace key and the managed-agents beta header; the console supplies these for its own requests.

package/dist/ui/managed-agents-console/docs/dreams.md

@@ -0,0 +1,5 @@
+# Dreams
+
+> [!WARNING] Status: **Not ready in v1.** OMA does not run asynchronous dream or memory-distillation jobs.
+
+Dreams depend on durable memory stores, which OMA also does not implement. Session history remains available for inspection, but OMA does not automatically summarize it into reusable memory or expose dream status, cancellation, output, billing, or limits.

package/dist/ui/managed-agents-console/docs/environments.md

@@ -0,0 +1,27 @@
+# Environments
+
+> [!NOTE] Status: **Shipped alpha for local sandbox configuration and bounded egress.**
+
+Environments define where a session runs and which outbound destinations, if any, it may reach. They are immutable: changing the policy means creating a new environment and session.
+
+## Create an environment
+
+Create environments from the console or API. The environment stores its configuration, while the configured local provider enforces it when a session starts. The console queries the server for supported networking presets rather than inventing local options.
+
+## Networking
+
+New environments are Offline by default. Docker-local supports reviewed npm + PyPI, GitHub + package registries, and validated custom HTTPS host allowlists. Custom lists accept exact hosts and leading wildcards; a wildcard does not match the bare domain.
+
+> [!WARNING] OMA has no unrestricted networking. Microsandbox-local remains offline-only. A network preset is not a promise that every third-party service or protocol will work.
+
+## Lifecycle
+
+List and retrieve environments through the API and console. Environment archive and delete endpoints are not available yet, so environments currently accumulate. The console does not pretend otherwise.
+
+## Prove the supported path
+
+```
+oma smoke --egress
+```
+
+This deterministic Docker proof checks approved package and GitHub access, denial of an unrelated HTTPS host, and cleanup.

package/dist/ui/managed-agents-console/docs/events.md

@@ -0,0 +1,19 @@
+# Session event stream
+
+> [!NOTE] Status: **Shipped alpha.** Events are persisted, listable, and streamable over server-sent events (SSE).
+
+## Read the event history
+
+Use `GET /v1/sessions/{id}/events` to page through persisted history, or open the console session detail. Events include user messages and interrupts, tool use and results, agent messages, status changes, model-request spans, and terminal errors where OMA emits them.
+
+## Stream and resume
+
+Use `GET /v1/sessions/{id}/events/stream` for SSE. Send `Last-Event-ID` to resume after a known event. A reconnecting stream is not the source of truth: list persisted events to backfill if a client needs reliable consolidation.
+
+## Text and previews
+
+OMA emits a complete buffered `agent.message` after generation. It does not emit token previews, `agent.thinking`, or `system.message`; requests using the unsupported `event_deltas[]` parameter fail with HTTP 400 rather than silently doing nothing.
+
+## Confirmation and custom tools
+
+`user.tool_confirmation` resolves an ask-gated built-in or MCP tool request. `user.custom_tool_result` resolves a custom-tool wait. These events are part of the session's persisted audit trail.

package/dist/ui/managed-agents-console/docs/files.md

@@ -0,0 +1,17 @@
+# Files
+
+> [!NOTE] Status: **Shipped alpha for uploads, session mounts, output files, listing, downloading, and deletion.**
+
+## Upload and inspect
+
+Files are workspace-scoped resources. Use the Files console screen or API to upload, list, download, and delete them. Session output files remain available for inspection through the session and Files surfaces.
+
+## Mount files when creating a session
+
+Pass file resources at session creation. OMA validates ownership and creates the internal snapshot required by the selected sandbox provider before the session starts.
+
+> [!WARNING] A session accepts at most 10 mounted files, while CMA documents 100. OMA also rewrites mount paths below its session uploads root and returns the original upload file ID; do not rely on CMA's literal mount-path or session-scoped file-ID behavior.
+
+## Running-session changes
+
+OMA does not support adding, listing, or deleting mounts on an already-created session. Create a new session when its file inputs need to change.

package/dist/ui/managed-agents-console/docs/github.md

@@ -0,0 +1,11 @@
+# Accessing GitHub
+
+> [!WARNING] Status: **Not ready in v1.** OMA does not currently provide CMA-style GitHub repository resources, repository mounts, pull-request creation, or token rotation for GitHub integration.
+
+## What works today
+
+An environment may allow approved GitHub HTTPS hosts for sandbox commands when Docker-local egress is enabled. That is ordinary bounded network access, not a GitHub integration feature.
+
+## Do not assume
+
+OMA does not clone or mount a repository from a session resource, manage repository credentials, create pull requests on a user's behalf, or expose hosted GitHub lifecycle controls. A future GitHub integration will be documented only when its resource, credential, permission, and audit behavior exist.

package/dist/ui/managed-agents-console/docs/integrations.md

@@ -0,0 +1,19 @@
+# MCP connector
+
+> [!NOTE] Status: **Shipped alpha for supported MCP servers and vault-backed authentication.**
+
+## Declare MCP servers on an agent
+
+Configure an MCP server in the agent's versioned configuration. OMA resolves it when the session starts and records MCP tool use and result events in the session history.
+
+## Configure available tools
+
+MCP tools remain subject to the agent's permission policy. Inspect the session event stream to see evaluation, confirmation, execution, and result behavior rather than treating a configured server as proof that every tool is usable.
+
+## Provide authentication
+
+Attach the needed [vault](#docs=vaults) at session creation. OMA supports the shipped static-bearer and MCP OAuth flows, including configured validation. Credentials are not rendered as plaintext in the console or passed as ordinary browser data.
+
+## Current boundaries
+
+OMA does not provide MCP tunnels, arbitrary rich content blocks, or long-output spill-to-file behavior. It also does not provide generic environment-variable credential injection.

package/dist/ui/managed-agents-console/docs/memory.md

@@ -0,0 +1,11 @@
+# Using agent memory
+
+> [!WARNING] Status: **Not ready in v1.** OMA has no memory-store, memory-version, or cross-session memory resource API.
+
+## Current behavior
+
+Each session has its own persisted event record and explicitly attached input files. That persistence helps inspection and replay, but it is not agent memory that can be mounted into a later session.
+
+## Compatibility note
+
+Memory-store resources are rejected at the session-resource boundary. Do not build an integration around CMA memory endpoints or paths until OMA ships the underlying storage, access, versioning, and audit semantics.

package/dist/ui/managed-agents-console/docs/migration.md

@@ -0,0 +1,17 @@
+# Migration
+
+> [!NOTE] Status: **Partial alpha guidance.** OMA borrows the managed-agent resource model, but it is not a drop-in replacement for every hosted CMA feature.
+
+## From a custom agent loop
+
+Move durable configuration into an agent, choose an environment before execution, create a session for each persisted run, and consume the session event log over HTTP or SSE. OMA owns the local runtime bridge, sandbox lifecycle, persisted transcript, and tool-confirmation state.
+
+You still own model-provider credentials, appliance operation, workspace-key distribution, and any application UI or job queue around OMA.
+
+## Compatibility boundary
+
+Start from the synchronous single-agent path: agent, environment, session, user event, and persisted event stream. Check [API reference and compatibility](#docs=reference) before depending on a request shape or lifecycle detail.
+
+## Features not to assume
+
+Per-session agent overrides, live session updates, hosted provisioning, memory stores, outcomes, webhooks, GitHub repository resources, scheduled deployments, and multi-agent threads are not part of the current alpha. Use the dedicated deferred pages for their current status rather than designing against hosted-only behavior.

package/dist/ui/managed-agents-console/docs/multiagent.md

@@ -0,0 +1,11 @@
+# Multi-agent orchestration
+
+> [!WARNING] Status: **Not ready in v1.** OMA supports the synchronous single-agent workflow only.
+
+## Current behavior
+
+An agent cannot delegate to a roster, create session threads, or emit thread lifecycle events. Non-null multi-agent configuration is rejected rather than stored as an inert promise.
+
+## What to use instead
+
+Coordinate separate OMA sessions from your own application if needed, but treat that orchestration as application-owned. OMA does not provide coordinator semantics, shared agent context, or CMA-compatible thread APIs today.

package/dist/ui/managed-agents-console/docs/outcomes.md

@@ -0,0 +1,11 @@
+# Define outcomes
+
+> [!WARNING] Status: **Not ready in v1.** OMA has no outcome rubric, grader, evaluation events, deliverable retrieval, or outcome status API.
+
+## Current alternative
+
+Use session events, tool results, output files, and your own application-level evaluation to assess a completed run. These are execution records, not a managed outcome system.
+
+## Compatibility note
+
+Do not send outcome-definition events or expect outcome-evaluation spans. OMA deliberately does not advertise those event types until it can process them with a defensible public contract.

package/dist/ui/managed-agents-console/docs/overview.md

@@ -0,0 +1,41 @@
+# Open Managed Agents overview
+
+Open Managed Agents (OMA) is a local-first appliance for creating, running, and inspecting managed-agent workflows on infrastructure you control.
+
+> [!NOTE] Status: **Alpha.** This guide describes behavior that ships in OMA. Where CMA offers a broader feature, OMA names the boundary rather than implying parity.
+
+## Start here
+
+- [Quickstart](#docs=quickstart) — install from a checkout, prove the local runtime, and start the appliance.
+- [Prototype in Console](#docs=console) — create a real agent, environment, session, and prompt from the browser.
+- [Start a session](#docs=sessions) — understand the persisted work unit.
+- [API reference and compatibility](#docs=reference) — use exact endpoint contracts and see current differences.
+
+## Core concepts
+
+| Concept | OMA meaning |
+| --- | --- |
+| Agent | A versioned model, instruction, tool, MCP-server, and skill configuration. |
+| Environment | An immutable sandbox and networking policy selected before a session runs. |
+| Session | A persisted run of one agent in one environment. |
+| Event | A persisted user, tool, agent, model-span, status, or error record that can be listed or streamed. |
+| Vault | A workspace credential container for supported integrations. |
+
+## How it works
+
+1. **Create an agent.** Select a configured provider and model, instructions, capabilities, and tool-confirmation policy.
+2. **Create an environment.** Keep it offline or choose a bounded HTTPS allowlist before work begins.
+3. **Start a session.** Select the agent and environment, attach allowed resources, and send a user event.
+4. **Inspect and steer.** Read persisted events, respond to confirmations, interrupt work, and inspect outputs.
+
+## When to use OMA
+
+Use OMA when you want a self-hosted, inspectable, synchronous single-agent coding workflow with explicit sandbox and network boundaries. It is an alpha appliance, not a hosted long-running automation platform.
+
+## Supported tools
+
+The current coding path provides Bash, read, write, edit, glob, and provider-owned grep in a pinned local image. Files, custom skills, MCP servers, and vault credentials are available within their documented boundaries. [Web fetch and web search](#docs=tools) are not enabled.
+
+## Beyond v1
+
+Memory, dreams, outcomes, multi-agent orchestration, GitHub repository resources, scheduled deployments, and webhooks have dedicated pages in this guide. They are intentional **not-ready-in-v1** states, not hidden controls.

package/dist/ui/managed-agents-console/docs/permissions.md

@@ -0,0 +1,24 @@
+# Permission policies
+
+> [!NOTE] Status: **Shipped alpha for built-in tools and MCP tools.**
+
+Permission policies decide whether a tool call is automatically allowed or requires a human decision. They complement, rather than replace, the environment's filesystem and network boundaries.
+
+## Policy types
+
+| Policy | Behavior |
+| --- | --- |
+| `always_allow` | OMA runs the permitted tool without a confirmation prompt. |
+| `always_ask` | OMA pauses the session and emits a confirmation request. |
+
+Unknown policy types and duplicate built-in tool configuration are rejected before an agent is persisted. Omitted built-in tool configuration receives OMA's documented default policy.
+
+## Respond to a confirmation
+
+Use the session detail in the console, or send a `user.tool_confirmation` event through the API with `allow` or `deny`. Inspect the requested tool and input before allowing it.
+
+> [!WARNING] OMA auto-denies an unanswered confirmation after five minutes. CMA documents indefinite waiting, so do not use the alpha for unattended long approval workflows.
+
+## What a policy cannot grant
+
+An allow decision cannot bypass the environment's immutable network policy, escape the sandbox, enable web tools, or expose vault secret values to the guest. It only resolves the pending tool action.

package/dist/ui/managed-agents-console/docs/quickstart.md

@@ -0,0 +1,51 @@
+# Get started with OMA
+
+> [!NOTE] Status: **Canonical alpha path.** This flow installs from a source checkout; public package installers and Homebrew are not available yet.
+
+## Prerequisites
+
+Use Node.js 22.19 or newer and Docker or OrbStack. A model credential is optional for the deterministic local proof and required for a real provider-backed session.
+
+## Install and diagnose
+
+```
+git clone https://github.com/oneryalcin/open-managed-agents.git
+cd open-managed-agents
+npm ci
+npm link
+oma doctor
+```
+
+`oma doctor` is read-only and secret-safe. A missing provider credential is a warning for the local-compatible proof, not a reason to skip it.
+
+## Prove the local runtime
+
+```
+oma smoke --local-compatible
+```
+
+The smoke starts isolated temporary services, uses a local-compatible model fixture, executes a real Docker tool call, observes public events, and cleans up afterward.
+
+## Start the appliance
+
+```
+export ANTHROPIC_API_KEY="…"
+oma up
+```
+
+Startup prints the API URL, console URL, and first workspace key once. Keep the appliance process running while you use it. Other supported provider credentials can be configured with the `oma auth` and `oma models` commands described in the repository's Getting Started guide.
+
+## Create your first session
+
+1. **Sign in with a workspace key.** The key is exchanged for an opaque, revocable console session, so a reload restores the workspace without storing the key in the browser.
+2. **Create an agent.** Select a credential-ready model and choose its tools and confirmation policy.
+3. **Create an environment.** Start Offline unless the work requires an approved HTTPS allowlist.
+4. **Create a session and send a prompt.** Inspect the event stream, tool calls, results, confirmations, output files, and errors.
+
+## What's happening
+
+OMA persists the agent version selected for the session, creates the sandbox state required by its environment, and records events in a durable session log. Sandbox readiness is proved by a real tool call, not guessed by the browser.
+
+## Next steps
+
+Read [Agent setup](#docs=agents), [Environments](#docs=environments), and [Session event stream](#docs=events). For a deterministic proof of supported network behavior, run `oma smoke --egress`.

package/dist/ui/managed-agents-console/docs/reference.md

@@ -0,0 +1,27 @@
+# API reference and compatibility
+
+> [!NOTE] Status: **Shipped alpha reference.** The OpenAPI schema is the wire-contract authority.
+
+Use the console for guided operations and the bundled [OpenAPI reference](/docs/) for endpoint-level integration details. The machine-readable schema is available at `/openapi.json`.
+
+## Authentication and errors
+
+Managed-agent API requests are workspace-scoped and require a workspace key plus the managed-agents beta header. Successful POST operations use the documented API response shape; errors use a structured envelope with a request ID. Use the schema rather than this guide as the field-level authority.
+
+## Shipped alpha scope
+
+| Area | Current behavior |
+| --- | --- |
+| Agents | Create, retrieve, list, immutable update/version history, and archive. |
+| Environments | Create, retrieve, list, safe networking presets, and custom-host validation. No archive/delete yet. |
+| Sessions | Create, retrieve, list with bidirectional cursors, archive/delete when idle, send events, list events, and SSE resume. |
+| Tools | Bounded coding tools, tool confirmations, custom-tool result events, files, skills, MCP, and supported vault credentials. |
+| Console | Real API-backed alpha workflow and interactive OpenAPI documentation. |
+
+## Deliberate differences and deferred surfaces
+
+OMA is not a complete hosted CMA implementation. It currently lacks web tools, memory, dreams, outcomes, GitHub repository resources, webhooks, scheduled deployments, multi-agent threads, per-session overrides, live session updates, streaming token previews, and broad hosted-provisioning options. The corresponding pages in this guide explain each boundary.
+
+## Source of truth
+
+This documentation is a user guide. The appliance's OpenAPI schema is authoritative for wire contracts, while the repository's `PARITY.md` records evidence-backed compatibility work and known differences. When those sources change, this guide must be updated before the console advertises a new capability.

package/dist/ui/managed-agents-console/docs/sandbox-reference.md

@@ -0,0 +1,19 @@
+# Sandbox reference
+
+> [!NOTE] Status: **Shipped alpha image reference.** This describes the pinned coding image used by the supported local providers, not a hosted CMA cloud image.
+
+## Included tooling
+
+The default image includes Bash, Node and npm, Python and uv, Git, curl, jq, ripgrep, common archive tools, and a basic C/C++ build baseline. It supports the built-in read, write, edit, glob, grep, and Bash workflow.
+
+## Filesystem and identity
+
+The guest runs as a non-root user with a read-only root filesystem. Project files, virtual environments, package caches, and npm globals belong under `/workspace`. This is an alpha coding baseline, not a promise that arbitrary system packages or language runtimes are available.
+
+## Network access
+
+Networking is controlled by the environment, not by the image. New environments are offline. Docker-local can use approved HTTPS presets or a validated custom host allowlist; microsandbox-local stays offline-only.
+
+## Image selection
+
+OMA uses a reviewed, digest-pinned image. Users cannot provide arbitrary image references through the public environment API because image selection and egress are security boundaries.

package/dist/ui/managed-agents-console/docs/sandbox-security.md

@@ -0,0 +1,15 @@
+# Sandbox security
+
+> [!NOTE] Status: **Shipped baseline for Docker-local.** Security posture is provider-specific and is not a substitute for your own host security controls.
+
+## OMA-enforced baseline
+
+Docker-local drops Linux capabilities, uses `no-new-privileges`, runs a non-root UID, mounts a read-only root filesystem, and uses constrained temporary filesystems. The default environment denies network access.
+
+## Egress and credentials
+
+When a Docker environment uses an approved allowlist, OMA limits traffic to HTTPS and the selected hosts. Network permission is explicit and immutable. Vault secret values are not displayed to the sandbox or console user as plaintext.
+
+## Operator responsibilities
+
+Protect the appliance host, Docker daemon, workspace and admin keys, and persistent OMA data. Review custom host allowlists carefully. Do not treat alpha sandboxing as a multi-tenant isolation guarantee, and do not enable an untrusted workload solely because a tool-confirmation policy allows it.

package/dist/ui/managed-agents-console/docs/scheduled-deployments.md

@@ -0,0 +1,5 @@
+# Scheduled deployments
+
+> [!WARNING] Status: **Not ready in v1.** OMA has no deployment, deployment-run, cron, pause, archive, or manual-run API.
+
+Run sessions from your own scheduler only if you can own the credential, idempotency, monitoring, retry, and cleanup behavior around it. OMA does not yet expose a managed scheduling contract or webhook-based deployment reporting.

package/dist/ui/managed-agents-console/docs/self-hosted-sandboxes.md

@@ -0,0 +1,15 @@
+# Self-hosted sandboxes
+
+> [!WARNING] Status: **Not a CMA-compatible feature in v1.** OMA is a self-hosted appliance, but it does not implement CMA's remote self-hosted worker protocol or custom-tool tunnels.
+
+## What OMA supports now
+
+The local appliance runs sessions through its configured local sandbox provider. Docker-local is the recommended alpha provider. Microsandbox-local is available for offline execution only.
+
+## What is not available
+
+OMA has no worker registration, remote queue, tunnel, externally hosted custom-tool service, or caller-submitted sandbox result protocol. Do not point an external worker at the session API expecting CMA self-hosted sandbox semantics.
+
+## Operator guidance
+
+Run the appliance on infrastructure you control, keep the workspace and API keys private, and use the supported local smoke commands before admitting real workloads. A future remote-worker architecture must preserve the same default-deny network and secret-boundary guarantees.

package/dist/ui/managed-agents-console/docs/session-operations.md

@@ -0,0 +1,21 @@
+# Session operations
+
+> [!NOTE] Status: **Shipped alpha for create, retrieve, list, archive, and delete.**
+
+## Session states
+
+A session is persisted and can be idle, running, rescheduling, or terminated. Runtime activity is observed through events; status is not a promise that a browser still has a live SSE connection.
+
+## Retrieve and list
+
+Use the console or API to retrieve a session and inspect its selected agent reference, environment, events, resources, and timestamps. Session lists support cursor pagination in both directions and preserve the requested order.
+
+## Archive and delete
+
+Archive an idle session to retain its record without continuing work. Delete an idle session only when you no longer need its persisted events and files.
+
+> [!WARNING] OMA rejects archive and delete for a running session. Send an interrupt event or wait for the turn to settle; a rejected deletion does not stop work.
+
+## Operations not available
+
+OMA does not yet support updating a session, changing its agent configuration while idle, or adding and removing session resources after creation.

package/dist/ui/managed-agents-console/docs/sessions.md

@@ -0,0 +1,21 @@
+# Start a session
+
+> [!NOTE] Status: **Shipped alpha for synchronous, single-agent sessions.**
+
+## Create a session
+
+Create a session with an agent and environment. A bare agent ID selects the latest version; an agent reference with a version pins that immutable revision. The stored session keeps the resolved version for runtime execution.
+
+At creation, supply any supported vault and file resources. Resources are validated and prepared before execution; OMA does not support adding or removing them later.
+
+## Start work
+
+Send a `user.message` event to begin a turn. The console supports prompts, interrupts, and confirmation responses when its live API capability allows them. API clients should use the documented idempotency contract for retry-safe writes.
+
+## Follow progress
+
+Use the session detail and [event stream](#docs=events) to inspect complete agent messages, tool calls and results, confirmations, errors, and raw payloads. Persisted history survives an SSE reconnect.
+
+## Current limitations
+
+OMA does not support agent overrides at session creation, live session updates, token previews, multi-agent threads, or hosted-style asynchronous session scheduling.

package/dist/ui/managed-agents-console/docs/skills.md

@@ -0,0 +1,15 @@
+# Skills
+
+> [!NOTE] Status: **Shipped alpha.** Custom skills are versioned workspace resources delivered to the runtime.
+
+## Create a skill
+
+Upload a skill bundle through the API or console. OMA stores the skill and its versions, validates admission, and snapshots the selected version for runtime use. The API supports creating, listing, retrieving, versioning, and deleting skills.
+
+## Attach a skill to an agent
+
+Reference the desired skill configuration in the agent. A session uses the agent's immutable version, so later agent updates do not change a running or historical session.
+
+## Boundaries
+
+Skills are not arbitrary host access. They run within the selected sandbox and environment policy. Some skill-specific hardening follow-ups remain tracked separately; consult the API reference for the accepted bundle and resource shapes.

package/dist/ui/managed-agents-console/docs/tools.md

@@ -0,0 +1,23 @@
+# Tools
+
+> [!NOTE] Status: **Shipped alpha for the bounded coding toolset.**
+
+## Available tools
+
+OMA supports `bash`, `read`, `write`, `edit`, `glob`, and provider-owned `grep` for the supported local providers. The pinned coding image contains Node/npm, Python/uv, Git, curl, jq, archive tools, and a basic native build baseline.
+
+## Configure a toolset
+
+Tool configuration lives on the agent. OMA validates known built-in names, rejects duplicate configuration, and supports `always_allow` and `always_ask` policies. Use [Permission policies](#docs=permissions) for the review workflow and timeout boundary.
+
+## Custom tools
+
+Custom-tool calls are persisted as events and wait for a `user.custom_tool_result` response from the API client. They are not an invitation to run arbitrary code in the browser or appliance host.
+
+## Web tools
+
+> [!WARNING] `web_fetch` and `web_search` are disabled. Approved Docker egress permits only the environment's HTTPS allowlist; it does not turn host-network access into provider-owned web tools.
+
+## Related resources
+
+Use [Files](#docs=files) for mounts and output, [Skills](#docs=skills) for reusable bundles, and [MCP connector](#docs=integrations) for external tool servers.

package/dist/ui/managed-agents-console/docs/vaults.md

@@ -0,0 +1,19 @@
+# Authenticate with vaults
+
+> [!NOTE] Status: **Shipped alpha for vaults and supported MCP credential flows.**
+
+## Create a vault
+
+Vaults organize workspace-scoped credentials. The console can show vault and credential metadata and health without rendering secret values. The API supports vault and credential lifecycle operations, including archive and delete where the server permits them.
+
+## Use a credential in a session
+
+Attach the needed vault at session creation and configure the compatible MCP server on the agent. OMA resolves supported authentication inside the connector path; the sandbox does not receive a browser-visible plaintext secret.
+
+## Supported and deferred types
+
+OMA supports the shipped static bearer and MCP OAuth flows, including validation where configured. Environment-variable substitution and arbitrary secret injection are not current public credential types.
+
+## Rotation and failures
+
+Archive, update, or replace credentials through their real lifecycle actions. If an OAuth refresh or connector call fails, inspect the resulting session events and credential health; OMA does not claim that a credential is usable merely because its metadata exists.

package/dist/ui/managed-agents-console/docs/webhooks.md

@@ -0,0 +1,11 @@
+# Subscribe to webhooks
+
+> [!WARNING] Status: **Not ready in v1.** OMA has no webhook endpoint registration, signing, delivery queue, retry policy, or event-family subscription API.
+
+## Current alternative
+
+Use the persisted session event API and SSE stream from an application you control. Your application is responsible for reconnecting, backfilling history, deduplicating events, and delivering any downstream notifications.
+
+## Compatibility note
+
+Do not expose a webhook receiver expecting OMA callbacks. A future webhook surface will document its event names, signature verification, delivery semantics, and retry behavior before it is considered available.