@pasko70/pibo 1.16.6 → 2.1.1

package/dist/tools/session-service.js

@@ -0,0 +1,193 @@
+import { randomUUID } from "node:crypto";
+import { PiboToolMcpBridge, } from "./mcp-bridge.js";
+import { createPiboSessionToolDefinitions } from "./session-tool-set.js";
+function sessionKey(piboSessionId, sessionGeneration) {
+    return `${piboSessionId}\u0000${sessionGeneration}`;
+}
+function assertIdentifier(value, label) {
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`${label} is required`);
+    return normalized;
+}
+export class PiboPortableToolService {
+    bridge;
+    sessions = new Map();
+    constructor(options = {}) {
+        this.bridge = options.bridge ?? new PiboToolMcpBridge({
+            payloadWriter: options.payloadWriter,
+            resolveTools: (scope) => this.resolveTools(scope.piboSessionId, scope.sessionGeneration),
+            isSessionGenerationActive: (scope) => this.sessions.get(sessionKey(scope.piboSessionId, scope.sessionGeneration))?.active === true,
+            resolveExecutionContext: (scope) => {
+                const record = this.sessions.get(sessionKey(scope.piboSessionId, scope.sessionGeneration));
+                return record
+                    ? {
+                        piboSessionId: record.input.piboSessionId,
+                        piboRoomId: record.input.piboRoomId,
+                        profileName: record.input.profile.profileName,
+                        cwd: record.input.cwd,
+                        getActiveMessage: record.input.getActiveMessage,
+                        getConversationEntries: record.getConversationEntries,
+                    }
+                    : {};
+            },
+        });
+    }
+    createSession(input) {
+        const piboSessionId = assertIdentifier(input.piboSessionId, "piboSessionId");
+        const runtimeInstanceId = assertIdentifier(input.runtimeInstanceId, "runtimeInstanceId");
+        const adapterId = assertIdentifier(input.adapterId, "adapterId");
+        const cwd = assertIdentifier(input.cwd, "cwd");
+        const sessionGeneration = input.sessionGeneration
+            ? assertIdentifier(input.sessionGeneration, "sessionGeneration")
+            : randomUUID();
+        const key = sessionKey(piboSessionId, sessionGeneration);
+        const record = {
+            key,
+            active: true,
+            input: {
+                ...input,
+                piboSessionId,
+                runtimeInstanceId,
+                adapterId,
+                cwd,
+            },
+            controllers: {
+                subagentRunner: input.subagentRunner,
+                runToolController: input.runToolController,
+                runtimeToolController: input.runtimeToolController,
+                codexBrowserController: input.codexBrowserController,
+            },
+            getConversationEntries: input.getConversationEntries,
+            sessionGeneration,
+        };
+        this.sessions.set(key, record);
+        return this.createSessionHandle(record);
+    }
+    async dispose() {
+        for (const record of this.sessions.values()) {
+            record.active = false;
+            this.bridge.credentials.revokeSessionGeneration(record.input.piboSessionId, record.sessionGeneration);
+            this.bridge.closeSessionGeneration(record.input.piboSessionId, record.sessionGeneration);
+        }
+        this.sessions.clear();
+        await this.bridge.stop();
+    }
+    createDefinitions(record, options = {}) {
+        if (!record.active)
+            throw new Error(`Portable tool session for "${record.input.piboSessionId}" is disposed.`);
+        return createPiboSessionToolDefinitions({
+            profile: record.input.profile,
+            toolContext: {
+                piboSessionId: record.input.piboSessionId,
+                piboRoomId: record.input.piboRoomId,
+                profileName: record.input.profile.profileName,
+                cwd: record.input.cwd,
+                getActiveMessage: record.input.getActiveMessage,
+                getConversationEntries: record.getConversationEntries,
+            },
+            ...record.controllers,
+            nativeYieldableTools: options.nativeYieldableTools,
+        });
+    }
+    resolveTools(piboSessionId, generation) {
+        const record = this.sessions.get(sessionKey(piboSessionId, generation));
+        if (!record?.active)
+            return [];
+        return this.createDefinitions(record).filter((tool) => tool.portable !== false);
+    }
+    createSessionHandle(record) {
+        return {
+            piboSessionId: record.input.piboSessionId,
+            runtimeInstanceId: record.input.runtimeInstanceId,
+            adapterId: record.input.adapterId,
+            sessionGeneration: record.sessionGeneration,
+            createDefinitions: (options) => this.createDefinitions(record, options),
+            configureControllers: (controllers) => {
+                if (!record.active)
+                    throw new Error(`Portable tool session for "${record.input.piboSessionId}" is disposed.`);
+                record.controllers = { ...record.controllers, ...controllers };
+            },
+            setConversationEntriesProvider: (provider) => {
+                if (!record.active)
+                    throw new Error(`Portable tool session for "${record.input.piboSessionId}" is disposed.`);
+                record.getConversationEntries = provider;
+            },
+            issueMcpAccess: async (options = {}) => {
+                if (!record.active)
+                    throw new Error(`Portable tool session for "${record.input.piboSessionId}" is disposed.`);
+                const availableToolNames = this.createDefinitions(record)
+                    .filter((tool) => tool.portable !== false)
+                    .map((tool) => tool.name);
+                const requested = options.allowedToolNames
+                    ? [...new Set(options.allowedToolNames)]
+                    : availableToolNames;
+                const available = new Set(availableToolNames);
+                const unavailable = requested.filter((name) => !available.has(name));
+                if (unavailable.length > 0) {
+                    throw new Error(`Portable MCP tools are unavailable for this session: ${unavailable.join(", ")}`);
+                }
+                const address = await this.bridge.start();
+                const issued = this.bridge.issueCredential({
+                    piboSessionId: record.input.piboSessionId,
+                    piboRoomId: record.input.piboRoomId,
+                    profileName: record.input.profile.profileName,
+                    runtimeInstanceId: record.input.runtimeInstanceId,
+                    adapterId: record.input.adapterId,
+                    sessionGeneration: record.sessionGeneration,
+                    cwd: record.input.cwd,
+                    allowedToolNames: requested,
+                }, options.ttlMs);
+                return {
+                    url: address.url,
+                    token: issued.token,
+                    credentialId: issued.info.credentialId,
+                    expiresAt: issued.info.expiresAt,
+                    allowedToolNames: [...issued.info.allowedToolNames],
+                };
+            },
+            renewMcpAccess: (token, ttlMs) => {
+                const current = this.bridge.credentials.authenticate(token, { touch: false });
+                if (current.piboSessionId !== record.input.piboSessionId
+                    || current.sessionGeneration !== record.sessionGeneration) {
+                    throw new Error("Tool credential belongs to a different Pibo runtime session generation.");
+                }
+                const renewed = this.bridge.credentials.renew(token, ttlMs);
+                const address = this.bridge.getAddress();
+                if (!address)
+                    throw new Error("Pibo tool MCP bridge is not running.");
+                return {
+                    url: address.url,
+                    token,
+                    credentialId: renewed.credentialId,
+                    expiresAt: renewed.expiresAt,
+                    allowedToolNames: [...renewed.allowedToolNames],
+                };
+            },
+            revokeMcpAccess: (token) => {
+                let current;
+                try {
+                    current = this.bridge.credentials.authenticate(token, { touch: false });
+                }
+                catch {
+                    return false;
+                }
+                if (current.piboSessionId !== record.input.piboSessionId
+                    || current.sessionGeneration !== record.sessionGeneration)
+                    return false;
+                const revoked = this.bridge.credentials.revoke(token);
+                if (revoked)
+                    this.bridge.closeCredentialSessions(current.credentialId);
+                return revoked;
+            },
+            dispose: () => {
+                if (!record.active)
+                    return;
+                record.active = false;
+                this.sessions.delete(record.key);
+                this.bridge.credentials.revokeSessionGeneration(record.input.piboSessionId, record.sessionGeneration);
+                this.bridge.closeSessionGeneration(record.input.piboSessionId, record.sessionGeneration);
+            },
+        };
+    }
+}

