@pikku/core 0.12.111 → 0.12.113

package/CHANGELOG.md

@@ -1,3 +1,90 @@
+## 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
+
+- 02eeffb: fix: hot reload reads the changed source instead of a leftover compiled copy
+
+  `pikku dev` announced `Hot-reloaded: <fn>` and kept serving the previous
+  implementation whenever a `.js` from an earlier `tsc`, `pikku dist` or bundler
+  run sat beside the edited `.ts` — the reloader preferred that file, and dev
+  never rebuilds it. The changed source is now what runs, and the module runner
+  resolves and compiles the project's own TypeScript dependencies so a helper
+  edited alongside its caller reloads with it.
+
 ## 0.12.111
 
 ### Patch Changes

package/dist/dev/hot-reload.d.ts

@@ -3,7 +3,6 @@ export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 interface PikkuDevReloaderOptions {
     srcDirectories: string[];
     logger: Logger;
-    pikkuDir?: string;
 }
 export interface PikkuDevReloaderHandle {
     close: () => void;

package/dist/dev/hot-reload.js

@@ -1,5 +1,4 @@
 import { watch } from 'node:fs';
-import { stat } from 'node:fs/promises';
 import { basename, join, resolve, relative } from 'node:path';
 import { pikkuState } from '../pikku-state.js';
 import { clearMiddlewareCache } from '../middleware-runner.js';
@@ -14,24 +13,6 @@ const isFunctionConfig = (value) => {
         'func' in value &&
         typeof value.func === 'function');
 };
