feat(server): instructions accepts a function form (lazy/per-session) — closes #1347

[bokelley]

Closes #1347.

Lifts the captured-once limitation on instructions. createAdcpServer.instructions and DecisioningPlatform.instructions now accept either a static string (historical form) or a (ctx: SessionContext) => string | undefined function. Under serve({ reuseAgent: false }) (the default) the factory runs per HTTP request, so the function fires per session — adopters surface tenant-shaped prose (per-buyer brand manifests, storefront-platform copy, premium-vs-standard partner guidance) without a Map shim outside the SDK.

Surface

import { createAdcpServer, type SessionContext, type OnInstructionsError } from '@adcp/sdk/server';

createAdcpServer({
  // existing string form still works
  instructions: 'Publisher-wide brand safety: alcohol disallowed.',

  // or function form — re-evaluated per createAdcpServer invocation
  instructions: (ctx: SessionContext) => brandManifests.get(currentTenant)?.intro,

  // throw semantics — default 'skip'
  onInstructionsError: 'skip', // or 'fail'
});

Three design questions resolved (per the #1347 triage thread)

1. SessionContext shape — slim { authInfo?: ResolvedAuthInfo; agent?: BuyerAgent }. Both reserved; currently always undefined because the framework doesn't yet plumb auth/registry state into the factory before MCP initialize. Today-pattern for tenant identity is closures captured in HTTP-scoped factory state. Forward-compatible: when the framework wires authInfo/agent through, existing function bodies pick up populated fields without changes.

2. reuseAgent: true + function-form is refused. The function would only fire once for the lifetime of the shared agent — silently degrading to "constant after all" is worse than failing loud. serve() returns 500 with a message naming the workaround (drop reuseAgent: true for fresh agent per request, OR pass a static string).

3. Throw semantics via onInstructionsError:

   • 'skip' (default) — log server-side, treat as undefined. Right for prose-of-flavor (brand manifests, marketing copy) where a registry fetch failure must not kill the buyer's session.
   • 'fail' — rethrow → MCP initialize transport-level failure. Right when instructions carry load-bearing policy where stale/missing guidance is worse than a connection retry.

What ships

• createAdcpServer.instructions type extended; onInstructionsError option added (default 'skip').
• DecisioningPlatform.instructions type extended; onInstructionsError plumbed through from-platform.ts. Platform wins over opts.instructions when both supplied (same precedence as agentRegistry).
• SessionContext + OnInstructionsError type exports from @adcp/sdk/server.
• ADCP_INSTRUCTIONS_FN symbol export — serve() reads it to detect function-form servers and refuse reuseAgent: true.
• Async return is not yet supported. A function returning a Promise throws ConfigurationError at construction (regardless of onInstructionsError); pre-resolve before invoking createAdcpServer if you need to fetch. Future-compat: type signature accepts only sync return today; future revisions can extend.

Tests (test/server-instructions-fn.test.js)

10 new tests cover:

• string form regression (passes through unchanged)
• function evaluated at construction; re-eval per createAdcpServer call drives per-session semantics under reuseAgent: false
• ADCP_INSTRUCTIONS_FN marker presence (function form) / absence (string form)
• function returning undefined → no instructions, marker still set
• SessionContext shape (currently empty, future-compatible)
• onInstructionsError: 'skip' (default) catches throws — function returning throw resolves to undefined
• onInstructionsError: 'fail' rethrows
• explicit 'skip' matches default
• Promise return → ConfigurationError regardless of onInstructionsError

214/214 pass across the broader server-config test suite (no regressions).

Test plan

• npm run build
• npx tsc --noEmit
• npm run format:check
• node --test test/server-instructions-fn.test.js (10/10)
• node --test test/server-decisioning-from-platform.test.js test/server-decisioning-instructions.test.js test/server-create-adcp-server.test.js (204/204)

🤖 Generated with Claude Code