@pikku/core 0.12.112 → 0.12.113

package/CHANGELOG.md

@@ -1,3 +1,77 @@
+## 0.12.113
+
+### Patch Changes
+
+- c842054: A pikku command never ends in a node internals warning, and a secret can be set from a script.
+
+  `pikku fabric secrets set NAME` prompted for the value through readline in terminal mode. On a stdin that is not a tty that promise never settles at all, so the command printed `BETTER_AUTH_SECRET value:` and then node's "Detected unsettled top-level await", naming a line of `@pikku/cli`'s own bin — under bun it simply hung. The prompt now reads the first line of stdin when there is no tty, so `echo '<value>' | pikku fabric secrets set NAME` works, and refuses with the flag to reach for (`--value`) when stdin is closed or empty. `promptConfirm` gained the same backstop, so a caller that forgets its `isTTY` gate gets a refusal instead of a hang.
+
+  Alongside it, the places a raw stack could still reach a user:
+
+  - The `pikku` binary formats through `formatCLIError` instead of printing `error.message`, and installs `uncaughtException` / `unhandledRejection` handlers so nothing escaping a listener or a floating promise is dumped unformatted. A `CLIError` the runner already printed is no longer printed twice.
+  - The generated local and channel CLI bootstraps do the same, rather than `console.error('Fatal error:', error.message)` — which dropped the stack even when one was asked for.
+  - A missing `pikku.config.json` says where it looked and what to do, as a `PikkuCLIConfigError`, which is now a `PikkuError` along with `GitError` and every remaining plain `Error` raised by a `pikku fabric` command. A directory-wide test keeps it that way.
+  - `pikku dev`'s watcher and the MCP schema loader log their causes through the logger at debug level instead of `console.error(err)` over the top of the output.
+
+  Stacks are unchanged where they are the answer: an unexpected error still keeps its frames, and `--verbose` / `PIKKU_DEBUG` still prints the stack for a deliberate one. `formatCLIError` and `wantsStackTrace` are exported from `@pikku/core/cli` so every entrypoint that can be the last thing to catch an error prints it the same way.
+
+- dfd7019: An MCP tool reads the claims its host verified
+
+  `PikkuHTTP` gains an `authInfo` of the new `PikkuHTTPAuthInfo`: the token,
+  client and scopes a transport that already verified a bearer token hands on.
+  It is strictly pass-through — nothing in pikku derives it from a request's own
+  headers, because verifying a token is the host's job. A function could always
+  read the `Authorization` header itself; what this adds is what the raw header
+  cannot carry.
+
+  `PikkuMCPServer`'s server factory now carries the SDK's `authInfo` onto the
+  wire beside the request, so the `authInfo` a host passes to
+  `createFetchHandler` reaches the tool rather than stopping at the SDK.
+
+  `pikkuCredentialOAuth` also names itself when it provisions the platform user.
+  Every other pikku plugin passes a source to `internalAdapter.createUser`, and
+  better-auth refuses a `user.validateUserInfo` gate that is handed none — so an
+  app with that hook configured could not link a singleton credential at all.
+
+- dfd7019: An MCP call that needs a session is refused with an OAuth challenge
+
+  A tool fronting a session-requiring function used to answer an unauthenticated
+  caller with `200` and `isError: true`, which a client reads as a tool that
+  broke rather than one it has not authenticated for — so OAuth discovery never
+  began. Such a call now gets `401` with a `WWW-Authenticate: Bearer` challenge
+  naming the resource metadata, and `/.well-known/oauth-protected-resource` is
+  served alongside the MCP endpoint.
+
+  The endpoint is not gated as a whole. `mcpTargetRequiresSession` reads the
+  declarations the runner already enforces — a `pikkuFunc` needs a session, a
+  `pikkuSessionlessFunc` needs one only where it says `auth: true` — so public
+  and private tools can share one server and only the private ones are
+  challenged.
+
+  `createFetchHandler` and `createHTTPRequestHandler` take an optional `auth`
+  describing what to advertise (`authorizationServers`, `scopesSupported`,
+  `resourceName`), surfaced on both servers as an `mcpAuth` option. Every field
+  defaults from the request, because a pikku app is usually its own
+  authorization server. Both handlers now also return `ownsPath`, because the
+  discovery document lives outside `mcpPath` and a host routing on the endpoint
+  alone would 404 the document its own challenge points at.
+
+- 9b978e7: A failed SSE stream reports the error in the protocol its client is parsing
+
+  An SSE route can now declare `streamProtocol: 'agui'`, and the generated agent
+  stream and resume routes do. A function that throws mid-stream then ends the
+  stream with a single AG-UI `RUN_ERROR` instead of Pikku's `error`/`done` frames,
+  which an AG-UI client could only surface as a Zod parse failure with the real
+  message nowhere in sight.
+
+- 1469e73: The app names which of an addon's functions reach MCP
+
+  `wireAddon`'s `mcp` takes a list as well as `true`. `true` still offers every
+  function the addon declared `mcp: true`; a list names the tools this deployment
+  offers, whether or not the addon declared them, and is typed against the
+  function names that addon publishes — a typo is a compile error rather than a
+  tool silently missing from the menu.
+
 ## 0.12.112
 
 ### Patch Changes

