@phyzess/pappra 0.1.0-beta.11 → 0.1.0-beta.13

package/README.md

@@ -8,7 +8,7 @@ Pappra is the manager. External coding hosts, code-graph engines and collaborati
 
 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.
+The package is published as `@phyzess/pappra`. Install it once for daily use (`npm install -g @phyzess/pappra@beta`, the command is `pappra`), or run it with `npx` when you want a zero-install, version-pinned invocation.
 
 ```sh
 # In an empty target workspace
@@ -38,6 +38,11 @@ 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.
 
+For a new workspace or a new machine, `pappra onboard --dry-run --json` shows the plan and
+the host version matrix; `pappra onboard --yes --apply-host --json` applies config, runtime
+and verified host wiring (host trust still needs one approval). See
+[portability](docs/portability.md).
+
 The runtime copy can be managed directly:
 
 ```sh
@@ -66,6 +71,7 @@ They are not needed for the core workflow above.
 - **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. Registrations are stored under the workspace `.pappra/local/code`, never inside a repository checkout, so a multi-repository workspace does not turn its checkouts into nested workspaces.
 - **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).
+- **Agent-native tools:** `pappra mcp` exposes read-only and gated write tools over stdio MCP; `pappra host mcp install` registers it for Claude Code or Pi, and Codex uses `codex mcp add`. `pappra task pin <id> --auto-resume` lets hooks inject a bounded resume packet. See [agent-native usage](docs/agent-native.md).
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -89,7 +95,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.11`) 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.11`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.13`) 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.13`, 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.
 

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

@@ -1,5 +1,8 @@
 # Operations reference
 
+- `pappra onboard` plans or applies a whole workspace setup (config, durable runtime,
+  verified host wiring). `--dry-run` writes nothing; `--apply-host` still leaves host trust
+  to the person.
 - `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
@@ -18,6 +21,8 @@
   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 mcp` starts the stdio MCP server; `pappra host mcp install --host <name> --apply`