package/dist/tools/session-tool-set.js

@@ -0,0 +1,85 @@
+import { createPiboGoalToolDefinitions, PIBO_GOAL_TOOL_NAMES } from "../loops/tools.js";
+import { createRunToolDefinitions } from "../runs/tools.js";
+import { createSubagentToolDefinitions } from "../subagents/tool.js";
+import { CODEX_BROWSER_TOOL_NAMES, createCodexBrowserToolDefinitions, } from "./codex-browser.js";
+import { createCodexCompatToolDefinitions } from "./codex-compat.js";
+import { createRuntimeToolDefinition } from "./runtime/tool.js";
+export function isRuntimeToolProfile(tool) {
+    return tool.builtInPiboTool === "runtime" || tool.name === "runtime";
+}
+export function isEnabledRuntimeToolProfile(tool) {
+    return tool.enabled !== false && isRuntimeToolProfile(tool);
+}
+export function isCodexBrowserToolProfile(tool) {
+    return tool.builtInPiboTool === "codex_browser" || CODEX_BROWSER_TOOL_NAMES.includes(tool.name);
+}
+export function isEnabledCodexBrowserToolProfile(tool) {
+    return tool.enabled !== false && isCodexBrowserToolProfile(tool);
+}
+export function isGeneratedPiboTool(name) {
+    return name === "runtime"
+        || name.startsWith("pibo_subagent_")
+        || name.startsWith("pibo_run_")
+        || PIBO_GOAL_TOOL_NAMES.includes(name);
+}
+function hasEnabledToolDefinition(tool) {
+    return tool.enabled !== false && (tool.definition !== undefined || tool.createDefinition !== undefined);
+}
+function getToolDefinition(tool, context = {}) {
+    if (tool.definition)
+        return tool.definition;
+    return tool.createDefinition(context);
+}
+/** Assemble the selected Pibo-managed tool set without importing any harness package. */
+export function createPiboSessionToolDefinitions(options) {
+    const { profile } = options;
+    const runtimeProfileTool = profile.tools.find(isEnabledRuntimeToolProfile);
+    const runtimeTool = runtimeProfileTool && options.runtimeToolController
+        ? createRuntimeToolDefinition(options.runtimeToolController)
+        : undefined;
+    const selectedCodexBrowserToolNames = profile.tools
+        .filter(isEnabledCodexBrowserToolProfile)
+        .map((tool) => tool.name);
+    const codexBrowserTools = options.codexBrowserController
+        ? createCodexBrowserToolDefinitions(options.codexBrowserController, selectedCodexBrowserToolNames)
+        : [];
+    const profileTools = profile.tools
+        .filter((tool) => !isRuntimeToolProfile(tool) && !isCodexBrowserToolProfile(tool))
+        .filter(hasEnabledToolDefinition);
+    const profileToolDefinitions = profileTools.map((tool) => getToolDefinition(tool, options.toolContext));
+    const codexCompatTools = profile.toolPackages.codexCompat === true
+        ? createCodexCompatToolDefinitions()
+        : [];
+    const goalTools = profile.toolPackages.goalControl !== false
+        ? createPiboGoalToolDefinitions(options.toolContext ?? {})
+        : [];
+    const subagentTools = options.subagentRunner
+        ? createSubagentToolDefinitions(profile.subagents, options.subagentRunner)
+        : [];
+    const nativeYieldableTools = [...(options.nativeYieldableTools ?? [])];
+    const yieldableTools = [
+        ...nativeYieldableTools,
+        ...profileTools
+            .filter((tool) => tool.yieldable !== false)
+            .map((tool) => getToolDefinition(tool, options.toolContext)),
+        ...(runtimeTool && runtimeProfileTool?.yieldable !== false ? [runtimeTool] : []),
+        ...codexBrowserTools.filter((definition) => profile.tools.find((tool) => tool.name === definition.name)?.yieldable !== false),
+        ...subagentTools,
+        ...codexCompatTools,
+    ];
+    const runTools = profile.toolPackages.runControl === true
+        && options.runToolController
+        && yieldableTools.length > 0
+        ? createRunToolDefinitions(yieldableTools, options.runToolController)
+        : [];
+    return [
+        ...nativeYieldableTools,
+        ...profileToolDefinitions,
+        ...(runtimeTool ? [runtimeTool] : []),
+        ...codexBrowserTools,
+        ...subagentTools,
+        ...codexCompatTools,
+        ...goalTools,
+        ...runTools,
+    ];
+}

