Orca Pixel Office

Projects Orca-managed agents into one Pixel Agents office room per repository. The dependency-free TypeScript bridge uses Orca's public JSON CLI snapshots; it deliberately never reads terminal output, prompts, tool input, previews, or assistant messages.

Install

Node.js 20 or newer is required. Start the published package without a permanent install:

npx orca-pixel-office

The command prints the private local office URL once and stays alive while the office is running. Open that URL in a browser. It contains the ephemeral bearer token, so do not redirect the command output to a file or share the URL.

Press Ctrl-C to stop the office. SIGINT and SIGTERM both trigger a clean PluginRuntime.stop() before the command exits.

For development from this repository:

bun install
bun run build

Start and open the office

PluginRuntime.open() lazily starts the managed Pixel Agents process tree and returns the authenticated URL that the Orca integration should hand directly to its browser tab. Repeated calls attach to the same in-process runtime and return the same pending or resolved URL.

import { PluginRuntime } from './dist/src/index.js';

const office = new PluginRuntime();
const privateOfficeUrl = await office.open();
// Hand privateOfficeUrl directly to the Orca browser tab. Do not log it.

The bearer token is generated for each server start, retained only in memory, and passed to the child runtime over Node IPC. Child stdout and stderr are not forwarded because authenticated URLs must never enter logs.

Stop the office

stop() tears down the managed process immediately. The runtime also schedules the same teardown ten minutes after the child reports that its last office client disconnected; a reconnect during the grace period cancels shutdown.

await office.stop();

Configuration

Pass options to PluginRuntime when embedding it:

Option	Default	Purpose
host	127.0.0.1	Local bind address handed to the Pixel Agents child runtime.
port	0	Requested port; zero lets the operating system choose an ephemeral port.
shutdownGraceMs	600000	Delay after the last office client disconnects before teardown.
packageRoot	inferred package root	Override only for tests or a nonstandard installation layout.

Keep the default loopback bind unless remote access has been deliberately secured.

Runtime lookup

The runtime prefers vendor/pixel-agents/, then falls back to the sibling development checkout at ../pixel-agents-orca. A usable build must contain both dist/stream-runtime.js and dist/webview/index.html. The runtime entry is the fork-owned generic composition host: it receives the token, bind configuration, and bridge module path over Node IPC and reports readiness and office-client counts over the same channel. The bridge module must export a named, zero-argument createStreamProvider() factory. The ordinary dist/cli.js is intentionally not used because it owns a different token lifecycle and cannot compose the plugin's stream provider.

Scripts

npm run prepack

Builds this package and the sibling ../pixel-agents-orca checkout, then recreates the ignored vendor/pixel-agents/ publish artifact. The artifact contains only dist/stream-runtime.js, the complete dist/webview/, a small CommonJS package boundary required by Node, and the fork's upstream MIT LICENSE. The runtime's Fastify dependencies are declared as this package's production dependencies and installed normally by npm; node_modules is not vendored.

Release machines must have the sibling fork checked out with its dependencies installed. The script does not modify the fork's source.

npm run verify:packed -- <tarball>

Installs a packed tarball into a clean temporary directory, launches its CLI with the current plain Node executable, verifies authenticated and unauthenticated HTTP responses, sends SIGTERM, and confirms a clean exit. The bearer token remains in process memory and is redacted from output; the temporary installation is removed afterward.

bun run live-verify

Starts the runtime, connects one office client, and prints every agent the bridge projects with its room and display name, then shuts the runtime down. Use it to check the projection against real Orca agents after changing the collector, reconciler, or labels.

bun run build
bun run live-verify

Prerequisites: a built Pixel Agents runtime resolvable per Runtime lookup, and a running Orca app with at least one agent. The script prints no bearer token.

Bridge core

