summary: "Pi provider adapter for workstation inference with lifecycle-read-only text paths and scheduler-claimed one-shot audio dispatch." read_when:

• "Starting work in this package workspace."
• "Wiring Pi to workstation baseline-text inference without giving Pi runtime authority." system4d: container: "Monorepo package for a Pi-side provider over workstation-owned inference." compass: "Expose workstation inference to Pi while preserving lane-op as runtime authority." engine: "Read lane-op-exported contract -> register provider -> health-check read-only -> forward requests." fog: "Main risk is accidentally recreating a runtime control plane inside Pi."

@tryinget/pi-workstation-inference-provider

Pi provider adapter for workstation-owned inference endpoints. Ordinary text/provider discovery remains lifecycle-read-only; the explicitly invoked audio path consumes one externally issued scheduler claim.

Local-first hot path

This package treats the workstation as the primary inference plane. Contract files are parsed into an immutable in-memory generation, ordinary text requests use cached nonblocking health, and governed audio retains blocking owner checks. Modal or another remote provider is an explicit overflow lane rather than a dependency.

Design and rollout details:

• Local-first workstation design packet
• Implementation plan
• Hot-path ADR

This package is intentionally not a llama.cpp manager. It does not download models, build runtimes, start services, stop services, warm models, or decide promotion. Workstation lane-op remains the runtime authority for baseline/canary/experiment state, GPU/coexistence gates, receipts, and rollback.

The audio path is not globally read-only: it mutates only the externally owned scheduler claim through bounded pre-effect, post-effect, complete, or quarantine consumer operations. It cannot issue claims, reserve resources, start or stop runtimes, reconcile indeterminate outcomes, or authorize retries.

What it does

• Reads a small lane-op/workstation-exported provider contract JSON.
• Registers a Pi provider, default id workstation-inference, with a provider-local API id workstation-inference.
• Delegates internally to Pi's OpenAI-compatible transport for workstation requests only, without owning the shared openai-completions transport.
• Maps contract models into Pi model entries.
• Primes and caches read-only health probes; ordinary text uses nonblocking stale-while-revalidate while governed audio remains blocking.
• Provides /workstation-inference status, /workstation-inference hot-path, and /workstation-inference contract.
• Implements the Pi 0.83 one-shot Inkling audio-send payload membrane; it requires and consumes an exact externally issued scheduler handoff before one provider dispatch.

What it must not do

• No model download/build/convert.
• No llama-server process ownership.
• No watchdog or runtime lease manager.
• No lane-op apply/start/stop/switch/reserve/run/compare/report calls.
• No canonical model/catalog authority inside Pi.

Contract source

An explicit inline or path contract is loaded alone:

1. PI_WORKSTATION_INFERENCE_CONTRACT_JSON — inline JSON for tests/manual smoke.
2. PI_WORKSTATION_INFERENCE_CONTRACT — path to one contract JSON.

Without either override, the extension loads and merges distinct workstation-owned files by model id:

1. canonical baseline: phasee/state/workstation-inference-provider.json;
2. optional baseline canary: phasee/state/workstation-inference-provider.canary.json;
3. optional Inkling canary: phasee/state/workstation-inference-provider.inkling-canary.json.

The canonical default path is:

~/ai-society/softwareco/infra/workstation/phasee/state/workstation-inference-provider.json

Example contract:

• examples/workstation-inference-provider.contract.example.json

Minimal shape:

{
  "schema_version": 1,
  "authority": "workstation/lane-op",
  "family": "baseline-text",
  "surface": "canonical",
  "base_url": "http://127.0.0.1:1234/v1",
  "health_url": "http://127.0.0.1:1234/health",
  "models": [
    {
      "pi_model_id": "baseline-text",
      "name": "Baseline text (lane-op canonical)",
      "context_window": 131072,
      "max_tokens": 16384,
      "reasoning": true,
      "thinking_format": "qwen-chat-template"
    }
  ]
}

Contracts must use credential-free loopback HTTP and a recognized workstation authority. If a contract has generated_at plus refresh_after_seconds (or the legacy stale_after_seconds), /workstation-inference status reports the refresh warning. Ordinary runtime requests fail closed on missing/invalid/unhealthy contracts through the package's custom stream handler; audio is stricter and rejects stale contract authority.