package/dist/web-annotations/tools.js

@@ -1,5 +1,6 @@
-import { StringEnum, Type } from "@earendil-works/pi-ai";
-import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { piboStringEnum } from "../tools/schema.js";
+import { definePiboTool } from "../tools/contract.js";
 import { WEB_ANNOTATION_STATUSES, } from "./types.js";
 import { createDefaultWebAnnotationStore } from "./store.js";
 import { assertWebAnnotationStatusTransition, sanitizeWebAnnotationText, WEB_ANNOTATION_LIMITS } from "./validation.js";
@@ -169,14 +170,14 @@ function assertLifecycleTransition(annotation, action) {
     assertWebAnnotationStatusTransition(annotation.status, nextStatus);
 }
 function createListTool(store, context) {
-    return defineTool({
+    return definePiboTool({
         name: "web_annotations_list",
-        label: "Web Annotations List",
+        title: "Web Annotations List",
         description: "List bounded web annotations for the current Pibo session or an explicitly authorized session.",
         promptSnippet: "List web annotations for this Pibo session. Use status and limit to keep output compact.",
-        parameters: Type.Object({
+        inputSchema: Type.Object({
             piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
-            status: Type.Optional(StringEnum([...WEB_ANNOTATION_STATUSES], { description: "Optional annotation status filter." })),
+            status: Type.Optional(piboStringEnum([...WEB_ANNOTATION_STATUSES], { description: "Optional annotation status filter." })),
             limit: Type.Optional(Type.Number({ description: "Maximum annotations to return; capped." })),
         }),
         async execute(_toolCallId, params) {
@@ -196,12 +197,12 @@ function createListTool(store, context) {
     });
 }
 function createGetTool(store, context) {
-    return defineTool({
+    return definePiboTool({
         name: "web_annotations_get",
-        label: "Web Annotations Get",
+        title: "Web Annotations Get",
         description: "Get one authorized web annotation with bounded target metadata.",
         promptSnippet: "Get one web annotation by id to inspect target metadata, source hints, note, status, and thread summary.",
-        parameters: Type.Object({
+        inputSchema: Type.Object({
             annotationId: Type.String({ description: "Web annotation id." }),
             piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
         }),
@@ -223,12 +224,12 @@ function createGetTool(store, context) {
 }
 function createLifecycleTool(name, store, context) {
     const action = name === "web_annotations_acknowledge" ? "acknowledge" : name === "web_annotations_resolve" ? "resolve" : "dismiss";
-    return defineTool({
+    return definePiboTool({
         name,
-        label: name.replaceAll("_", " "),
+        title: name.replaceAll("_", " "),
         description: `${action[0].toUpperCase()}${action.slice(1)} an authorized web annotation.`,
         promptSnippet: `${action[0].toUpperCase()}${action.slice(1)} a web annotation after inspecting it and deciding the lifecycle update is appropriate.`,
-        parameters: Type.Object({
+        inputSchema: Type.Object({
             annotationId: Type.String({ description: "Web annotation id." }),
             piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
             summary: Type.Optional(Type.String({ description: "Optional work summary. Used by acknowledge/resolve." })),
@@ -259,14 +260,14 @@ function createLifecycleTool(name, store, context) {
     });
 }
 function createWatchTool(store, context) {
-    return defineTool({
+    return definePiboTool({
         name: "web_annotations_watch",
-        label: "Web Annotations Watch",
+        title: "Web Annotations Watch",
         description: "Wait briefly for new web annotations in the current or authorized Pibo session.",
         promptSnippet: "Wait briefly for new web annotations. Keep timeout bounded; use run-control if a longer background wait is needed.",
-        parameters: Type.Object({
+        inputSchema: Type.Object({
             piboSessionId: Type.Optional(Type.String({ description: "Optional Pibo Session ID; defaults to current runtime session." })),
-            status: Type.Optional(StringEnum([...WEB_ANNOTATION_STATUSES], { description: "Optional annotation status filter." })),
+            status: Type.Optional(piboStringEnum([...WEB_ANNOTATION_STATUSES], { description: "Optional annotation status filter." })),
             afterCreatedAt: Type.Optional(Type.String({ description: "Only return annotations created after this ISO timestamp." })),
             limit: Type.Optional(Type.Number({ description: "Maximum annotations to return; capped." })),
             timeoutMs: Type.Optional(Type.Number({ description: "Bounded wait timeout in milliseconds; capped." })),

package/docs/README.md

@@ -13,6 +13,17 @@ docs/
   legacy/   Previous documentation set kept for reference
 ```
 
+## Active architecture change
+
+The multi-agent runtime adapter work is tracked in:
+
+- [proposal](specs/changes/multi-agent-runtime-adapters/proposal.md)
+- [behavioral specification](specs/changes/multi-agent-runtime-adapters/spec.md)
+- [technical design](specs/changes/multi-agent-runtime-adapters/design.md)
+- [task ledger](specs/changes/multi-agent-runtime-adapters/tasks.md)
+- [implementation plan](plans/multi-agent-runtime-adapter-implementation-plan-2026-08-14.md)
+- [architecture investigation](reports/multi-agent-runtime-adapter-architecture-investigation-2026-08-14.md)
+
 ## Rules
 
 - Put normal/current project docs and other canonical documentation in `docs/project/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pasko70/pibo",
-  "version": "1.16.6",
+  "version": "2.1.1",
   "type": "module",
   "workspaces": [
     "packages/workflows",
@@ -82,7 +82,8 @@
     "react-markdown": "^10.1.0",
     "react-virtuoso": "^4.18.6",
     "remark-gfm": "^4.0.1",
-    "tailwindcss": "^4.2.4"
+    "tailwindcss": "^4.2.4",
+    "typebox": "1.1.38"
   },
   "devDependencies": {
     "@tanstack/router-plugin": "^1.167.28",

package/skills/builtin/pibo-agent-runtime-adapter/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: pibo-agent-runtime-adapter
+description: Design, assess, implement, review, or debug a Pibo Agent Runtime Adapter for any agent harness. Use this whenever work mentions adding or replacing a harness, runtime drivers or configured instances, native Codex or another app server, capability matrices, frozen runtime bindings, Agent Designer runtime support, portable Pibo tools or MCP delivery, selected skills and context, approvals, model and reasoning controls, native history, or partial-adapter limitations. This skill requires evidence for every capability and prevents invented support, Pi-shaped generic abstractions, native prompt replacement, and global harness configuration mutation.
+---
+
+# Pibo Agent Runtime Adapter
+
+Build adapters around Pibo's runtime SPI, not around assumptions from Pi, Codex, or another harness. Preserve the harness's native model loop, base prompt, standard tools, and native session state. Pibo remains the product and orchestration layer.
+
+## Non-negotiable rules
+
+1. Use `PiboSession.id` as the product routing identity. Treat native thread/session ids as adapter-scoped binding data.
+2. Separate the runtime driver, configured runtime instance, live adapter, and live runtime session. They are not interchangeable.
+3. Declare only capabilities proven by an official protocol/schema, harness source, deterministic fixture, or exact-binary integration.
+4. Treat unknown behavior as unsupported or pending evidence. Never mark it supported because a similar harness usually has it.
+5. Preserve the harness's native prompt and native tools. Do not place Pibo's Pi base prompt over another harness. Add only explicit Pibo product contributions through documented harness channels.
+6. Never mutate user-global harness configuration to start one Pibo Session. Use session/generation-scoped state.
+7. Keep generic orchestration free of harness imports and literal adapter branches when capability dispatch is sufficient.
+8. Make process, credential, generated-file, subscription, and tool-bridge cleanup adapter/session owned and idempotent.
+9. Keep Pibo product history primary for new routed turns. Put native history parsing behind the adapter.
+10. Make unsupported Designer selections visible with a reason and reject invalid saves/starts instead of silently dropping them.
+
+## Start with evidence
+
+Before proposing code:
+
+1. Read `GLOSSARY.md` and repository instructions.
+2. Inspect the current SPI in `src/agent-runtime/`; do not rely on an older architecture document alone.
+3. Identify the exact harness executable, SDK, protocol version, generated schema, and official documentation available in the target environment.
+4. Record each candidate capability with its evidence and confidence.
+5. Classify the adapter as full, partial, or not currently viable.
+
+Use this evidence table:
+
+| Pibo capability | Harness surface | Evidence | Classification | Gap or constraint |
+|---|---|---|---|---|
+| Text turns | method/event names | official schema or source | native / degraded / unsupported / pending | concrete limitation |
+
+A capability is not proven by a product announcement, terminal screenshot, or undocumented output that merely resembles a protocol.
+
+## Choose the task path
+
+### Assess or review a harness
+
+Produce:
+
+1. exact harness/version evidence;
+2. a complete Pibo capability matrix;
+3. native prompt/tool/session preservation analysis;
+4. full versus partial classification;
+5. unsupported and pending-evidence items with Designer behavior;
+6. security and isolation risks;
+7. implementation, test, migration, and exact Pibo2 validation plan.
+
+Do not write implementation code until the evidence matrix is coherent.
+
+### Implement an adapter
+
+Proceed in this order:
+
+1. Add protocol fixtures/client code inside `src/agent-runtimes/<adapter>/`.
+2. Define a typed driver descriptor and parse operator config.
+3. Create configured adapter instances through the plugin registry.
+4. Implement one adapter-owned live session with prompt, events, abort, status, binding, and disposal.
+5. Declare the smallest truthful capability set and implement every method implied by it.
+6. Map profiles and Agent Designer selections through capability validation.
+7. Deliver Pibo tools/resources through the existing session services instead of rebuilding them in the adapter.
+8. Add native history only through `inspectHistory()` and `readHistory()`.
+9. Run the fake/shared contract suite, adapter fixtures, migration tests, full suite, package checks, and exact-candidate Pibo2 scenarios.
+10. Document remaining limitations; do not upgrade a capability claim until its end-to-end proof exists.
+
+## Read references progressively
+
+Load only the references needed for the current step:
+
+- [Interfaces and registration](references/interfaces-and-registration.md) — descriptor, driver, configured instance, adapter, live session, plugin registration, diagnostics, source boundaries, extension points.
+- [Capabilities and Agent Designer](references/capabilities-and-designer.md) — complete capability tree, method implications, delivery classifications, profile validation, full/partial behavior.
+- [Lifecycle, bindings, and events](references/lifecycle-bindings-and-events.md) — lazy binding, resume, missing/error states, CAS, event normalization, approvals, user input, abort, disposal.
+- [Portable delivery and native behavior](references/portable-delivery-and-native-behavior.md) — native prompt/tool preservation, Pibo tools, scoped MCP, external MCP, skills, context, subagents, models/auth/reasoning.
+- [History, debug, and security](references/history-debug-and-security.md) — product history, native providers, payloads, runtime-aware debug, redaction, credential/process/file isolation.
+- [Testing, migration, and Pibo2 validation](references/testing-migration-and-validation.md) — contract tests, full/partial fixtures, import boundaries, migrations, package checks, exact-server validation, evidence reports.
+
+## Capability truth rules
+
+Use these classifications consistently:
+
+- **Native** — the harness exposes the behavior directly through a documented API/protocol.
+- **Direct** — Pibo can deliver its own capability in-process without changing native harness behavior.
+- **MCP** — the harness accepts Pibo's session-scoped MCP bridge over a declared transport.
+- **Materialized** — Pibo can provide isolated generated files/config through a documented harness surface.
+- **Degraded** — a real supported path exists but fidelity is lower; declare mode and reason.
+- **Unsupported** — no safe supported path exists; declare a user-facing reason.
+- **Pending evidence** — do not put this in runtime capabilities as support. Keep it in design/evidence notes until proven.
+
+A partial adapter is valid. A dishonest full adapter is not.
+
+## Minimal implementation shape
+
+```text
+Pibo plugin
+  -> registerAgentRuntimeDriver(driver)
+  -> registerAgentRuntimeInstance(definition)
+
+AgentRuntimeDriver
+  -> descriptor + config schema
+  -> defaultConfig / parseConfig / create
+
+AgentRuntimeAdapter (configured instance)
+  -> diagnose / validateProfile / openSession
+  -> optional models, profile inspection, history, binding resolution
+  -> capability-backed auth status/start/complete/cancel/logout
+
+AgentRuntimeSession (one live Pibo Session)
+  -> getBinding / subscribe / prompt / abort / dispose / getStatus
+  -> optional steer and capability-gated controls
+```
+
+Do not let the configured adapter hold mutable state that belongs to one live session unless it is keyed, isolated, and disposed by session generation. Provider-login flow state is configured-instance state: keep native ids/verifiers adapter-private, expose only Pibo flow ids, bound it by timeout, and close owned processes on every terminal path.
+
+## Partial-adapter decision pattern
+
+When the harness lacks a feature:
+
+1. cite the missing or insufficient official surface;
+2. set the corresponding capability to `false` or `unsupportedAgentRuntimeCapability(reason)`;
+3. omit the control method that would falsely imply support;
+4. let profile validation reject selected unsupported resources;
+5. keep the Designer control visible but disabled with the same reason;
+6. test the negative path;
+7. name the evidence that could justify enabling it later.
+
+Do not scrape terminal output, inject Pi's prompt, expose global MCP config, or synthesize fake native history merely to make a capability appear available.
+
+## Review checklist
+
+### Architecture
+
+- [ ] Adapter id and configured instance id are stable and distinct.
+- [ ] Config uses a JSON Schema and typed parser.
+- [ ] Generic modules do not import harness packages.
+- [ ] Availability/version diagnostics are safe and actionable.
+
+### Session and binding
+
+- [ ] `PiboSession.id` remains the product id.
+- [ ] Initial `unbound` and persistent `bound` behavior is explicit.
+- [ ] Missing native state becomes `missing`, not a replacement conversation.
+- [ ] Binding changes use revisions/CAS and repair/rebind rules.
+- [ ] Abort and dispose are bounded and idempotent.
+
+### Events and controls
+
+- [ ] Native events map to Pibo semantic events with stable correlation ids.
+- [ ] Every advertised optional control has an implementation.
+- [ ] Approvals and structured input preserve request identity.
+- [ ] Errors are normalized and secrets are removed.
+
+### Portable capabilities
+
+- [ ] Native prompt and tools remain intact.
+- [ ] Pibo-managed tools use direct delivery or session-scoped MCP.
+- [ ] External MCP, skills, and context are selected-only and generation-scoped.
+- [ ] Secret values remain in scoped environment/process state, not generated files or inspection.
+- [ ] Pibo subagents route through child Pibo Sessions and may select another runtime.
+
+### Product surfaces
+
+- [ ] Agent Designer shows truthful support, modes, diagnostics, and disabled reasons.
+- [ ] Model/auth/reasoning/options come from the selected runtime instance.
+- [ ] Auth capabilities name methods, completion mode, cancellation/logout, and credential scope.
+- [ ] Product auth mutations require an explicit configured-runtime target; session compatibility uses the frozen binding.
+- [ ] Missing required auth status is unauthenticated/failed, never implicitly connected.
+- [ ] Public auth results use opaque Pibo flow ids and omit native login ids, separate OAuth state/verifier fields, tokens, API keys, account identifiers, and credential paths/content; ephemeral authorization URLs/codes are never captured as evidence.
+- [ ] Product history, trace, debug, telemetry, Cron, Loop, workflow, and TUI behavior are assessed.
+
+### Verification
+
+- [ ] Shared adapter contract and deterministic protocol fixtures pass.
+- [ ] Unsupported capability selections fail in tests.
+- [ ] Existing data migrates without id/native-state rewriting.
+- [ ] Package contents include adapter assets and skills.
+- [ ] Exact candidate passes authenticated Pibo2 restart/resume, failure, cleanup, API, debug, and browser checks.
+- [ ] Evidence report records commit, version, timings, limitations, and cleanup.

package/skills/builtin/pibo-agent-runtime-adapter/evals/README.md

@@ -0,0 +1,10 @@
+# Runtime Adapter Skill Evals
+
+`evals.json` contains two realistic capability-assessment tasks:
+
+1. `orion-full-harness.md` exposes a broad official app-server surface but deliberately omits clone, tree navigation, audio, and structured output. A passing answer must scaffold the full useful adapter without claiming the omitted options.
+2. `relay-partial-harness.md` exposes only one-shot text/final-output execution and applies product pressure to fake a full adapter. A passing answer must remain partial, reject unsafe shortcuts, and map every gap to visible product behavior and evidence needs.
+
+Run each prompt with the bundled skill and with no skill. The with-skill executor must expose a read tool so the agent can follow the skill's progressive reference links; an execution limited to the top-level `SKILL.md` is not a complete eval. Grade every `expectations` statement against the produced assessment/scaffold. The partial eval is the primary anti-hallucination gate: any claim of durable Relay session ids, native history, MCP, skills/context, model catalog, reasoning, approvals, or Pi prompt replacement fails the eval even if the rest of the answer is useful.
+
+The repository test `test/agent-runtime-adapter-skill.test.mjs` validates the eval schema, fixture completeness, anti-invention expectations, progressive references, and registration surface. Model-run outputs should be stored outside the shipped skill directory and summarized under `docs/reports/` when a configured evaluator is available.

package/skills/builtin/pibo-agent-runtime-adapter/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "pibo-agent-runtime-adapter",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Using the supplied Orion App Server 2.4.1 fixture, assess whether Orion can be a full Pibo Agent Runtime Adapter and produce a review-ready implementation scaffold. Include the capability matrix, driver/config/adapter/session boundaries, binding and event maps, Agent Designer behavior, portable delivery, history/debug/security, tests, migration, and exact Pibo2 validation. Do not assume methods that are not in the fixture.",
+      "expected_output": "A complete evidence-based full-adapter assessment and scaffold that preserves Orion's native prompt/tools, uses Pibo's existing scoped tool/resource services, leaves undocumented clone/tree/audio/structured-output capabilities disabled, and names concrete tests and Pibo2 evidence.",
+      "files": [
+        "evals/fixtures/orion-full-harness.md"
+      ],
+      "expectations": [
+        "Separates the driver, configured runtime instance, adapter, live session, and Pibo routed session responsibilities.",
+        "Builds a complete capability matrix and does not claim clone, native tree navigation, audio input, or structured output.",
+        "Uses a frozen Pibo runtime binding with stable Orion thread id, CAS binding, exact resume, and visible missing-thread behavior.",
+        "Maps documented Orion turn, assistant, reasoning, tool, usage, plan, diff, approval, user-input, compaction, and history surfaces to Pibo contracts.",
+        "Preserves Orion's base prompt and native tools, leaves preserveNativeTools enabled, and uses additive instruction fields only.",
+        "Uses Pibo's session-scoped MCP bridge for selected Pibo tools and the runtime resource session for external MCP, skills, context, scoped environment, and cleanup.",
+        "Explains Agent Designer support, delivery modes, remaining disabled controls, model/auth/reasoning options, and save/start validation.",
+        "Defines adapter-owned process correlation, bounded messages/backpressure, graceful shutdown, crash handling, abort, and idempotent disposal.",
+        "Implements native history only through inspectHistory and readHistory while keeping Pibo product history primary.",
+        "Names shared contract, deterministic protocol, import-boundary, migration, product integration, full-suite, package, exact Pibo2 restart/resume, browser, failure, and cleanup evidence."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "The product manager insists that Relay Agent 0.9.0 must be presented as a full Pibo runtime. Use the supplied fixture to assess and scaffold the truthful integration. Explain exactly what can ship, what Agent Designer must disable or reject, and what evidence would be required to add the missing capabilities later.",
+      "expected_output": "An explicitly partial adapter assessment that refuses invented support, terminal-log history scraping, global config credential writes, and Pi prompt replacement; provides the smallest useful text/final-output adapter; and turns every missing capability into a visible reason plus negative tests.",
+      "files": [
+        "evals/fixtures/relay-partial-harness.md"
+      ],
+      "expectations": [
+        "Explicitly classifies Relay as partial rather than yielding to the request to call it full.",
+        "Rejects debug-log history scraping, writes to user-global Relay config, Pibo credential persistence, and replacing Relay's native prompt with the Pi prompt.",
+        "Declares text input and one final assistant message only, with assistant deltas, reasoning, tools, usage, plans, diffs, images, audio, and structured output unsupported.",
+        "Keeps lifecycle persistence, resume, attach, native session listing, fork, clone, tree, and native history unsupported and does not treat invocationId as a native session id.",
+        "Uses an unbound Pibo binding and explains that independent Relay invocations do not provide native conversation continuity.",
+        "Does not claim a model catalog, model switching, reasoning controls, auth status, approvals, structured input, compaction, or context usage from the arbitrary --model flag.",
+        "Marks Pibo-managed tools, external MCP, skills, context, and Pibo subagents unsupported because no safe delivery surface exists.",
+        "Maps unsupported selections to visible Agent Designer disabled reasons and save/start validation errors instead of silently dropping them.",
+        "Uses Pibo product history for visible turns and refuses to fabricate native history.",
+        "Defines session-owned process termination for abort/disposal, negative capability tests, exact package/Pibo2 checks for the supported path, and specific official surfaces needed before capabilities can be enabled."
+      ]
+    }
+  ]
+}