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.

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.

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.

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.

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 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.

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 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:

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.

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.

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.

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.

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.

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 for complete context.

Development

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.