research platform assistant

Research: platform assistant (#52) — S0 spike findings

Status: verified 2026-10-14 on feat/52-platform-assistant (packages/server/test/assistant-spike.test.ts, offline, no network). Ground truth for the seams the M1 implementation rides on.

Superseded by the Plan B decision (same day): the user chose the full service-layer refactor (#53) — assistant tools call principal-carrying services directly. §1 below (ALS disproven, internal credential proposed) is the HISTORICAL RECORD of why in-process identity could not ride ambient context or self-HTTP; the mechanism itself is no longer part of the design. §2–§4 (pi-ai/pi-agent-core seams) remain current.

1. Identity: AsyncLocalStorage is DEAD through app.inject() — internal credential instead

The design's first sketch (ALS actor context opened around app.inject()) was disproven: light-my-request dispatches outside the caller's async context — the ALS store is empty inside onRequest hooks. Verified in bare Node (not just vitest):

const r = await als.run({ userId: 'u-1' }, () => app.inject({ url: '/w' }));
// hook sees: no store. (outside run: also no store — correct, but the
// inside-run case is the one that matters and it fails.)

A real loopback socket would not carry ALS either (server-side handlers run from the event loop). Settled mechanism (test-verified):

• boot-time random secret (randomBytes(32).base64url), held in server memory only; restart rotates it;
• tool executors call app.inject() with headers x-hnx-internal-auth: <secret> + x-hnx-actor: <userId>;
• the root auth hook's leading branch: timingSafeEqual on the secret, then a FRESH findUserById (disabled/demoted takes effect next call, matching the PAT path), then req.user + a viaAssistant audit marker; mismatch/absent → anonymous → the normal Bearer path.

Network clients cannot know the secret; header names are not the gate. Cryptographically equivalent to a minted JWT but per-process, no TTL juggling, nothing to revoke, and it survives any future transport change.

2. pi-ai gateway provider — createProvider is the models.json factory

createProvider({id, name, baseUrl, auth, models, api}) builds a Provider from parts (the same path models.json custom providers take). Verified shape for our LlmProvider rows:

• auth.apiKey.resolve: async () => ({ auth: { apiKey: decrypted }, source: 'credential' }) — resolution is deferred per request (the decrypt happens here, not at build time);
• registry models map to ProviderModel entries: api mapped 1:1 (anthropic→anthropic-messages, openai-chat→openai-completions, openai-responses→openai-responses), name/contextWindow/maxTokens from the #51 registry; reasoning: false default; input: ['text','image'] when vision;
• api: takes {stream, streamSimple} from the per-wire modules — import as @earendil-works/pi-ai/api/openai-completions (subpath; the ROOT index does NOT export the api factory functions; the .lazy variants export openAICompletionsApi()-style factories that wrap the same thing).

3. Agent loop + tool harness — fauxProvider is the test wire

• fauxProvider({models, tokensPerSecond}) + setResponses([...]) scripts assistant messages (text/thinking/toolCall blocks via fauxAssistantMessage) with ZERO I/O — the AssistantService unit tests never touch the network (repo rule);
• new Agent({initialState: {systemPrompt, model, tools, messages}, streamFn: models.streamSimple.bind(models), beforeToolCall, afterToolCall}) — verified end-to-end: scripted tool call → tool_execution_* → scripted conclusion → turn_end ×2 → agent_end; both audit hooks fire in order; tools are pi-native typebox schemas (piAi.Type.Object);
• Agent.state.messages is the rebuild-from-DB seam: assign per turn, pi owns nothing durable (platform-owned session persistence holds).

4. Environment

@earendil-works/{pi-agent-core,pi-ai}@1.1.0 (pinned exact) import cleanly on Node 22.22 (engines >=22.19; the #50 floor). pi-ai re-exports typebox Type — tool schemas need no extra dependency.