@liy/mote-pi-runtime 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.3.0 - 2026-09-16
+
+Split from `@liy/mote-sandbox-runtime` by process lifetime (ADR-084).
+
+- Carries everything an agent loads per run: the Pi RPC bridge, the extensions,
+  the universal skills, and the agent-facing `orchestrator` CLI. Updating this
+  package restarts nothing; a new version reaches the next agent launch.
+- Pins Pi, `pi-mcp-adapter`, `pi-web-access` and the component catalog CLI as
+  ordinary exact dependencies rather than peers, because this package is the
+  host that starts Pi.
+- Compiles all five Pi extensions at publish time, so no compiler reaches a
+  Sprite and Pi's loader does not transpile them.
+- Installs into a version-stamped directory published through an atomically
+  renamed `current` symlink, with stable `extensions` and `skills` names.
+
+## Unreleased

package/README.md

@@ -0,0 +1,63 @@
+# @liy/mote-pi-runtime
+
+Everything a Mote agent loads inside its own process: the Pi RPC bridge, the
+precompiled Pi extensions, the universal Agent Skills, and the agent-facing
+`orchestrator` CLI.
+
+| Binary | Role |
+| --- | --- |
+| `mote-pi-rpc` | Per-run Pi process the orchestrator spawns for each launch |
+| `orchestrator` | CLI agents invoke to call back into the orchestrator |
+
+## Why this package exists on its own
+
+ADR-084 tiers the sandbox by what loads an artifact. Nothing resident loads this
+package: Pi runs as a spawned, detached child. **A new version therefore takes
+effect at the next agent launch and needs no service restart.** Publishing a
+skill, a persona, an extension fix, or a new Pi release costs no downtime.
+
+## Dependencies
+
+Pi, its MCP adapter, `pi-web-access` and the component catalog CLI are ordinary
+dependencies pinned to exact versions. They are not peers: this package is the
+host that starts Pi, so nothing above it supplies an instance. Conflict
+detection is unaffected, because the adapter still declares its own peer range
+and npm still fails on an incompatible pair.
+
+## Precompiled extensions
+
+`scripts/compile-extensions.mjs` bundles all five extensions at publish time
+into `dist/extensions`, so no compiler reaches a Sprite and Pi's loader never
+transpiles them. Pi's SDK and installed JavaScript dependencies stay external,
+preserving SDK identity and native assets.
+
+The two third-party extensions locate their own worker, keyring helper and UI
+assets relative to their installed package. A banner resolves that directory on
+load rather than baking it in, because the install path is not known at publish
+time. It resolves the **real** path first: agent profiles reach this tree
+through a symlinked `extensions` directory and Pi's loader keeps that symlinked
+path, so walking up from `import.meta.url` alone would escape the package.
+
+## Installed layout
+
+```
+/opt/mote/pi-runtime/<version>/            complete npm install root
+/opt/mote/pi-runtime/<version>/extensions  -> the compiled extension tree
+/opt/mote/pi-runtime/<version>/skills      -> the shipped Agent Skills
+/opt/mote/pi-runtime/current               -> <version>
+```
+
+Agent profiles link to the stable `current` names, so a version swap needs no
+profile rewrite. The orchestrator resolves `current` when it spawns, not at
+boot, which is what lets an update land without restarting anything.
+
+## Contract
+
+`mote.contract` in the manifest pairs this package with the services that drive
+it. The orchestrator refuses to spawn against a contract it does not support,
+which is the only guard against a version pairing nobody tested.
+
+## Release
+
+`pnpm release:pi-runtime:check` packs a dry run. Publication is manual dispatch
+only, through npm trusted publishing.

package/dist/assets/skills/agent-browser/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: agent-browser
+description: Use the installed agent-browser CLI for browser interaction and validation.
+---
+
+# Agent Browser
+
+Load the version-matched workflow before using the browser CLI:
+
+```bash
+agent-browser skills get core
+```
+
+Use `agent-browser skills get core --full` when the task needs its complete
+command reference and templates.

