@pikku/core 0.12.112 → 0.12.114

package/dist/wirings/http/http.types.d.ts

@@ -40,9 +40,33 @@ export type CoreHTTPFunction = HTTPRouteBaseConfig & {
     /** Sends the returned value as-is rather than JSON-encoding it, for a route whose body is binary or already serialised. */
     returnsJSON?: false;
 };
+/**
+ * The claims a transport that already verified a bearer token hands on.
+ *
+ * Strictly pass-through: nothing in pikku derives this from a request's own
+ * headers, because verifying a token is the host's job, not the wire's. A
+ * function can always read the `Authorization` header itself — what this adds
+ * is what the raw header cannot carry, the scopes and client the token was
+ * actually issued for.
+ *
+ * Shaped to match the MCP SDK's `AuthInfo`, which is the one caller that
+ * populates it today.
+ */
+export interface PikkuHTTPAuthInfo {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    /** Seconds since the epoch. */
+    expiresAt?: number;
+    /** The RFC 8707 resource server this token is valid for. */
+    resource?: URL;
+    extra?: Record<string, unknown>;
+}
 export interface PikkuHTTP<In = unknown> {
     request?: PikkuHTTPRequest<In>;
     response?: PikkuHTTPResponse;
+    /** Verified token claims, when the transport was handed them. */
+    authInfo?: PikkuHTTPAuthInfo;
 }
 export type PikkuQuery<T = Record<string, string | undefined>> = Record<string, string | T | null | Array<T | null>>;
 /**
@@ -78,6 +102,13 @@ type HTTPWiringAuth<In, Out, PikkuFunction extends CorePikkuFunction<In, Out, an
     /** On an open route there is no session, so this must be a sessionless function. */
     func: CorePikkuFunctionConfig<PikkuFunctionSessionless, PikkuPermission, PikkuMiddleware>;
 };
+/**
+ * The event protocol a streaming route's frames follow, so the layer that
+ * terminates a failed stream can speak the same one the client is parsing.
+ * `'pikku'` frames are `{ type: 'error' | 'done' }`; `'agui'` frames are
+ * AG-UI events, where a failure is a single `RUN_ERROR`.
+ */
+export type HTTPStreamProtocol = 'pikku' | 'agui';
 /**
  * `sse` and `query` are each valid on one method only, so the method carries
  * them: streaming is a GET, and naming which input keys arrive in the query
@@ -92,6 +123,8 @@ type HTTPWiringMethod<In> = {
     method: 'get';
     /** Streams the response as server-sent events instead of returning it once. GET only. */
     sse?: boolean;
+    /** Which event protocol the frames on this stream follow. Defaults to `'pikku'`. */
+    streamProtocol?: HTTPStreamProtocol;
 } | {
     /** The HTTP method. A route and method together address one wiring. */
     method: 'post';
@@ -162,6 +195,8 @@ export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, an
     auth?: boolean;
     middleware?: PikkuMiddleware[];
     sse?: boolean;
+    /** Which event protocol the frames on this stream follow. Defaults to `'pikku'`. */
+    streamProtocol?: HTTPStreamProtocol;
 };
 export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
     basePath?: string;

package/dist/wirings/http/index.d.ts

@@ -5,4 +5,4 @@ export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js'
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';
 export { toWebRequest, applyWebResponse } from './web-request.js';
 export { httpRouter } from './routers/http-router.js';
-export type { AssertHTTPWiringParams, CoreHTTPFunctionWiring, HTTPMethod, HTTPRouteBaseConfig, HTTPRouteContract, HTTPRouteMap, HTTPWiringsMeta, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse, PikkuQuery, RunHTTPWiringOptions, } from './http.types.js';
+export type { AssertHTTPWiringParams, CoreHTTPFunctionWiring, HTTPMethod, HTTPRouteBaseConfig, HTTPRouteContract, HTTPRouteMap, HTTPWiringsMeta, PikkuHTTP, PikkuHTTPAuthInfo, PikkuHTTPRequest, PikkuHTTPResponse, PikkuQuery, RunHTTPWiringOptions, } from './http.types.js';

