v0.5.0 — canvas overhaul, server platform, +49% test coverage

Published on npm: https://www.npmjs.com/package/occ-orchestrator/v/0.5.0

npm install -g occ-orchestrator@0.5.0

---

Release notes follow the npm package version (occ-orchestrator).
33 commits since v0.4.0. Roll-up of every change since the last
release; per-feature detail lives in the section below + the older
2.x notes that document the earlier platform additions still kept on
disk for reference.

Headline features

• Interactive canvas overhaul — Obsidian Note kind, Terminal Agent
  with model selector + connected-context propagation (Portal URL,
  File content, Sticky text, Obsidian markdown all flow into the
  agent's system prompt), Portal/Terminal overlays render at native
  size with a single transform: scale(zoom) so SPAs stop reflowing
  at low zoom, File Viewer file picker, right-click no longer arms a
  phantom box-select / node-drag, custom-fontFamily CSS tokens with
  emoji/symbol fallbacks (no more "tofu" boxes for ⏸ ⚡ ↺ ▶).
• Server platform — codex CLI runner (mirrors claude-runner,
  no API key needed), customizable system prompts (/system-prompts
  GET/PUT/reset, hot-reloaded JSON), generic /agent-chat endpoint
  that routes through any configured provider, execution time-travel
  via GET /executions/:id/timeline (per-step checkpoint history).
• Pipelines from canvas — canvasToPipelineChains decomposes a
  multi-stage canvas into PipelineChainRef[]; SaveChainModal
  detects pipeline canvases via isPipelineCanvas and routes through
  savePipeline. New summarize_output field on PipelineChainRef
  to control how a stage's output flows downstream.
• Canvas-only chains — chains with zero steps and one or more
  non-step canvas items (Portal / Sticky / Terminal / File / Link /
  Free Text / Obsidian) save and reload exactly via the new
  canvas_items?: CanvasItemSerialized[] side-car. Loader's Zod
  schema accepts empty steps; executor refuses to run them with a
  clear "open in canvas editor" error.
• Floor color slot palette — replaces hardcoded color: "#hex"
  on FloorData with a colorSlot: 0..6 index into a design-space-
  derived palette resolved at render time, so floor colors stay in
  sync with the active theme. Persistence layer auto-migrates legacy
  hex records via inferSlotFromHex.
• Settings UI refactor — collapsible sections (state persisted in
  localStorage), system prompts editor (SystemPromptsSection),
  provider section gains the codex provider type, MCP/schedule
  sections light tweaks.
• Workflow chat planner — concrete bug fixes: planner respects
  existing canvas (no more disconnected parallel chains on
  "améliore"), MODIFY mode patches preTools / advanced /
  outputVar / depends_on rewires atomically, named-input
  detection drives the RUN modal and the [ACTION:RUN] JSON inputs
  block, floor-aware canvas context.
• Test coverage push +1075→1233 (frontend 27.6% → 49.4%
  statements) across 12 new test files: canvasContext,
  preToolsToData, detectInputs type-inference matrix, tools/pre-tools
  serialization, pretoolFields schema integrity, canvasRenderer
  helpers + main render, connectionHit (100%), useCanvasInteractions
  (regression for the right-click bug + drag/keyboard branches —
  86%), workflowChat applyPlanToCanvas + buildCanvasContext,
  workflowChat sessions / persistence (90%+), floors store,
  physarumSim (72%), blobRenderer (75%), workflowChat actions
  ([ACTION:ANALYZE/MODIFY/RUN]).
• Misc dev quality — frontend deps bumped to current wanted
  range (vite, react, vitest, storybook, react-query…), mcp-server
  deps bumped (@modelcontextprotocol/sdk 1.27→1.29, better-sqlite3,
  eslint…), index.html served Cache-Control: no-store so the
  browser stops holding stale asset hashes after every rebuild,
  .gitignore excludes system-prompts.json runtime artifact.

Removed

• Interactive Portal mode (Playwright + WebSocket screencast) —
  added in 2.2.0 / commit 96675f2, removed before npm release.
  See the explanatory section in the older 2.x notes below for the
  full rationale (anti-bot detection at the binary level kept finding
  new signals; macOS Dock-icon UX was hard to make invisible). Portal
  nodes keep only the static iframe proxy via GET /portal?url=….
  Surface dropped: mcp-server/src/portal-sessions.ts,
  mcp-server/src/portal-ws.ts, frontend-react/src/api/portal.ts,
  InteractivePortalOverlayItem, the async live-snapshot path in
  canvasContext.ts, REST endpoints (POST /portal/session,
  GET /portal/sessions, POST /portal/session/:id/navigate,
  DELETE /portal/session/:id, GET /portal/snapshot), deps ws
  • @types/ws, types portalMode / portalPersistKey, vite proxy
    ws: true on /portal. Net diff: −1473 / +35 lines.

Notes

• Versioning: this is the first OCC release that's published from a
  CI-validated main. Every commit since v0.4.0 was tested on the
  full matrix (ubuntu/macos/windows × Node 20/22).
• Historical 2.x section below is preserved as a reference for the
  earlier platform additions; future releases will use 0.x semver
  matching the npm package version.

v0.4.1 — Single-server frontend

What's New

One Server, One Port, One Process

The React dashboard is now served directly by Express. No more running two servers.

Before (v0.4.0):

cd mcp-server && npm run rest        # Backend :4242
cd frontend-react && npm run dev     # Frontend :5173 (proxy to :4242)

After (v0.4.1):

occ start    # Backend + Dashboard at http://localhost:4242

How it works

• npm run build:all builds the backend (TypeScript) and frontend (React) together
• Express serves the built React app as static files with SPA fallback
• API endpoints work as before on the same port
• Dev mode with Vite hot reload still works unchanged for development

npm package now includes the dashboard

npm install -g occ-orchestrator now gives you the full experience: CLI + API + Dashboard.

Full Changelog: v0.4.0...v0.4.1

v0.4.0 — occ init, occ start, occ doctor

What's New

Zero-Friction Onboarding

5 commands from install to first chain execution:

npm install -g occ-orchestrator
occ init my-project && cd my-project
occ doctor
occ start
occ run hello-world -i topic="quantum computing"

New CLI Commands

occ init [name] — Create a new OCC project with:

• chains/ directory with 3 example chains (hello-world, web-analyzer, parallel-pros-cons)
• pipelines/ directory ready for multi-chain workflows
• .env with sensible defaults
• .gitignore for databases and secrets

occ start — Start the OCC REST server automatically. Finds the entry point whether installed via npm, from source, or from the repo root.

occ doctor — Check all prerequisites with actionable fix hints:

• Node.js version
• Claude CLI installed + authenticated
• Ollama running (optional)
• Docker available (optional)
• Chains directory
• OCC server status

Improved Error Messages

When the server is not running, the CLI now suggests occ start and occ doctor instead of a cryptic error.

Help Reorganized

CLI help grouped into: Setup, Chain execution, Monitoring, Human-in-the-loop, Generation, System.

Full Changelog: v0.3.1...v0.4.0

v0.3.1 — Prerequisites Check Modal

What's New

Prerequisites Check Modal

On first launch, the dashboard now shows a Setup Check modal that verifies all dependencies before you start:

Required checks:

• OCC Backend running
• Claude CLI installed
• Claude CLI authenticated
• SQLite database

Optional checks:

• Chains directory
• LLM Providers configured
• Ollama (local models)
• Docker (sandboxed execution)

Features:

• Action buttons per item — copy install commands, open download pages, navigate to Settings
• Click-to-copy on hint codes with "Copied!" feedback
• Animated re-check with per-line spinners
• Auto-refresh every 5s when required items fail (detects when user fixes an issue)
• "Don't show again" checkbox (persisted in localStorage)
• Glass morphism design matching the dashboard theme

Getting Started improvements

• README now includes Claude CLI install instructions
• Setup Check modal mentioned in Quick Start section

Full Changelog: v0.3.0...v0.3.1

v0.3.0 — Benchmarks, Token Tracking, Typed Inputs, Image Gen

What's New

Real Benchmark Suite

• Economy of scale analysis: 10-step, 4-wave strategic analysis workflow
• OCC vs naive: 70% faster, 70% cheaper ($0.18 vs $0.60/run)
• OCC vs smart manual: 29% faster (69s vs 97s)
• Model routing alone: 80% cost reduction
• 3 reproducible scripts: run-benchmark.sh, run-benchmark-raw.py, run-benchmark-scale.py
• Full methodology in BENCHMARKS.md

Token Tracking Fixes

• Claude: now counts cache_read_input_tokens + cache_creation_input_tokens (was showing 9 instead of 26K+)
• Ollama/HuggingFace: added stream_options: { include_usage: true } for streaming

Typed Chain Inputs

• 9 input types: string, number, boolean, enum, file, image, json, url, text
• Validation at loader, executor, and REST layers
• RunModal with specialized widgets per type (file picker, toggle, range, preview)

Image Generation

• New image_gen step type and image_generate pre-tool
• Providers: OpenAI (DALL-E 3), HuggingFace (FLUX), Stability AI
• Outputs served via /images/:filename endpoint

HuggingFace Provider

• Full integration via router.huggingface.co/v1
• 63 curated models (free + PRO tiers) with live search
• Settings UI with tier filter, tag filters, rate limits panel

Workflow Chat Improvements

• Full markdown renderer (bold, italic, code, headers, blockquotes, images)
• Canvas context injection in chat stage
• Agentic actions: RUN, STOP, DEBUG, ANALYZE, DRY_RUN, MODIFY
• Triple regex fallback for action detection

Other

• Universal output renderer (JSON, CSV, HTML, images, file downloads)
• Windows CI fixes (EBUSY SQLite, path traversal, Docker)
• Path resolution for directories with spaces
• Ollama exact model name matching

Stats

• 2344 tests across 59 files (was 1814/50)
• Coverage: Statements 82%, Branches 75%, Functions 79%, Lines 84%
• 102 REST endpoints, 28 MCP tools, 30 pre-tool types, 6 LLM providers

Install

npm install -g occ-orchestrator

Full Changelog: v0.2.0...v0.3.0