Transport ownership membrane: this package must never register its custom streamSimple under shared built-in API ids such as openai-completions. Workstation models use api: "workstation-inference"; the stream handler then delegates internally to OpenAI-compatible transport after it has resolved the selected workstation contract and model.

Baseline aliases and thinking effort

For ordinary family: "baseline-text" requests, the HTTP model stays the selected pi_model_id (or normalized id), including baseline-text-visible and canary aliases. upstream_model describes the underlying artifact; it is not the adapter-facing request model. Sending that raw ID bypasses workstation's alias normalization, losing thinking-off defaults and effort-to-budget translation. Other contract families and claim-governed audio retain their upstream routing.

Pi forwards the contract-declared effort levels; the workstation adapter owns native model translation and thinking-token budgets. Do not replace this with a Pi-local copy of Aeon's effort map. In particular, an adapter can accept high even when the underlying model's chat template cannot. Visible aliases rely on the adapter's non-thinking default. Available levels remain contract-owned; this routing fix does not add max to contracts that do not expose it.

tests/workstation-inference-routing.test.mjs exercises the real Pi transport against synthetic SSE, covering the effort ladder, visible and canary aliases, other-family routing, fragmented tool arguments, and tool-result continuation. These hermetic tests are not a substitute for live Pi/model verification.

First-request health recovery

Healthy or not-yet-observed ordinary endpoints keep the nonblocking health hot path. After a cached negative result (including a startup health timeout), the next request instead awaits one shared, bounded health revalidation, even if the negative cache TTL has not expired. A recovered endpoint serves that same request; there is no need to submit the prompt twice. A fresh timeout, HTTP failure, or known-dead selected lane still blocks inference. Concurrent callers share the probe, and cancelling one waiter does not cancel the others.

The health timeout remains 1,500 ms by default; this is not a timeout increase, fail-open switch, model warm-up, or automatic retry of an inference request. Explicit/governed blocking health remains blocking. Tests cover both fresh and expired cached failures, recovery, persistent failures, cancellation, and zero provider dispatch when the refreshed check still fails.

Current workstation exporter command:

cd /home/tryinget/ai-society/softwareco/infra/workstation
python3 scripts/phasee/lane-op.py provider-contract baseline-text --surface canonical --write
python3 scripts/phasee/lane-op.py provider-contract inkling --surface canary --write

The exporter is a bounded write to phasee/state/workstation-inference-provider.json; runtime service lifecycle still belongs to lane-op's existing plan/apply surfaces.

Explicit provider-only entrypoint (AK5717)

Cold model-only hosts can opt in to the file, not the package directory:

/absolute/path/to/pi-workstation-inference-provider/extensions/workstation-inference-provider-only.ts

For Pi's SDK, use DefaultResourceLoader with noExtensions: true and additionalExtensionPaths: [absoluteEntrypointPath]. Disable unrelated resources, use private host configuration, reject loader errors, and transfer its pending provider registrations to a network-disabled ModelRuntime.create(). Resolve the exact provider/model pair; the host must not substitute another model. No AgentSession or agent loop is needed. Loading this explicit path is the opt-in; it is not added to pi.extensions, but is included in the publish file list. Do not co-load the full lifecycle entrypoint in that worker.

Bootstrap reads the existing contract sources and only calls registerProvider: no health priming/network, audio cleanup, timers, lifecycle handlers, tools, commands, session/UI APIs, or exec. Invalid/missing primary contracts and failed refreshes reject bootstrap. Existing optional-source parsing/merge rules remain: missing/invalid optional contracts contribute no models. Only lane-op models without audio declarations, a runtime profile, or the reserved Inkling identity are registered; scheduler-owned models are excluded even for text-only requests. An all-excluded catalog is an error. Registration never grants audio permission.

Invocation delegates to the unchanged workstation stream, preserving contract model mapping, baseline aliases, other-family upstream routing, thinking controls, and inherited payload hooks. Admission inspects message content and actual wire fields, not arbitrary text, tool schemas, or tool-call arguments. Complete v1 audio markers in the latest user text are rejected using the shared marker parser; quoted prefix literals and historical markers remain ordinary evidence. Final validation rejects route changes, native audio, and unsupported images, including hook/sampling overrides. Shared armed audio is rejected without consuming or cleaning it. Contract changes detected after registration require a fresh bootstrap; detected refresh errors fail closed. Contract TTL observation is still cached, not instantaneous file revocation.