package/dist/wirings/addon/wire-addon.d.ts

@@ -8,8 +8,13 @@ export type WireAddonConfig = {
     rpcEndpoint?: string;
     /** Requires a session for every function in the addon, whatever each one declares. Gates an addon whose functions are individually open. */
     auth?: boolean;
-    /** Offers the addon's functions to MCP clients as tools, without wiring each one. */
-    mcp?: boolean;
+    /**
+     * Offers the addon's functions to MCP clients as tools, without wiring each
+     * one. `true` offers every function the addon itself declared `mcp: true`; a
+     * list names the functions to offer, whether or not the addon declared them,
+     * and is typed against the addon's function names.
+     */
+    mcp?: boolean | string[];
     /** Filters this addon in and out of a build — see the `tags` option on `pikku all`. It has no effect at runtime. */
     tags?: string[];
     /** Required of every function in the addon, on top of the function's own. */

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

@@ -1,4 +1,10 @@
 export { wireCLI, runCLICommand, pikkuCLIRender, executeCLI, CLIError, } from './cli-runner.js';
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js';
 export { defineCLICommands } from './define-cli-commands.js';
+/**
+ * Exported so every entrypoint that can be the last thing to catch an error —
+ * the `pikku` binary, a generated bootstrap, a channel client — prints it the
+ * same way, instead of each inventing its own `console.error(error.message)`.
+ */
+export { formatCLIError, wantsStackTrace } from './format-cli-error.js';
 export type { CLIMeta, CLICommandMeta, CLIProgramMeta, CoreCLI, CoreCLICommandConfig, CorePikkuCLIRender, } from './cli.types.js';

package/dist/wirings/cli/index.js

@@ -1,3 +1,9 @@
 export { wireCLI, runCLICommand, pikkuCLIRender, executeCLI, CLIError, } from './cli-runner.js';
 export { parseCLIArguments, generateCommandHelp } from './command-parser.js';
 export { defineCLICommands } from './define-cli-commands.js';
+/**
+ * Exported so every entrypoint that can be the last thing to catch an error —
+ * the `pikku` binary, a generated bootstrap, a channel client — prints it the
+ * same way, instead of each inventing its own `console.error(error.message)`.
+ */
+export { formatCLIError, wantsStackTrace } from './format-cli-error.js';

package/dist/wirings/http/http-routes.js

@@ -54,6 +54,7 @@ function registerRoute(route, groupConfig) {
         timeout: route.timeout,
         headers: route.headers,
         sse: route.sse,
+        streamProtocol: route.streamProtocol,
         // `CoreHTTPFunctionWiring` is discriminated by `method`, and a group builds
         // its routes from a method chosen at runtime — no arm can be narrowed to.
     });

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

@@ -6,6 +6,7 @@ import { getErrorResponse } from '../../errors/error-handler.js';
 import { handleHTTPError } from '../../handle-error.js';
 import { isProduction } from '../../env.js';
 import { pikkuState } from '../../pikku-state.js';
+import { streamErrorFrames } from './http-stream-protocol.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 import { PikkuFetchHTTPRequest } from './pikku-fetch-http-request.js';
 // The leaf module, not the channel-rpc barrel: http needs one refusal
