@phyzess/pappra 0.0.0-stage → 0.1.0-beta.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 phyzess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# Pappra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pappra is a portable workspace manager for coding-agent workflows. It keeps workspace configuration, selected project knowledge, checkpoints, recovery context and bounded code navigation in files owned by the workspace rather than in one chat transcript.
+
+Pappra is the manager. External coding hosts, code-graph engines and collaboration controllers are optional integrations, not installation prerequisites.
+
+## Quick start
+
+Requirements: Node.js 24 or later. `pnpm` 12.3.4 is required only for development inside this repository; Git is required only when a command observes repository identity.
+
+The package is published as `@phyzess/pappra`. Run it with `npx` from the target workspace, or install it globally when you use it every day.
+
+```sh
+# In an empty target workspace
+mkdir -p /tmp/pappra-demo
+cd /tmp/pappra-demo
+curl -fsSL https://raw.githubusercontent.com/phyzess/pappra/main/examples/minimal-choices.json -o ./minimal-choices.json
+
+# Preview first. JSON/config mode is non-interactive and does not prompt.
+npx @phyzess/pappra@beta init --config ./minimal-choices.json --json
+
+# Apply the same choices. Apply also installs and binds a durable runtime copy,
+# so this converges with exit code 0; add --no-runtime to leave it pending.
+npx @phyzess/pappra@beta init --config ./minimal-choices.json --apply --json
+npx @phyzess/pappra@beta doctor --json
+```
+
+`examples/minimal-choices.json` is complete for a host-free, no-graph, single-directory workspace. The example intentionally has no repositories or optional hosts.
+
+For a non-interactive derived setup, `npx @phyzess/pappra@beta init --yes --apply --json` derives repositories, knowledge sources, code engine, validation commands, excludes and hosts from discovery. `--print-choices` prints that `pappra/init-choices/1` document and writes nothing, and `init --json` without selections returns the discovery candidates plus the suggested document. JSON mode never prompts; only a TTY without selections opens the wizard.
+
+Development from a checkout works the same way: `pnpm install --frozen-lockfile`, `pnpm build`, then invoke `dist/cli/main.js` by absolute path from the target workspace.
+
+`init --apply` also installs a durable runtime copy of the executing package under the
+Pappra data directory and binds it in `machine.json`, so an npx/dlx bootstrap survives
+cache eviction and the command converges with exit code `0`. Pass `--no-runtime` to leave
+that action pending instead; the result is then `ok:true` with
+`status:"external-actions-pending"` and a nonzero exit, which is a partial configuration
+write rather than a claim that a runtime exists.
+
+The runtime copy can be managed directly:
+
+```sh
+npx @phyzess/pappra@beta runtime install --apply [--from self|tarball|registry]
+npx @phyzess/pappra@beta runtime status --json
+npx @phyzess/pappra@beta runtime verify --json
+```
+
+A workspace that already has a valid `.pappra/workspace.json` is never rewritten silently.
+`init --yes --reconfigure --apply` rebuilds it from discovery (for example to move the
+recorded runtime version to the running package), backing the previous file up under
+`.pappra/local/backups`. Apply also reports advisory `nextActions`: `pappra code prepare`
+for a selected code engine and `pappra docs scan --apply` to register documents from the
+configured knowledge sources.
+
+Optional examples have prerequisites rather than generated files: code-graph and
+host commands require the selected external CLI/support, and collaboration
+requires an explicit controller. `--controller pi-rpc` is the host-directs/Pi-executes
+path, verified end to end against Pi 1.3.0; see [Pi RPC collaboration](docs/pi-rpc.md).
+They are not needed for the core workflow above.
+
+## What it manages
+
+- **Workspace configuration:** `.pappra/workspace.json` and checkout-local `.pappra/local/machine.json`.
+- **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
+- **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
+- **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle; Claude Code uses `${CLAUDE_PROJECT_DIR}` and Pi imports its runtime relatively, while Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json` (`host install --host codex --scope user`). `host bundle --marketplace` exports a marketplace that Claude Code and Codex accept without registering it. Plugin hooks are verified for Pi 1.3.0 and Claude Code 2.1.292 (startup) and unsupported for Codex, so `host install --mode plugin` fails closed with the per-host registration commands. See [host plugin validation](docs/host-plugin-validation.md).
+- **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
+
+## Optional integrations and support
+
+| Capability                                            | Requirement                                              | Default                                                   |
+| ----------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------- |
+| Workspace, init, doctor, checkpoint/resume, knowledge | Node.js only; Git for repository identity                | Core                                                      |
+| Code graph status/prepare/query                       | Optional external code-graph engine                      | Disabled unless selected; text fallback remains available |
+| Host hooks                                            | Explicitly selected Pi, Codex or Claude Code integration | Not installed automatically                               |
+| Collaboration controller                              | Explicit `--controller <fixture\|pi-rpc>`                | No implicit controller                                    |
+
+Host names and external protocol identifiers describe supported integration surfaces. They do not make any host, model, graph engine or private workspace a prerequisite for core use.
+
+## Development checks
+
+```sh
+pnpm check
+```
+
+The check runs the source policy, type checks, formatting, deterministic tests and a local package smoke test. The package smoke test prefers an offline local tarball (falling back to registry resolution when the runner has no offline metadata) and an isolated fixture home/state; it does not install a model or contact a model provider.
+
+## Status and limits
+
+Pappra is development software (`0.1.0-beta.10`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.10`, because pre-release versions are never republished.
+
+The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
+
+## License
+
+Pappra is licensed under the MIT License. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+More detail: [quick start](docs/quickstart.md), [API boundaries](docs/api.md), [support and limitations](docs/support.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,16 @@
+# Third-party notices
+
+Pappra depends on the following packages. Runtime dependencies are installed by
+the consumer and are not copied into Pappra source files.
+
+| Package          | Version | License    | Role                   |
+| ---------------- | ------- | ---------- | ---------------------- |
+| `@clack/prompts` | 1.8.1   | MIT        | Interactive prompts    |
+| `zod`            | 4.6.6   | MIT        | Runtime validation     |
+| `@types/node`    | 24.19.1 | MIT        | Development types      |
+| `prettier`       | 3.9.9   | MIT        | Development formatting |
+| `typescript`     | 7.0.2   | Apache-2.0 | Development compiler   |
+
+The package manager `pnpm` is a development tool and is not shipped in the
+published package contents. This notice is informational; it does not replace
+the license texts or attribution supplied by the projects above.

package/assets/integrations/skills/pappra/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: pappra
+description: Use Pappra workspace knowledge, checkpoint/resume, and selected-repository code intelligence from any supported coding agent. Use when a task needs durable handoff context, workspace documents, or bounded code navigation.
+---
+
+# Pappra
+
+Pappra keeps workspace knowledge, continuity, and code navigation outside the
+host transcript. Use the installed `pappra` CLI for durable operations; hooks
+only record bounded lifecycle observations and never start a model, download,
+index, or new writer.
+
+## Start here
+
+1. Read `references/lifecycle.md` before relying on a host lifecycle event.
+2. Read `references/hosts.md` when the host surface is Pi, Codex, or Claude.
+3. Use `pappra checkpoint` / `pappra resume` for handoffs. A stored checkpoint
+   is context, not permission to execute or to trust a previous session.
+4. Use `pappra docs`, `pappra code`, `pappra runtime` and `pappra host` only for
+   the workspace selected by the current root. Never infer a workspace from an
+   unrelated session. `pappra docs scan --apply` registers discovered documents;
+   `pappra runtime install --apply` keeps a durable copy of this package.
+5. For a new bounded collaboration request, build an explicit
+   `pappra/collaboration-goal/1` from the user's objective and named choices,
+   run `pappra collab prepare --goal <file> --domain-root <dir>`, admit against a fresh capability
+   card, then use `pappra collab run` with the reviewed controller. `--controller
+pi-rpc` launches a real owned Pi session and is verified for Pi 1.3.0. Never
+   turn prose into identity, approval, or capability claims.
+
+## One-request collaboration
+
+`pappra collab prepare --goal <file> --domain-root <dir>` requires an explicit
+shared domain. It validates the canonical domain/tasks/task/private namespace
+before writing any task metadata and again around each write, so a task-root or
+mid-write directory redirect fails closed instead of scattering artifacts. It
+then writes a private task record, assignment, prompt, and resource claims; read
+resources stay read claims. The captured identities also guard live query, finish, disposal and lower RPC artifact writes; after a redirect, no new query/execution/proof/current-result pathname is written. `pappra collab run` requires an explicit `--controller <fixture|pi-rpc>`,
+performs the single admitted launch, and accepts bounded
+`pappra/collaboration-command/1` JSONL on stdin; it emits
+`pappra/collaboration-event/1` JSONL. `query` reads persisted history only and
+reports live ownership as unknown. A `finish` produces one deterministic REPORT;
+only a result whose stored classification was `applied` for the same fixed
+identity/attempt/input may repeat successfully as a duplicate — repeated
+rejections stay rejected. Cancel records and validates intent first: a denied
+intent never calls the native controller. Claims are retained and stop proof is
+never invented.
+
+Use `--controller fixture` only for deterministic, no-model tests; it is a
+restricted explicit fixture, never a silent default. The optional `pi-rpc` controller
+uses the existing owned Pi RPC daily path and preserves required skills, tools,
+MCP, hooks, and model settings; missing capabilities or stale/forged admission
+fail before launch. A native run reports only the current prompt-correlated
+result: terminal success requires a supported terminal reason and no pending
+tool call, so text-plus-toolUse/intermediate, tool-only, empty, old, malformed or
+missing answers are `unknown`; an explicit error is `failed` and an abort is
+`cancelled`. The current result must be published as validated
+`native-current-result/1` evidence; EIO/conflict/symlink/partial publication
+makes delivery `unknown`, not success, and repeated finish reuses verified
+content instead of overwriting it. A clean transport exit is not task success.
+No approval is auto-answered, no cancel is inferred from an acknowledgement, and no new thread or
+arbitrary PID is adopted. Do not launch a model or real user session without
+the task's explicit authorization.
+
+## Boundaries
+
+- Hooks are local and bounded. They do not read transcripts, run commands,
+  call models, fetch the network, or continue a conversation.
+- Missing semantic context stays missing; do not fabricate summaries.
+- Treat unknown ownership, stale bundles, untrusted hooks, and changed host
+  versions as visible conditions, not silent fallbacks.
+- Preserve user settings and unrelated keys when integrating a host.

package/assets/integrations/skills/pappra/references/hosts.md

@@ -0,0 +1,40 @@
+# Host surfaces
+
+## Pi
+
+The project integration installs an extension plus a copied `pappra` skill; the
+generated entrypoint imports the fixed Pappra runtime by absolute file URL.
+`pappra host bundle --host pi` exports a self-contained package instead: the
+entry imports `./runtime.mjs` next to it, so the package survives a moved
+checkout. Pi 1.3.0 was verified in a real session through the packaged extension
+(`pi install <dir> -l -a` + `pi -p -a`).
+
+## Codex
+
+Codex 0.163.0 loads command hooks only from its user configuration directory.
+Wire it with `pappra host install --host codex --scope user`, which merges only
+Pappra-owned entries into `$CODEX_HOME/hooks.json` (existing hooks and unrelated
+keys are preserved) and copies the bundled hook there. Project
+`.codex/hooks.json` and plugin-bundle hooks are not loaded at this version.
+Codex hook definitions are trusted individually; installation is not trust.
+Observed 0.163.0 hook keys do not include a compact event, so compact and
+automatic checkpoint requests remain unsupported.
+
+## Claude Code
+
+The project integration installs a command-hook entry and merges only
+Pappra-owned entries into `settings.json`; the command uses
+`${CLAUDE_PROJECT_DIR}`. `pappra host bundle --host claude --marketplace` exports
+a plugin whose hook uses `${CLAUDE_PLUGIN_ROOT}`; the marketplace validates with
+`claude plugin validate` and startup was verified in a real session. `SessionStart`
+and `PostCompact` are distinct; matchers, trust, timeout, and output behavior
+remain host/version-specific. Installing a command is not proof it ran.
+
+## Common safety
+
+All surfaces use the event's canonical cwd/root, bounded stdin, a one-second
+local deadline, no transcript reads, no arbitrary configured commands, and no
+network/model/index/session side effects. Paths with spaces or Unicode are
+passed as argv/file URLs, never interpolated into a shell. Plugin registration is
+host-specific; never claim a hook is loaded because files were written or a
+validator passed.

package/assets/integrations/skills/pappra/references/lifecycle.md

@@ -0,0 +1,41 @@
+# Lifecycle reference
+
+## Supported mapping
+
+Pappra distinguishes four local lifecycle intents:
+
+| Intent               | Pi                           | Codex                                      | Claude                                     |
+| -------------------- | ---------------------------- | ------------------------------------------ | ------------------------------------------ |
+| `startup`            | `session_start`              | `SessionStart` with source `startup`/`new` | `SessionStart` with source `startup`/`new` |
+| `resume`             | `session_start`              | `SessionStart` with source `resume`        | `SessionStart` with source `resume`        |
+| `compact`            | `session_before_compact`     | unsupported in observed 0.163.0 hook keys  | `PostCompact`                              |
+| `checkpoint-request` | explicit Pappra command/hook | unsupported automatic event                | unsupported automatic event                |
+
+The matrix is version-specific. A host version outside the observed support
+range is `unsupported`/`unknown`, not a fallback to name similarity.
+
+Codex 0.163.0 loads these hook keys only from its user configuration directory
+(`$CODEX_HOME/hooks.json`); project `.codex/hooks.json` and plugin bundles are
+not loaded by that version. Claude Code and Pi wire hooks in project scope.
+
+## What a hook does
+
+A hook validates the host payload, resolves the current workspace from the
+event cwd (never from a last-session cache), derives a bounded event identity,
+suppresses a duplicate identity, and records a private local event observation.
+It may print a short advisory context. It never starts a model, fetches,
+indexes, runs arbitrary commands, creates a new agent, or writes a checkpoint
+with invented semantics.
+
+## Manual continuity
+
+`pappra checkpoint --task <id> ...` and `pappra resume <id>` remain available
+without hooks. A hook observation is not a checkpoint and does not grant
+`executionAllowed`. A resume packet is read-only context; an unknown or
+non-stopped writer fails closed.
+
+## Reload and trust
+
+Installing files does not prove the host loaded them or trusted their exact
+definition. Report reload-needed and trust-needed separately. Do not approve a
+host trust prompt on the user's behalf.

package/assets/integrations/skills/pappra/references/operations.md

@@ -0,0 +1,27 @@
+# Operations reference
+
+- `pappra init` plans or applies workspace configuration. `--yes` derives
+  selections from discovery, `--print-choices` prints that document without
+  writing, `--reconfigure` rebuilds an existing valid `workspace.json`, and
+  `--no-runtime` leaves the durable runtime action pending.
+- `pappra runtime <install|status|verify|remove>` manages the durable runtime
+  copy. `install --apply` defaults to `--from self`; writes require `--apply`.
+- `pappra doctor` is passive: it does not install hooks, start hosts, or fix
+  state. `runtime verify` is the active runtime check.
+- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a stored
+  snapshot and reports whether execution is allowed.
+- `pappra docs <list|check|archive|scan>` manages the knowledge catalog.
+  `scan --apply` registers documents found under the configured sources.
+- `pappra code` operates on an explicitly selected repository and keeps index
+  mutations behind an explicit `--apply`.
+- `pappra host <detect|describe|plan|install|verify|bundle>` wires an optional
+  host. Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json`, so use
+  `install --host codex --scope user`; `bundle --marketplace` exports a plugin
+  directory without registering it, and `install --mode plugin` fails closed.
+- `pappra collab <prepare|run|query>` runs one bounded collaboration request.
+  `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
+  session.
+
+Preserve user bytes. If an operation reports a conflict or residual path,
+inspect that path and resolve ownership before retrying. Never delete an
+unknown file to make a retry succeed.

package/assets/manifest.json

@@ -0,0 +1,4 @@
+{
+  "schema": "pappra/assets/1",
+  "stage": "toolchain"
+}

package/dist/app/collaboration.d.ts

@@ -0,0 +1,170 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import { type CollaborationEvent, type CollaborationGoal, type CollaborationPrepared } from '../schemas/collaboration.js';
+import { admitLaunch } from '../collab/admission.js';
+import type { Assignment } from '../collab/contracts.js';
+export type CollaborationFailureStatus = 'invalid' | 'needs_input' | 'conflict' | 'unsupported' | 'failed';
+export interface CollaborationFailure {
+    readonly ok: false;
+    readonly status: CollaborationFailureStatus;
+    readonly code: string;
+    readonly message: string;
+    readonly nextAction: string | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export type CollaborationResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | CollaborationFailure;
+export interface PrepareOptions {
+    readonly domainRoot: string;
+    readonly clock?: number;
+}
+export interface PreparedBundle {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+}
+export interface StartOptions {
+    readonly capabilitiesFile: string;
+    readonly controller: CollaborationController;
+    readonly controllerId: string;
+    readonly clock?: number;
+}
+export interface ControllerStartRequest {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+    readonly capabilitiesFile: string;
+    readonly prompt: string;
+    readonly promptFile: string;
+    readonly taskRoot: string;
+    readonly evidenceDir: string;
+    readonly namespace?: PrivateNamespace;
+}
+export interface ControllerObservation {
+    readonly status: string;
+    readonly detail: string | null;
+    readonly data: unknown;
+}
+export interface ControllerCancel {
+    readonly acknowledged: boolean;
+    readonly terminal_observed: boolean;
+    readonly stop_evidence: unknown;
+}
+export interface ControllerFinish {
+    readonly outcome: string;
+    readonly status: string;
+    readonly exitCode: number | null;
+    readonly sessionId: string | null;
+    readonly outputs: readonly unknown[];
+    readonly nativeRef: unknown;
+    readonly evidenceRef: string | null;
+}
+export interface ControllerSession {
+    query(): Promise<ControllerObservation>;
+    cancel(): Promise<ControllerCancel>;
+    finish(): Promise<ControllerFinish>;
+    dispose?(): Promise<void>;
+}
+export interface CollaborationController {
+    readonly id: string;
+    start(token: object, request: ControllerStartRequest): Promise<{
+        readonly ok: true;
+        readonly session: ControllerSession;
+    } | {
+        readonly ok: false;
+        readonly status: CollaborationFailureStatus;
+        readonly code: string;
+        readonly message: string;
+        readonly nextAction: string | null;
+        readonly possible_start?: boolean;
+    }>;
+}
+interface NamespaceIdentity {
+    readonly path: string;
+    readonly canonical: string;
+    readonly dev: number;
+    readonly ino: number;
+}
+export interface PrivateNamespace {
+    readonly domain: NamespaceIdentity;
+    readonly taskRoot: NamespaceIdentity;
+    readonly privateDir: NamespaceIdentity;
+}
+export declare function validateLaunchToken(token: unknown, expected: {
+    readonly taskRoot: string;
+    readonly assignmentDigest: string;
+    readonly subtaskId: string;
+    readonly attempt: number;
+}): boolean;
+export declare function prepareCollaboration(input: unknown, options: PrepareOptions): Promise<CollaborationResult<PreparedBundle>>;
+export interface AdmissionResult {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+    readonly admission: Awaited<ReturnType<typeof admitLaunch>>;
+    readonly token: object;
+}
+export declare function admitPrepared(preparedFile: string, capabilitiesFile: string, options?: {
+    readonly clock?: number;
+}): Promise<CollaborationResult<AdmissionResult>>;
+export interface StartedRun {
+    readonly prepared: CollaborationPrepared;
+    readonly goal: CollaborationGoal;
+    readonly assignment: Assignment;
+    readonly token: object;
+    readonly controller: CollaborationController;
+    readonly session: ControllerSession;
+    readonly reservationId: string | null;
+}
+export declare function startPrepared(preparedFile: string, options: StartOptions): Promise<CollaborationResult<StartedRun>>;
+export interface ReportResult {
+    readonly ok: boolean;
+    readonly messageId: string;
+    readonly duplicate: boolean;
+    readonly classification: string | null;
+    readonly detail: string | null;
+}
+export declare function submitResultReport(started: StartedRun, finish: ControllerFinish, { clock }?: {
+    clock?: number;
+}): ReportResult;
+export declare function finishStarted(started: StartedRun): Promise<CollaborationResult<ControllerFinish>>;
+export declare function driveRun(started: StartedRun, commands: AsyncIterable<unknown>, emit: (event: CollaborationEvent) => void, { clock }?: {
+    clock?: number;
+}): Promise<CollaborationResult<ReportResult>>;
+export declare class FixtureController implements CollaborationController {
+    private readonly options;
+    readonly id = "fixture";
+    constructor(options?: {
+        readonly status?: 'completed' | 'failed' | 'cancelled' | 'needs_input';
+        readonly outputs?: readonly unknown[];
+        readonly sessionId?: string;
+    });
+    start(token: object, request: ControllerStartRequest): Promise<{
+        readonly ok: true;
+        readonly session: ControllerSession;
+    } | {
+        readonly ok: false;
+        readonly status: CollaborationFailureStatus;
+        readonly code: string;
+        readonly message: string;
+        readonly nextAction: string | null;
+        readonly possible_start?: boolean;
+    }>;
+}
+export declare class PiRpcController implements CollaborationController {
+    readonly id = "pi-rpc";
+    start(token: object, request: ControllerStartRequest): Promise<{
+        readonly ok: true;
+        readonly session: ControllerSession;
+    } | {
+        readonly ok: false;
+        readonly status: CollaborationFailureStatus;
+        readonly code: string;
+        readonly message: string;
+        readonly nextAction: string | null;
+        readonly possible_start?: boolean;
+    }>;
+}
+export declare function inspectPreparedHistory(preparedFile: string): CollaborationResult<Record<string, unknown>>;
+export {};