@xenosystem/agent-sdk 0.9.11 → 0.9.14

package/README.md

@@ -1,511 +1,511 @@
-# XENO Agent SDK
-
-Core runtime for XENO agent-enabled products. It provides the agent loop, tool execution, permissions, sessions, memory, audit logging, and provider integration used across the XENO platform.
-
-## Runtime Ownership
-
-The ownership program targets P2 feature parity, but this checkout must be described by its generated audit rather than by the target. Run `npm run build && npm run compliance:ownership:artifacts` or inspect `docs/compliance/ownership-inventory.md`. Node remains an explicitly external host through P2, and development/build packages remain third-party build inputs. Do not claim that a release is fully proprietary, entirely Xeno-owned, or free of third-party runtime code unless the packaged release smoke prints the corresponding achieved level and the required provenance/counsel gates are complete.
-
-The canonical policy and engineering clean-room controls are under `ownership/`.
-
-## Vision
-
-Every XENO creative app (Pixel, Motion, Sound) has an AI agent embedded directly into the interface. Users open a sidebar, type what they want ("remove the background from this layer", "cut the silence from this podcast", "match-cut these two clips"), and the agent translates that into tool calls against the app's engine. One request can span multiple apps: "Create a product video from these photos with background music" triggers coordinated work across Pixel, Motion, and Sound simultaneously.
-
-The SDK is designed so the same governed agent contracts can be embedded across
-creative products instead of rebuilding orchestration in every application.
-
-```
-Without agent SDK:  User manually opens Pixel, edits, opens Motion, edits, opens Sound, edits
-With agent SDK:     User says "Create a product video" -> agents in all 3 apps coordinate automatically
-```
-
-## Current State
-
-- **Provider-agnostic runtime** with XENO-hosted, local, direct-provider, and
-  generic compatible routes
-- **Extensible tool system** with demand-loaded schemas, managed background
-  operations, terminal support, and host-registered domain tools
-- **4 permission modes**: `default`, `acceptEdits`, `bypassPermissions`, `plan`
-- **4-level identity hierarchy**: global, project, role, session
-- **4-level memory system** with auto-capture (conversation, session, project, global)
-- **Session persistence** with checkpoints, transcript writing, and crash recovery
-- **Audit logging** in JSON-lines format (who, what, when, result)
-- **Agent orchestration** with profiles, delegation, teams, goals, workflows,
-  monitors, schedules, hooks, and durable recovery
-- **Artifact and evidence protocol** with immutable revisions, review events,
-  stable anchors, provenance, and evidence graphs
-- **Secure execution contracts and capability leases** that preserve
-  profile/host denials and distinguish policy, hardening, and containment
-- **Agent Skills v2** with interoperable `SKILL.md` discovery, progressive
-  disclosure, hash-bound resources, policy intersection, and privacy-safe audit
-- **Current MCP transport and OAuth** with Streamable HTTP, resumable SSE,
-  session recovery, legacy negotiation, PKCE/resource binding, refresh rotation,
-  and network-policy enforcement
-- **Advanced governed contracts** for cross-model Oracle review, commit-bound
-  source research, portable Recipes, Git mutation restore, plugin signatures
-  and relevance, MCP Apps, and authenticated hosted channels
-- Dual ESM/CommonJS package conditions for every public entry point, TypeScript
-  7 native typechecking, TypeScript 6 compiler-API compatibility, tsup build
-- Production dependencies: none
-
-### Agent Profiles
-
-The SDK includes versioned specialist contracts that bind prompts to
-enforceable tool, permission, skill, hook, memory, Soul, isolation,
-external-action, and completion policies. Profiles compile through monotonic
-capability intersection, so organization and host boundaries can narrow but
-never widen authority. See [docs/agent-profiles.md](docs/agent-profiles.md).
-
-### Artifact Protocol and secure execution foundations
-
-`@xenosystem/agent-sdk/artifacts` provides the durable interchange
-contract for plans, patches, diffs, documents, diagrams, screenshots,
-recordings, tests, reviews, releases, SBOMs, provenance, and attestations.
-Content revisions are immutable; comments and decisions are append-only; an
-approval applies only to the exact revision and content hash reviewed.
-
-The artifact barrel also provides first-class Wave 3 planning and review
-contracts. `XenoSpecLifecycleService` persists separately hashed requirements,
-design, task-graph, and plan artifacts; approved plans remain immutable while
-execution and task evidence advance through separate revisions.
-`detectXenoSpecDrift()` checks plan binding, dependencies, acceptance evidence,
-and observed paths. `XenoMultiAgentReviewCoordinator` runs independent review
-dimensions, deduplicates findings, requires verifier reproduction (or an
-explicit evidence quorum) before marking a finding verified, and emits one
-portable `xeno.review-report.v1` artifact.
-
-`@xenosystem/agent-sdk/intelligence` provides the persistent
-repository-index contract: bounded documents and chunks, symbols, imports,
-test/document links, Git provenance, deterministic lexical retrieval,
-host-supplied exact-model semantic vectors, multi-workspace identity, freshness
-inspection, relationship traversal, and an atomic owner-private file store.
-Semantic vectors are compared only when model identity and dimensions match.
-Hosts retain source collection and embedding-provider authority.
-
-`@xenosystem/agent-sdk/control-room` projects durable product state
-into one hash-bound supervision snapshot. It validates agent hierarchies and
-task dependencies, categorizes health and stale heartbeats, aggregates usage,
-prioritizes attention, and plans scoped actions. Source adapters can explicitly
-narrow advertised actions; they cannot grant controls disallowed by runtime
-status. This lets CLI, Hub, and hosted clients share one view without
-fabricating unsupported buttons or exposing private reasoning.
-
-`@xenosystem/agent-sdk/hosted` defines the immutable hosted-
-environment, trigger, replay, execution-adapter, cross-device control, and run-
-result contracts. Protocol-v2 adapter certificates bind interactive control,
-Artifact Protocol output, and Git-result reporting in addition to the OS
-containment claims. Hosted messages and exact-scope approval decisions are
-normalized, bounded, and tamper-evident; acknowledgements are normalized; run
-results hash-bind Git/credential-free PR metadata and artifact/evidence IDs.
-These contracts let the Agents API, CLI, and Hub interoperate without treating
-policy metadata as proof of containment.
-
-Graphical and web renderers must import
-`@xenosystem/agent-sdk/artifacts/browser`. That browser-safe entry
-contains bounded record/diff projection and protocol types without importing
-the Node filesystem, process-lock, or crypto implementations owned by the main
-artifact barrel.
-
-The security barrel exposes capability leases and the Secure Execution
-Contract. A lease is narrow, expiring, operation-bound authority and cannot
-override an Agent Profile or host denial. The execution contract fingerprints
-the effective filesystem, network, process, environment, secret,
-external-action, browser, and computer-use boundary. These are shared protocol
-foundations; they do not by themselves make an OS adapter release-certified.
-
-### Governed browser and computer automation
-
-`@xenosystem/agent-sdk/automation` defines one versioned operation
-catalog and adapter contract for XENO Browser and XENO Use. The governed
-executor validates the execution-contract fingerprint and real preflight
-target, persists required before evidence, consumes an exact capability lease,
-dispatches through the adapter, revalidates the resulting target, and persists
-after/recording evidence as Artifact Protocol records. Missing required evidence
-is quarantined as `evidence-incomplete` rather than accepted as success.
-
-`XenoLoopbackAutomationAdapter` provides the bearer-authenticated, response-
-bounded local transport to XENO Browser. Read and action domain authority are
-separate; explicit browser/network deny rules take precedence; operation IDs
-are idempotent; and immediate stop propagates to the bound native target. See
-[Governed Automation](docs/GOVERNED_AUTOMATION.md).
-
-### Agent Skills v2
-
-`@xenosystem/agent-sdk/skills` provides a host-neutral implementation
-of directory-based `SKILL.md` packages. Discovery reads only metadata and hashed
-resource descriptors. `createXenoSkillTool()` demand-loads and re-verifies full
-instructions when invoked, then intersects tool and external-action policy with
-the active host/Profile boundary. Standard `allowed-tools` is treated as a
-preapproval request, never as an authority grant. Legacy inline XENO skills can
-be adapted without breaking existing hosts.
-
-### MCP Streamable HTTP and OAuth
-
-`@xenosystem/agent-sdk/mcp` targets MCP protocol `2025-11-25`.
-URL-only server configs use Streamable HTTP; explicit `sse` remains available
-for deprecated servers and can be negotiated only after a rejected Streamable
-HTTP initialization. The transport handles protocol/session headers, JSON and
-SSE responses, `Last-Event-ID` resumption, duplicate suppression, session
-reinitialization, server instructions, manual redirect checks, and permission-
-profile validation.
-
-`MCPOAuthClient` implements protected-resource and authorization-server
-discovery, PKCE S256, RFC 8707 resource binding, pre-registered/CIMD/explicit
-DCR client selection, authorization-code exchange, refresh-token rotation, and
-bounded metadata responses. Hosts own user interaction and secret persistence;
-token values are never added to MCP state or model context.
-
-### Advanced runtime contracts
-
-The SDK also exposes additive contracts for cross-model Oracle reports,
-commit-bound remote-source research, portable Recipes, automatic Git mutation
-checkpoints, signed/locked plugins, repository-aware relevance, MCP Apps, and
-authenticated GitLab/Teams/Jira hosted events. These contracts bind identity,
-authority, evidence, and persistence without granting a host UI, network,
-credential, or deployment authority. See
-[Advanced Runtime Contracts](docs/ADVANCED_RUNTIME_CONTRACTS.md).
-
-## Delivery automation
-
-The SDK repo now carries the same production automation discipline as the CLI:
-
-- `.github/workflows/ci.yml` -- cross-platform build verification plus full Linux runtime checks
-- `.github/workflows/certification.yml` -- scheduled production/stress verification and large-repo coding benchmarks
-- `.github/workflows/release.yml` -- npm Trusted Publishing with provenance, checksums, and GitHub release artifacts
-
-## Architecture
-
-```
-xeno-agent-sdk/
-src/
-  core/, runtime/, providers/       Agent loop, streaming, context, providers
-  tools/, terminal/, media/         Tools and managed operations
-  security/, governance/            Policy, permissions, leases, execution law
-  session/, memory/, identity/      Durable user and conversation context
-  orchestration/, control-plane/    Agents, teams, workflows, goals, recovery
-  agents/, prompts/, soul/          Profiles, prompts, learned state
-  artifacts/                        Artifacts, reviews, provenance, evidence
-  automation/                       Governed browser/computer adapter protocol
-  oracle/, research/, recipes/      Independent review, source evidence, reusable DAGs
-  hosted/, intelligence/            Fleet contracts and repository intelligence
-  skills/                           Skills v2 discovery, loading, policy, audit
-  hooks/, plugins/, mcp/            Extension and interoperability contracts
-  app-server/, integrations/        Remote and host protocols
-  audit/, observability/            Audit, usage, telemetry, diagnostics
-  ui/, electron/, adapters/         Optional UI and host integration layers
-  persistence/, config/, utils/     Durable and cross-cutting utilities
-```
-
-## Selected subsystems
-
-| Subsystem | Purpose | Key exports |
-|-----------|---------|-------------|
-| **Core Loop** | Agentic turn loop with tool dispatch, streaming, reducer | `AgentLoop`, `AgentLoopConfig` |
-| **Tools** | Demand-loaded registry, built-ins, managed operations, host tools | `ToolRegistry`, `registry` |
-| **Security** | Permissions, policy, leases, execution contracts, adapter claims | `PermissionEngine`, `SecureExecutionContract` |
-| **Session** | Persistence, checkpoints, transcripts, locks, recovery | `SessionManager`, `CheckpointManager` |
-| **Identity** | Persona loading and resolution across 4 levels | `IdentityLoader`, `IdentityResolver` |
-| **Memory** | Hierarchical memory with budget management | `MemoryManager`, `MemoryBudget` |
-| **Audit** | JSON-lines logging for every action | `AuditLogger` |
-| **Config** | Model settings, API endpoints, defaults | `XENO_API_BASE`, `DEFAULT_MODEL` |
-| **Delegation** | Planner/executor/reviewer sub-agent workflows | `DelegatedAgent`, `DelegatedTurn` |
-| **Artifacts** | Immutable revisions, review lifecycle, anchors, evidence graph | `XenoArtifact`, `ArtifactRepository` |
-| **Agent Profiles** | Enforceable specialist runtime identities | `CompiledAgentProfile` |
-| **Agent Skills** | Metadata-first `SKILL.md` catalog and demand-loaded invocation | `discoverXenoSkills`, `createXenoSkillTool` |
-| **MCP** | Stdio, Streamable HTTP, legacy SSE, OAuth discovery/PKCE/refresh | `MCPManager`, `StreamableHTTPTransport`, `MCPOAuthClient` |
-| **Oracle** | Independent opinions, adjudication, citations, disagreement | `XenoOracleCoordinator` |
-| **Research** | Commit-bound source excerpts, findings, provenance | `XenoSourceResearchReport` |
-| **Recipes** | Strict portable DAGs with authority, budgets, and fingerprints | `compileXenoRecipe` |
-| **Plugin trust** | Signatures, locks, publisher policy, advisory relevance | `verifyPluginSupplyChain`, `scorePluginRelevance` |
-| **Types** | All shared TypeScript types | `ExecutionMode`, `ResolvedIdentity`, etc. |
-
-## How Apps Integrate
-
-The primary entry point is `createXenoAgent()`. Each app registers its own operations as tools, and the SDK handles everything else: the agentic loop, permission checks, audit logging, memory, sessions.
-
-```typescript
-import { createXenoAgent } from '@xenosystem/agent-sdk'
-
-// Each app defines its domain-specific tools
-const pixelTools = {
-  'layer.remove-bg': {
-    description: 'Remove background from the active layer',
-    execute: async (params) => {
-      const result = await xenoLib.rmbg(params.layerId)   // xeno-lib AI model
-      await engine.applyMask(params.layerId, result.mask)  // app engine
-      return { success: true, layerId: params.layerId }
-    },
-    confirm: true,  // requires user approval
-  },
-  'brush.draw': {
-    description: 'Draw a stroke on the active layer',
-    execute: async (params) => engine.drawStroke(params),
-    confirm: false,  // safe, no confirmation needed
-  },
-  'file.export': {
-    description: 'Export the current document',
-    execute: async (params) => exporter.save(params),
-    confirm: true,
-    destructive: false,
-  },
-}
-
-const agent = await createXenoAgent({
-  toolRegistry: pixelTools,
-  model: 'claude-sonnet-4-20250514',
-  permissionConfig: { mode: 'default' },
-  // identity, memory, session all auto-configured
-})
-```
-
-### End-to-End Example
-
-User types in Pixel's agent sidebar: **"Remove the background from this layer"**
-
-```
-1. Agent receives natural language input
-2. LLM decides to call tool: layer.remove-bg({ layerId: 'layer-3' })
-3. Permission engine checks: confirm=true -> prompts user for approval
-4. User approves -> tool executes:
-     a. Calls xeno-lib's RMBG model (Rust, ONNX, GPU-accelerated)
-     b. Receives alpha mask
-     c. Applies mask to layer in Pixel's rendering engine
-5. Audit logger records: who=user, what=layer.remove-bg, when=timestamp, result=success
-6. Agent responds: "Done. Background removed from Layer 3."
-```
-
-## The Tool Registry Pattern
-
-Apps extend the SDK by registering their operations as tools. The SDK provides
-file, search, shell, background-process, terminal, media, and other reusable
-tool contracts; apps add namespaced domain-specific tools:
-
-| App | Example tools |
-|-----|---------------|
-| **Pixel** | `brush.draw`, `layer.remove-bg`, `selection.expand`, `filter.blur`, `file.export` |
-| **Motion** | `timeline.cut`, `clip.speed`, `transition.add`, `keyframe.set`, `render.export` |
-| **Sound** | `track.eq`, `region.normalize`, `master.lufs`, `effect.reverb`, `bounce.export` |
-| **Hub** | `workspace.create`, `app.launch`, `agent.dispatch` |
-
-Each tool declares: `description` (for the LLM), `execute` (the implementation), `confirm` (whether to ask the user), and `destructive` (whether it's irreversible).
-
-## Cross-App Orchestration
-
-One agent request can trigger coordinated work across multiple apps. The Hub acts as an orchestrator, dispatching tasks to per-app agents via a mailbox system.
-
-```
-User: "Create a product video from these photos with background music"
-
-xeno-hub (orchestrator)
-    |-- mailbox.send('pixel-agent', { task: 'export hero images as PNGs' })
-    |-- mailbox.send('motion-agent', { task: 'create timeline from exported images' })
-    |-- mailbox.send('sound-agent', { task: 'add background track, master to -14 LUFS' })
-
-Each agent receives via:
-    mailbox.onMessage((msg) => agent.execute(msg.task))
-```
-
-Messages are JSON-serializable for cross-process IPC. The SDK includes agent
-protocol/registry and `CrossAppRouter` primitives with bounded delivery.
-Production transport, durable replay, authentication, and product adoption are
-host responsibilities and must be verified in each consuming repository.
-
-## Security Model
-
-### Permission Modes
-
-| Mode | Behavior |
-|------|----------|
-| `default` | Ask user before writes and shell commands |
-| `acceptEdits` | Auto-approve file edits, ask for shell commands |
-| `bypassPermissions` | Auto-approve everything (development/testing only) |
-| `plan` | Read-only mode, agent can only plan and suggest |
-
-### Safety Features
-
-- **Policy enforcement**: canonical physical-path checks reject traversal through symlinks/junctions, UNC/device, extended-length, drive-relative, root-relative, alternate-data-stream, reserved-device, and ambiguous paths
-- **Shell policy**: parsed PowerShell/Bash file operands, redirections, and path parameters enforce read/write capabilities; unresolved dynamic filesystem operands fail closed
-- **Execution security levels**: `policy-only`, `process-hardened`, and `contained` are separate API contracts. The legacy `requireOsContainment: true` flag now means strict `contained` and never accepts process hardening as a substitute.
-- **Windows process hardening**: `executionLevel: "process-hardened"` uses a reduced primary token, low integrity for read-only execution, an explicit inherited-handle allowlist, a minimized environment, and a kill-on-close Job Object. It does not isolate filesystem reads or network access and is for trusted workspaces only.
-- **Fail-closed containment**: the SDK ships five reviewed, digest-pinned runtime executables plus two Windows host-preparation helpers extracted from the integrity-pinned MXC 0.7.0 artifact; it does not install or execute MXC's JavaScript wrapper or transitive `node-pty` graph. Windows x64/ARM64, Linux x64/ARM64, and macOS ARM64 are supported, but asset presence is not certification. Windows setup is an explicit elevated host operation and is never attempted by normal agent execution. `contained` activates only with a short-lived, candidate-, platform-, adapter-, native-report-, and independently signed reviewer-bound host manifest. A source build, unsupported target, mismatch, or missing binding fails with `CONTAINMENT_UNAVAILABLE`; executable discovery is never treated as certification.
-- **Destructive action gates**: delete, overwrite, and shell commands require explicit approval
-- **Audit trail**: every tool call logged in JSON-lines format with trace IDs
-- **Risk classification**: each tool call classified as low/medium/high risk
-- **Permission rules**: per-tool, per-path override rules
-
-The policy layer and Windows process hardening are defense in depth, not a claim that arbitrary untrusted code is contained. See [Security Boundaries](docs/SECURITY_BOUNDARIES.md) for the capability matrix and migration contract.
-
-### Managed Shell Processes
-
-`UnifiedExecManager` is the canonical owner for pipe and PTY process lifecycles. `BackgroundProcessManager` remains the task-oriented compatibility facade and adds owner scoping, bounded file-backed output, same-process foreground-to-background promotion, completion events, input, resize, and human-writer leases.
-
-- `Bash` accepts `tty: true` only with `run_in_background: true`.
-- `TaskInput` writes to or waits on an interactive task. Input text is projected to byte-count/task metadata before audit, permission, callback, and transcript sinks.
-- PTY support is adapter based. Hosts register an optional `XenoPtyAdapter`; missing capability returns `PTY_UNAVAILABLE` and never silently falls back to a pipe.
-- App-server `exec.start` accepts `tty`, `cols`, and `rows`; `exec.resize` is owner scoped alongside write, output, list, and terminate.
-- `SessionManager.recordDirectShellResult` persists bounded local-command output as user-role untrusted context with semantic metadata, not as a fabricated model tool call.
-
-### Managed Tool Operations
-
-Tool calls now receive a stable operation ID, deadline, completion policy (`await`, `observe`, or `detach`), progress counters, terminal reason, and artifact evidence. Recovery snapshots are written atomically under the user control-plane directory, while redacted operation transitions are appended to a private JSONL ledger. Raw command text is not copied into operation lists or the ledger.
-
-- A promotable foreground `Bash` command moves to the background by changing presentation on the same process. PID, task/process IDs, output cursor, and deadline are retained; the command is never re-executed.
-- `TaskOutput({ task_id, offset })` remains a nonblocking compatibility read. `wait: true` adds an event-driven wait capped at 30 seconds and always reports explicit `Operation terminal: yes|no`, state, runtime, idle time, output delta, UTF-8-safe next offset, and suggested action.
-- Finite model-created background work defaults to `await`. The parent turn suspends without another provider request and resumes from a durable continuation notification after terminal output arrives. User stop, detach, clear, interrupt, or rewind cancels stale automatic continuation.
-- `expected_outputs` on `Bash` records generic file postconditions. Missing or unstable outputs fail the logical operation even after exit code 0; partial artifacts are still reported after timeout/failure.
-- `ReadImage` preflights format, dimensions, and bytes. The dependency-free `xeno-owned-raster` path performs owned PNG/DEFLATE decode and encode, JPEG, GIF, VP8/VP8L WebP decode, bounded SVG software rasterization, and resizing; BMP and Netpbm inputs normalize through the same owned PNG path. Oversized supported inputs become owner-private bounded PNG previews without an ambient decoder or canvas fallback. Private previews are removed during session cleanup and originals stay unchanged. The exact approved profiles and explicit rejections are documented in [`docs/owned-media-matrix.md`](docs/owned-media-matrix.md).
-
-Temporary rollback controls default to enabled: `XENO_TOOL_OPERATION_RUNTIME`, `XENO_AUTO_BACKGROUND_FOREGROUND_BASH`, `XENO_TASK_OUTPUT_WAIT`, `XENO_AUTO_TOOL_CONTINUATION`, and `XENO_READ_IMAGE_AUTO_PREVIEW`. Setting a control to `0` disables its optional behavior without deleting active tasks or persisted operation records.
-
-On Windows, ordinary managed pipe tasks use the existing kill-on-close Job Object launcher when available and report `windows-job-object`; the explicit `windows-tree-fallback` uses tree termination but is not reported as verified Job ownership. Persistent PowerShell defaults to Windows PowerShell 5.1. Set `XENO_POWERSHELL_EXECUTABLE=pwsh.exe` to use PowerShell 7. Process ownership and cleanup are not claims of untrusted-code containment.
-
-See [docs/managed-tool-operations.md](docs/managed-tool-operations.md) for the runtime and troubleshooting contract.
-
-### Agent Harness Reliability
-
-- Tool inputs are JSON-schema validated by default; malformed calls are returned to the model as typed errors.
-- Interrupted or orphaned tool exchanges are repaired before resumable history is sent back to a provider.
-- Repeated identical failing tool calls are circuit-broken before they can loop indefinitely.
-- Query lifecycle transitions are emitted as typed runtime events and guarded by idle, active-operation lease, and hard timeouts.
-- Context overflow triggers one semantic compact-and-retry path. Old tool payloads are compacted before conversation history is dropped, message count has a hard cap, and preflight token estimates are model-aware with an injectable exact-tokenizer seam.
-- The default tool registry demand-loads optional schemas through `ToolSearch` instead of advertising every full schema on every request.
-
-### Direct Provider Adapters
-
-Provider-normalized deployments can continue using the default Xeno API transport. Direct integrations are available from the provider subpath:
-
-```typescript
-import { createDirectProvider } from '@xenosystem/agent-sdk/providers'
-import { createXenoAgent } from '@xenosystem/agent-sdk'
-
-const provider = createDirectProvider({
-  kind: 'openai-responses', // 'anthropic' | 'openai-responses' | 'google' | 'openai-compatible'
-  apiKey: process.env.PROVIDER_API_KEY!,
-})
-
-const { agent } = await createXenoAgent({ provider })
-```
-
-The adapters translate streaming text, images, parallel tool calls/results, usage, cancellation, and typed failures for Messages, Responses, Gemini, and explicitly profiled chat-compatible endpoints. Generic endpoints require a capability profile and local HTTP requires an explicit local-network endpoint profile. See [docs/PROVIDER_CONFORMANCE.md](docs/PROVIDER_CONFORMANCE.md).
-
-The provider subpath also exposes a capability-driven product catalog, atomic workspace connection store, bounded credential/model probe, and routing policy. Connections hold credential reference names, never raw credentials. Presets for Azure OpenAI, Bedrock, and Vertex truthfully report `requires-host-adapter` until dedicated adapters are supplied.
-
-```typescript
-import {
-  FileXenoProviderConnectionStore,
-  XenoProviderCatalog,
-  probeXenoProvider,
-  selectXenoProviderRoute,
-} from '@xenosystem/agent-sdk/providers'
-```
-
-### Secure Sharing and Handoff
-
-`@xenosystem/agent-sdk/sharing` provides deterministic redaction, Ed25519-signed expiring read-only shares, capability/audience/revocation verification, signed session handoffs, and an atomic checksum-protected local registry. Embedded public keys prove integrity but do not imply issuer trust; consuming products supply their own trust store and must intersect handoff authority with local policy.
-
-```typescript
-import {
-  createXenoSecureShare,
-  verifyXenoSecureShare,
-  createXenoSessionHandoff,
-  verifyXenoSessionHandoff,
-  FileXenoShareRegistry,
-} from '@xenosystem/agent-sdk/sharing'
-```
-
-## Session Persistence
-
-- Sessions have unique IDs with embedded timestamps
-- Full conversation transcripts written to disk
-- Checkpoint system for long-running workflows
-- Lock management prevents concurrent access to the same session
-- Turn restore for crash recovery (resume mid-conversation)
-- Session registry tracks all sessions per project
-
-## Memory System
-
-4-level hierarchy with automatic capture and budget management:
-
-| Level | Scope | Persists | Example |
-|-------|-------|----------|---------|
-| **Conversation** | Current turn | No | "The user just asked about Layer 3" |
-| **Session** | Current session | Until session ends | "We're working on the hero image" |
-| **Project** | Current project | Yes | "This project uses 300 DPI, CMYK" |
-| **Global** | All projects | Yes | "User prefers dark theme, metric units" |
-
-Memory is injected into the system prompt with configurable token budgets to avoid context overflow.
-
-## LLM Providers
-
-| Provider | How | When |
-|----------|-----|------|
-| **Xeno API** (cloud) | `api.xenostudio.ai` proxy to hosted models | Online, highest capability |
-| **xeno-rt** (local) | OpenAI-compatible API on localhost | Offline, privacy, no cost |
-| **Ollama** (local) | OpenAI-compatible API | Alternative local provider |
-
-The SDK is provider-agnostic. OpenAI-compatible endpoints are supported through an explicit capability and endpoint-security profile; compatibility is verified by conformance fixtures rather than inferred from the endpoint label. Provider selection and fallback logic are handled by the config subsystem.
-
-## Consumers
-
-| App | How it uses the SDK | Example agent task |
-|-----|--------------------|--------------------|
-| **xeno-agent-cli** | Terminal agent (reference implementation) | "Refactor this codebase" |
-| **xeno-pixel** | Image editing agent sidebar | "Remove backgrounds from 50 images" |
-| **xeno-motion** | Video editing agent sidebar | "Cut this interview into a highlight reel" |
-| **xeno-sound** | Audio editing agent sidebar | "Master this podcast to -16 LUFS" |
-| **xeno-hub** | Orchestrator routing tasks between apps | "Create marketing materials" dispatches to Pixel + Motion + Sound |
-
-## Xeno-Owned UI
-
-The `/ui` subpath provides a framework-neutral controller, semantic accessibility view, and optional owned DOM renderer. It has no React runtime or peer dependency and remains isolated from the Node-only core entry point.
-
-```ts
-import {
-  createAgentUiController,
-  mountAgentUi,
-} from "@xenosystem/agent-sdk/ui";
-
-const controller = createAgentUiController({
-  agent: myAgentLoop,
-  enablePermissionRequests: true,
-});
-const view = mountAgentUi(document.querySelector("#agent")!, controller, {
-  agentName: "Xeno Agent",
-});
-
-// App shutdown:
-view.dispose();
-controller.dispose();
-```
-
-Framework integrations can subscribe to immutable controller snapshots and call `createAgentUiView` instead of mounting the DOM renderer. Renderer contract version `1` includes message streaming, tool state, token usage, cancellation, retry, permission decisions, safe markdown segments, keyboard submission, and accessible roles/live regions. See [the UI v1 migration guide](docs/migrations/sdk-ui-v1.md).
-
-## Ecosystem Position
-
-```
-LAYER 5 -- APPS (Pixel, Motion, Sound, Hub)
-    | embed xeno-agent-sdk for AI automation
-    | agent sidebar in every app
-LAYER 3 -- THIS REPO (xeno-agent-sdk)
-    | uses LLM providers + invokes AI models
-LAYER 2 -- COMPUTE (xeno-rt for LLM, xeno-lib for 17 AI models)
-    | runs on
-LAYER 1 -- PLATFORM (servers, auth, credits)
-```
-
-See [Full Ecosystem Report](../XENO%20CORPORATION%20-%20Full%20Ecosystem%20Report.md) for complete context.
-
-## Development
-
-```bash
-npm install
-npm run build      # tsup -> ESM + CommonJS package outputs
-npm run typecheck   # TypeScript 7 native strict-mode check
-npm run typecheck:compat # TypeScript 6 compatibility check for API-based tooling
-```
-
-## License
-
-Proprietary and confidential. Copyright (c) 2026 XENO Corporation.
-All rights reserved.
+# XENO Agent SDK
+
+Core runtime for XENO agent-enabled products. It provides the agent loop, tool execution, permissions, sessions, memory, audit logging, and provider integration used across the XENO platform.
+
+## Runtime Ownership
+
+The ownership program targets P2 feature parity, but this checkout must be described by its generated audit rather than by the target. Run `npm run build && npm run compliance:ownership:artifacts` or inspect `docs/compliance/ownership-inventory.md`. Node remains an explicitly external host through P2, and development/build packages remain third-party build inputs. Do not claim that a release is fully proprietary, entirely Xeno-owned, or free of third-party runtime code unless the packaged release smoke prints the corresponding achieved level and the required provenance/counsel gates are complete.
+
+The canonical policy and engineering clean-room controls are under `ownership/`.
+
+## Vision
+
+Every XENO creative app (Pixel, Motion, Sound) has an AI agent embedded directly into the interface. Users open a sidebar, type what they want ("remove the background from this layer", "cut the silence from this podcast", "match-cut these two clips"), and the agent translates that into tool calls against the app's engine. One request can span multiple apps: "Create a product video from these photos with background music" triggers coordinated work across Pixel, Motion, and Sound simultaneously.
+
+The SDK is designed so the same governed agent contracts can be embedded across
+creative products instead of rebuilding orchestration in every application.
+
+```
+Without agent SDK:  User manually opens Pixel, edits, opens Motion, edits, opens Sound, edits
+With agent SDK:     User says "Create a product video" -> agents in all 3 apps coordinate automatically
+```
+
+## Current State
+
+- **Provider-agnostic runtime** with XENO-hosted, local, direct-provider, and
+  generic compatible routes
+- **Extensible tool system** with demand-loaded schemas, managed background
+  operations, terminal support, and host-registered domain tools
+- **4 permission modes**: `default`, `acceptEdits`, `bypassPermissions`, `plan`
+- **4-level identity hierarchy**: global, project, role, session
+- **4-level memory system** with auto-capture (conversation, session, project, global)
+- **Session persistence** with checkpoints, transcript writing, and crash recovery
+- **Audit logging** in JSON-lines format (who, what, when, result)
+- **Agent orchestration** with profiles, delegation, teams, goals, workflows,
+  monitors, schedules, hooks, and durable recovery
+- **Artifact and evidence protocol** with immutable revisions, review events,
+  stable anchors, provenance, and evidence graphs
+- **Secure execution contracts and capability leases** that preserve
+  profile/host denials and distinguish policy, hardening, and containment
+- **Agent Skills v2** with interoperable `SKILL.md` discovery, progressive
+  disclosure, hash-bound resources, policy intersection, and privacy-safe audit
+- **Current MCP transport and OAuth** with Streamable HTTP, resumable SSE,
+  session recovery, legacy negotiation, PKCE/resource binding, refresh rotation,
+  and network-policy enforcement
+- **Advanced governed contracts** for cross-model Oracle review, commit-bound
+  source research, portable Recipes, Git mutation restore, plugin signatures
+  and relevance, MCP Apps, and authenticated hosted channels
+- Dual ESM/CommonJS package conditions for every public entry point, TypeScript
+  7 native typechecking, TypeScript 6 compiler-API compatibility, tsup build
+- Production dependencies: none
+
+### Agent Profiles
+
+The SDK includes versioned specialist contracts that bind prompts to
+enforceable tool, permission, skill, hook, memory, Soul, isolation,
+external-action, and completion policies. Profiles compile through monotonic
+capability intersection, so organization and host boundaries can narrow but
+never widen authority. See [docs/agent-profiles.md](docs/agent-profiles.md).
+
+### Artifact Protocol and secure execution foundations
+
+`@xenosystem/agent-sdk/artifacts` provides the durable interchange
+contract for plans, patches, diffs, documents, diagrams, screenshots,
+recordings, tests, reviews, releases, SBOMs, provenance, and attestations.
+Content revisions are immutable; comments and decisions are append-only; an
+approval applies only to the exact revision and content hash reviewed.
+
+The artifact barrel also provides first-class Wave 3 planning and review
+contracts. `XenoSpecLifecycleService` persists separately hashed requirements,
+design, task-graph, and plan artifacts; approved plans remain immutable while
+execution and task evidence advance through separate revisions.
+`detectXenoSpecDrift()` checks plan binding, dependencies, acceptance evidence,
+and observed paths. `XenoMultiAgentReviewCoordinator` runs independent review
+dimensions, deduplicates findings, requires verifier reproduction (or an
+explicit evidence quorum) before marking a finding verified, and emits one
+portable `xeno.review-report.v1` artifact.
+
+`@xenosystem/agent-sdk/intelligence` provides the persistent
+repository-index contract: bounded documents and chunks, symbols, imports,
+test/document links, Git provenance, deterministic lexical retrieval,
+host-supplied exact-model semantic vectors, multi-workspace identity, freshness
+inspection, relationship traversal, and an atomic owner-private file store.
+Semantic vectors are compared only when model identity and dimensions match.
+Hosts retain source collection and embedding-provider authority.
+
+`@xenosystem/agent-sdk/control-room` projects durable product state
+into one hash-bound supervision snapshot. It validates agent hierarchies and
+task dependencies, categorizes health and stale heartbeats, aggregates usage,
+prioritizes attention, and plans scoped actions. Source adapters can explicitly
+narrow advertised actions; they cannot grant controls disallowed by runtime
+status. This lets CLI, Hub, and hosted clients share one view without
+fabricating unsupported buttons or exposing private reasoning.
+
+`@xenosystem/agent-sdk/hosted` defines the immutable hosted-
+environment, trigger, replay, execution-adapter, cross-device control, and run-
+result contracts. Protocol-v2 adapter certificates bind interactive control,
+Artifact Protocol output, and Git-result reporting in addition to the OS
+containment claims. Hosted messages and exact-scope approval decisions are
+normalized, bounded, and tamper-evident; acknowledgements are normalized; run
+results hash-bind Git/credential-free PR metadata and artifact/evidence IDs.
+These contracts let the Agents API, CLI, and Hub interoperate without treating
+policy metadata as proof of containment.
+
+Graphical and web renderers must import
+`@xenosystem/agent-sdk/artifacts/browser`. That browser-safe entry
+contains bounded record/diff projection and protocol types without importing
+the Node filesystem, process-lock, or crypto implementations owned by the main
+artifact barrel.
+
+The security barrel exposes capability leases and the Secure Execution
+Contract. A lease is narrow, expiring, operation-bound authority and cannot
+override an Agent Profile or host denial. The execution contract fingerprints
+the effective filesystem, network, process, environment, secret,
+external-action, browser, and computer-use boundary. These are shared protocol
+foundations; they do not by themselves make an OS adapter release-certified.
+
+### Governed browser and computer automation
+
+`@xenosystem/agent-sdk/automation` defines one versioned operation
+catalog and adapter contract for XENO Browser and XENO Use. The governed
+executor validates the execution-contract fingerprint and real preflight
+target, persists required before evidence, consumes an exact capability lease,
+dispatches through the adapter, revalidates the resulting target, and persists
+after/recording evidence as Artifact Protocol records. Missing required evidence
+is quarantined as `evidence-incomplete` rather than accepted as success.
+
+`XenoLoopbackAutomationAdapter` provides the bearer-authenticated, response-
+bounded local transport to XENO Browser. Read and action domain authority are
+separate; explicit browser/network deny rules take precedence; operation IDs
+are idempotent; and immediate stop propagates to the bound native target. See
+[Governed Automation](docs/GOVERNED_AUTOMATION.md).
+
+### Agent Skills v2
+
+`@xenosystem/agent-sdk/skills` provides a host-neutral implementation
+of directory-based `SKILL.md` packages. Discovery reads only metadata and hashed
+resource descriptors. `createXenoSkillTool()` demand-loads and re-verifies full
+instructions when invoked, then intersects tool and external-action policy with
+the active host/Profile boundary. Standard `allowed-tools` is treated as a
+preapproval request, never as an authority grant. Legacy inline XENO skills can
+be adapted without breaking existing hosts.
+
+### MCP Streamable HTTP and OAuth
+
+`@xenosystem/agent-sdk/mcp` targets MCP protocol `2025-11-25`.
+URL-only server configs use Streamable HTTP; explicit `sse` remains available
+for deprecated servers and can be negotiated only after a rejected Streamable
+HTTP initialization. The transport handles protocol/session headers, JSON and
+SSE responses, `Last-Event-ID` resumption, duplicate suppression, session
+reinitialization, server instructions, manual redirect checks, and permission-
+profile validation.
+
+`MCPOAuthClient` implements protected-resource and authorization-server
+discovery, PKCE S256, RFC 8707 resource binding, pre-registered/CIMD/explicit
+DCR client selection, authorization-code exchange, refresh-token rotation, and
+bounded metadata responses. Hosts own user interaction and secret persistence;
+token values are never added to MCP state or model context.
+
+### Advanced runtime contracts
+
+The SDK also exposes additive contracts for cross-model Oracle reports,
+commit-bound remote-source research, portable Recipes, automatic Git mutation
+checkpoints, signed/locked plugins, repository-aware relevance, MCP Apps, and
+authenticated GitLab/Teams/Jira hosted events. These contracts bind identity,
+authority, evidence, and persistence without granting a host UI, network,
+credential, or deployment authority. See
+[Advanced Runtime Contracts](docs/ADVANCED_RUNTIME_CONTRACTS.md).
+
+## Delivery automation
+
+The SDK repo now carries the same production automation discipline as the CLI:
+
+- `.github/workflows/ci.yml` -- cross-platform build verification plus full Linux runtime checks
+- `.github/workflows/certification.yml` -- scheduled production/stress verification and large-repo coding benchmarks
+- `.github/workflows/release.yml` -- npm Trusted Publishing with provenance, checksums, and GitHub release artifacts
+
+## Architecture
+
+```
+xeno-agent-sdk/
+src/
+  core/, runtime/, providers/       Agent loop, streaming, context, providers
+  tools/, terminal/, media/         Tools and managed operations
+  security/, governance/            Policy, permissions, leases, execution law
+  session/, memory/, identity/      Durable user and conversation context
+  orchestration/, control-plane/    Agents, teams, workflows, goals, recovery
+  agents/, prompts/, soul/          Profiles, prompts, learned state
+  artifacts/                        Artifacts, reviews, provenance, evidence
+  automation/                       Governed browser/computer adapter protocol
+  oracle/, research/, recipes/      Independent review, source evidence, reusable DAGs
+  hosted/, intelligence/            Fleet contracts and repository intelligence
+  skills/                           Skills v2 discovery, loading, policy, audit
+  hooks/, plugins/, mcp/            Extension and interoperability contracts
+  app-server/, integrations/        Remote and host protocols
+  audit/, observability/            Audit, usage, telemetry, diagnostics
+  ui/, electron/, adapters/         Optional UI and host integration layers
+  persistence/, config/, utils/     Durable and cross-cutting utilities
+```
+
+## Selected subsystems
+
+| Subsystem | Purpose | Key exports |
+|-----------|---------|-------------|
+| **Core Loop** | Agentic turn loop with tool dispatch, streaming, reducer | `AgentLoop`, `AgentLoopConfig` |
+| **Tools** | Demand-loaded registry, built-ins, managed operations, host tools | `ToolRegistry`, `registry` |
+| **Security** | Permissions, policy, leases, execution contracts, adapter claims | `PermissionEngine`, `SecureExecutionContract` |
+| **Session** | Persistence, checkpoints, transcripts, locks, recovery | `SessionManager`, `CheckpointManager` |
+| **Identity** | Persona loading and resolution across 4 levels | `IdentityLoader`, `IdentityResolver` |
+| **Memory** | Hierarchical memory with budget management | `MemoryManager`, `MemoryBudget` |
+| **Audit** | JSON-lines logging for every action | `AuditLogger` |
+| **Config** | Model settings, API endpoints, defaults | `XENO_API_BASE`, `DEFAULT_MODEL` |
+| **Delegation** | Planner/executor/reviewer sub-agent workflows | `DelegatedAgent`, `DelegatedTurn` |
+| **Artifacts** | Immutable revisions, review lifecycle, anchors, evidence graph | `XenoArtifact`, `ArtifactRepository` |
+| **Agent Profiles** | Enforceable specialist runtime identities | `CompiledAgentProfile` |
+| **Agent Skills** | Metadata-first `SKILL.md` catalog and demand-loaded invocation | `discoverXenoSkills`, `createXenoSkillTool` |
+| **MCP** | Stdio, Streamable HTTP, legacy SSE, OAuth discovery/PKCE/refresh | `MCPManager`, `StreamableHTTPTransport`, `MCPOAuthClient` |
+| **Oracle** | Independent opinions, adjudication, citations, disagreement | `XenoOracleCoordinator` |
+| **Research** | Commit-bound source excerpts, findings, provenance | `XenoSourceResearchReport` |
+| **Recipes** | Strict portable DAGs with authority, budgets, and fingerprints | `compileXenoRecipe` |
+| **Plugin trust** | Signatures, locks, publisher policy, advisory relevance | `verifyPluginSupplyChain`, `scorePluginRelevance` |
+| **Types** | All shared TypeScript types | `ExecutionMode`, `ResolvedIdentity`, etc. |
+
+## How Apps Integrate
+
+The primary entry point is `createXenoAgent()`. Each app registers its own operations as tools, and the SDK handles everything else: the agentic loop, permission checks, audit logging, memory, sessions.
+
+```typescript
+import { createXenoAgent } from '@xenosystem/agent-sdk'
+
+// Each app defines its domain-specific tools
+const pixelTools = {
+  'layer.remove-bg': {
+    description: 'Remove background from the active layer',
+    execute: async (params) => {
+      const result = await xenoLib.rmbg(params.layerId)   // xeno-lib AI model
+      await engine.applyMask(params.layerId, result.mask)  // app engine
+      return { success: true, layerId: params.layerId }
+    },
+    confirm: true,  // requires user approval
+  },
+  'brush.draw': {
+    description: 'Draw a stroke on the active layer',
+    execute: async (params) => engine.drawStroke(params),
+    confirm: false,  // safe, no confirmation needed
+  },
+  'file.export': {
+    description: 'Export the current document',
+    execute: async (params) => exporter.save(params),
+    confirm: true,
+    destructive: false,
+  },
+}
+
+const agent = await createXenoAgent({
+  toolRegistry: pixelTools,
+  model: 'claude-sonnet-4-20250514',
+  permissionConfig: { mode: 'default' },
+  // identity, memory, session all auto-configured
+})
+```
+
+### End-to-End Example
+
+User types in Pixel's agent sidebar: **"Remove the background from this layer"**
+
+```
+1. Agent receives natural language input
+2. LLM decides to call tool: layer.remove-bg({ layerId: 'layer-3' })
+3. Permission engine checks: confirm=true -> prompts user for approval
+4. User approves -> tool executes:
+     a. Calls xeno-lib's RMBG model (Rust, ONNX, GPU-accelerated)
+     b. Receives alpha mask
+     c. Applies mask to layer in Pixel's rendering engine
+5. Audit logger records: who=user, what=layer.remove-bg, when=timestamp, result=success
+6. Agent responds: "Done. Background removed from Layer 3."
+```
+
+## The Tool Registry Pattern
+
+Apps extend the SDK by registering their operations as tools. The SDK provides
+file, search, shell, background-process, terminal, media, and other reusable
+tool contracts; apps add namespaced domain-specific tools:
+
+| App | Example tools |
+|-----|---------------|
+| **Pixel** | `brush.draw`, `layer.remove-bg`, `selection.expand`, `filter.blur`, `file.export` |
+| **Motion** | `timeline.cut`, `clip.speed`, `transition.add`, `keyframe.set`, `render.export` |
+| **Sound** | `track.eq`, `region.normalize`, `master.lufs`, `effect.reverb`, `bounce.export` |
+| **Hub** | `workspace.create`, `app.launch`, `agent.dispatch` |
+
+Each tool declares: `description` (for the LLM), `execute` (the implementation), `confirm` (whether to ask the user), and `destructive` (whether it's irreversible).
+
+## Cross-App Orchestration
+
+One agent request can trigger coordinated work across multiple apps. The Hub acts as an orchestrator, dispatching tasks to per-app agents via a mailbox system.
+
+```
+User: "Create a product video from these photos with background music"
+
+xeno-hub (orchestrator)
+    |-- mailbox.send('pixel-agent', { task: 'export hero images as PNGs' })
+    |-- mailbox.send('motion-agent', { task: 'create timeline from exported images' })
+    |-- mailbox.send('sound-agent', { task: 'add background track, master to -14 LUFS' })
+
+Each agent receives via:
+    mailbox.onMessage((msg) => agent.execute(msg.task))
+```
+
+Messages are JSON-serializable for cross-process IPC. The SDK includes agent
+protocol/registry and `CrossAppRouter` primitives with bounded delivery.
+Production transport, durable replay, authentication, and product adoption are
+host responsibilities and must be verified in each consuming repository.
+
+## Security Model
+
+### Permission Modes
+
+| Mode | Behavior |
+|------|----------|
+| `default` | Ask user before writes and shell commands |
+| `acceptEdits` | Auto-approve file edits, ask for shell commands |
+| `bypassPermissions` | Auto-approve everything (development/testing only) |
+| `plan` | Read-only mode, agent can only plan and suggest |
+
+### Safety Features
+
+- **Policy enforcement**: canonical physical-path checks reject traversal through symlinks/junctions, UNC/device, extended-length, drive-relative, root-relative, alternate-data-stream, reserved-device, and ambiguous paths
+- **Shell policy**: parsed PowerShell/Bash file operands, redirections, and path parameters enforce read/write capabilities; unresolved dynamic filesystem operands fail closed
+- **Execution security levels**: `policy-only`, `process-hardened`, and `contained` are separate API contracts. The legacy `requireOsContainment: true` flag now means strict `contained` and never accepts process hardening as a substitute.
+- **Windows process hardening**: `executionLevel: "process-hardened"` uses a reduced primary token, low integrity for read-only execution, an explicit inherited-handle allowlist, a minimized environment, and a kill-on-close Job Object. It does not isolate filesystem reads or network access and is for trusted workspaces only.
+- **Fail-closed containment**: the SDK ships five reviewed, digest-pinned runtime executables plus two Windows host-preparation helpers extracted from the integrity-pinned MXC 0.7.0 artifact; it does not install or execute MXC's JavaScript wrapper or transitive `node-pty` graph. Windows x64/ARM64, Linux x64/ARM64, and macOS ARM64 are supported, but asset presence is not certification. Windows setup is an explicit elevated host operation and is never attempted by normal agent execution. `contained` activates only with a short-lived, candidate-, platform-, adapter-, native-report-, and independently signed reviewer-bound host manifest. A source build, unsupported target, mismatch, or missing binding fails with `CONTAINMENT_UNAVAILABLE`; executable discovery is never treated as certification.
+- **Destructive action gates**: delete, overwrite, and shell commands require explicit approval
+- **Audit trail**: every tool call logged in JSON-lines format with trace IDs
+- **Risk classification**: each tool call classified as low/medium/high risk
+- **Permission rules**: per-tool, per-path override rules
+
+The policy layer and Windows process hardening are defense in depth, not a claim that arbitrary untrusted code is contained. See [Security Boundaries](docs/SECURITY_BOUNDARIES.md) for the capability matrix and migration contract.
+
+### Managed Shell Processes
+
+`UnifiedExecManager` is the canonical owner for pipe and PTY process lifecycles. `BackgroundProcessManager` remains the task-oriented compatibility facade and adds owner scoping, bounded file-backed output, same-process foreground-to-background promotion, completion events, input, resize, and human-writer leases.
+
+- `Bash` accepts `tty: true` only with `run_in_background: true`.
+- `TaskInput` writes to or waits on an interactive task. Input text is projected to byte-count/task metadata before audit, permission, callback, and transcript sinks.
+- PTY support is adapter based. Hosts register an optional `XenoPtyAdapter`; missing capability returns `PTY_UNAVAILABLE` and never silently falls back to a pipe.
+- App-server `exec.start` accepts `tty`, `cols`, and `rows`; `exec.resize` is owner scoped alongside write, output, list, and terminate.
+- `SessionManager.recordDirectShellResult` persists bounded local-command output as user-role untrusted context with semantic metadata, not as a fabricated model tool call.
+
+### Managed Tool Operations
+
+Tool calls now receive a stable operation ID, deadline, completion policy (`await`, `observe`, or `detach`), progress counters, terminal reason, and artifact evidence. Recovery snapshots are written atomically under the user control-plane directory, while redacted operation transitions are appended to a private JSONL ledger. Raw command text is not copied into operation lists or the ledger.
+
+- A promotable foreground `Bash` command moves to the background by changing presentation on the same process. PID, task/process IDs, output cursor, and deadline are retained; the command is never re-executed.
+- `TaskOutput({ task_id, offset })` remains a nonblocking compatibility read. `wait: true` adds an event-driven wait capped at 30 seconds and always reports explicit `Operation terminal: yes|no`, state, runtime, idle time, output delta, UTF-8-safe next offset, and suggested action.
+- Finite model-created background work defaults to `await`. The parent turn suspends without another provider request and resumes from a durable continuation notification after terminal output arrives. User stop, detach, clear, interrupt, or rewind cancels stale automatic continuation.
+- `expected_outputs` on `Bash` records generic file postconditions. Missing or unstable outputs fail the logical operation even after exit code 0; partial artifacts are still reported after timeout/failure.
+- `ReadImage` preflights format, dimensions, and bytes. The dependency-free `xeno-owned-raster` path performs owned PNG/DEFLATE decode and encode, JPEG, GIF, VP8/VP8L WebP decode, bounded SVG software rasterization, and resizing; BMP and Netpbm inputs normalize through the same owned PNG path. Oversized supported inputs become owner-private bounded PNG previews without an ambient decoder or canvas fallback. Private previews are removed during session cleanup and originals stay unchanged. The exact approved profiles and explicit rejections are documented in [`docs/owned-media-matrix.md`](docs/owned-media-matrix.md).
+
+Temporary rollback controls default to enabled: `XENO_TOOL_OPERATION_RUNTIME`, `XENO_AUTO_BACKGROUND_FOREGROUND_BASH`, `XENO_TASK_OUTPUT_WAIT`, `XENO_AUTO_TOOL_CONTINUATION`, and `XENO_READ_IMAGE_AUTO_PREVIEW`. Setting a control to `0` disables its optional behavior without deleting active tasks or persisted operation records.
+
+On Windows, ordinary managed pipe tasks use the existing kill-on-close Job Object launcher when available and report `windows-job-object`; the explicit `windows-tree-fallback` uses tree termination but is not reported as verified Job ownership. Persistent PowerShell defaults to Windows PowerShell 5.1. Set `XENO_POWERSHELL_EXECUTABLE=pwsh.exe` to use PowerShell 7. Process ownership and cleanup are not claims of untrusted-code containment.
+
+See [docs/managed-tool-operations.md](docs/managed-tool-operations.md) for the runtime and troubleshooting contract.
+
+### Agent Harness Reliability
+
+- Tool inputs are JSON-schema validated by default; malformed calls are returned to the model as typed errors.
+- Interrupted or orphaned tool exchanges are repaired before resumable history is sent back to a provider.
+- Repeated identical failing tool calls are circuit-broken before they can loop indefinitely.
+- Query lifecycle transitions are emitted as typed runtime events and guarded by idle, active-operation lease, and hard timeouts.
+- Context overflow triggers one semantic compact-and-retry path. Old tool payloads are compacted before conversation history is dropped, message count has a hard cap, and preflight token estimates are model-aware with an injectable exact-tokenizer seam.
+- The default tool registry demand-loads optional schemas through `ToolSearch` instead of advertising every full schema on every request.
+
+### Direct Provider Adapters
+
+Provider-normalized deployments can continue using the default Xeno API transport. Direct integrations are available from the provider subpath:
+
+```typescript
+import { createDirectProvider } from '@xenosystem/agent-sdk/providers'
+import { createXenoAgent } from '@xenosystem/agent-sdk'
+
+const provider = createDirectProvider({
+  kind: 'openai-responses', // 'anthropic' | 'openai-responses' | 'google' | 'openai-compatible'
+  apiKey: process.env.PROVIDER_API_KEY!,
+})
+
+const { agent } = await createXenoAgent({ provider })
+```
+
+The adapters translate streaming text, images, parallel tool calls/results, usage, cancellation, and typed failures for Messages, Responses, Gemini, and explicitly profiled chat-compatible endpoints. Generic endpoints require a capability profile and local HTTP requires an explicit local-network endpoint profile. See [docs/PROVIDER_CONFORMANCE.md](docs/PROVIDER_CONFORMANCE.md).
+
+The provider subpath also exposes a capability-driven product catalog, atomic workspace connection store, bounded credential/model probe, and routing policy. Connections hold credential reference names, never raw credentials. Presets for Azure OpenAI, Bedrock, and Vertex truthfully report `requires-host-adapter` until dedicated adapters are supplied.
+
+```typescript
+import {
+  FileXenoProviderConnectionStore,
+  XenoProviderCatalog,
+  probeXenoProvider,
+  selectXenoProviderRoute,
+} from '@xenosystem/agent-sdk/providers'
+```
+
+### Secure Sharing and Handoff
+
+`@xenosystem/agent-sdk/sharing` provides deterministic redaction, Ed25519-signed expiring read-only shares, capability/audience/revocation verification, signed session handoffs, and an atomic checksum-protected local registry. Embedded public keys prove integrity but do not imply issuer trust; consuming products supply their own trust store and must intersect handoff authority with local policy.
+
+```typescript
+import {
+  createXenoSecureShare,
+  verifyXenoSecureShare,
+  createXenoSessionHandoff,
+  verifyXenoSessionHandoff,
+  FileXenoShareRegistry,
+} from '@xenosystem/agent-sdk/sharing'
+```
+
+## Session Persistence
+
+- Sessions have unique IDs with embedded timestamps
+- Full conversation transcripts written to disk
+- Checkpoint system for long-running workflows
+- Lock management prevents concurrent access to the same session
+- Turn restore for crash recovery (resume mid-conversation)
+- Session registry tracks all sessions per project
+
+## Memory System
+
+4-level hierarchy with automatic capture and budget management:
+
+| Level | Scope | Persists | Example |
+|-------|-------|----------|---------|
+| **Conversation** | Current turn | No | "The user just asked about Layer 3" |
+| **Session** | Current session | Until session ends | "We're working on the hero image" |
+| **Project** | Current project | Yes | "This project uses 300 DPI, CMYK" |
+| **Global** | All projects | Yes | "User prefers dark theme, metric units" |
+
+Memory is injected into the system prompt with configurable token budgets to avoid context overflow.
+
+## LLM Providers
+
+| Provider | How | When |
+|----------|-----|------|
+| **Xeno API** (cloud) | `api.xenostudio.ai` proxy to hosted models | Online, highest capability |
+| **xeno-rt** (local) | OpenAI-compatible API on localhost | Offline, privacy, no cost |
+| **Ollama** (local) | OpenAI-compatible API | Alternative local provider |
+
+The SDK is provider-agnostic. OpenAI-compatible endpoints are supported through an explicit capability and endpoint-security profile; compatibility is verified by conformance fixtures rather than inferred from the endpoint label. Provider selection and fallback logic are handled by the config subsystem.
+
+## Consumers
+
+| App | How it uses the SDK | Example agent task |
+|-----|--------------------|--------------------|
+| **xeno-agent-cli** | Terminal agent (reference implementation) | "Refactor this codebase" |
+| **xeno-pixel** | Image editing agent sidebar | "Remove backgrounds from 50 images" |
+| **xeno-motion** | Video editing agent sidebar | "Cut this interview into a highlight reel" |
+| **xeno-sound** | Audio editing agent sidebar | "Master this podcast to -16 LUFS" |
+| **xeno-hub** | Orchestrator routing tasks between apps | "Create marketing materials" dispatches to Pixel + Motion + Sound |
+
+## Xeno-Owned UI
+
+The `/ui` subpath provides a framework-neutral controller, semantic accessibility view, and optional owned DOM renderer. It has no React runtime or peer dependency and remains isolated from the Node-only core entry point.
+
+```ts
+import {
+  createAgentUiController,
+  mountAgentUi,
+} from "@xenosystem/agent-sdk/ui";
+
+const controller = createAgentUiController({
+  agent: myAgentLoop,
+  enablePermissionRequests: true,
+});
+const view = mountAgentUi(document.querySelector("#agent")!, controller, {
+  agentName: "Xeno Agent",
+});
+
+// App shutdown:
+view.dispose();
+controller.dispose();
+```
+
+Framework integrations can subscribe to immutable controller snapshots and call `createAgentUiView` instead of mounting the DOM renderer. Renderer contract version `1` includes message streaming, tool state, token usage, cancellation, retry, permission decisions, safe markdown segments, keyboard submission, and accessible roles/live regions. See [the UI v1 migration guide](docs/migrations/sdk-ui-v1.md).
+
+## Ecosystem Position
+
+```
+LAYER 5 -- APPS (Pixel, Motion, Sound, Hub)
+    | embed xeno-agent-sdk for AI automation
+    | agent sidebar in every app
+LAYER 3 -- THIS REPO (xeno-agent-sdk)
+    | uses LLM providers + invokes AI models
+LAYER 2 -- COMPUTE (xeno-rt for LLM, xeno-lib for 17 AI models)
+    | runs on
+LAYER 1 -- PLATFORM (servers, auth, credits)
+```
+
+See [Full Ecosystem Report](../XENO%20CORPORATION%20-%20Full%20Ecosystem%20Report.md) for complete context.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsup -> ESM + CommonJS package outputs
+npm run typecheck   # TypeScript 7 native strict-mode check
+npm run typecheck:compat # TypeScript 6 compatibility check for API-based tooling
+```
+
+## License
+
+Proprietary and confidential. Copyright (c) 2026 XENO Corporation.
+All rights reserved.