package/dist/assets/skills/gen-app/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: gen-app
+description: Build, modify, validate, and integrate static React SPAs in Mote. Discover supported components with component-catalog; use inline-widget for timeline visualizations.
+---
+
+# Gen App
+
+Write explanations and user-facing labels in the user’s language; preserve component names, prop keys, and CLI syntax.
+
+## Discover components
+
+```bash
+component-catalog list
+component-catalog describe Table
+```
+
+Describe each selected component before authoring. The command returns its props,
+constraints, example, and guide path for this release. Read the referenced guide.
+Use the available components; report missing capabilities rather than adding
+local component definitions.
+
+## Build the app
+
+Read the ticket and inspect the app repository. Require
+`MOTE_AGENTIC_COMPONENT_CATALOG_PACKAGE`; if absent, report the missing requirement
+and finish without changing application files. Install the selected package:
+
+```bash
+npm install --save-exact "$MOTE_AGENTIC_COMPONENT_CATALOG_PACKAGE" \
+  react@19.2.7 react-dom@19.2.7 scheduler@0.27.0
+```
+
+Use a Vite React TypeScript SPA with `base: "./"` and output in `dist/`. Keep browser
+dependencies bundled. Compose a json-render `Spec`, validate with
+`assertComponentSpec`, and render with `ComponentRenderer`. Import the catalog
+stylesheet, supply prepared datasets, and set `visible: true` on unconditional
+elements. The installed app dependency must match the catalog release used for
+discovery.
+
+## Registered queries
+
+Every app declares `mote.queries.json` at the repository root, outside `dist/`;
+use `{ "queries": [] }` when no data is needed. Each query declares `key`, `sql`,
+positional `parameters` (`name`, `type`, `nullable`), and `maxRows` (at most 2000).
+Use Analytics Datasets and `$1`, `$2`, etc.; test with `query_analytics_sql`.
+Never import SQL or the manifest into browser code.
+
+Wrap the app in `GenAppQueryProvider`, call `useGenAppQuery(key, parameters)`,
+and keep `GenAppQueryStatus` beside each data view. Adapt ready rows into prepared
+datasets; retain denial, empty, scope, and truncation feedback. Registration
+supplies output column contracts. The host supplies bundle/mode bootstrap;
+app code must not select another bundle or widen public scope.
+
+## Validate and integrate
+
+Authors typecheck and build their ticket worktree, verify `dist/index.html`,
+commit the complete app, and run `orchestrator workspace check <ticket-id>`.
+Include validation results and evidence references in the required
+`orchestrator ticket handoff`; raw tool evidence is retained automatically.
+
+Gatekeepers merge canonical `main` into their ticket worktree, review the result
+against the ticket, and use the browser when it materially validates requirements.
+Then run `orchestrator integration <ticket-id>`. It builds the clean committed
+head, verifies artifacts, uploads and registers an immutable bundle, fast-forwards
+`main`, and conditionally advances preview. Do not run another build in the
+canonical repository.
+
+Report the integrated commit and returned `bundleVersionId`, and open the preview
+handoff. Publication is a separate administrator review under selected datasets
+and Farms. Retry failed integration with the same command; the orchestrator
+reconciles the retained upload. Do not rebuild or copy artifacts into the
+canonical repository.
+
+Artifacts are limited to 8 MiB and 512 regular files. Symlinks, hidden or escaping
+paths, and source query manifests are rejected. Sandbox serving is for active
+local development only.

package/dist/assets/skills/inline-widget/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: inline-widget
+description: Compose or revise inline charts, tables, and cards in Mote timelines. Discover supported components with component-catalog; use gen-app for application source and deployment work.
+---
+
+# Inline widget
+
+Write explanations and user-facing labels in the user’s language; preserve component names, prop keys, and CLI syntax.
+
+## Discover components
+
+```bash
+component-catalog list
+component-catalog describe Table
+```
+
+Describe each selected component before authoring. The command returns its props,
+constraints, example, and guide path for this release. Read the referenced guide
+and `submissionGuide` for the widget envelope and limits. Use the available
+components; report missing capabilities rather than inventing a renderer.
+
+## Compose and submit
+
+Acquire data through authorized MCP reads. Normalize decimal strings to numbers,
+preserve nulls, and share prepared datasets across components. Use a tree with concrete props and `visible: true` for unconditional elements.
+Local state, conditional visibility, and event bindings follow the shared catalog. Filter or aggregate upstream to fit
+submission limits; disclose scope, truncation, and missing data in `summary`.
+
+Call `mote_render_inline_widget` directly, or use one MCP proxy call that retains
+the original result. Do not wrap submission in `mcpScript`, which can omit its
+result. Correct validation errors using the returned details.
+
+For an update, reuse `widget_id` and submit the complete replacement spec and
+datasets. Local controls do not fetch more records; new data requires another
+authorized read. Domain writes use the proposal workflow.
+
+After success, explain the takeaway without repeating JSON or all rows.
+No ticket, app scaffold, or deployment is needed.

