@pasko70/pibo 1.16.6 → 2.0.0

package/skills/builtin/pibo-agent-runtime-adapter/references/interfaces-and-registration.md

@@ -0,0 +1,214 @@
+# Interfaces and Registration
+
+Use this reference when creating the runtime driver, configured adapter instance, live session, plugin registration, or import-boundary plan.
+
+## Current source map
+
+Read the implementation before copying a pattern:
+
+- `src/agent-runtime/types.ts` — descriptor, driver, adapter, open input, session, controls, status, models/auth, diagnostics.
+- `src/agent-runtime/capabilities.ts` — complete capability shape and consistency validation.
+- `src/agent-runtime/registry.ts` — id/config/instance registration, diagnostics, model/auth inspection, history-provider enforcement, session contract enforcement.
+- `src/agent-runtime/contract.ts` — live session methods implied by advertised capabilities.
+- `src/agent-runtime/testing/fake-adapter.ts` — deterministic minimal adapter.
+- `src/agent-runtime/testing/contract.ts` — reusable lifecycle/prompt/event/abort/disposal contract.
+- `src/plugins/types.ts` and `src/plugins/registry.ts` — plugin-facing registration and capability catalog.
+- `src/agent-runtimes/pi/adapter.ts` — compatibility-rich embedded adapter example, not a generic template.
+- `test/agent-runtime-boundaries.test.mjs` — import rules.
+
+## Four distinct layers
+
+### Driver
+
+The driver describes one adapter type and creates configured instances. It owns:
+
+- stable adapter id;
+- display name and transport;
+- operator config JSON Schema;
+- declared capabilities;
+- protocol name/range;
+- default config and config parsing;
+- configured adapter construction.
+
+The driver is registration-time state, not one live conversation.
+
+### Configured adapter instance
+
+An `AgentRuntimeAdapter` represents one named operator configuration such as `codex-native`, `codex-work`, or `remote-orion`. It owns:
+
+- parsed config;
+- enabled state;
+- availability/version diagnostics;
+- profile validation;
+- optional model/auth/profile/history/binding inspection;
+- creation of isolated live sessions.
+
+Do not put one session's process, subscription, current thread, credential, or generated directory in unkeyed adapter fields.
+
+### Live runtime session
+
+An `AgentRuntimeSession` represents one active Pibo Session generation. It owns:
+
+- native process/client/thread handle;
+- current frozen binding;
+- subscriptions and correlation maps;
+- prompt/steer/abort behavior;
+- pending approval/input requests;
+- generated configuration and credentials supplied by Pibo services;
+- idempotent disposal.
+
+### Pibo routed session
+
+`RuntimeRoutedSession` is product orchestration. It owns queues, active-message correlation, Pibo event distribution, controls dispatch, continuation policy, and product actions. Do not move harness protocol code into it.
+
+## Driver skeleton
+
+Adapt this shape; do not copy unsupported capabilities from another adapter.
+
+```ts
+import type {
+  AgentRuntimeAdapter,
+  AgentRuntimeCapabilities,
+  AgentRuntimeDriver,
+  AgentRuntimeDriverCreateInput,
+  PiboJsonObject,
+} from "@pasko70/pibo";
+
+type OrionConfig = PiboJsonObject & {
+  executable: string;
+  startupTimeoutMs: number;
+};
+
+const capabilities: AgentRuntimeCapabilities = /* evidence-based matrix */;
+
+export const ORION_RUNTIME_DRIVER: AgentRuntimeDriver<OrionConfig> = {
+  descriptor: {
+    id: "orion",
+    displayName: "Orion App Server",
+    transport: "stdio-rpc",
+    configSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        executable: { type: "string", minLength: 1 },
+        startupTimeoutMs: { type: "integer", minimum: 1000 },
+      },
+      required: ["executable", "startupTimeoutMs"],
+    },
+    capabilities,
+    protocol: { name: "orion-app-server", supportedRange: ">=2.4 <3" },
+    supportsMultipleInstances: true,
+  },
+  defaultConfig() {
+    return { executable: "orion", startupTimeoutMs: 15_000 };
+  },
+  parseConfig(value) {
+    // Validate every field and reject unknown/unsafe values.
+    return parseOrionConfig(value);
+  },
+  create(input: AgentRuntimeDriverCreateInput<OrionConfig>): AgentRuntimeAdapter {
+    return new OrionAgentRuntimeAdapter(input, capabilities);
+  },
+};
+```
+
+The registry validates descriptor ids and the capability object. It clones raw config, calls `parseConfig()`, and verifies that the created adapter reports the requested instance and adapter ids.
+
+## Plugin registration
+
+Register the driver before instances:
+
+```ts
+export const orionPlugin = definePiboPlugin({
+  id: "pibo.runtime.orion",
+  name: "Orion Runtime",
+  register(api) {
+    api.registerAgentRuntimeDriver(ORION_RUNTIME_DRIVER);
+    api.registerAgentRuntimeInstance({
+      id: "orion-native",
+      adapterId: "orion",
+      displayName: "Orion Native",
+      enabled: true,
+      config: { executable: "orion", startupTimeoutMs: 15_000 },
+    });
+  },
+});
+```
+
+A profile selects the configured instance id, not the adapter id. Existing sessions keep their frozen binding when a profile default changes.
+
+Do not claim a compatibility alias owned by another profile. Native Codex, for example, uses `codex-native`; it does not reinterpret a persisted Pi-backed `codex` reference.
+
+## Adapter required methods
+
+Every configured adapter implements:
+
+- `diagnose()` — bounded availability/version/config diagnostics;
+- `validateProfile()` — adapter-specific profile diagnostics;
+- `openSession()` — creates one isolated live session.
+
+Optional methods are capability-driven:
+
+- `inspectProfile()` for delivery/fidelity inspection;
+- `listModels()` when `models.catalog` is true;
+- `getAuthStatus()` for safe auth presence/status;
+- `inspectHistory()` and `readHistory()` together when `maintenance.history` is true;
+- `resolveBinding()` when native state needs adapter-owned verification/repair.
+
+Do not return raw stderr, process environment, token values, cookies, generated config contents, or locator values in general diagnostics.
+
+## Session required methods
+
+Every live session implements:
+
+- identity: `adapterId`, `runtimeInstanceId`, `cwd`;
+- `capabilities` matching actual live behavior;
+- `getBinding()`;
+- `subscribe()` with unsubscribe;
+- `prompt()`;
+- `abort()`;
+- `dispose()`;
+- `getStatus()`.
+
+`dispose()` must be safe to call twice. The registry's shared contract does this deliberately.
+
+Optional `steer()` and `controls` methods must agree with capabilities. `assertAgentRuntimeSessionContract()` rejects mismatches.
+
+## Diagnostics
+
+Use stable diagnostic codes and safe messages:
+
+```ts
+{
+  severity: "error",
+  code: "orion_executable_not_found",
+  message: "Orion executable is not available for runtime instance \"orion-native\".",
+  path: "config.executable"
+}
+```
+
+Prefer diagnostics over throwing for inspectable availability/profile problems. Throw for impossible construction, malformed protocol state, or an operation that cannot continue safely.
+
+## Extension-point map
+
+| Need | Extension point |
+|---|---|
+| New harness type | `AgentRuntimeDriver` |
+| Operator-specific config | `AgentRuntimeInstanceDefinition` |
+| Per-session native process/thread | `AgentRuntimeAdapter.openSession()` |
+| Runtime event stream | `AgentRuntimeSession.subscribe()` |
+| Optional controls | `AgentRuntimeControls` plus capability flags |
+| Model catalog | `AgentRuntimeAdapter.listModels()` |
+| Auth inspection | `AgentRuntimeAdapter.getAuthStatus()` |
+| Native history | `inspectHistory()` and `readHistory()` |
+| Binding verification | `resolveBinding()` |
+| Profile delivery inspection | `inspectProfile()` / resource inspection |
+| Pibo-managed tools | `input.services.portableTools` |
+| Selected skills/context/MCP | `input.services.resources` |
+| Contract fixtures | `src/agent-runtime/testing/` |
+
+## Import boundaries
+
+Generic code under `src/agent-runtime/`, routing, sessions, tools, data, trace, and debug may depend on Pibo-owned contracts. It must not import an adapter SDK or protocol package.
+
+Put harness code under `src/agent-runtimes/<adapter>/`. Compatibility facades must be narrow, documented, and allowlisted by architectural tests. Prefer dependency injection and capability dispatch over `if (adapterId === "...")`.