package/dist/wirings/mcp/index.d.ts

@@ -1,4 +1,5 @@
 export { MCPEndpointRegistry } from './mcp-endpoint-registry.js';
 export { MCPError, wireMCPResource, wireMCPPrompt, runMCPResource, runMCPTool, runMCPPrompt, } from './mcp-runner.js';
-export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, } from './mcp-runner.js';
+export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, mcpTargetRequiresSession, mcpEveryTargetRequiresSession, mcpWireName, mcpResolveWireName, } from './mcp-runner.js';
+export type { McpTargetType } from './mcp-runner.js';
 export type { AssertMCPResourceURIParams, CoreMCPPrompt, CoreMCPResource, MCPPromptResponse, MCPResourceMeta, MCPResourceResponse, MCPToolMeta, MCPToolResponse, MCPPromptMeta, PikkuMCP, } from './mcp.types.js';

package/dist/wirings/mcp/index.js

@@ -1,3 +1,3 @@
 export { MCPEndpointRegistry } from './mcp-endpoint-registry.js';
 export { MCPError, wireMCPResource, wireMCPPrompt, runMCPResource, runMCPTool, runMCPPrompt, } from './mcp-runner.js';
-export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, } from './mcp-runner.js';
+export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, mcpTargetRequiresSession, mcpEveryTargetRequiresSession, mcpWireName, mcpResolveWireName, } from './mcp-runner.js';

package/dist/wirings/mcp/mcp-runner.d.ts