package/dist/assets/skills/orchestrator/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: orchestrator
+description: Use the sandbox-local orchestrator CLI to work the ticket board and app workspaces; create apps and maintain shared briefs, integrate and clean worktrees, transition tickets, read native timelines, and read the agent roster.
+---
+
+# Orchestrator CLI
+
+The `orchestrator` command is the only way to read or change the work board.
+Never invent ticket IDs, statuses, or results; the CLI response is the source
+of truth. Treat output as JSON: continue only when `ok` is `true`, otherwise
+report `error.message`.
+
+The sandbox derives your authoritative identity from the operating-system
+process connected to the orchestrator Unix socket. `AGENT_ID` and, for Drone
+work, `MOTE_TICKET_ID` describe runtime context only; they are not credentials.
+The agent receives no Mote access token. Never add identity, Org, delegation,
+authorization, destination URL, upstream-origin, or credential fields to a
+request: the command channel rejects those claims and selects authority from
+kernel identity.
+
+## Current task context
+
+Start with `ticket brief` for the ticket named by `MOTE_TICKET_ID`, including in a
+conversation attached to that ticket. It includes ticket state and worklog context.
+Use `ticket get` for general ticket information; it does not return timeline records.
+For `MOTE_APP_ID`, read the shared brief with `app get`. Infer the assignment
+from the current ticket and handoff, never from the agent's persona or role.
+Use the `gen-app` skill for app changes or integration, and `agent-browser`
+when browser interaction materially validates the requirements.
+
+Track executable work in tickets. Direct answers, brief edits, inline widgets
+and immediate action proposals need no ticket. After initiating work in a
+conversation, finish the turn; the scheduler handles subsequent assessment.
+
+## Protected MCP
+
+Use the Pi `mcp` or `mcpScript` tool for the Mote MCP tools. The installed
+`pi-mcp-adapter` runs `orchestrator mcp mote` internally as its configured stdio
+transport. Do not invoke that command through Bash or construct JSON-RPC
+payloads yourself.
+
+## Commands
+
+```bash
+orchestrator app create <app-code> "<name>" "<shared brief>"
+orchestrator app get <app-id>
+orchestrator app update <app-id> "<shared brief>"                            # Overmind only; code is immutable
+orchestrator ticket list --status <waiting|ongoing|intervention|done> [--unassigned]
+orchestrator ticket get <ticket-id>                                     # general ticket information
+orchestrator ticket create '{"title":"...","summary":"...","description":"...","scope":["code"],"appId":"..."}'  # appId optional; omit for standalone work
+orchestrator ticket assign '{"ticketId":"...","assigneeAgentId":"..."}'   # Overmind only; optional summary adds context
+orchestrator ticket park   '{"ticketId":"...","summary":"<required human action or blocker>"}'  # Overmind only; waiting tickets only
+orchestrator ticket unpark '{"ticketId":"...","summary":"<why it can proceed>"}'  # Overmind only
+orchestrator ticket done   '{"ticketId":"...","summary":"<acceptance>"}'  # Overmind only
+orchestrator ticket archive <ticket-id>                                  # Overmind only; aborts its active Drone and waits for termination
+orchestrator ticket unarchive <ticket-id>                                # Overmind only; restores its prior board state
+orchestrator ticket brief <ticket-id> [--after <cursor>] [--through <highWaterMark>]
+orchestrator ticket worklog <ticket-id> [--after <cursor>] [--through <highWaterMark>]
+orchestrator ticket decision <ticket-id> '{"choice":"...","rationale":"..."}'
+orchestrator ticket handoff <ticket-id> '{"results":"...","validation":"...","remainingWork":"...","references":["<event ID, commit or durable artifact>"]}'
+orchestrator ticket guide <ticket-id> '{"message":"..."}'                 # Overmind only; passive advice
+orchestrator ticket timeline <ticket-id> [--after <cursor>] [--through <highWaterMark>]
+orchestrator workspace check <ticket-id>
+orchestrator integration <ticket-id>                                    # assigned gatekeeper drone only
+orchestrator workspace cleanup <ticket-id>                              # Overmind only; ticket must be done
+orchestrator agent list | agent get <name> | agent prompt <name>
+```
+
+Ticket status is lifecycle-derived: the orchestrator moves an assigned
+ticket to `ongoing` when its Drone run starts and back to `waiting` when the
+run ends. Agents never start, accept, yield, or release tickets. Before ending
+each assignment, write one `ticket handoff`, including unfinished work and any
+failed or unperformed checks. A normal final response does not replace it.
+The orchestrator gives at most one handoff-only reminder, bounded to 60 seconds;
+if still absent, the terminal outcome records it explicitly. A handoff does not
+mark the ticket complete. Pi already records routine messages and tool results.
+
+Read `ticket brief` first: it returns current ticket state, the latest handoff
+(or null), and a bounded `notes` page of decisions and guides. Inspect the
+handoff's execution ID: it may describe an earlier assignment. `ticket worklog`
+returns only decisions, handoffs and guides, preserving canonical IDs, sequences,
+authors and execution IDs. To continue a notes/worklog page, pass its `cursor`
+as `--after` and retain its `highWaterMark` as `--through`. Use `ticket timeline`
+sparingly: it returns raw timeline records, including messages and tool results.
+Read targeted pages only when ticket information and worklogs leave an evidence
+gap; event sequence N is after cursor N-1. Do not scan the full timeline by default.
+
+Use `ticket decision` optionally for a consequential choice and its rationale.
+Use `ticket guide` for passive Overmind advice: it records context without waking
+or steering Pi, changing the assignment, or requiring immediate agreement.
+Only the assigned Drone writes its handoff; an Overmind may write decisions
+and guides. Keep records concise. Maximum field lengths: choice/validation/
+remainingWork 1024 characters, rationale/results/message 2048. References are
+optional (up to 8, 512 characters each); use durable pointers, not copied logs.
+For a transport retry, preserve the command ID with `--command-id <uuid>`. An accepted
+handoff is immutable for that execution; additional corrections can be decisions.
+
+Transition verbs still require a short `summary` explaining the decision.
+Assignment changes retain the old and new assignee as host-authoritative facts.
+Do not pass channel or identity fields; the orchestrator supplies provenance.
+
+Tickets are independent work items, with no typed links or parent chain.
+In an assessment session, `ticket create` requires `contextTicketId` naming a
+ticket in your authorized set. This is used once to copy its source conversation
+and is not stored as a relationship. Drone creation uses its current ticket;
+conversation creation uses the current channel. Newly created tickets enter the
+launch's authorized set so they can be read and assigned in the same turn.
+
+## App workspace flow
+
+App association is optional and fixed at ticket creation. For generated-app
+work, create or reuse the app first and pass `appId` to `ticket create`.
+Use `app get` to read its shared brief, and `app update` to maintain the goal,
+constraints and acceptance criteria. Do not create a coordination-only ticket.
+Standalone work runs in the assigned agent's ticket session directory and
+requires no app, repository or integration. Its timeline preserves handoffs
+between agents; their scratch directories are separate.
+
+The orchestrator derives all Git mechanics; agents do not invent paths or
+branches:
+
+```text
+repository: /workspace/<appId>
+worktree:   /worktree/<appId>/<ticketId>
+branch:     ticket/<ticketId>
+```
+
+Every app ticket runs in its worktree. The author commits, writes its ticket
+handoff, and finishes without integrating; the orchestrator returns
+the ticket to the queue. Overmind assigns a different Drone as gatekeeper.
+The gatekeeper merges the latest `main` into the ticket branch, reviews and
+tests that combined state, then runs `orchestrator integration <ticket-id>`.
+Authors can run `orchestrator workspace check <ticket-id>` before handoff.
+The command updates canonical `main` with `git merge --ff-only`; a concurrent
+integration makes it fail stale and the gatekeeper must repeat the merge and
+checks. Overmind marks the ticket done only after integration evidence is
+present. Cleanup removes only clean, merged worktrees and branches and never
+forces deletion.
+
+## Board model
+
+- `waiting` is the judgment queue: every finished Drone run lands its ticket
+  back here, unassigned, for Overmind to resolve — assign (re-assigning the
+  same agent resumes its session), park, or done. Overmind must resolve
+  every unassigned `waiting` ticket; the native timeline records
+  how the last run ended and the Gen App build result. Dispatch is
+  automatic: the orchestrator spawns the ticket owner's Overmind for a
+  board assessment shortly after judgment work appears. Do not poll.
+- `waiting` + assigned = the orchestrator will spawn that drone and move the
+  ticket to `ongoing` itself. Do not poll.
+- `ongoing` mirrors a live Drone run exactly; it always drains back to
+  `waiting` when the run ends, whatever the outcome.
+- `intervention` = parked for a human or a blocker; nothing runs. Only
+  `waiting` tickets park (Overmind judgment, or the scheduler at a
+  repeated-failure cap).
+- `done` is terminal and only Overmind sets it.
+- Archived tickets retain their workflow state but are absent from all four
+  board queues. Archiving first aborts any active Drone for that ticket and
+  waits for terminal execution state; unarchiving restores the ticket to the
+  queue for its retained state.