@pikku/core 0.12.112 → 0.12.114

package/CHANGELOG.md

@@ -1,3 +1,140 @@
+## 0.12.114
+
+### Patch Changes
+
+- cb8f57e: Global middleware now runs for a dispatch that belongs to an addon, not just for one in the root namespace.
+
+  `combineMiddleware` read the global list out of a single namespace — the `packageName` the dispatch carried. For anything wired by the application itself that namespace is `null`, so it worked; for a wiring contributed by an addon (an MCP tool registered through `wireAddon({ mcp: [...] })`, say) it was the addon's own package name, and the application's globals were simply not in that list. The practical effect was that an addon's tools ran with no session middleware at all: every one of them refused with "authentication required" no matter who was calling, while the identical function reached through HTTP authenticated fine.
+
+  Global middleware is application-wide by definition, and an addon's function is still running inside the host application, so the root namespace always applies. A dispatch in the root namespace resolves `[null]` as before; one in an addon resolves `[null, packageName]` — the host's globals first, then the addon's own. Globals registered by one addon still do not reach another's dispatches.
+
+- cb8f57e: MCP clients can now discover that a server needs signing in to, and can see tools whose names carry a namespace.
+
+  Three separate reasons a client ended up connected to a server it could do nothing with:
+
+  - **The handshake was never challenged.** A client decides at connection time whether a server speaks OAuth, and all it has to go on is whether `initialize` came back `401` with a `WWW-Authenticate` challenge. Answering it `200` and then refusing every subsequent call told the client "no sign-in needed" and then gave it nothing — Claude's connector setup, for one, reported the server as open access. `initialize` is now challenged when `mcpEveryTargetRequiresSession()` holds, which is the only case where answering it openly is a lie; a server with even one open target still completes the handshake unauthenticated, as it should.
+  - **Namespaced names were dropped on the floor.** MCP constrains tool and prompt names to `[A-Za-z0-9_-]{1,64}`, and pikku's namespace separator is `:`. Clients discard the names they cannot accept rather than failing the connection, so an addon's entire surface went missing with nothing more than a note about "tools with unsupported names". Names are now rewritten at the transport boundary (`mcpWireName`) and resolved back on the way in (`mcpResolveWireName`), so `bb2:getMe` is offered as `bb2_getMe` and calls to it dispatch correctly. The registry keeps its own spelling, since that is what dispatch keys on, and a tool genuinely registered under the wire spelling still wins over a rewritten match.
+  - **An addon-only app generated no tool metadata.** `pikku all` decided whether to emit the MCP file from the set of source files calling `wireMCPTool`/`Resource`/`Prompt`. An addon that contributes its tools through `wireAddon({ mcp: [...] })` adds none, so an application whose only MCP surface came from addons got neither wirings nor meta — the tools were listed from `mcp.gen.json` and then every call failed to resolve, because `toolsMeta` (which carries the `pikkuFuncId`) had never been written. Content now decides; the file set only decides whether there are imports to serialize.
+
+  Also in here: the resource URL advertised in the challenge honours `X-Forwarded-Proto` and `X-Forwarded-Host`, so a server behind a TLS-terminating proxy advertises the `https://` URL the client actually reached rather than its own internal `http://` origin — which the client would reject as a resource mismatch.
+
+- 6db6a14: A wiring can now decide whether an addon's credential is per-user or deployment-wide
+
+  `wireAddon`'s `credentialOverrides` takes an object as well as a rename string:
+
+  ```ts
+  wireAddon({
+    name: 'gmail',
+    package: '@pikku/addon-gmail',
+    credentialOverrides: {
+      gmailOAuth: { mode: 'wire' }, // each user connects their own
+      calendarOAuth: { name: 'CAL', mode: 'singleton' },
+    },
+  })
+  ```
+
+  An addon author declares a default with `defineCredential`; the deployment decides, so one addon serves both a per-user product and a single team account.
+
+  The wire credential service now resolves each credential by what it _is_ rather than by what a lookup returned: `wire` reads only the user's value, `singleton` reads the deployment's. A per-user credential can no longer pick up a platform-level value because the user has not connected — which, before, would have quietly run someone's request against the deployment's own account.
+
+  A credential is never read from the secret vault. The wire credential service no longer takes a `SecretService` at all, so the only way a credential arrives is the one its mode names — the user's own value, or the deployment's.
+
+  Modes are resolved at generation time into the credentials meta, so the console's connect flow reflects the wiring rather than the addon's default.
+
+  Two credentials that resolve to one name are rejected unless they agree on the mode. Generation writes a single metadata entry per name, so a `wire` credential aliased onto a `singleton` one used to take whichever wiring was read last — a per-user credential served from the deployment's own account, or a deployment credential handed out per user. The inspector reports the collision against both wirings by name, and `buildCredentialResolutions` refuses it at runtime too.
+
+  A mode-only override is checked against the credential it names. `{ mode: 'wire' }` renames nothing, so nothing was validated: an override naming a credential that does not exist was dropped in silence and the credential kept the mode its author declared.
+
+  A credential the wiring resolves as `singleton` is no longer read out of the user's own store. Per-user values are imported first and a name already present is left alone, so a value stored under a singleton's name — from an earlier wiring, or a connect flow since rewired — decided what the deployment's own slot resolved to. It is now skipped by mode, the same way a `wire` credential is kept away from the deployment's value.
+
+  The project's own credentials are registered into pikku state from the generated credentials file, so `wire.getCredential` resolves an app-level singleton the same way it resolves an addon's.
+
+  `pikku new addon` no longer requires a `pikku.config.json` in the working directory. Scaffolding an addon is something you do before a project config exists, so the command now reads one when it is there and falls back to the working directory when it is not.
+
+  An addon's `pikkuAddonWireServices` factory now declares the same service contract its singleton factory does: what it destructures off the parent's bag is required, and what it returns is built by the addon. Before, a service an addon built per wire was demanded from the consumer, and a wire-only addon declared no contract at all. A nested callback that names its own parameter after the factory's is no longer read as the factory's own: what it destructured went onto the addon's contract, so a consumer was asked for a service the addon never wanted from them.
+
+  An OAuth2 credential now implies its app secret, so nobody hand-writes one. The client id and secret an OAuth app needs is the same shape every time — `OAuth2AppCredential`, which is what the runtime already reads it as — so the inspector registers a secret for each credential's `appCredentialSecretId`. A hand-written `defineSecret` covering that id still 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.
+
+  `optional` now means a secret is not reported as missing. `getMissing()` filtered on "not configured" alone, so a secret whose declaration said absence was supported still showed up on the list of things a deployment had to go and supply — burying the ones that genuinely were. `getAllStatus()` still reports it, flagged `optional`.
+
+  An OAuth2 secret carries its declaration's `optional` through code generation, to the app credential and to the token store alike: nobody connects without the client id and secret, so a deployment allowed to omit the app is never asked for its tokens either. That branch never looked at the flag before.
+
+  `credentialOAuthProviders` treats an app secret that resolves `undefined` as unconfigured. An optional secret resolves rather than throws, so the absence arrived past the `catch` that was meant to skip the provider — and `.reveal()` on it threw a `TypeError` that took every `getSession` down with it, which is the exact failure that code exists to prevent.
+
+## 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/function/function-runner.js