-const findCompiledFile = async (tsFile, srcDir, pikkuDir) => {
-    const rel = relative(srcDir, tsFile).replace(/\.ts$/, '.js');
-    const candidates = [
-        join(pikkuDir, 'dist', rel),
-        join(srcDir, rel),
-        tsFile.replace(/\.ts$/, '.js'),
-    ];
-    for (const candidate of candidates) {
-        try {
-            await stat(candidate);
-            return candidate;
-        }
-        catch {
-            // not found, try next
-        }
-    }
-    return null;
-};
 const isWatchedTsFile = (filename) => {
     return (filename.endsWith('.ts') &&
         !filename.endsWith('.test.ts') &&
@@ -55,9 +36,8 @@ const reloadFailureReason = (error) => {
     return `  ${error.stack ?? error.message}`;
 };
 export async function pikkuDevReloader(options) {
-    const { srcDirectories, logger, pikkuDir = '.pikku' } = options;
+    const { srcDirectories, logger } = options;
     const absSrcDirs = srcDirectories.map((d) => resolve(d));
-    const absPikkuDir = resolve(pikkuDir);
     const watchers = [];
     const functionsMap = pikkuState(null, 'function', 'functions');
     const moduleRunner = createModuleRunner();
@@ -68,15 +48,14 @@ export async function pikkuDevReloader(options) {
         const srcDir = absSrcDirs.find((d) => changedTsFile.startsWith(d));
         if (!srcDir)
             return;
-        const compiledFile = await findCompiledFile(changedTsFile, srcDir, absPikkuDir);
-        const importPath = compiledFile ?? changedTsFile;
-        const result = await moduleRunner.run(importPath);
+        // knowledge: decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md
+        const result = await moduleRunner.run(changedTsFile);
         if (!result.ok) {
             // Keeping the old code leaves the process disagreeing with the file on
             // disk, and the only symptom is stale output from a function that looks
             // correct in the editor — so the reason has to be printed here, where it
             // is still known, rather than left for the developer to reconstruct.
-            logger.error(`Failed to import: ${relative(process.cwd(), importPath)} (keeping old code)\n` +
+            logger.error(`Failed to import: ${relative(process.cwd(), changedTsFile)} (keeping old code)\n` +
                 reloadFailureReason(result.error));
             return;
         }

package/dist/dev/module-runner.js

@@ -1,6 +1,6 @@
-import { readFile } from 'node:fs/promises';
+import { readFileSync, statSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { compileFunction } from 'node:vm';
 let transformSync;
@@ -18,7 +18,78 @@ const loadTransform = async () => {
  *  is correct, and no amount of re-reading it will reveal that the reloader —
  *  not the file — is what cannot cope. */
 export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(error.message);
+const TYPESCRIPT_FILE = /\.(m|c)?tsx?$/;
+const isFile = (path) => {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** Where a relative specifier's TypeScript source lives, for the specifiers a
+ *  plain `require` cannot resolve. A TS project writes `./sibling.js` for a file
+ *  that only exists as `./sibling.ts`, and a reloaded module is the source, so
+ *  every one of its relative imports arrives in that unresolvable form. */
+const findTypeScriptSource = (specifier, importerDir) => {
+    if (!specifier.startsWith('.') && !isAbsolute(specifier))
+        return undefined;
+    const base = resolve(importerDir, specifier);
+    const withoutJs = base.replace(/\.(m|c)?js$/, '');
+    const candidates = [
+        `${withoutJs}.ts`,
+        `${withoutJs}.tsx`,
+        `${withoutJs}.mts`,
+        `${withoutJs}.cts`,
+        join(base, 'index.ts'),
+        join(base, 'index.tsx'),
+    ];
+    return candidates.find(isFile);
+};
+const isProjectTypeScript = (path) => TYPESCRIPT_FILE.test(path) && !path.includes(`${sep}node_modules${sep}`);
+/** JSX is a syntax esbuild only parses when asked, so a `.tsx` helper handed to
+ *  the `ts` loader fails to compile and the file importing it keeps its old
+ *  code. */
+const loaderFor = (path) => {
+    if (path.endsWith('.tsx'))
+        return 'tsx';
+    if (TYPESCRIPT_FILE.test(path))
+        return 'ts';
+    if (path.endsWith('.jsx'))
+        return 'jsx';
+    return 'js';
+};
+const evaluateModule = (absPath, cache) => {
+    const cached = cache.get(absPath);
+    if (cached)
+        return cached;
+    const source = readFileSync(absPath, 'utf-8');
+    const { code } = transformSync(source, {
+        loader: loaderFor(absPath),
+        format: 'cjs',
+        sourcefile: absPath,
+    });
+    const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
+    const moduleObj = { exports: {} };
+    // Seeded before evaluation so an import cycle terminates the way CJS's own
+    // cache makes it terminate, and overwritten after because esbuild's `cjs`
+    // emit assigns a fresh `module.exports` on the way out.
+    cache.set(absPath, moduleObj.exports);
+    fn(createRequireForFile(absPath, cache), moduleObj.exports, moduleObj, absPath, dirname(absPath));
+    cache.set(absPath, moduleObj.exports);
+    return moduleObj.exports;
+};
 /** The `require` a reloaded module is run with.
+ *
+ *  Resolution goes through the host first, so every package binds to the
+ *  instance the rest of the process holds and a user file's `wire*` side
+ *  effect mutates live state rather than a private copy.
+ *
+ *  A resolved TypeScript file outside `node_modules` is the project's own
+ *  source, and is compiled here instead of handed back to the host: both hosts
+ *  cache what they load, so a helper edited alongside the function importing it
+ *  would otherwise keep answering with the version loaded at startup — the same
+ *  stale-code-under-a-successful-reload the reloader exists to avoid.
  *
  *  On Bun, `createRequire`'s referrer stops being honoured somewhere in a
  *  long-running process: the same relative specifier that resolves in a fresh
@@ -27,47 +98,55 @@ export const isTopLevelAwaitLimitation = (error) => /top-level await/i.test(erro
  *  is left serving the previous code from an edit that looked applied. Bun's
  *  own resolver still answers correctly when handed the importer's directory
  *  outright, so the specifier is resolved to an absolute path first and the
- *  referrer never has to survive the trip. Anything Bun's resolver declines —
- *  builtins among them — falls through to `require` unchanged.
+ *  referrer never has to survive the trip.
+ *
+ *  What neither host resolves is a relative `./sibling.js` whose only file on
+ *  disk is `./sibling.ts` — node's `require` has no `.js → .ts` rewrite, and
+ *  the reloader hands it source. Those, and only those, are compiled here.
  */
-const createRequireForFile = (absPath) => {
+const createRequireForFile = (absPath, cache) => {
     const base = createRequire(pathToFileURL(absPath));
     const bun = globalThis.Bun;
-    if (!bun)
-        return base;
     const importerDir = dirname(absPath);
-    const resolveThroughBun = (specifier) => {
+    const resolveThroughHost = (specifier) => {
+        if (bun) {
+            try {
+                return bun.resolveSync(specifier, importerDir);
+            }
+            catch {
+                return undefined;
+            }
+        }
         try {
-            return bun.resolveSync(specifier, importerDir);
+            return base.resolve(specifier);
         }
         catch {
-            return specifier;
+            return undefined;
         }
     };
     // Only resolution is delegated; the require itself stays outside the guard so
     // a module that throws while evaluating reports its own error rather than
     // being retried under a second specifier.
-    const bunRequire = ((specifier) => base(resolveThroughBun(specifier)));
-    return Object.assign(bunRequire, base);
+    const loadingRequire = ((specifier) => {
+        const resolved = resolveThroughHost(specifier) ??
+            findTypeScriptSource(specifier, importerDir);
+        if (!resolved)
+            return base(specifier);
+        if (isProjectTypeScript(resolved))
+            return evaluateModule(resolved, cache);
+        return base(resolved);
+    });
+    return Object.assign(loadingRequire, base);
 };
 export const createModuleRunner = () => {
     const registry = new Map();
     const run = async (filePath) => {
         const absPath = resolve(filePath);
         try {
-            const transform = await loadTransform();
-            const source = await readFile(absPath, 'utf-8');
-            const { code } = transform(source, {
-                loader: absPath.endsWith('.ts') ? 'ts' : 'js',
-                format: 'cjs',
-                sourcefile: absPath,
-            });
-            const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
-            const require = createRequireForFile(absPath);
-            const moduleObj = { exports: {} };
-            fn(require, moduleObj.exports, moduleObj, absPath, dirname(absPath));
-            registry.set(absPath, moduleObj.exports);
-            return { ok: true, exports: moduleObj.exports };
+            await loadTransform();
+            const exports = evaluateModule(absPath, new Map());
+            registry.set(absPath, exports);
+            return { ok: true, exports };
         }
         catch (thrown) {
             // A bad edit, or the one known limitation: a file using top-level

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/internals/a-reset-suite-makes-the-dev-seed-the-fixture.md

@@ -0,0 +1,50 @@
+---
+type: decision
+title: With scenarios.reset on, the dev seed is the fixture every assertion is written against
+description: The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
+tags: cli, scenarios
+---
+
+# A reset suite makes the dev seed the fixture
+
+`scenarios.reset` takes a copy of every table when the suite starts and restores
+that copy between scenarios. It is a snapshot-and-restore, not a
+truncate-and-reseed: nothing replays the seed file, and nothing regenerates its
+rows.
+
+Two things follow, and both are easy to get wrong.
+
+**The seed is the fixture.** Before a reset was available, a project usually had
+a hand-rolled reset RPC that wiped and re-created the handful of rows its
+scenarios touched. That RPC was the fixture and the seed was scenery. With the
+rollback on, the whole seed is in scope — every booking, invoice and event a
+developer put there for their own convenience is now a row some scenario can
+count. Assertions written as counts against the old narrow fixture go wrong the
+moment the baseline widens.
+
+**A date literal in the seed expires.** A seed is applied once, and from then on
+the restore keeps handing back the same rows. Write `'2026-03-14'` and the
+fixture is correct on the day it was written and quietly wrong a month later —
+the booking that was supposed to be upcoming is in the past, and the scenario
+that asserts on it fails for a reason that has nothing to do with the code. Seed
+dates belong relative to the moment the seed is applied:
+
+```sql
+INSERT INTO booking (id, starts_at, ends_at) VALUES
+  ('b_upcoming', date('now', '+200 days'), date('now', '+207 days')),
+  ('b_ended',    date('now', '-8 days'),   date('now', '-1 days'));
+```
+
+`date('now', ...)` in sqlite, `now() + interval '200 days'` in postgres. Pick the
+offsets so each row sits unambiguously on the side of whatever boundary the
+scenarios test, rather than a day away from it.
+
+There is a third limit worth stating plainly: the baseline is the database _as
+the suite starts_, so it is not a pristine seed. Run N+1 inherits whatever run N
+left behind. A value that must be unique in the database — an invoice number, a
+reference code — has to be scoped to the run, not hard-coded, or the second run
+collides with the first.
+
+**What this rules out:** treating the reset as "the suite starts from the seed
+every time". It starts from wherever the database was, and keeps returning
+there.

package/knowledge/decisions/internals/hot-reload-reads-the-changed-source-never-a-compiled-copy.md

@@ -0,0 +1,38 @@
+---
+type: decision
+title: Hot reload reads the changed source, never a compiled copy of it
+description: 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
+tags: core, dev
+---
+
+# Hot reload reads the changed source, never a compiled copy of it
+
+The reloader watches `.ts` files and runs the file that changed. It used to
+look for a compiled `.js` first — `<outDir>/dist/<rel>.js`, then the sibling
+`<file>.js` — and import the source only when neither existed.
+
+`pikku dev` compiles nothing. Every one of those `.js` files is a leftover from
+an earlier `tsc`, `pikku dist` or bundler run, so reading one re-registered the
+implementation the developer had just replaced and logged `Hot-reloaded: <fn>`
+over the top of it. The log line reads as confirmation, so the change looks
+applied and wrong rather than unapplied — which is the expensive way round
+(#1721).
+
+The lookup was a leftover of the first implementation, which imported raw file
+content through a `data:` URL and genuinely could not handle TypeScript. The
+module runner has transpiled with esbuild since, so the source was loadable all
+along and the compiled candidates could only ever supply stale code.
+
+Loading the source means the reloader also owns resolution. `require('./x.js')`
+where only `x.ts` exists is what every relative import in a TypeScript project
+looks like, and node's `require` has no `.js → .ts` rewrite. Resolution goes
+through the host first — so packages bind to the instance the rest of the
+process holds and `wire*` side effects mutate live state — and a resolved
+TypeScript file outside `node_modules` is then compiled by the reloader rather
+than handed back, because both node and Bun cache what they load and a helper
+edited alongside its caller would otherwise keep answering with the copy loaded
+at startup. That cache is scoped to a single reload for the same reason.
+
+**What this rules out:** reintroducing a compiled-output lookup as a
+"performance" shortcut, and letting the host load project `.ts` dependencies so
+reloads inherit its module cache.

package/knowledge/decisions/internals/index.md

@@ -12,6 +12,7 @@ caller is entitled to assume.
 <!-- pikku:knowledge-index -->
 
 - [A non-streaming agent run registers with aiRunState on the same terms as a streaming one](a-non-streaming-agent-run-registers-with-airunstate-too.md) — Otherwise interruptAIAgent finds the run, passes the ownership check, then cannot stop it — and reports that as if the run were on another host
+- [With scenarios.reset on, the dev seed is the fixture every assertion is written against](a-reset-suite-makes-the-dev-seed-the-fixture.md) — The rollback restores the database as the suite found it, so seed rows are the shared baseline — which makes an absolute date in the seed a test that expires
 - [A resumed turn is as interruptible as the first one](a-resumed-agent-turn-is-as-interruptible-as-the-first.md) — It is the same person listening to the same voice, and after an approval it is where most of the reply actually gets spoken
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
@@ -73,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
+- [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
 - [HTTP route groups cascade config in a fixed, per-field order](http-route-groups-cascade-config-in-a-fixed-order.md) — basePath concatenates, tags and middleware merge outward-in, auth is overridden by the innermost group

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.111",
+  "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"
   ]
 }