Ordinary invocation retains existing health behavior: a background probe for an unknown/stale endpoint, blocking bounded revalidation after a cached failure, and known-dead-lane rejection. No startup network does not mean no invocation I/O. Contract credentials are resolved by the shared stream at invocation; registration uses inert key metadata rather than executing Pi config-value expressions.

Pi 0.84.3/0.84.4 image input is { type: "image", data: base64, mimeType: "image/png" }. The newer documentation's source shape is not supported by those installed serializers and is rejected rather than silently losing bytes. Images require an image-capable contract model, including after inherited hooks. Final wire image blocks must be image_url objects with a valid inline image MIME/base64 URL and optional auto/low/high detail. Remote image URLs are not admitted. Provider hooks and custom fetch functions remain trusted in-process code, not a security sandbox.

The intended baseline-multimodal integration target is a family: "baseline-text" contract whose selected alias advertises input: ["text", "image"]. Other ordinary families remain registered with existing upstream routing, but the shared stream may return message.model = upstream_model, not the selected alias. An AIconvo-style worker requiring exact returned identity will reject those responses. This patch does not fix that shared limitation or claim general AIconvo compatibility.

Core bootstrap/alias/host acceptance and new review scenarios bind executable Given/When/Then steps on Node's test runner, with observable step diagnostics; this is Gherkin-style TDD, not a Cucumber dependency or a Gherkin parser.

Acceptance evidence and proof limits cover hermetic fake-SSE transport and real host loading only: no AIconvo integration, installation/reload, live model, latency, quality, or canary claims.

Commands

/workstation-inference status
/workstation-inference refresh
/workstation-inference lane-status
/workstation-inference contract
/workstation-inference audio-send --handoff <claim.json> --scheduler-db <scheduler.sqlite3> <audio> -- <prompt>
/workstation-inference help

status reads the contract and probes the configured health URL. refresh explicitly asks workstation lane-op to rewrite canonical and baseline-canary contracts; it attempts the distinct Inkling export as an optional add-on that cannot block baseline recovery. lane-status delegates to read-only lane-op status baseline-text --surface canonical.

Inkling audio input

The model is discoverable as workstation-inference/inkling-small-iq2m-canary. Invocation requires a fresh handoff created by the external scheduler owner; Pi cannot issue one:

/workstation-inference audio-send \
  --handoff /private/one-turn-handoff.json \
  --scheduler-db /private/scheduler.sqlite3 \
  /absolute/or/relative/question.wav \
  -- What is the pupil asking?

Current execution status: implemented and claim-gated. Model visibility, a healthy endpoint, and a fresh contract are still not invocation authorization. Before reading audio, the extension validates that the bounded no-follow handoff binds exactly:

workstation-capability-graph
-> inkling-tts-canary
-> inkling-small:0
-> workstation-inference/inkling-small-iq2m-canary

It then validates the contract-listed wav, mp3, or flac regular file. Immediately before creating the Pi turn, it invokes only the local-ai-control-plane consumer surface for one pre-effect consumption. The extension never invokes external-claim, reservation, release, reconciliation, retry, lifecycle, or model-load commands.

The adapter opens the final audio path without following a symlink, verifies format magic and owner-exported raw/encoded size bounds, and keeps bytes only in expiring process memory. A nonce identifies the exact user turn. Inside the provider transport, Pi's inherited payload hook runs first; final validation rejects tools or pre-existing audio and then replaces that nonce with exactly one llama.cpp input_audio block immediately before HTTP dispatch.

The audio turn sends no tools and forces provider retries to zero. A successful stream is withheld from terminal completion until post-effect revalidation and repository-issued causal completion succeed. The content-free completion result binds one dispatch, the exact handoff digest/attempt, provider/model, and completed stream; its private temporary file is removed immediately. A provider error or interrupted result is quarantined once as outcome unknown. If completion itself becomes indeterminate, Pi does not retry, quarantine, release, or reconcile automatically.

A second session attempt fails before another HTTP request because the one-shot pre-effect consumption and attachment are already consumed. Audio bytes/base64, prompt, transcript, and response content are not written to handoffs, scheduler results, contracts, or AK evidence.