+  registers it. `pappra task pin <id> --auto-resume` controls hook resume injection.
 - `pappra collab <prepare|run|query>` runs one bounded collaboration request.
   `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
   session.

package/dist/app/collab-from.d.ts

@@ -0,0 +1,35 @@
+import type { HostName } from '../schemas/host.js';
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import { type PreparedBundle } from './collaboration.js';
+export interface CollabResource {
+    readonly path: string;
+    readonly access: 'read' | 'write';
+}
+export interface PrepareFromObjectiveInput {
+    readonly domainRoot: string;
+    readonly objective: string;
+    readonly taskId: string;
+    readonly subtaskId?: string;
+    readonly attempt?: number;
+    readonly phase?: 'discovery' | 'implementation' | 'review' | 'handoff' | 'fix';
+    readonly acceptance: readonly string[];
+    readonly prompt?: string;
+    readonly coordinatorSession: string;
+    readonly assigneeSession: string;
+    readonly harness?: HostName;
+    readonly resources: readonly CollabResource[];
+}
+export type PrepareFromObjectiveResult = {
+    readonly ok: true;
+    readonly prepared: PreparedBundle['prepared'];
+    readonly goal: PreparedBundle['goal'];
+    readonly cardPath: string;
+    readonly card: Record<string, unknown>;
+    readonly notes: readonly string[];
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    readonly diagnostics: readonly Diagnostic[];
+};
+export declare function prepareFromObjective(input: PrepareFromObjectiveInput): Promise<PrepareFromObjectiveResult>;

package/dist/app/collab-from.js

@@ -0,0 +1,84 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { prepareCollaboration } from './collaboration.js';
+export async function prepareFromObjective(input) {
+    const harness = input.harness ?? 'pi';
+    if (input.resources.length === 0) {
+        return {
+            ok: false,
+            code: 'collab_resource_required',
+            message: 'A collaboration goal needs at least one explicit resource (file or directory).',
+            diagnostics: [],
+        };
+    }
+    const goal = {
+        schema: 'pappra/collaboration-goal/1',
+        task_id: input.taskId,
+        subtask_id: input.subtaskId ?? 'work',
+        attempt: input.attempt ?? 1,
+        phase: input.phase ?? 'implementation',
+        objective: input.objective,
+        acceptance: [...input.acceptance],
+        prompt: input.prompt ?? input.objective,
+        coordinator: {
+            agent_id: 'coordinator',
+            session_id: input.coordinatorSession,
+            harness: 'codex',
+            owner_epoch: 1,
+        },
+        assignee: {
+            agent_id: 'worker',
+            session_id: input.assigneeSession,
+            harness,
+            surface: 'rpc',
+            configuration_id: 'daily',
+            cwd: input.resources[0].path,
+        },
+        resources: input.resources.map((resource) => ({
+            path: resource.path,
+            access: resource.access,
+        })),
+        required: { skills: [], tools: [] },
+        preferred: { skills: [], tools: [] },
+    };
+    const prepared = await prepareCollaboration(goal, {
+        domainRoot: input.domainRoot,
+    });
+    if (!prepared.ok) {
+        return {
+            ok: false,
+            code: prepared.code,
+            message: prepared.message,
+            diagnostics: prepared.diagnostics ?? [],
+        };
+    }
+    const card = {
+        schema: 'harness-collab/capabilities/1',
+        agent_id: goal.assignee.agent_id,
+        session_id: goal.assignee.session_id,
+        harness: goal.assignee.harness,
+        surface: goal.assignee.surface,
+        configuration_id: goal.assignee.configuration_id,
+        cwd: goal.assignee.cwd,
+        observed_at: new Date().toISOString(),
+        evidence_level: 'declared',
+        skills: [],
+        tools: [],
+    };
+    const cardPath = join(prepared.value.prepared.prepared_dir, 'card.declared.json');
+    await mkdir(prepared.value.prepared.prepared_dir, { recursive: true });
+    await writeFile(cardPath, `${JSON.stringify(card, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    return {
+        ok: true,
+        prepared: prepared.value.prepared,
+        goal: prepared.value.goal,
+        cardPath,
+        card,
+        notes: [
+            'The generated capability card is declared, not runtime evidence: a work launch will refuse it.',
+            'For a real launch, provide a runtime capability card observed from an admitted session.',
+        ],
+    };
+}

package/dist/app/host-mcp.d.ts

@@ -0,0 +1,25 @@
+import type { HostName } from '../schemas/host.js';
+declare const MCP_ENTRY: {
+    readonly command: 'pappra';
+    readonly args: readonly ['mcp'];
+};
+export type HostMcpState = 'create' | 'unchanged' | 'conflict' | 'manual';
+export interface HostMcpPlan {
+    readonly host: HostName;
+    readonly target: string | null;
+    readonly state: HostMcpState;
+    readonly entry: typeof MCP_ENTRY;
+    readonly command: readonly string[] | null;
+    readonly message: string;
+}
+export interface HostMcpResult extends HostMcpPlan {
+    readonly applied: boolean;
+    readonly verified: boolean;
+    readonly detail: string | null;
+}
+export declare function planHostMcp(host: HostName, root: string): Promise<HostMcpPlan>;
+export declare function applyHostMcp(plan: HostMcpPlan, options: {
+    readonly force: boolean;
+}): Promise<HostMcpResult>;
+export declare function verifyHostMcp(plan: HostMcpPlan): Promise<HostMcpResult>;
+export {};

package/dist/app/host-mcp.js

@@ -0,0 +1,227 @@
+import { spawnSync } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const MCP_ENTRY = { command: 'pappra', args: ['mcp'] };
+function mcpConfigPath(host, root) {
+    if (host === 'claude')
+        return `${root}/.mcp.json`;
+    if (host === 'pi')
+        return `${root}/.pi/mcp.json`;
+    return null;
+}
+function sameEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    const args = record['args'];
+    return (record['command'] === MCP_ENTRY.command &&
+        Array.isArray(args) &&
+        args.length === MCP_ENTRY.args.length &&
+        args.every((arg, index) => arg === MCP_ENTRY.args[index]));
+}
+async function readConfig(path) {
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return { ok: true, value: {}, exists: false };
+        }
+        return {
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    try {
+        const value = JSON.parse(text);
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return { ok: false, message: 'MCP config is not a JSON object.' };
+        }
+        return { ok: true, value: value, exists: true };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: `MCP config is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function planHostMcp(host, root) {
+    if (host === 'codex') {
+        return {
+            host,
+            target: null,
+            state: 'manual',
+            entry: MCP_ENTRY,
+            command: ['codex', 'mcp', 'add', 'pappra', '--', 'pappra', 'mcp'],
+            message: 'Codex MCP servers are user-scoped; pappra prints the host command instead of merging TOML.',
+        };
+    }
+    const target = mcpConfigPath(host, root);
+    if (target === null) {
+        return {
+            host,
+            target: null,
+            state: 'manual',
+            entry: MCP_ENTRY,
+            command: null,
+            message: `No MCP registration is defined for ${host}.`,
+        };
+    }
+    const config = await readConfig(target);
+    if (!config.ok) {
+        return {
+            host,
+            target,
+            state: 'conflict',
+            entry: MCP_ENTRY,
+            command: null,
+            message: config.message,
+        };
+    }
+    const servers = config.value['mcpServers'];
+    if (servers !== undefined &&
+        (typeof servers !== 'object' || servers === null || Array.isArray(servers))) {
+        return {
+            host,
+            target,
+            state: 'conflict',
+            entry: MCP_ENTRY,
+            command: null,
+            message: 'mcpServers must be a JSON object.',
+        };
+    }
+    const existing = typeof servers === 'object' && servers !== null
+        ? servers['pappra']
+        : undefined;
+    const state = existing === undefined
+        ? 'create'
+        : sameEntry(existing)
+            ? 'unchanged'
+            : 'conflict';
+    return {
+        host,
+        target,
+        state,
+        entry: MCP_ENTRY,
+        command: null,
+        message: state === 'create'
+            ? `Register pappra in ${target}.`
+            : state === 'unchanged'
+                ? 'pappra is already registered.'
+                : 'A different pappra MCP entry exists; use --force to replace it.',
+    };
+}
+export async function applyHostMcp(plan, options) {
+    if (plan.state === 'manual') {
+        if (plan.host === 'codex' && plan.command !== null) {
+            const result = spawnSync(plan.command[0], plan.command.slice(1), {
+                encoding: 'utf8',
+                shell: false,
+                timeout: 60_000,
+            });
+            const verified = await verifyHostMcp(plan);
+            return {
+                ...plan,
+                applied: result.status === 0,
+                verified: verified.verified,
+                detail: result.status === 0
+                    ? null
+                    : `${result.stdout ?? ''}${result.stderr ?? ''}`
+                        .trim()
+                        .slice(0, 1000),
+            };
+        }
+        return {
+            ...plan,
+            applied: false,
+            verified: false,
+            detail: plan.message,
+        };
+    }
+    if (plan.state === 'conflict' && !options.force) {
+        return { ...plan, applied: false, verified: false, detail: plan.message };
+    }
+    const target = plan.target;
+    if (target === null) {
+        return { ...plan, applied: false, verified: false, detail: plan.message };
+    }
+    const config = await readConfig(target);
+    if (!config.ok) {
+        return { ...plan, applied: false, verified: false, detail: config.message };
+    }
+    const servers = config.value['mcpServers'];
+    const nextServers = {
+        ...(typeof servers === 'object' && servers !== null
+            ? servers
+            : {}),
+        pappra: MCP_ENTRY,
+    };
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify({ ...config.value, mcpServers: nextServers }, null, 2)}\n`);
+    const verified = await verifyHostMcp(plan);
+    return {
+        ...plan,
+        state: 'unchanged',
+        applied: true,
+        verified: verified.verified,
+        detail: null,
+    };
+}
+export async function verifyHostMcp(plan) {
+    if (plan.host === 'codex') {
+        const listed = spawnSync('codex', ['mcp', 'list', '--json'], {
+            encoding: 'utf8',
+            shell: false,
+            timeout: 60_000,
+        });
+        if (listed.status !== 0) {
+            return {
+                ...plan,
+                applied: false,
+                verified: false,
+                detail: `${listed.stdout ?? ''}${listed.stderr ?? ''}`
+                    .trim()
+                    .slice(0, 1000),
+            };
+        }
+        try {
+            const value = JSON.parse(listed.stdout);
+            const found = Array.isArray(value) &&
+                value.some((item) => typeof item === 'object' &&
+                    item !== null &&
+                    'name' in item &&
+                    item.name === 'pappra');
+            return { ...plan, applied: false, verified: found, detail: null };
+        }
+        catch (error) {
+            return {
+                ...plan,
+                applied: false,
+                verified: false,
+                detail: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    if (plan.target === null) {
+        return { ...plan, applied: false, verified: false, detail: plan.message };
+    }
+    const config = await readConfig(plan.target);
+    if (!config.ok) {
+        return { ...plan, applied: false, verified: false, detail: config.message };
+    }
+    const servers = config.value['mcpServers'];
+    const entry = typeof servers === 'object' && servers !== null
+        ? servers['pappra']
+        : undefined;
+    return {
+        ...plan,
+        applied: false,
+        verified: sameEntry(entry),
+        detail: null,
+    };
+}

package/dist/app/host-probe.d.ts

@@ -0,0 +1,16 @@
+import type { HostName } from '../schemas/host.js';
+export interface HostProbeResult {
+    readonly host: HostName;
+    readonly command: string;
+    readonly version: string | null;
+    readonly pinnedVersion: string;
+    readonly protocol: 'pi-rpc' | 'version-only';
+    readonly ok: boolean;
+    readonly details: Readonly<Record<string, unknown>>;
+    readonly message: string;
+}
+/**
+ * Protocol-level probe. It never sends a prompt, starts a model, or writes workspace
+ * state; the Pi path only asks for `get_state` in a throwaway session directory.
+ */
+export declare function probeHost(host: HostName): HostProbeResult;

package/dist/app/host-probe.js

@@ -0,0 +1,125 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { HOST_SUPPORT } from '../hosts/integration/support.js';
+function commandVersion(command) {
+    const result = spawnSync(command, ['--version'], {
+        encoding: 'utf8',
+        shell: false,
+        timeout: 10_000,
+    });
+    if (result.status !== 0)
+        return null;
+    const match = /(\d+\.\d+\.\d+)/.exec(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+    return match?.[1] ?? null;
+}
+/**
+ * Protocol-level probe. It never sends a prompt, starts a model, or writes workspace
+ * state; the Pi path only asks for `get_state` in a throwaway session directory.
+ */
+export function probeHost(host) {
+    const pinnedVersion = HOST_SUPPORT[host].version;
+    const command = host;
+    const version = commandVersion(command);
+    if (version === null) {
+        return {
+            host,
+            command,
+            version: null,
+            pinnedVersion,
+            protocol: 'version-only',
+            ok: false,
+            details: {},
+            message: `${command} is not callable on PATH.`,
+        };
+    }
+    if (host !== 'pi') {
+        return {
+            host,
+            command,
+            version,
+            pinnedVersion,
+            protocol: 'version-only',
+            ok: version === pinnedVersion,
+            details: { matchesPinnedVersion: version === pinnedVersion },
+            message: version === pinnedVersion
+                ? 'Version matches the pinned support matrix; lifecycle callability still needs a real session.'
+                : `Version ${version} does not match the pinned ${pinnedVersion}.`,
+        };
+    }
+    const directory = mkdtempSync(join(tmpdir(), 'pappra-pi-probe-'));
+    const sessionId = randomUUID();
+    try {
+        const probe = spawnSync(command, ['--mode', 'rpc', '--session-dir', directory, '--session-id', sessionId], {
+            encoding: 'utf8',
+            shell: false,
+            timeout: 15_000,
+            input: `${JSON.stringify({ id: 'probe-1', type: 'get_state' })}\n`,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        const lines = `${probe.stdout ?? ''}`
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line !== '');
+        let state = null;
+        for (const line of lines) {
+            try {
+                const value = JSON.parse(line);
+                if (typeof value === 'object' &&
+                    value !== null &&
+                    'id' in value &&
+                    value.id === 'probe-1' &&
+                    'data' in value &&
+                    typeof value.data === 'object' &&
+                    value.data !== null) {
+                    state = value.data;
+                    break;
+                }
+            }
+            catch {
+                // Non-JSON extension UI lines are expected; keep scanning.
+            }
+        }
+        if (state === null) {
+            return {
+                host,
+                command,
+                version,
+                pinnedVersion,
+                protocol: 'pi-rpc',
+                ok: false,
+                details: {
+                    exitCode: probe.status,
+                    stderr: `${probe.stderr ?? ''}`.slice(0, 500),
+                },
+                message: 'Pi RPC did not answer get_state within the probe deadline.',
+            };
+        }
+        const reportedSessionId = state['sessionId'];
+        const reportedSessionFile = state['sessionFile'];
+        const sessionIdMatches = reportedSessionId === sessionId;
+        const sessionFileReported = typeof reportedSessionFile === 'string' && reportedSessionFile !== '';
+        return {
+            host,
+            command,
+            version,
+            pinnedVersion,
+            protocol: 'pi-rpc',
+            ok: sessionIdMatches && sessionFileReported,
+            details: {
+                sessionIdMatches,
+                sessionFileReported,
+                isStreaming: state['isStreaming'] ?? null,
+                pendingMessageCount: state['pendingMessageCount'] ?? null,
+            },
+            message: sessionIdMatches && sessionFileReported
+                ? 'Pi RPC answered get_state with the contracted session identity; no prompt was sent.'
+                : 'Pi RPC answered, but the session identity or session file did not match.',
+        };
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+}

package/dist/app/init.d.ts

@@ -6,6 +6,7 @@ import { type WorkspaceConfig, type WorkspaceValidation } from '../schemas/works
 import type { MachineConfigInspection, WorkspaceConfigInspection } from '../workspace/config.js';
 import { type WorkspaceDiscovery } from '../workspace/discover.js';
 import { type PlannedFileContent } from '../install/plan.js';
+import { type RuntimeInstallResult } from '../install/runtime.js';
 export type InitFailureStatus = 'needs_input' | 'invalid' | 'conflict' | 'unavailable';
 export interface InitFailure {
     readonly ok: false;
@@ -150,6 +151,7 @@ export interface DerivedInitChoices {
     readonly rules: readonly InitChoiceRule[];
     readonly candidates: InitChoiceCandidates;
 }
+export declare function detectedHostVersion(command: string, pathEnv: string): string | null;
 /**
  * Derives deterministic init selections from discovery alone. Every value is
  * reported with the rule that produced it so a caller can audit the choice
@@ -169,3 +171,16 @@ export declare function planWorkspaceInit(options: PlanInitOptions): Promise<Ini
  * reported as pending and never executed here.
  */
 export declare function applyInitPlan(bundle: InitPlanBundle, options?: InitApplyOptions): Promise<InitApplyResult>;
+export interface RuntimeFlowResult {
+    readonly ok: boolean;
+    readonly completion: boolean;
+    readonly runtime: RuntimeInstallResult | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function bindAndRecordRuntime(root: string, installed: RuntimeInstallResult): Promise<RuntimeFlowResult>;
+/**
+ * Converges the runtime binding by installing a durable copy of the package that
+ * is currently executing. Reusing an already verified copy is cheap: the install
+ * machinery short-circuits before packing.
+ */
+export declare function ensureDefaultRuntime(root: string, targetVersion: string): Promise<RuntimeFlowResult>;