@@ -194,11 +195,10 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             singletonServices.logger.error(e instanceof Error ? e.message : e);
             try {
                 const errorResponse = getErrorResponse(e);
-                http?.response?.arrayBuffer(JSON.stringify({
-                    type: 'error',
-                    errorText: errorResponse?.message ?? 'Internal server error',
-                }));
-                http?.response?.arrayBuffer(JSON.stringify({ type: 'done' }));
+                const message = errorResponse?.message ?? 'Internal server error';
+                for (const frame of streamErrorFrames(matchedRoute.route.streamProtocol, message)) {
+                    http?.response?.arrayBuffer(JSON.stringify(frame));
+                }
             }
             catch { }
             channel?.close();

package/dist/wirings/http/http-stream-protocol.d.ts

@@ -0,0 +1,12 @@
+import type { HTTPStreamProtocol } from './http.types.js';
+/**
+ * The frames that terminate a stream whose function threw after the response
+ * was already committed to streaming.
+ *
+ * A stream's consumer parses every frame against the protocol it was promised,
+ * so an error announced in the wrong one reaches it as a parser failure with
+ * the actual message nowhere in sight. AG-UI accepts `RUN_ERROR` as the first
+ * event as readily as the last, and forbids anything after it, so a failure
+ * there is that one frame — never a trailing `done`.
+ */
+export declare const streamErrorFrames: (protocol: HTTPStreamProtocol | undefined, message: string) => Array<Record<string, unknown>>;

package/dist/wirings/http/http-stream-protocol.js

@@ -0,0 +1,16 @@
+/**
+ * The frames that terminate a stream whose function threw after the response
+ * was already committed to streaming.
+ *
+ * A stream's consumer parses every frame against the protocol it was promised,
+ * so an error announced in the wrong one reaches it as a parser failure with
+ * the actual message nowhere in sight. AG-UI accepts `RUN_ERROR` as the first
+ * event as readily as the last, and forbids anything after it, so a failure
+ * there is that one frame — never a trailing `done`.
+ */
+export const streamErrorFrames = (protocol, message) => {
+    if (protocol === 'agui') {
+        return [{ type: 'RUN_ERROR', message }];
+    }
+    return [{ type: 'error', errorText: message }, { type: 'done' }];
+};

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,4 @@
 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, } 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, } from './mcp-runner.js';

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

@@ -32,3 +32,18 @@ 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;

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

@@ -187,3 +187,41 @@ 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) => {
+    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;
+};

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.113",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -216,6 +216,7 @@
     "getMCPPromptsMeta",
     "getMCPResourcesMeta",
     "getMCPToolsMeta",
+    "mcpTargetRequiresSession",
     "runMCPPrompt",
     "runMCPResource",
     "runMCPTool",
@@ -263,6 +264,18 @@
     "pikkuAgentScorer",
     "wireAgentScorerQueueWorkers"
   ],
+  "./analytics": [
+    "LoggerAnalyticsService",
+    "anonymousAnalyticsIdentity",
+    "composeAnalyticsIdentity",
+    "cookieAnalyticsIdentity",
+    "createInvocationAnalytics",
+    "defineAnalyticsEvents",
+    "fanOutAnalytics",
+    "flattenAnalyticsEvent",
+    "mintCookie",
+    "randomDigits"
+  ],
   "./gateway": [
     "createListenerMessageHandler",
     "resolveGatewayAdapter",
@@ -272,10 +285,12 @@
     "CLIError",
     "defineCLICommands",
     "executeCLI",
+    "formatCLIError",
     "generateCommandHelp",
     "parseCLIArguments",
     "pikkuCLIRender",
     "runCLICommand",
+    "wantsStackTrace",
     "wireCLI"
   ],
   "./cli/command-parser": [
@@ -563,17 +578,5 @@
     "pikkuDevReloader",
     "reconcileAddonRegistry",
     "reloadGeneratedMeta"
-  ],
-  "./analytics": [
-    "LoggerAnalyticsService",
-    "anonymousAnalyticsIdentity",
-    "composeAnalyticsIdentity",
-    "cookieAnalyticsIdentity",
-    "createInvocationAnalytics",
-    "defineAnalyticsEvents",
-    "fanOutAnalytics",
-    "flattenAnalyticsEvent",
-    "mintCookie",
-    "randomDigits"
   ]
 }