package/skills/builtin/pibo-agent-runtime-adapter/references/lifecycle-bindings-and-events.md

@@ -0,0 +1,193 @@
+# Lifecycle, Bindings, and Events
+
+Use this reference for native session creation/resume, persisted binding transitions, process ownership, event normalization, approvals, user input, abort, and cleanup.
+
+## Identity model
+
+Keep these identities separate:
+
+- **Pibo Session id** — stable `ps_...` product routing identity.
+- **Runtime instance id** — configured adapter instance selected and frozen for the Pibo Session.
+- **Adapter id** — harness integration type.
+- **Native session/thread id** — optional opaque harness id, unique within the adapter scope.
+- **Runtime session generation** — one live router lifecycle used for tool credentials and generated resources.
+- **Turn/message/tool ids** — per-operation correlation identities.
+
+Never route product APIs by a native id. Never assume a native id is a filesystem path.
+
+## Binding shape
+
+`RuntimeSessionBinding` contains:
+
+- `piboSessionId`;
+- `runtimeInstanceId`;
+- `adapterId`;
+- optional `nativeSessionId`;
+- state `unbound | bound | missing | error`;
+- optional protocol, protocol version, adapter version;
+- optional adapter-resolved locator and metadata;
+- revision and timestamps when persisted.
+
+Locator and metadata values are adapter/internal data. Product inspection should expose only safe fields, locator kind where explicitly needed, and metadata key names.
+
+## Binding states
+
+### `unbound`
+
+The Pibo Session is frozen to a runtime instance, but no durable native conversation is established. Use this for lazy native creation or harnesses without a durable native id.
+
+A live session contract rejects an `unbound` binding that exposes a native id.
+
+### `bound`
+
+A native conversation exists and must use the recorded id. A bound binding requires `nativeSessionId`.
+
+On resume, open that exact native state. Do not silently create a replacement if it is missing.
+
+### `missing`
+
+The binding expects native state, but the adapter cannot find or attach to it. Keep the Pibo Session and product history visible. Return a diagnostic and require explicit repair/rebind decisions.
+
+### `error`
+
+The native binding exists or was being established, but the adapter encountered a persistent binding/protocol error. Preserve diagnostic evidence without leaking secrets.
+
+## Transition and CAS rules
+
+Use the store's revisioned transition helpers:
+
+- initial bindings start at revision 1;
+- `unbound -> bound` requires the expected revision;
+- changing runtime instance or adapter requires `rebind` mode;
+- `missing/error -> bound` requires `repair` or `rebind` mode;
+- `bound -> unbound` requires `rebind` mode;
+- changing a bound native id requires `rebind` mode;
+- `bound` and `missing` require a native id.
+
+The adapter session returns its current binding through `getBinding()`. The router/store owns persistence and conflict handling. Do not let two concurrent native creations overwrite each other.
+
+## Open/resume algorithm
+
+A persistent adapter should follow this shape:
+
+1. Receive the frozen binding and workspace in `openSession()`.
+2. Validate binding adapter/instance identity.
+3. If `bound`, verify and resume the exact native id.
+4. If expected native state is absent, report `missing`; do not create a new native conversation.
+5. If `unbound` and lazy binding is supported, create native state at the documented point, usually open or first prompt.
+6. Produce the updated binding with protocol/version/locator metadata.
+7. Let the router persist it with the expected revision.
+8. Subscribe to native events only after correlation and cleanup structures exist.
+9. Return a session whose `getBinding()` always reflects current live state.
+
+For an empty native artifact that the harness legitimately deletes, distinguish disposable reservation state from durable conversation history. Do not mark it permanently expected until the harness has meaningful native history.
+
+## Restart behavior
+
+After gateway restart:
+
+- configured instances are recreated from operator config;
+- Pibo reloads the persisted binding;
+- the adapter resumes the same native id when supported;
+- generated tool/resource sessions receive a new live generation;
+- old credentials and generated directories are invalid/removed;
+- product history remains available even if native state is missing.
+
+Prove restart behavior using the exact installed package and real server path. Queue acceptance or an auth failure is not proof of resumed model behavior.
+
+## Adapter-owned process/client lifecycle
+
+For process-backed adapters:
+
+- spawn one process per adapter or session only when the protocol supports that ownership model;
+- keep stdout protocol and stderr diagnostics separate;
+- bound startup time and initialize handshake;
+- correlate every request/response id;
+- serialize or backpressure writes;
+- bound message sizes and pending requests;
+- reject malformed notifications safely;
+- handle process exit and protocol EOF exactly once;
+- terminate child processes on failed startup, abort escalation, disposal, and gateway shutdown;
+- avoid killing another session's shared process;
+- remove listeners/timers and settle pending promises on shutdown.
+
+Do not parse a human TUI stream as a protocol when an official app server exists.
+
+## Semantic event normalization
+
+Map native protocol notifications into `AgentRuntimeSemanticEvent` values:
+
+- turn lifecycle: `turn_started`, `turn_completed`, `turn_failed`;
+- adapter lifecycle: `starting`, `ready`, `restarting`, `stopped`, `crashed`;
+- assistant: `assistant_delta`, `assistant_message`;
+- reasoning: `reasoning_started`, `reasoning_delta`, `reasoning_finished`;
+- tools: call, execution start/update/finish;
+- usage, plans, diffs;
+- compaction start/end;
+- approval and structured user-input requests;
+- warnings/errors;
+- optional redacted `native_event` diagnostics.
+
+Preserve stable turn, content-index, tool-call, request, and native-entry identities. The routed session uses them to avoid duplicate output, nest trace nodes, persist product history, and route responses.
+
+## Event ordering rules
+
+- Emit `turn_started` before turn-scoped assistant/reasoning/tool events.
+- Emit one terminal `turn_completed` or `turn_failed` per accepted turn.
+- Keep assistant content indexes stable across deltas and final content.
+- Keep tool call ids stable across call/start/update/finish.
+- Do not emit a successful turn completion after a terminal failure.
+- Do not include credentials or unredacted provider bodies in `native_event`.
+- Treat duplicate, late, or post-disposal native events deterministically.
+
+Use deterministic protocol fixtures for out-of-order, duplicate, malformed, crash, and partial-stream cases.
+
+## Prompt and steering
+
+`prompt()` accepts `AgentRuntimePromptInput` with text, source, and optional capability scope. Set streaming state before sending the native request and settle it after the terminal event.
+
+Advertise `input.steering` only when the harness can modify an active turn through a supported operation. Implement `steer()` with the same correlation and cancellation rules. Queuing a second normal turn is not steering.
+
+## Approvals and structured user input
+
+When the harness requests approval:
+
+1. emit `approval_requested` with a stable request id and bounded arguments;
+2. set `pendingApproval`;
+3. expose `respondToApproval()` only when the capability is true;
+4. validate decisions against the native protocol;
+5. clear pending state exactly once after response/cancellation/failure.
+
+For structured input, preserve question ids, options, multi-select/freeform semantics, and request identity. Do not flatten a structured request into an uncorrelated chat message if the protocol expects a response method.
+
+## Errors
+
+Normalize errors by layer:
+
+- registration/config errors before instance creation;
+- availability/profile diagnostics during inspection;
+- binding missing/errors during open/resolve;
+- protocol/startup errors during live creation;
+- turn failures as semantic terminal events;
+- capability-unavailable errors for unsupported controls.
+
+Redact tokens, cookies, authorization headers, environment values, generated config contents, local locators, and raw provider request bodies. Preserve safe codes, phase, correlation id, exit status, and bounded stderr summaries.
+
+## Abort and disposal
+
+`abort()` cancels active work without disposing the reusable session when the harness supports it. It should be safe when idle.
+
+`dispose()` ends the live generation:
+
+- unsubscribe native listeners;
+- reject/settle pending requests;
+- abort active turns as required;
+- close native session/client/process according to ownership;
+- revoke Pibo tool MCP credentials;
+- dispose Pibo runtime resources;
+- remove generated files;
+- clear timers/maps;
+- emit no later product events;
+- succeed when called again.
+
+Test abort and dispose separately. Process death may implement abort only if the process is session-owned and the resulting native-session semantics are explicit.