@@ -11,6 +11,7 @@ import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js';
 import { verifyScopes } from '../scopes.js';
 import { assertFeatureAvailable } from '../wirings/flag/assert-feature-available.js';
 import { PikkuCredentialWireService, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
+import { buildCredentialResolutions, credentialOverrideAliases, } from '../wirings/credential/credential-overrides.js';
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
 import { createInvocationAudit, resolveAuditConfig, } from '../services/audit-service.js';
 import { createInvocationAnalytics } from '../analytics/analytics.js';
@@ -125,6 +126,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     const resolvedWire = allChannelMiddleware.length > 0 && wire.channel
         ? wrapChannelWithMiddleware(wire, resolvedSingletonServices, allChannelMiddleware)
         : wire;
+    const declaredCredentials = pikkuState(funcPackageName ?? null, 'package', 'credentialsMeta');
     // Set up early so middleware can use setCredential. An addon instance with
     // credentialOverrides always gets a fresh alias-aware service, even when a
     // parent credential service is already present on the wire.
@@ -132,12 +134,16 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         // Credentials belong to the consuming project, so resolve them via the
         // project's credentialService (the addon's own singletons may not carry it).
         const aliasedCredentialWireService = new PikkuCredentialWireService(singletonServices.credentialService ??
-            resolvedSingletonServices.credentialService, resolvedWire, addonInstance.credentialOverrides);
+            resolvedSingletonServices.credentialService, resolvedWire, credentialOverrideAliases(addonInstance.credentialOverrides), {
+            resolutions: buildCredentialResolutions(declaredCredentials, addonInstance.credentialOverrides),
+        });
         Object.assign(resolvedWire, createWireServicesCredentialWireProps(aliasedCredentialWireService));
     }
     else if (!resolvedWire.getCredentials) {
         const resolvedCredentialWireService = credentialWireService ??
-            new PikkuCredentialWireService(resolvedSingletonServices.credentialService, resolvedWire);
+            new PikkuCredentialWireService(resolvedSingletonServices.credentialService, resolvedWire, undefined, {
+                resolutions: buildCredentialResolutions(declaredCredentials, undefined),
+            });
         Object.assign(resolvedWire, createWireServicesCredentialWireProps(resolvedCredentialWireService));
     }
     const resolvedAuditConfig = resolveAuditConfig(funcConfig.audit);