This command never starts the Inkling canary. The external owner must first establish the fresh scheduler reservation/claim and start the runtime through its accepted owner path. Keep the handoff file available until the turn reaches completion or quarantine because each bounded consumer command revalidates it against the scheduler repository.

For the accepted Workbench design, extensions/workstation-authority-channel.ts provides the separate child-side authority membrane for workbench-inkling-canary; the legacy handoff path above deliberately rejects that profile so it cannot inherit Pi-side completion or quarantine authority. The broker-owned Pi child supplies its non-reconnectable inherited descriptor through PI_WORKSTATION_INFERENCE_AUTHORITY_FD, and the broker invokes /workstation-inference workbench-audio-send <staged-wav> -- <prompt>. The extension receives one exact arm_turn, verifies the staged audio digest, and sends authorize_dispatch only after final payload validation. A successful owner response is a distinct, exact dispatch_permit bound to the turn, provider/model, durable scheduler intent, and reservation/lease identity. The permit is valid for at most 1000 ms. The dedicated Workbench HTTP transport acquires one unpooled loopback connection without flushing headers or body. Only after the socket is connected does one synchronous write-boundary callback recheck the audio attachment, recheck both absolute and monotonic permit expiry, consume the permit, increment dispatch count, and call request.end() with the exact request bytes. Expiry while connection acquisition is pending destroys the connection with zero provider bytes; any failure after request.end() is ambiguous and never retried. It never calls the legacy scheduler consumer from this path.

Authority schema workbench-inkling-authority/v2 and digest b78278b0ae541b25274f930adf5c977b5a4df9742a7ebe38f129129966247421 are byte-aligned with the canonical local-ai-control-plane contract at commits af506f0 and 45b12cf. The package also pins broker schema digest b1b50956002df6ed65fd7891ab4a218eedcc80970a678c3bbf1059ba87139fc5. Arm and disposition use exact canonical echoes; authorization never accepts an echo and requires the canonical recomputable permit. Duplicate keys and any missing, malformed, mismatched, future-dated, expired, replayed, or lost frame permanently block further dispatch. Caller-supplied fetch transports are rejected on this governed path, and provider retries remain zero. The membrane exposes no scheduler path and no release, completion, reconciliation, retry, or quarantine operation. The governed transport accepts only the exact credential-free http://127.0.0.1:<port>/v1/chat/completions target, creates no pooled or redirecting alternate path, and marks a possible dispatch in the same connected-socket callback immediately before admitting bytes with request.end(). Hermetic tests hold a connected socket before that callback, cross permit expiry, and prove the provider receives zero bytes; installation, reload, profile activation, model invocation, and end-to-end runtime behavior remain separately owner-gated and are not claimed here.

These commands may call the workstation-owned lane-op CLI, but they do not start/stop/switch/warm services or apply lane changes. Runtime lifecycle remains behind lane-op's existing plan/apply surfaces.

Runtime dependencies

This audio path requires Pi 0.83.x host payload callbacks. The package expects Pi host runtime APIs and declares them as peer dependencies:

• @earendil-works/pi-coding-agent
• @earendil-works/pi-ai

When using UI APIs (ctx.ui), guard interactive-only behavior with ctx.hasUI so pi -p non-interactive runs stay stable.

Package checks

Run from package directory:

npm install
npm run check

Run from monorepo root through the canonical package gate:

bash ./scripts/package-quality-gate.sh ci packages/pi-workstation-inference-provider

Provider module split

Provider registration/commands, contract loading, streaming, audio turns, scheduler parsing, inherited authority, and governed HTTP transport are split into bounded modules. The unchanged workstation-scheduler-json.ts scanner remains the sole exact-lexeme handoff canonicalizer.

Live package activation

Install the package into Pi from the package directory containing this package's package.json:

pi install /home/tryinget/ai-society/softwareco/owned/pi-extensions/packages/pi-workstation-inference-provider

Then in Pi:

1. run /reload
2. run /workstation-inference status
3. select a workstation-inference/... model only after the contract is healthy

Copier lifecycle policy

• Keep .copier-answers.yml committed.
• Do not edit .copier-answers.yml manually.
• Run update/recopy from a clean destination repo.
• After recopy, re-apply local deltas intentionally and run npm run check.