@@ -32,3 +32,30 @@ export declare function runMCPPrompt(request: JsonRpcRequest, params: RunMCPEndp
 export declare const getMCPResourcesMeta: () => import("./mcp.types.js").MCPResourceMeta;
 export declare const getMCPToolsMeta: () => import("./mcp.types.js").MCPToolMeta;
 export declare const getMCPPromptsMeta: () => import("./mcp.types.js").MCPPromptMeta;
+/**
+ * Whether a call to this MCP target would need a session to run.
+ *
+ * Read from the same declarations the runner enforces: a `pikkuFunc` always
+ * needs one, and a `pikkuSessionlessFunc` needs one only where it says
+ * `auth: true`. A transport asks this to answer an unauthenticated call with a
+ * `401` challenge instead of dispatching it — the status and the
+ * `WWW-Authenticate` header have to be chosen before the response starts, which
+ * is earlier than the refusal itself can be known.
+ *
+ * Unknown targets are treated as open: a name nobody registered is a
+ * `Method not found`, and answering it with a challenge would invite a client
+ * to authenticate its way towards a tool that does not exist.
+ */
+export declare const mcpTargetRequiresSession: (type: 'tool' | 'resource' | 'prompt', name: string) => boolean;
+/**
+ * Whether every registered MCP target needs a session. An empty registry is
+ * not "all gated" — there is nothing to gate.
+ *
+ * See `the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md`.
+ */
+export declare const mcpEveryTargetRequiresSession: () => boolean;
+export type McpTargetType = 'tool' | 'resource' | 'prompt';
+/** How a registered target's name is spelled on the wire. */
+export declare const mcpWireName: (type: McpTargetType, name: string) => string;
+/** The registered name a client's wire name refers to. */
+export declare const mcpResolveWireName: (type: McpTargetType, wireName: string) => string;

package/dist/wirings/mcp/mcp-runner.js

@@ -187,3 +187,114 @@ export const getMCPToolsMeta = () => {
 export const getMCPPromptsMeta = () => {
     return pikkuState(null, 'mcp', 'promptsMeta');
 };
+/**
+ * Whether a call to this MCP target would need a session to run.
+ *
+ * Read from the same declarations the runner enforces: a `pikkuFunc` always
+ * needs one, and a `pikkuSessionlessFunc` needs one only where it says
+ * `auth: true`. A transport asks this to answer an unauthenticated call with a
+ * `401` challenge instead of dispatching it — the status and the
+ * `WWW-Authenticate` header have to be chosen before the response starts, which
+ * is earlier than the refusal itself can be known.
+ *
+ * Unknown targets are treated as open: a name nobody registered is a
+ * `Method not found`, and answering it with a challenge would invite a client
+ * to authenticate its way towards a tool that does not exist.
+ */
+export const mcpTargetRequiresSession = (type, name) => {
+    // The transport passes the name exactly as the client sent it, which is the
+    // wire spelling — see `mcpWireName`.
+    name = mcpResolveWireName(type, name);
+    const meta = type === 'tool'
+        ? pikkuState(null, 'mcp', 'toolsMeta')[name]
+        : type === 'resource'
+            ? pikkuState(null, 'mcp', 'resourcesMeta')[name]
+            : pikkuState(null, 'mcp', 'promptsMeta')[name];
+    if (!meta) {
+        return false;
+    }
+    let funcName = meta.pikkuFuncId;
+    let packageName = null;
+    if (funcName.includes(':')) {
+        const resolved = resolveNamespace(funcName);
+        if (resolved) {
+            funcName = resolved.function;
+            packageName = resolved.package;
+        }
+    }
+    const funcMeta = pikkuState(packageName, 'function', 'meta')[funcName];
+    if (!funcMeta) {
+        return false;
+    }
+    return !funcMeta.sessionless || funcMeta.auth === true;
+};
+/**
+ * Whether every registered MCP target needs a session. An empty registry is
+ * not "all gated" — there is nothing to gate.
+ *
+ * See `the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md`.
+ */
+export const mcpEveryTargetRequiresSession = () => {
+    const targets = [
+        ['tool', Object.keys(pikkuState(null, 'mcp', 'toolsMeta'))],
+        ['resource', Object.keys(pikkuState(null, 'mcp', 'resourcesMeta'))],
+        ['prompt', Object.keys(pikkuState(null, 'mcp', 'promptsMeta'))],
+    ];
+    let seen = 0;
+    for (const [type, names] of targets) {
+        for (const name of names) {
+            seen++;
+            if (!mcpTargetRequiresSession(type, name)) {
+                return false;
+            }
+        }
+    }
+    return seen > 0;
+};
+const mcpMetaFor = (type) => type === 'tool'
+    ? pikkuState(null, 'mcp', 'toolsMeta')
+    : type === 'resource'
+        ? pikkuState(null, 'mcp', 'resourcesMeta')
+        : pikkuState(null, 'mcp', 'promptsMeta');
+const WIRE_LEGAL = /^[A-Za-z0-9_-]+$/;
+/**
+ * Registered name -> wire name for every target of one type.
+ *
+ * See `mcp-wire-names-are-assigned-over-the-whole-registry.md`.
+ */
+const mcpWireNames = (type) => {
+    const names = Object.keys(mcpMetaFor(type)).sort();
+    const assigned = new Map();
+    const taken = new Set();
+    for (const name of names) {
+        if (WIRE_LEGAL.test(name)) {
+            assigned.set(name, name);
+            taken.add(name);
+        }
+    }
+    for (const name of names) {
+        if (assigned.has(name)) {
+            continue;
+        }
+        const base = name.replace(/[^A-Za-z0-9_-]/g, '_');
+        let candidate = base;
+        let n = 2;
+        while (taken.has(candidate)) {
+            candidate = `${base}_${n++}`;
+        }
+        assigned.set(name, candidate);
+        taken.add(candidate);
+    }
+    return assigned;
+};
+/** How a registered target's name is spelled on the wire. */
+export const mcpWireName = (type, name) => mcpWireNames(type).get(name) ?? name;
+/** The registered name a client's wire name refers to. */
+export const mcpResolveWireName = (type, wireName) => {
+    for (const [name, wire] of mcpWireNames(type)) {
+        if (wire === wireName) {
+            return name;
+        }
+    }
+    return wireName;
+};

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
@@ -47,7 +48,7 @@ export interface ResolvedFunction {
         rpcEndpoint?: string;
         secretOverrides?: Record<string, string>;
         variableOverrides?: Record<string, string>;
-        credentialOverrides?: Record<string, string>;
+        credentialOverrides?: CredentialOverrides;
         /** Set by the consuming app: secrets it lends this instance, as the addon names them */
         secretGrants?: string[];
         /** Set by the consuming app: credentials it lends this instance, as the addon names them */

package/dist/wirings/secret/derive-oauth2-app-secrets.d.ts

@@ -0,0 +1,20 @@
+import type { CredentialDefinitions } from '../credential/credential.types.js';
+import type { SecretDefinitions } from './secret.types.js';
+/**
+ * The app secrets implied by the OAuth2 credentials a project declares.
+ *
+ * An OAuth2 credential always needs the app's client id and secret, and that
+ * pair is the same shape every time — `OAuth2AppCredential`, which is what the
+ * runtime reads it as and what the generated types already say it is. Making
+ * every author restate it as a hand-written `defineSecret` bought nothing and
+ * was silently skipped often enough that deployments were never asked for
+ * credentials their connect flow needed.
+ *
+ * A declaration that already covers the secret id wins, so an author who wants
+ * their own description or `docsUrl` keeps it.
+ *
+ * The derived secret is optional, matching what every hand-written declaration
+ * chose: an addon that also authenticates by API key must still deploy without
+ * an OAuth app configured.
+ */
+export declare const deriveOAuth2AppSecrets: (credentials: CredentialDefinitions, declared: SecretDefinitions) => SecretDefinitions;

package/dist/wirings/secret/derive-oauth2-app-secrets.js

@@ -0,0 +1,47 @@
+/**
+ * The app secrets implied by the OAuth2 credentials a project declares.
+ *
+ * An OAuth2 credential always needs the app's client id and secret, and that
+ * pair is the same shape every time — `OAuth2AppCredential`, which is what the
+ * runtime reads it as and what the generated types already say it is. Making
+ * every author restate it as a hand-written `defineSecret` bought nothing and
+ * was silently skipped often enough that deployments were never asked for
+ * credentials their connect flow needed.
+ *
+ * A declaration that already covers the secret id wins, so an author who wants
+ * their own description or `docsUrl` keeps it.
+ *
+ * The derived secret is optional, matching what every hand-written declaration
+ * chose: an addon that also authenticates by API key must still deploy without
+ * an OAuth app configured.
+ */
+export const deriveOAuth2AppSecrets = (credentials, declared) => {
+    const covered = new Set(declared.map((secret) => secret.secretId));
+    const derived = [];
+    for (const credential of credentials) {
+        const { oauth2 } = credential;
+        if (!oauth2)
+            continue;
+        if (covered.has(oauth2.appCredentialSecretId))
+            continue;
+        covered.add(oauth2.appCredentialSecretId);
+        derived.push({
+            name: `${credential.name}App`,
+            displayName: `${credential.displayName} OAuth App`,
+            description: `OAuth2 app client id and secret for ${credential.displayName}.`,
+            secretId: oauth2.appCredentialSecretId,
+            optional: true,
+            docsUrl: credential.docsUrl,
+            oauth2: {
+                tokenSecretId: oauth2.tokenSecretId,
+                authorizationUrl: oauth2.authorizationUrl,
+                tokenUrl: oauth2.tokenUrl,
+                scopes: oauth2.scopes,
+                pkce: oauth2.pkce,
+                additionalParams: oauth2.additionalParams,
+            },
+            sourceFile: credential.sourceFile,
+        });
+    }
+    return derived;
+};

package/dist/wirings/secret/index.d.ts

@@ -1,3 +1,4 @@
 export { defineSecret } from './secret.types.js';
 export type { CoreSecret, OAuth2CredentialConfig, SecretDefinitionMeta, SecretDefinitionsMeta, SecretDefinitions, } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';
+export { deriveOAuth2AppSecrets } from './derive-oauth2-app-secrets.js';

package/dist/wirings/secret/index.js

@@ -1,2 +1,3 @@
 export { defineSecret } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';
+export { deriveOAuth2AppSecrets } from './derive-oauth2-app-secrets.js';

package/knowledge/decisions/internals/global-middleware-resolves-from-the-root-namespace-too.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: Global middleware resolves from the root namespace too
+description: An addon's dispatch carries the addon's package name, so reading globals from that namespace alone meant the application's own global middleware never ran for it
+tags: [middleware, addons, packages]
+---
+
+# Global middleware resolves from the root namespace too
+
+`combineMiddleware` collects global middleware from `[null]` for a root
+dispatch, and from `[null, packageName]` for a dispatch belonging to a package.
+
+It previously read one namespace: whichever `packageName` the dispatch carried.
+Application wirings carry `null`, so they were unaffected. A wiring contributed
+by an addon carries that addon's package name, and the application's own globals
+were not in that list — so an addon-contributed MCP tool ran with no session
+middleware at all and refused every caller, while the same function reached over
+HTTP authenticated normally.
+
+Global middleware is application-wide by definition, and an addon's function
+still runs inside the host application, so the root namespace always applies.
+One addon's globals still do not reach another addon's dispatches.
+
+The consequence is that a global written against the application's services now
+runs where those services may not exist — an addon builds its own. Middleware
+that reaches for a service it was not given has to stand down rather than throw;
+see `a-session-middleware-stands-down-where-it-cannot-authenticate.md` in
+`@pikku/better-auth`, which is where this first surfaced.
+
+**What this rules out:** treating a package namespace as a middleware boundary
+in both directions. It is a boundary for what an addon contributes, not a wall
+that the host application's own policy stops at.

package/knowledge/decisions/internals/index.md

@@ -74,6 +74,7 @@ caller is entitled to assume.
 - [Gateway webhook challenges echo bytes not JSON](gateway-webhook-challenges-echo-bytes-not-json.md) — String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
 - [Gateway wiring is a meta-wiring over HTTP and channels](gateway-wiring-is-a-meta-wiring-over-http-and-channels.md) — wireGateway writes handler implementations into the HTTP and channel state directly while the inspector compiles the corresponding meta, so runtime registration deliberately writes no meta
 - [Generated src paths in pikku meta are absolute](generated-src-paths-in-pikku-meta-are-absolute.md) — emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
+- [Global middleware resolves from the root namespace too](global-middleware-resolves-from-the-root-namespace-too.md) — An addon's dispatch carries the addon's package name, so reading globals from that namespace alone meant the application's own global middleware never ran for it
 - [Hot reload reads the changed source, never a compiled copy of it](hot-reload-reads-the-changed-source-never-a-compiled-copy.md) — A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
 - [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
 - [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
@@ -87,6 +88,7 @@ caller is entitled to assume.
 - [In-memory workflow history aliases the live step object](in-memory-workflow-history-aliases-the-live-step-object.md) — stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
 - [Istanbul statement counts attach to the start line only](istanbul-statement-counts-attach-to-the-start-line-only.md) — The istanbul coverage reader credits a statement's hits to its first line, so an enclosing multi-line statement cannot mask an unexecuted inner one
 - [Local trigger and gateway services assume a single process](local-trigger-and-gateway-services-assume-a-single-process.md) — InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
+- [MCP wire names are assigned over the whole registry, not derived per name](mcp-wire-names-are-assigned-over-the-whole-registry.md) — Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
 - [Node-only builtins are imported dynamically](node-only-builtins-are-imported-dynamically.md) — V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
 - [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
 - [Only functions marked `expose: true` enter a virtual user's catalogue](only-exposed-functions-enter-a-virtual-user-catalogue.md) — Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
@@ -111,6 +113,7 @@ caller is entitled to assume.
 - [The embedding model is pinned per service and doc/query embedding is split](the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md) — AIEmbeddingService fixes its model at construction so index and query share a vector space, and separates embedDocuments from embedQuery for asymmetric models
 - [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLock/withStepLock as pass-throughs, because inline execution has no second holder to exclude
 - [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
+- [The MCP handshake is challenged only when every target is gated](the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md) — A client decides whether a server speaks OAuth from the handshake alone, so a fully-gated server that answers initialize with a 200 is detected as needing no sign-in
 - [The middleware resolution cache is deliberately unbounded](the-middleware-resolution-cache-is-deliberately-unbounded.md) — Its keyspace is the set of registered wires, not request traffic, and middleware is dynamic — so eviction would buy nothing and cost the dedupe guarantee
 - [The per-invocation rpc view is a class, because an object literal with a getter is slow to build](the-per-invocation-rpc-view-is-a-class.md) — An accessor declared on an object literal is defined per instance, which drops the literal off V8's fast construction path — measured at 1.15µs against 0.47µs, on every request
 - [The persona runtime is exported from @pikku/core/persona, never from services](the-persona-runtime-is-exported-from-the-persona-entry-point.md) — Those values reach the actor-flow and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names

package/knowledge/decisions/internals/mcp-wire-names-are-assigned-over-the-whole-registry.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: MCP wire names are assigned over the whole registry, not derived per name
+description: Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
+tags: [mcp, naming]
+---
+
+# MCP wire names are assigned over the whole registry
+
+MCP clients constrain tool and prompt names to `[A-Za-z0-9_-]`. Pikku's
+namespace separator is `:`, so every target contributed by an addon — `bb2:getMe`
+and friends — carries a name the client cannot accept. Clients drop such names
+from the session rather than fail the connection, which reads as the tools simply
+not existing. The names are therefore rewritten at the transport boundary and
+resolved back on the way in; the namespace itself is untouched, since it is what
+dispatch keys on.
+
+The rewrite is computed for **all** names of a target type at once, not for one
+name in isolation. Replacing illegal characters one name at a time is not
+injective: `a:b` and `a.b` both sanitise to `a_b`, so the list handlers would
+advertise one name twice and the resolver could only ever pick one of them. The
+other target becomes unreachable, silently.
+
+The assignment runs in two passes over the sorted names:
+
+1. Every name that is already wire-legal claims itself. A target whose name a
+   client can already spell keeps that spelling, whatever else is registered.
+2. The rest are sanitised, and a collision takes the next free `_2`, `_3`, …
+   suffix.
+
+Sorting makes the result depend only on the set of registered names, so the same
+registry always produces the same wire names, across processes and restarts.
+
+**What this rules out:** a pure `wireName(name)` function. Correctness here is a
+property of the whole registry, and a signature that cannot see the registry
+cannot have it. It also rules out percent-style escaping, which would be
+injective but would turn every namespaced tool into something unreadable in the
+client's UI, for a collision that needs two targets differing only in their
+separator.

package/knowledge/decisions/internals/the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: The MCP handshake is challenged only when every target is gated
+description: A client decides whether a server speaks OAuth from the handshake alone, so a fully-gated server that answers initialize with a 200 is detected as needing no sign-in
+tags: [mcp, auth, oauth]
+---
+
+# The MCP handshake is challenged only when every target is gated
+
+`requestNeedsCredentials` challenges `initialize` when
+`mcpEveryTargetRequiresSession()` is true, and only then.
+
+A client decides at connection time whether a server speaks OAuth, and the only
+thing it can decide from is whether the handshake came back `401` with a
+`WWW-Authenticate` header naming the resource metadata. A server that answers
+`initialize` with a `200` and then `401`s every single tool call has told the
+client "no sign-in needed" and then refused it everything. That is how a fully
+gated server ends up shown as open, with no way for the user to sign in — the
+client never offers the option, because it was told there was nothing to offer.
+
+The condition is deliberately all-or-nothing. A server with even one open target
+genuinely is usable anonymously, and challenging its handshake would lock out
+clients that have no credentials to offer at all. An empty registry is not "all
+gated" either: there is nothing there to gate, so the handshake stays open.
+
+**What this rules out:** challenging the handshake whenever _any_ target needs a
+session. The handshake is not the place to express per-target policy — the
+per-target `401` already does that, and a client that has been let in can act on
+it. The handshake only answers "is there a sign-in here at all".

package/knowledge/decisions/security/an-mcp-refusal-is-decided-before-dispatch.md

@@ -0,0 +1,48 @@
+---
+type: decision
+title: An MCP refusal is decided before dispatch, not raised from the tool
+description: mcpTargetRequiresSession lets the transport answer 401 with an OAuth challenge, because the MCP response streams and the status is gone by the time the runner refuses
+tags: mcp, permissions, transport
+---
+
+# An MCP refusal is decided before dispatch, not raised from the tool
+
+An MCP client discovers how to authenticate from a `401` carrying a
+`WWW-Authenticate` challenge — that header names the RFC 9728 Protected Resource
+Metadata document, which names the authorization server, which is where OAuth
+starts. Delivered any other way, the refusal is not a refusal: a `MissingSessionError`
+flattened into a JSON-RPC result arrives as `200` with `isError: true`, which a
+client reads as a tool that failed, and no discovery happens.
+
+The obvious implementation — catch the refusal in `tools/call` and set the status
+afterwards — cannot work, and not for a reason a test makes obvious. The MCP HTTP
+response **streams**: the entry returns a `Response` whose body the transport is
+still writing when the JSON-RPC handler runs. Instrumenting both ends shows the
+entry observing its own flag as unset *before* the tool ever refuses. Status and
+headers are chosen at the top of the response; by the time anything knows a
+session was missing, they are already on the wire.
+
+So the decision moves earlier, to the only two things knowable before dispatch:
+which target the request body names, and whether the request presents anything to
+authenticate with. `mcpTargetRequiresSession` answers the first from the same
+declarations the runner enforces — a `pikkuFunc` always needs a session, a
+`pikkuSessionlessFunc` needs one only where it says `auth: true` — so the
+transport's answer and the runner's cannot disagree. An unregistered name is
+treated as open, because a name nobody registered is a `Method not found`, and
+challenging it invites a client to authenticate its way towards a tool that does
+not exist.
+
+This is what makes a single endpoint serve public and private tools together,
+which the MCP spec allows and pikku's per-function `auth` flag already describes.
+`tools/list` stays ungated, so a client can see the menu before it has a token.
+
+**What this rules out:** verifying tokens in the transport. Only a request with
+*no* credentials is challenged; a present-but-expired token is dispatched and its
+refusal reaches the client as a tool error. Doing better means resolving the
+session before dispatch, which runs the app's middleware twice per call and puts
+the transport in the business of second-guessing the middleware that owns session
+resolution. The cheaper half — no credentials at all — covers the case that
+actually matters, because that is the state every client starts in.
+
+Also ruled out: gating the endpoint as a whole with `requireBearerAuth`. It would
+work, and it would make every public tool private, which is a different product.

package/knowledge/decisions/security/an-oauth2-credential-is-read-by-its-account-row.md

@@ -0,0 +1,40 @@
+---
+type: decision
+title: An OAuth2 credential is read by its account row, not by its provider name
+description: better-auth 1.7.5 selects an account by row id under a strict body schema, so BetterAuthCredentialService resolves the row through the internal adapter before asking for a token
+tags: better-auth, credentials, oauth2
+---
+
+# An OAuth2 credential is read by its account row, not by its provider name
+
+A pikku OAuth2 credential is named — `user-oauth`, `company-slack` — and that
+name is the better-auth `providerId` its account row carries. Reading the
+credential used to mean handing better-auth the name:
+`getAccessToken({ body: { providerId, userId } })`.
+
+better-auth 1.7.5 stopped accepting that. `get-access-token` and
+`unlink-account` both take a strict union selecting the account by its **own row
+id**, so a provider name is not merely ignored, it is rejected — `[body] Invalid
+input`, a 500 on every read of a linked credential: a tool's token, an agent's,
+the console's status card. An agent that cannot resolve its credential never
+makes a model call, so the failure surfaces far from its cause.
+
+So the name is resolved to a row first, through
+`context.internalAdapter.findAccounts(userId)` — the same lookup the link
+callback writes the row with and `unlinkAccount` already used. That is also the
+only account lookup that takes a userId at all: `listUserAccounts` resolves the
+*caller's session* and throws UNAUTHORIZED server-side, which is no use for the
+two revocations that have no session — a platform credential, whose owner never
+signs in, and an admin acting on someone else's.
+
+A useful consequence: an unlinked provider is now answered before better-auth is
+asked, rather than by catching its `ACCOUNT_NOT_FOUND`. The catch stays, because
+a failed refresh must still not read as "not connected yet" — that would show a
+connect button for an account that is linked but broken.
+
+**What this rules out:** treating `providerId` as a credential's address
+anywhere a token is read or revoked. It remains the credential's *name* — what
+an app declares and what the link flow writes — but the row id is what
+better-auth is spoken to in. A fake of better-auth that keys tokens by provider
+name will pass while the real thing rejects every call, which is how this
+survived a bump with 222 green unit tests behind it.

package/knowledge/decisions/security/index.md

@@ -34,6 +34,8 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [Agent tool permission filtering reads the live function config, not the metadata](ai-agent-tool-filtering-reads-the-live-function-config.md) — The pikkuAuth brand survives only on live permission objects, so a metadata-driven check would silently admit every gated tool
 - [An agent approval is claimed before the tool runs](an-agent-approval-is-claimed-before-the-tool-runs.md) — resolveApproval is a compare-and-swap returning whether this caller won, because the read that precedes it is not a claim and ten concurrent approvals would otherwise mean ten refunds
 - [An empty owners constraint matches nothing](an-empty-owners-constraint-matches-nothing.md) — owners is an authorization boundary, so every storage backend must treat [] as no rows rather than no filter
+- [An MCP refusal is decided before dispatch, not raised from the tool](an-mcp-refusal-is-decided-before-dispatch.md) — mcpTargetRequiresSession lets the transport answer 401 with an OAuth challenge, because the MCP response streams and the status is gone by the time the runner refuses
+- [An OAuth2 credential is read by its account row, not by its provider name](an-oauth2-credential-is-read-by-its-account-row.md) — better-auth 1.7.5 selects an account by row id under a strict body schema, so BetterAuthCredentialService resolves the row through the internal adapter before asking for a token
 - [An exposed function with no gate is reported at codegen, not at boot](an-exposed-ungated-function-is-a-codegen-warning.md) — The check runs in the inspector where function meta and every wireAddon declaration are both in hand, because neither source alone can tell a gated function from an ungated one
 - [An upload is counted as it arrives, not buffered and then measured](an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md) — Reading the whole body before checking its size hands an unauthenticated caller a way to spend the server's memory
 - [The console addon's privileged functions gate themselves](console-addon-privileged-functions-gate-themselves.md) — Thread listing is owner-scoped unless the caller holds admin, and addon installation requires an admin session, rather than trusting the host to register a global permission

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.112",
+  "version": "0.12.114",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",