package/skills/builtin/pibo-agent-runtime-adapter/references/portable-delivery-and-native-behavior.md

@@ -0,0 +1,226 @@
+# Portable Delivery and Native Behavior
+
+Use this reference when integrating Pibo-managed tools, external MCP, skills, context, subagents, models/auth/reasoning, or any harness configuration surface.
+
+## Preserve the harness first
+
+The harness owns:
+
+- native model loop;
+- base system prompt;
+- standard tools and their semantics;
+- native session/thread state;
+- native compaction, approvals, and user-input behavior where available;
+- protocol-specific resource discovery.
+
+Pibo owns product context, profile selections, Pibo-managed tools, subagents, jobs/loops/workflows, routing, data, debug, and UI.
+
+Do not place Pibo's Pi base prompt over another harness. Do not disable native tools just to make the harness resemble Pi. Do not rewrite global harness config to inject one Pibo Session's resources.
+
+## Open-session services
+
+`OpenAgentRuntimeSessionInput.services` may provide:
+
+- `portableTools` — one Pibo-owned tool session for the live generation;
+- `resources` — selected skills, ordered context, selected external MCP config, scoped environment, and delivery inspection;
+- subagent/run/runtime controllers through Pibo's router;
+- telemetry/compatibility services.
+
+Consume these services; do not recreate their selection, credential, payload, filesystem, or cleanup logic inside the adapter.
+
+The tool session and resource session share the same random runtime generation. Treat them as one disposable scope.
+
+## Pibo-managed tools
+
+Pibo tools use the harness-neutral `PiboToolDefinition` contract in `src/tools/contract.ts`:
+
+- TypeBox/JSON-Schema input;
+- optional structured output schema;
+- text/image content;
+- structured content and details;
+- cancellation and progress;
+- correlation metadata;
+- durable payload references for large results.
+
+### Direct delivery
+
+Use `{ support: "direct" }` only when the adapter can compile/call Pibo definitions in-process without requiring harness-private context. Pi uses a direct compiler under `src/agent-runtimes/pi/tool-compiler.ts`.
+
+Do not expose a legacy definition with `portable:false` outside its compatibility adapter.
+
+### MCP delivery
+
+Use MCP when the external harness supports an official MCP configuration or runtime API. The adapter obtains access from `services.portableTools.issueMcpAccess()`.
+
+The returned URL/token are sensitive session-owned process state:
+
+- keep the raw token only in memory or scoped process configuration;
+- never persist it in runtime bindings or Pibo data;
+- never print it in logs, diagnostics, Context Build, screenshots, or errors;
+- pass only the selected allowlisted tool names;
+- renew only within the existing scope;
+- revoke on disposal;
+- do not reuse an MCP transport session with another credential/session.
+
+Pibo's bridge is loopback Streamable HTTP, validates schemas, propagates cancellation/progress, supports text/images/structured content, and offloads large results. Do not build a second adapter-specific bridge.
+
+Account for the harness's native MCP approval policy. A server that connects and lists tools is not usable if every model-initiated call is silently rejected. When the product has already selected a Pibo-owned tool set and the credential independently enforces that exact session/generation/allowlist, an adapter may mark only that generated Pibo MCP server as pre-approved through an official harness setting. Do not apply the same policy globally or automatically to unrelated external MCP servers. Prove a model-initiated call, not only a direct protocol call.
+
+### Native tool yielding
+
+`tools.nativeToolYielding` is separate. `pibo_run_start` can yield Pibo-managed tool work. It cannot wrap a private native harness tool unless the adapter provides an explicit native-tool-yielding mechanism. Keep that limitation visible.
+
+## External MCP servers
+
+`services.resources` provides selected external MCP server configs and a generated selected-only configuration when the adapter advertises delivery.
+
+Use:
+
+- `getMcpConfigPath()` for materialized config;
+- `getExternalMcpServerConfigs()` only inside adapter-owned launch state;
+- `getAdapterEnvironment()` for scoped secret environment variables;
+- `getInspection()` for safe delivery and verified inventory.
+
+Requirements:
+
+- include only selected servers;
+- preserve transport and official harness config semantics;
+- bind secret-bearing literals/arguments through session-only environment references;
+- verify actual protocol initialization and tool/resource/template inventory;
+- report configured versus connected versus failed accurately;
+- do not mutate source MCP config or user-global harness config;
+- dispose child processes/config with the generation.
+
+A written config file is not proof of connection.
+
+## Skills
+
+`SKILL.md` remains Pibo's canonical skill format. The resource session exposes selected skill paths in source or materialized mode.
+
+Use native delivery when the harness accepts additional skill roots through an official API/config. Use materialized delivery when isolated directories are supported.
+
+Security/behavior rules:
+
+- only selected built-in, plugin, and user skills are present;
+- unselected skills never appear in adapter-visible roots;
+- preserve each selected skill directory and bundled resources;
+- reject escaping symlinks, cycles, excessive files, and excessive bytes;
+- do not point the harness at Pibo's global skill catalog;
+- report delivery mode, fidelity, target, status, and diagnostic.
+
+Do not claim skill support merely because arbitrary prompt text can be appended. If that is the only path and genuinely useful, classify it as degraded context with a reason, not native skill support.
+
+## Context contributions
+
+The resource session returns ordered context contributions with intent:
+
+- developer;
+- project;
+- session;
+- user-visible.
+
+Contributions may come from Pibo product context, managed/plugin context files, automatic project discovery, or generated state.
+
+Map them into documented harness channels without replacing the native base prompt. Preserve order and intended scope. Report fidelity:
+
+- `exact` — content and scope preserved;
+- `equivalent` — semantics preserved through an official but different channel;
+- `lossy` — real delivery with a documented loss;
+- `none` — unsupported or failed.
+
+Automatic AGENTS.md/CLAUDE.md discovery may be claimed for materialized adapters only when the adapter declares `native-project-discovery` and proves the harness discovers it in the isolated workspace/config.
+
+Never include resolved secret values in context or generated instructions.
+
+## Generated runtime paths
+
+Materialized state lives under a private generation tree similar to:
+
+```text
+$PIBO_HOME/agent-runtimes/<runtime-instance>/<pibo-session>/<generation>/
+  home/
+  skills/
+  context/
+  config/
+  protocol/
+```
+
+Directories are private and disposable. The adapter may add protocol files under its generation, but must not write outside the provided root unless the official harness requires another isolated path and the design documents it.
+
+Do not reuse a generation after session disposal or gateway restart.
+
+## Native prompt and tool checks
+
+Before and after integration, capture:
+
+- native system/developer prompt behavior;
+- native standard tool inventory;
+- native approval behavior;
+- native project-instruction discovery;
+- native session persistence.
+
+Add tests that fail if Pibo injects Pi-specific prompt text or removes native tools. A successful answer is not enough; inspect the actual protocol/config/tool inventory when available.
+
+## Models, auth, reasoning, and adapter options
+
+The selected configured runtime owns these surfaces:
+
+- `listModels()` returns only models valid for that runtime instance;
+- `models.optionsSchema` describes persisted adapter-native options;
+- reasoning values match exact harness values;
+- live model switching is advertised only when the native protocol supports it.
+
+Provider auth is an explicit configured-instance capability, not a global Pi service. Declare `capabilities.auth` with:
+
+- `status` support;
+- Pibo method ids (`device_code`, `browser_oauth`, or `api_key`) and each method's `immediate`, `explicit`, or `notification` completion mode;
+- cancellation and logout support;
+- credential scope: `runtime-instance` or `adapter-shared`.
+
+The capability declaration and methods must match exactly:
+
+- `getAuthStatus()` returns every known provider with connected, disconnected, pending, partial, unsupported, or failed state;
+- `startAuth()` starts only declared methods;
+- `completeAuth()` reads explicit/notification flow progress and terminal outcome;
+- `cancelAuth()` and `logoutAuth()` exist only when claimed;
+- `disposeAuth()` is required for non-immediate methods, closes pending adapter-owned processes/transient state, and leaves the configured adapter reusable after router restart.
+
+Use only Pibo-owned provider ids, method ids, status, flow, and result types at the boundary. Generate an opaque Pibo flow id and keep native login ids, separate OAuth state/verifier fields, account identifiers, and protocol payloads inside the adapter. An interactive flow may return only the bounded verification/authorization URL, optional one-time user code, bounded instructions, and Pibo flow metadata needed by the user; never persist that ephemeral URL/code in bindings, normalized product history, screenshots, or reports.
+
+Pibo product settings require an explicit configured-runtime target. A legacy session-bound action may target the active session's frozen runtime binding, but a random Pibo Session id must never be ignored or treated as global auth scope. Multiple configured instances may intentionally use different accounts. If the harness uses one existing shared store, declare `adapter-shared`, prevent conflicting same-provider flows across that scope, cancel scoped pending flows on logout, and recycle cached sessions for every affected instance rather than pretending the instances are isolated.
+
+Join model providers to auth status for the same runtime instance. If that runtime declares auth but status is missing or failed, never default models to authenticated. Keep models visible with disabled/missing-auth explanation when the product spec requires discoverability.
+
+Validate adapter options at save and start boundaries. Do not pass unknown arbitrary JSON to a process without schema validation and filtering.
+
+Never reuse Chat Web cookies, machine keys, Pibo tool tokens, another harness's auth, local OAuth files, or browser cookies as model-provider credentials. Never use unstable token-injection protocol variants merely because they appear in generated schemas. Tests must prove target routing, timeout/cancellation, restart persistence, same-adapter instance isolation where claimed, and redaction from events, bindings, logs, diagnostics, snapshots, and reports.
+
+## Pibo-managed subagents
+
+Subagents remain Pibo product orchestration:
+
+- a subagent tool creates or reuses a child Pibo Session using a bounded stable thread key;
+- the child profile selects and freezes its own configured runtime instance and binding;
+- parent and child may use different adapters;
+- hierarchy/correlation remains in Pibo data and events;
+- child tools/resources receive their own generation and credentials;
+- parent interruption and tool cancellation abort active child work without deleting the reusable child session;
+- `pibo_run_start` may yield selected Pibo subagent tools even when private harness-native tool yielding is unsupported.
+
+An adapter does not need native harness subagents to support Pibo-managed subagents. It does need a working Pibo-managed tool delivery path, model-call approval semantics that actually permit the selected Pibo tool, and restart/resume evidence for the parent and child bindings.
+
+Do not flatten a child session into an undocumented native tool call and then claim cross-runtime subagent support.
+
+## Context Build and inspection
+
+Agent Designer and Context Build must show:
+
+- selected runtime instance/adapter and diagnostics;
+- effective capability modes;
+- selected tool delivery and portability;
+- skills/context/MCP delivery status, fidelity, target, and inventory;
+- disabled reasons for unsupported selections;
+- redacted secret environment key names, never values;
+- native prompt preservation assumptions/evidence.
+
+Inspection may create temporary generation state but must use non-strict mode, avoid delegated work, dispose before return, and not persist a harness conversation.