• src/collector.ts polls orca worktree ps --json and orca terminal list --json, with configurable jittered intervals and a connected-client gate.
• src/normalizer.ts is the privacy boundary: only explicitly allowlisted identity, placement, activity, and timestamp fields survive.
• src/reconciler.ts detects coarse lifecycle edges while terminal incarnation identity prevents pane reuse.
• src/tools.ts maps harness-native tool names to office vocabulary.
• src/provider.ts exposes the dependency-free, kind-based event-envelope stream provider used by the Pixel Agents integration. Session display metadata stays outside events and is available through getSessionMeta; the Milestone 3 seam decides how that metadata reaches the renderer.

The package targets plain Node.js 20 or newer. Bun is used only for development:

bun install
bun test
bun run build

Status

All four milestones are implemented. The bridge, the StreamProvider seam and the composition host that joins them have been verified against live Orca agents: real Claude, Codex and Antigravity sessions render in the office with their room and display name. The read-only Orca event-surface spike behind these decisions is documented in docs/event-surface-spike.md.

Product and architecture decisions are recorded in GLOSSARY.md, docs/adr/, and docs/implementation-plan.md. Polling remains the implementation; note the correction recorded in ADR 0001, which found that Orca does expose an agent.status.changed plugin event and that the ADR's original premise was wrong.

Distribution

The public npm package is named orca-pixel-office; nothing has been published yet. Its explicit package allowlist includes the compiled bridge/runtime, CLI entry, README, and the publish-time Pixel Agents bundle. Source files, tests, repository metadata, and scratch output are excluded.

npm pack and npm publish --dry-run run prepack, which builds the sibling Pixel Agents fork and recreates vendor/pixel-agents/. The tarball therefore contains its required server entry and webview without committing generated assets to Git. The fork runtime's Fastify production dependencies are installed through the package's normal npm dependency graph rather than copied into vendor/.

CI/CD and releases

The CI workflow runs for pushes and pull requests against main on both Node.js 20 and the current Node.js release. Each job checks out this repository as orca-pixel-office/ and mtb77/pixel-agents as the adjacent pixel-agents-orca/ directory required by prepack. It installs Bun only for the development test and TypeScript build, then creates an npm tarball and runs the existing plain-Node verification script with Bun removed from PATH:

bun run test
bun run build
npm pack
node scripts/verify-packed.mjs orca-pixel-office-<version>.tgz

If mtb77/pixel-agents is private, add a repository Actions secret named PIXEL_AGENTS_REPO_TOKEN. It must contain a fine-grained personal access token with read access to that repository's contents. For a public fork, the workflow falls back to the standard GITHUB_TOKEN.

The Release workflow runs only for tags matching v*. Before publishing, it requires the tag to equal v plus the version in package.json, builds and verifies the packed artifact under plain Node.js, checks that the version is not already present on npm, and requires an NPM_TOKEN repository secret with publish access. It publishes with npm provenance using GitHub's OIDC token.

The package is MIT licensed. It bundles a build of Pixel Agents, which is also MIT; its character sprites derive from a CC0 pack. See LICENSE for the full attribution. The release workflow still refuses to publish if the license is ever set back to UNLICENSED.

Related project

The Pixel Agents integration fork is checked out next to this repository as ../pixel-agents-orca and tracks pixel-agents-hq/pixel-agents through its upstream Git remote.

Intended responsibilities

• Start, stop, and inspect the Pixel Agents runtime.
• Hand the authenticated local office URL to a browser window without logging its bearer token.
• Project all Orca-managed agent types through one bridge.
• Keep harness-specific behavior out of the bridge whenever Orca already exposes it generically.

Development

bun install
bun test
bun run build
bun run live-verify

This project is not an Orca plugin. Orca's plugin API (orca-plugin.json) contributes panels, commands, events, language packs, keybindings, VM recipes and agent profiles, and its panels run under a sandbox that forbids network access, so it cannot host this office. The office is a local web app opened in a browser window instead. See ADR 0004.

skills/pixel-office/SKILL.md is a Claude/Codex skill, not an Orca contribution.