package/dist/middleware-runner.js

@@ -88,9 +88,14 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
         return middlewareCache[wireType][uid];
     }
     const resolved = [];
-    const globals = pikkuState(packageName, 'middleware', 'global');
-    if (globals && globals.length > 0) {
-        resolved.push(...globals);
+    // Global middleware is application-wide, so the root namespace always
+    // applies — an addon's function still runs inside the host application.
+    // See `global-middleware-resolves-from-the-root-namespace-too.md`.
+    for (const ns of packageName === null ? [null] : [null, packageName]) {
+        const globals = pikkuState(ns, 'middleware', 'global');
+        if (globals && globals.length > 0) {
+            resolved.push(...globals);
+        }
     }
     if (wireInheritedMiddleware) {
         for (const meta of wireInheritedMiddleware) {

package/dist/services/credential-wire-service.d.ts

@@ -1,13 +1,29 @@
 import type { CredentialService } from './credential-service.js';
 import type { PikkuRawWire } from '../types/core.types.js';
+/**
+ * Where one credential's value is read from. Decided by what the credential IS
+ * — its declared type, as the wiring may have overridden it — and never by
+ * whether a per-user lookup came back empty. An absence-driven fallback would
+ * let a user who has not connected read the deployment's own token.
+ */
+export type CredentialResolution = {
+    mode: 'wire';
+} | {
+    mode: 'singleton';
+};
+export type CredentialResolutionConfig = {
+    /** Keyed by the resolved (post-alias) credential name. */
+    resolutions: Record<string, CredentialResolution>;
+};
 export declare class PikkuCredentialWireService {
     private credentialService?;
     private wire?;
     private aliases?;
+    private resolution?;
     private credentials;
     private loaded;
     private loadPromise;
-    constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined);
+    constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined, resolution?: CredentialResolutionConfig | undefined);
     private resolveName;
     /**
      * A credential is one of the few places vault material is meant to end up, so
@@ -35,6 +51,20 @@ export declare class PikkuCredentialWireService {
      * nothing to fetch — so they should reach the fast path too.
      */
     private doLoad;
+    /**
+     * The other half of resolving by type. A user's own store can hold a value
+     * under a name the wiring made `singleton` — from an earlier wiring, or a
+     * connect flow that has since been rewired — and importing it would put the
+     * user in charge of a slot the deployment owns. What `set` wrote is left
+     * alone: that is the deployment's own path, not the user's.
+     */
+    private isSingleton;
+    /**
+     * The `singleton` half of the dispatch. `wire` is absent here on purpose:
+     * those values arrive with `getAll(userId)` above, so a wire credential can
+     * never pick up a platform value that happens to exist.
+     */
+    private loadDeploymentCredentials;
 }
 export declare function createMiddlewareCredentialWireProps(credentialWire: PikkuCredentialWireService): {
     setCredential: (name: string, value: unknown) => void;

package/dist/services/credential-wire-service.js

@@ -4,13 +4,15 @@ export class PikkuCredentialWireService {
     credentialService;
     wire;
     aliases;
+    resolution;
     credentials = {};
     loaded = false;
     loadPromise;
-    constructor(credentialService, wire, aliases) {
+    constructor(credentialService, wire, aliases, resolution) {
         this.credentialService = credentialService;
         this.wire = wire;
         this.aliases = aliases;
+        this.resolution = resolution;
     }
     resolveName(name) {
         return this.aliases?.[name] ?? name;
@@ -73,23 +75,58 @@ export class PikkuCredentialWireService {
      */
     async doLoad() {
         try {
-            if (!this.credentialService || !this.wire)
+            if (!this.credentialService && !this.resolution)
                 return;
-            const userId = defaultPikkuUserIdResolver(this.wire);
-            if (!userId)
-                return;
-            this.wire.pikkuUserId = userId;
-            const allCreds = await this.credentialService.getAll(userId);
-            for (const [name, value] of Object.entries(allCreds)) {
-                if (!(name in this.credentials)) {
-                    this.credentials[name] = value;
+            const userId = this.wire
+                ? defaultPikkuUserIdResolver(this.wire)
+                : undefined;
+            if (this.credentialService && this.wire && userId) {
+                this.wire.pikkuUserId = userId;
+                const allCreds = await this.credentialService.getAll(userId);
+                for (const [name, value] of Object.entries(allCreds)) {
+                    if (this.isSingleton(name))
+                        continue;
+                    if (!(name in this.credentials)) {
+                        this.credentials[name] = value;
+                    }
                 }
             }
+            await this.loadDeploymentCredentials();
         }
         finally {
             this.loaded = true;
         }
     }
+    /**
+     * The other half of resolving by type. A user's own store can hold a value
+     * under a name the wiring made `singleton` — from an earlier wiring, or a
+     * connect flow that has since been rewired — and importing it would put the
+     * user in charge of a slot the deployment owns. What `set` wrote is left
+     * alone: that is the deployment's own path, not the user's.
+     */
+    isSingleton(name) {
+        return this.resolution?.resolutions[name]?.mode === 'singleton';
+    }
+    /**
+     * The `singleton` half of the dispatch. `wire` is absent here on purpose:
+     * those values arrive with `getAll(userId)` above, so a wire credential can
+     * never pick up a platform value that happens to exist.
+     */
+    async loadDeploymentCredentials() {
+        const resolutions = this.resolution?.resolutions;
+        if (!resolutions)
+            return;
+        if (!this.credentialService)
+            return;
+        for (const [name, resolution] of Object.entries(resolutions)) {
+            if (resolution.mode === 'wire' || name in this.credentials)
+                continue;
+            const value = await this.credentialService.get(name);
+            if (value !== null) {
+                this.credentials[name] = value;
+            }
+        }
+    }
 }
 export function createMiddlewareCredentialWireProps(credentialWire) {
     return {

package/dist/services/typed-secret-service.d.ts

@@ -13,6 +13,8 @@ export interface CredentialStatus {
     name: string;
     displayName: string;
     isConfigured: boolean;
+    /** Declared `optional: true`, so absence is a supported state rather than a misconfiguration. */
+    optional?: boolean;
     oauth2?: {
         tokenSecretId: string;
     };
@@ -42,5 +44,14 @@ export declare class TypedSecretService<TMap = Record<string, unknown>> implemen
     deleteSecret(key: string): Promise<void>;
     getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     getAllStatus(): Promise<CredentialStatus[]>;
+    /**
+     * The secrets a deployment still has to supply.
+     *
+     * An optional one is absent from this list however it is stored: `optional`
+     * already declares that absence is supported, which is why `getSecret`
+     * resolves `undefined` for it rather than throwing. Reporting it as missing
+     * contradicts that, and buries the required secrets someone actually has to
+     * go and configure. `getAllStatus` still reports it, flagged.
+     */
     getMissing(): Promise<CredentialStatus[]>;
 }

package/dist/services/typed-secret-service.js

@@ -65,13 +65,23 @@ export class TypedSecretService {
                 name: meta.name,
                 displayName: meta.displayName,
                 isConfigured: await this.secrets.hasSecret(secretId),
+                optional: meta.optional,
                 oauth2: meta.oauth2,
             });
         }
         return results;
     }
+    /**
+     * The secrets a deployment still has to supply.
+     *
+     * An optional one is absent from this list however it is stored: `optional`
+     * already declares that absence is supported, which is why `getSecret`
+     * resolves `undefined` for it rather than throwing. Reporting it as missing
+     * contradicts that, and buries the required secrets someone actually has to
+     * go and configure. `getAllStatus` still reports it, flagged.
+     */
     async getMissing() {
         const all = await this.getAllStatus();
-        return all.filter((c) => !c.isConfigured);
+        return all.filter((c) => !c.isConfigured && !c.optional);
     }
 }

package/dist/types/state.types.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrides } from '../wirings/credential/credential-overrides.js';
 import type { PikkuErrorConstructor, ErrorDetails } from '../errors/error-handler.js';
 import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
 import type { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js';
@@ -43,7 +44,7 @@ export interface PikkuPackageState {
             /** Per-instance name-aliases: logical name the addon reads -> actual project variable name */
             variableOverrides?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
-            credentialOverrides?: Record<string, string>;
+            credentialOverrides?: CredentialOverrides;
             /** Secrets the host lends this instance, named as the addon reads them */
             secretGrants?: string[];
             /** Credentials the host lends this instance, named as the addon reads them */

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

@@ -1,9 +1,10 @@
 import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { CredentialOverrides } from '../credential/credential-overrides.js';
 export type AddonInstance = {
     namespace: 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/addon/wire-addon.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 export type WireAddonConfig = {
     /** How this instance is addressed. One package may be wired more than once, and the name is what tells the instances apart. */
@@ -8,8 +9,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. */
@@ -18,8 +24,12 @@ export type WireAddonConfig = {
     secretOverrides?: Record<string, string>;
     /** Points a variable the addon reads at a different key in this deployment. */
     variableOverrides?: Record<string, string>;
-    /** Points a credential the addon reads at a different key in this deployment. */
-    credentialOverrides?: Record<string, string>;
+    /**
+     * Points a credential the addon reads at a different key in this deployment,
+     * and — in the object form — decides whether it is per-user or
+     * deployment-wide. An addon declares a default; the wiring decides.
+     */
+    credentialOverrides?: CredentialOverrides;
     /** Extra secrets this instance may read, named as the addon reads them — the scope check runs before `secretOverrides` renames them. */
     secretGrants?: string[];
     /** Credentials this instance may read on top of the ones it declared. */

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/credential/credential-overrides.d.ts

@@ -0,0 +1,26 @@
+import type { CredentialResolution } from '../../services/credential-wire-service.js';
+/**
+ * How one credential is wired into a deployment. A bare string renames it, as
+ * it always has. The object form also decides where its value is read from,
+ * which is what lets one addon serve a per-user product and a single team
+ * account without the addon author choosing for both.
+ */
+export type CredentialOverride = string | {
+    /** The key this deployment holds the value under. */
+    name?: string;
+    /** `wire` is per user, `singleton` is one value for the deployment. */
+    mode?: 'singleton' | 'wire';
+};
+export type CredentialOverrides = Record<string, CredentialOverride>;
+/** The rename half, in the `Record<string, string>` shape the alias path wants. */
+export declare const credentialOverrideAliases: (overrides: CredentialOverrides | undefined) => Record<string, string>;
+/**
+ * Where each credential the package declared is read from, keyed by the
+ * resolved name so the wire service can look it up without re-aliasing.
+ *
+ * A credential with no override keeps the type its author declared, which is
+ * what makes an addon that reads one way work under either wiring.
+ */
+export declare const buildCredentialResolutions: (declared: Record<string, {
+    type?: string;
+}> | null | undefined, overrides: CredentialOverrides | undefined) => Record<string, CredentialResolution>;

package/dist/wirings/credential/credential-overrides.js

@@ -0,0 +1,45 @@
+/** The rename half, in the `Record<string, string>` shape the alias path wants. */
+export const credentialOverrideAliases = (overrides) => {
+    const aliases = {};
+    for (const [name, override] of Object.entries(overrides ?? {})) {
+        const target = typeof override === 'string' ? override : override.name;
+        if (target) {
+            aliases[name] = target;
+        }
+    }
+    return aliases;
+};
+/**
+ * Where each credential the package declared is read from, keyed by the
+ * resolved name so the wire service can look it up without re-aliasing.
+ *
+ * A credential with no override keeps the type its author declared, which is
+ * what makes an addon that reads one way work under either wiring.
+ */
+export const buildCredentialResolutions = (declared, overrides) => {
+    const resolutions = {};
+    const names = new Set([
+        ...Object.keys(declared ?? {}),
+        ...Object.keys(overrides ?? {}),
+    ]);
+    /** Which declaration put each resolution there, for the collision message. */
+    const claimedBy = {};
+    for (const name of names) {
+        const override = overrides?.[name];
+        const resolved = (typeof override === 'string' ? override : override?.name) ?? name;
+        const mode = (typeof override === 'object' ? override.mode : undefined) ??
+            declared?.[name]?.type;
+        const resolution = mode === 'singleton' ? { mode: 'singleton' } : { mode: 'wire' };
+        const existing = resolutions[resolved];
+        if (existing && existing.mode !== resolution.mode) {
+            throw new Error(`Credentials '${claimedBy[resolved]}' and '${name}' both resolve to '${resolved}' ` +
+                `but disagree on how it is read: '${existing.mode}' and '${resolution.mode}'. ` +
+                `Only one mode can win, so the loser would silently read the other's ` +
+                `value — a per-user credential served from the deployment's own account, ` +
+                `or the reverse. Give them separate names, or wire both to the same mode.`);
+        }
+        resolutions[resolved] = resolution;
+        claimedBy[resolved] = name;
+    }
+    return resolutions;
+};

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

@@ -1,3 +1,5 @@
 export { defineCredential } from './define-credential.js';
 export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js';
 export type { CoreCredential, CredentialDefinitionsMeta, CredentialDefinitions, } from './credential.types.js';
+export { credentialOverrideAliases, buildCredentialResolutions, } from './credential-overrides.js';
+export type { CredentialOverride, CredentialOverrides, } from './credential-overrides.js';

package/dist/wirings/credential/index.js

@@ -1,2 +1,3 @@
 export { defineCredential } from './define-credential.js';
 export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js';
+export { credentialOverrideAliases, buildCredentialResolutions, } from './credential-overrides.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' }];
+};