@pikku/core 0.12.64 → 0.12.66

package/dist/wirings/ai-agent/ai-agent-stream.js

@@ -3,9 +3,9 @@ import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { randomUUID } from './ai-agent-utils.js';
 import { combineChannelMiddleware, wrapChannelWithMiddleware, } from '../channel/channel-middleware-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './ai-agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, assertAgentAuthorized, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
-function createPersistingChannel(parent, storage, threadId) {
+function createPersistingChannel(parent, storage, threadId, logger) {
     let fullText = '';
     let stepText = '';
     let stepGenerativeUI = null;
@@ -51,6 +51,22 @@ function createPersistingChannel(parent, storage, threadId) {
             await storage.saveMessages(threadId, messages);
         }
     };
+    /**
+     * `send` is synchronous and so cannot await the flush. A rejection would have
+     * nothing to propagate to and would take the process down as an unhandled
+     * rejection — a model reusing a toolCallId, which is a primary key in AI
+     * storage, is enough to trigger it. Persistence from inside `send` is
+     * therefore best-effort: the run carries on, and the awaited `flush()` on the
+     * suspend paths still surfaces failures to its caller.
+     */
+    const flushDetached = () => {
+        void flushStep().catch((error) => {
+            logger?.error('Failed to persist agent messages', {
+                threadId,
+                error,
+            });
+        });
+    };
     const channel = {
         channelId: parent.channelId,
         openingData: parent.openingData,
@@ -97,10 +113,10 @@ function createPersistingChannel(parent, storage, threadId) {
                         totalUsage.outputTokens += event.tokens.output;
                         if (event.model)
                             totalUsage.model = event.model;
-                        flushStep();
+                        flushDetached();
                         break;
                     case 'done':
-                        flushStep();
+                        flushDetached();
                         break;
                 }
             }
@@ -469,7 +485,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
             ...streamMiddleware,
         ],
     });
-    const persistingChannel = createPersistingChannel(channel, storage, threadId);
+    const persistingChannel = createPersistingChannel(channel, storage, threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;
@@ -578,8 +594,13 @@ export async function resumeAIAgent(input, channel, params, options) {
     if (!pending) {
         throw new Error(`No pending approval for toolCallId ${input.toolCallId} on run ${input.runId}`);
     }
-    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { agent, packageName, resolvedName } = resolveAgent(run.agentName);
+    // Gate before resolving the approval: recording it is a persisted side
+    // effect, so an unauthorized caller must not reach it. Run ownership alone is
+    // not enough — a grant revoked while the run was suspended must stop the
+    // caller from approving its pending tool calls.
+    await assertAgentAuthorized(agent, params, packageName);
+    await aiRunState.resolveApproval(input.toolCallId, input.approved ? 'approved' : 'denied');
     const { storage } = resolveMemoryServices(agent, singletonServices);
     const memoryConfig = agent.memory;
     const agentRunner = singletonServices.aiAgentRunner;
@@ -807,7 +828,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             ...streamMiddleware,
         ],
     });
-    const persistingChannel = createPersistingChannel(channel, storage, run.threadId);
+    const persistingChannel = createPersistingChannel(channel, storage, run.threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;

package/dist/wirings/ai-agent/ai-agent.types.d.ts

@@ -211,7 +211,7 @@ export type AIAgentMemoryConfig = {
     lastMessages?: number;
     workingMemory?: unknown;
 };
-export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
+export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>, Scope extends string = string> = {
     name: string;
     description: string;
     summary?: string;
@@ -244,6 +244,23 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     middleware?: PikkuMiddleware[];
     channelMiddleware?: CorePikkuChannelMiddleware<any, any>[];
     aiMiddleware?: PikkuAIMiddlewareHooks<any, any>[];
+    /**
+     * Whether a session is required to run this agent. Defaults to `false`, since
+     * agents are commonly invoked from an already-authenticated `pikkuFunc` or
+     * from genuinely sessionless contexts (crons, queue workers). Set `true` to
+     * require a session at the agent itself. `scopes` and `permissions` are
+     * enforced either way.
+     */
+    auth?: boolean;
+    /**
+     * Scopes the session must hold to run this agent. All of them are required
+     * (AND), and they are checked before `permissions` — unlike permissions,
+     * which OR together, a scope can only narrow access.
+     *
+     * Narrowed to the generated `ScopeId` union in a project's own
+     * `pikku-types.gen.ts`, so an undeclared scope is a compile error.
+     */
+    scopes?: Scope[];
     permissions?: CorePermissionGroup<PikkuPermission>;
 };
 export type AIStreamEvent = {
@@ -413,6 +430,17 @@ export interface AgentRunService {
     listThreads(options?: {
         agentName?: string;
         resourceId?: string;
+        /**
+         * Restrict results to threads owned by one of these session principals. A
+         * thread matches when its `resourceId` is the principal itself or one of its
+         * `principal:` sub-partitions, mirroring the composition
+         * `resolveOwnerResourceId` writes.
+         *
+         * Unlike `resourceId`, which is an optional exact-match filter, this is an
+         * authorization constraint: an empty array matches nothing. Callers exposing
+         * threads over the wire must derive it from the session, never from input.
+         */
+        owners?: string[];
         limit?: number;
         offset?: number;
     }): Promise<AIThread[]>;

package/dist/wirings/ai-agent/index.d.ts

@@ -4,6 +4,6 @@ export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
 export { voiceInput } from './voice-input.js';
 export { voiceOutput } from './voice-output.js';
-export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
+export { type RunAIAgentParams, type StreamAIAgentOptions, ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';
 export type { AIAgentInput, AIAgentInputAttachment, AIAgentMeta, AIAgentMemoryConfig, AIAgentStep, AIContentPart, AgentRunRow, AgentRunService, AgentRunState, AIMessage, AIStreamChannel, AIStreamEvent, AIThread, CoreAIAgent, PendingApproval, PikkuAIMiddlewareHooks, } from './ai-agent.types.js';

package/dist/wirings/ai-agent/index.js

@@ -4,5 +4,5 @@ export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
 export { voiceInput } from './voice-input.js';
 export { voiceOutput } from './voice-output.js';
-export { ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
+export { ToolApprovalRequired, ToolCredentialRequired, canAccessThread, isOwnedByPrincipal, sessionPrincipals, threadOwnerConstraint, } from './ai-agent-prepare.js';
 export { addAIAgent, approveAIAgent, getAIAgents, getAIAgentsMeta, } from './ai-agent-registry.js';

package/dist/wirings/ai-agent/voice-input.js

@@ -23,8 +23,8 @@ async function fetchAsUint8Array(url, allowedAudioHosts) {
 }
 export const voiceInput = (config) => pikkuAIMiddleware({
     modifyInput: async (services, { messages, instructions }) => {
-        const transcribeAudio = services.aiAgentRunner?.transcribe;
-        if (!transcribeAudio)
+        const aiAgentRunner = services.aiAgentRunner;
+        if (!aiAgentRunner?.transcribe)
             return { messages, instructions };
         const last = messages[messages.length - 1];
         if (!last || last.role !== 'user' || typeof last.content === 'string') {
@@ -51,7 +51,7 @@ export const voiceInput = (config) => pikkuAIMiddleware({
             const audioData = p.data
                 ? base64ToUint8Array(p.data)
                 : await fetchAsUint8Array(p.url, config.allowedAudioHosts);
-            const result = await transcribeAudio({
+            const result = await aiAgentRunner.transcribe({
                 model: config.model,
                 audio: audioData,
                 ...(config.language

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

@@ -319,6 +319,9 @@ export async function executeCLI({ programName, args, createConfig, createSingle
             console.log(helpText);
             return;
         }
+        // Non-fatal diagnostics (unknown options are still accepted) go to stderr
+        // so they never pollute a command's machine-readable stdout.
+        parsed.warnings.forEach((warning) => console.error(`Warning: ${warning}`));
         if (parsed.errors.length > 0) {
             // Check if any error is about an unknown command
             const hasUnknownCommand = parsed.errors.some((error) => error.startsWith('Unknown command:') ||

package/dist/wirings/cli/command-parser.d.ts

@@ -8,6 +8,8 @@ export interface ParsedCommand {
     positionals: Record<string, any>;
     options: Record<string, any>;
     errors: string[];
+    /** Non-fatal diagnostics (e.g. unknown options that were accepted+ignored) */
+    warnings: string[];
 }
 /**
  * Parses raw CLI arguments into structured data for a specific program

package/dist/wirings/cli/command-parser.js

@@ -8,6 +8,54 @@ function toCamelCase(str) {
 function toKebabCase(str) {
     return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
 }
+/** Options the runner handles itself — never reported as unknown. */
+const RESERVED_OPTIONS = new Set(['help']);
+/** Levenshtein distance, capped-free and dependency-free. Used only to suggest
+ *  a near-miss option name, so the naive O(n*m) implementation is fine. */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min(row[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+/** Finds the closest declared option (distance <= 2) to what the user typed.
+ *  Compares against the kebab-case rendering, since that is what is typed. */
+function suggestOption(typed, availableOptions) {
+    let best = null;
+    let bestDistance = 3;
+    for (const name of Object.keys(availableOptions)) {
+        const kebab = toKebabCase(name);
+        const distance = Math.min(levenshtein(typed, kebab), levenshtein(typed, name));
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = kebab;
+        }
+    }
+    return best;
+}
+/** Records a warning that an unknown long option was accepted but ignored.
+ *  Unknown options stay non-fatal for forward compatibility (a newer command
+ *  version may understand them) — they are just no longer silent. */
+function warnUnknownOption(typed, availableOptions, result) {
+    if (RESERVED_OPTIONS.has(toCamelCase(typed))) {
+        return;
+    }
+    const suggestion = suggestOption(typed, availableOptions);
+    result.warnings.push(`Unknown option: --${typed} (ignored)` +
+        (suggestion ? ` Did you mean --${suggestion}?` : ''));
+}
 /**
  * Parses raw CLI arguments into structured data for a specific program
  */
@@ -18,6 +66,7 @@ export function parseCLIArguments(args, programName, allMeta) {
         positionals: {},
         options: {},
         errors: [],
+        warnings: [],
     };
     const meta = allMeta.programs[programName];
     if (!meta) {
@@ -106,7 +155,11 @@ export function parseCLIArguments(args, programName, allMeta) {
                 // --option=value format
                 const key = toCamelCase(arg.slice(2, equalIndex));
                 const optionDef = availableOptions[key];
-                // Unknown options are allowed for forward compatibility
+                // Unknown options are allowed for forward compatibility, but warned
+                // about so they are not silently dropped by the input schema.
+                if (!optionDef) {
+                    warnUnknownOption(arg.slice(2, equalIndex), availableOptions, result);
+                }
                 const value = arg.slice(equalIndex + 1);
                 optionArgs[key] = parseOptionValue(value, optionDef);
             }
@@ -114,7 +167,11 @@ export function parseCLIArguments(args, programName, allMeta) {
                 // --option value format
                 const key = toCamelCase(arg.slice(2));
                 const optionDef = availableOptions[key];
-                // Unknown options are allowed for forward compatibility
+                // Unknown options are allowed for forward compatibility, but warned
+                // about so they are not silently dropped by the input schema.
+                if (!optionDef) {
+                    warnUnknownOption(arg.slice(2), availableOptions, result);
+                }
                 if (optionDef && optionDef.array) {
                     // Array option - collect all following non-flag values
                     currentIndex++;

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

@@ -5,6 +5,13 @@ export type CoreCredential<T = unknown> = {
     description?: string;
     type: 'singleton' | 'wire';
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig & {
         appCredentialSecretId: string;
     };
@@ -15,6 +22,13 @@ export type CredentialDefinitionMeta = {
     description?: string;
     type: 'singleton' | 'wire';
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig & {
         appCredentialSecretId: string;
     };

package/dist/wirings/credential/validate-credential-definitions.js

@@ -31,6 +31,7 @@ export function validateAndBuildCredentialDefinitionsMeta(definitions, schemaLoo
             type: def.type,
             schema: def.schema,
             oauth2: def.oauth2,
+            docsUrl: def.docsUrl,
             sourceFile: def.sourceFile,
         };
     }

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

@@ -1,6 +1,6 @@
 import { pikkuState } from '../../pikku-state.js';
 import { NotFoundError, UnauthorizedError } from '../../errors/errors.js';
-import { addFunction } from '../../function/function-runner.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { runMiddleware } from '../../middleware-runner.js';
 import { httpRouter } from '../http/routers/http-router.js';
 /**
@@ -9,6 +9,52 @@ import { httpRouter } from '../http/routers/http-router.js';
  * requests share one construction).
  */
 const resolvedAdapters = new WeakMap();
+/**
+ * The generated function id a gateway's handler is registered under.
+ */
+const gatewayHandlerFuncId = (name) => `gateway__${name}__handler`;
+/**
+ * Bridges a session established by gateway middleware onto the wire so the
+ * handler's gate can see it.
+ *
+ * Gateway middleware is the only place a webhook can acquire a session (e.g.
+ * mapping a verified platform sender to a user). Middleware that assigns
+ * `wire.session` needs nothing, but middleware using the idiomatic
+ * `wire.setSession()` writes to the enclosing wiring's session service, which
+ * the handler's own invocation does not read — without this the session would
+ * be silently invisible to `auth` and `scopes`.
+ */
+const bridgeMiddlewareSession = async (wire) => {
+    if (wire.session || !wire.getSession)
+        return;
+    const session = await wire.getSession();
+    if (session) {
+        wire.session = session;
+    }
+};
+/**
+ * Registers a gateway's handler as a real pikku function so that invoking it
+ * goes through the function runner's gate. Without this the handler is called
+ * directly and its own `auth`, `scopes` and `permissions` are never evaluated.
+ *
+ * The handler is registered as sessionless: a gateway's inbound traffic is
+ * platform-authenticated (adapter signature verification), not session-bearing,
+ * so requiring a session by default would break every webhook. A handler that
+ * does need one declares `auth: true`, exactly like `pikkuSessionlessFunc`.
+ * `scopes` and `permissions` are always enforced when declared.
+ */
+const registerGatewayHandler = (config) => {
+    const funcId = gatewayHandlerFuncId(config.name);
+    const funcMeta = pikkuState(null, 'function', 'meta');
+    funcMeta[funcId] = {
+        pikkuFuncId: funcId,
+        inputSchemaName: null,
+        outputSchemaName: null,
+        sessionless: true,
+    };
+    addFunction(funcId, config.func);
+    return funcId;
+};
 export const resolveGatewayAdapter = (config, services) => {
     let resolved = resolvedAdapters.get(config);
     if (!resolved) {
@@ -107,12 +153,13 @@ const wireWebhookGateway = (config) => {
  *  2. Parse body via adapter → GatewayInboundMessage (or null to ignore)
  *  3. Populate `wire.gateway`
  *  4. Run user middleware (which can read `wire.gateway` for auth)
- *  5. Call user func with parsed message
+ *  5. Invoke the handler through the function runner, which enforces its
+ *     `auth`/`scopes`/`permissions` before running it
  *  6. Auto-send response via adapter if func returns outbound content
  */
 const createWebhookPostHandler = (config) => {
-    const { name, func: userFunc, middleware: userMiddleware } = config;
-    const userFuncConfig = userFunc;
+    const { name, middleware: userMiddleware } = config;
+    const handlerFuncId = registerGatewayHandler(config);
     return async (services, data, wire) => {
         const adapter = await resolveGatewayAdapter(config, services);
         // Check for POST-based webhook verification (e.g. Slack url_verification)
@@ -136,23 +183,28 @@ const createWebhookPostHandler = (config) => {
             send: (msg) => adapter.send(parsed.senderId, msg),
         };
         wire.gateway = gateway;
-        // Build combined middleware chain: gateway-level + func-level
-        const allMiddleware = [
-            ...(userMiddleware || []),
-            ...(userFuncConfig.middleware || []),
-        ];
-        const exec = async () => {
-            const result = await userFuncConfig.func(services, parsed, wire);
-            // Auto-send response if the func returns outbound content
-            if (result && (result.text || result.richContent || result.attachments)) {
-                await adapter.send(parsed.senderId, result);
-            }
-            return { ok: true };
+        // Gateway middleware runs first and outside the gate, so it can establish
+        // the session the gate then checks. The handler is invoked through the
+        // function runner, which enforces its auth, scopes and permissions and
+        // applies the handler's own middleware.
+        const invoke = async () => {
+            await bridgeMiddlewareSession(wire);
+            return await runPikkuFunc('gateway', name, handlerFuncId, {
+                singletonServices: services,
+                data: () => parsed,
+                auth: config.auth,
+                wire: wire,
+            });
         };
-        if (allMiddleware.length > 0) {
-            return await runMiddleware(services, wire, allMiddleware, exec);
+        const gatewayMiddleware = userMiddleware;
+        const result = gatewayMiddleware?.length
+            ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
+            : await invoke();
+        // Auto-send response if the func returns outbound content
+        if (result && (result.text || result.richContent || result.attachments)) {
+            await adapter.send(parsed.senderId, result);
         }
-        return await exec();
+        return { ok: true };
     };
 };
 /**
@@ -215,8 +267,8 @@ const wireWebsocketGateway = (config) => {
         connect: { pikkuFuncId: connectFuncId },
         message: { pikkuFuncId: messageFuncId },
     };
-    const userFuncConfig = config.func;
     const userMiddleware = config.middleware;
+    const handlerFuncId = registerGatewayHandler(config);
     // Register onConnect
     addFunction(connectFuncId, {
         auth: false,
@@ -249,22 +301,21 @@ const wireWebsocketGateway = (config) => {
                 },
             };
             wire.gateway = gateway;
-            const allMiddleware = [
-                ...(userMiddleware || []),
-                ...(userFuncConfig.middleware || []),
-            ];
-            const exec = async () => {
-                const result = await userFuncConfig.func(services, parsed, wire);
-                if (result &&
-                    (result.text || result.richContent || result.attachments)) {
-                    wire.channel?.send(result);
-                }
+            const invoke = async () => {
+                await bridgeMiddlewareSession(wire);
+                return await runPikkuFunc('gateway', name, handlerFuncId, {
+                    singletonServices: services,
+                    data: () => parsed,
+                    auth: config.auth,
+                    wire: wire,
+                });
             };
-            if (allMiddleware.length > 0) {
-                await runMiddleware(services, wire, allMiddleware, exec);
-            }
-            else {
-                await exec();
+            const gatewayMiddleware = userMiddleware;
+            const result = gatewayMiddleware?.length
+                ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
+                : await invoke();
+            if (result && (result.text || result.richContent || result.attachments)) {
+                wire.channel?.send(result);
             }
         },
     });
@@ -300,8 +351,8 @@ const wireListenerGateway = (config) => {
  * @param singletonServices - Singleton services to pass to handler/middleware
  */
 export const createListenerMessageHandler = (name, config, singletonServices) => {
-    const userFuncConfig = config.func;
     const userMiddleware = config.middleware;
+    const handlerFuncId = registerGatewayHandler(config);
     return async (rawData) => {
         const adapter = await resolveGatewayAdapter(config, singletonServices);
         const parsed = adapter.parse(rawData);
@@ -315,21 +366,20 @@ export const createListenerMessageHandler = (name, config, singletonServices) =>
             send: (msg) => adapter.send(parsed.senderId, msg),
         };
         wire.gateway = gateway;
-        const allMiddleware = [
-            ...(userMiddleware || []),
-            ...(userFuncConfig.middleware || []),
-        ];
-        const exec = async () => {
-            const result = await userFuncConfig.func(singletonServices, parsed, wire);
-            if (result && (result.text || result.richContent || result.attachments)) {
-                await adapter.send(parsed.senderId, result);
-            }
+        const invoke = async () => {
+            await bridgeMiddlewareSession(wire);
+            return await runPikkuFunc('gateway', name, handlerFuncId, {
+                singletonServices,
+                data: () => parsed,
+                auth: config.auth,
+                wire,
+            });
         };
-        if (allMiddleware.length > 0) {
-            await runMiddleware(singletonServices, wire, allMiddleware, exec);
-        }
-        else {
-            await exec();
+        const result = userMiddleware?.length
+            ? await runMiddleware(singletonServices, wire, userMiddleware, invoke)
+            : await invoke();
+        if (result && (result.text || result.richContent || result.attachments)) {
+            await adapter.send(parsed.senderId, result);
         }
     };
 };

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

@@ -1,5 +1,5 @@
 import type { CommonWireMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CoreSingletonServices } from '../../types/core.types.js';
-import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { PikkuHTTPRequest } from '../http/http.types.js';
 /**
  * Attachment in gateway messages (images, files, etc.)
@@ -102,7 +102,7 @@ export type GatewayTransportType = 'webhook' | 'websocket' | 'listener';
 /**
  * Core gateway configuration for wireGateway()
  */
-export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuPermission extends CorePikkuPermission = CorePikkuPermission, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
+export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>, PikkuMiddleware extends CorePikkuMiddleware = CorePikkuMiddleware> = Partial<Pick<CommonWireMeta, 'title' | 'summary' | 'description' | 'errors'>> & {
     /** Unique name for this gateway */
     name: string;
     /** Transport type */
@@ -117,11 +117,14 @@ export type CoreGateway<PikkuFunctionConfig = CorePikkuFunctionConfig<any, any>,
     func: PikkuFunctionConfig;
     /** Optional middleware chain (e.g., auth) */
     middleware?: CorePikkuMiddlewareGroup<any, any>;
-    /** Optional permissions */
-    permissions?: CorePermissionGroup | PikkuPermission[];
     /** Optional tags for categorization */
     tags?: string[];
-    /** Whether authentication is required (default: true) */
+    /**
+     * Whether the handler requires a session. Left unset, the handler's own
+     * `auth` governs, and a gateway handler is sessionless by default — inbound
+     * gateway traffic is platform-authenticated by the adapter, not
+     * session-bearing. Set `true` to require a session for every message.
+     */
     auth?: boolean;
 };
 /**

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

@@ -71,7 +71,7 @@ export type PikkuQuery<T = Record<string, string | undefined>> = Record<string,
  * @template PikkuFunctionSessionless - The sessionless API function type, defaults to `CorePikkuFunctionSessionless`.
  * @template PikkuPermission - The permission function type, defaults to `CorePikkuPermission`.
  */
-export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any>> = (CoreHTTPFunction & {
+export type CoreHTTPFunctionWiring<In, Out, R extends string, PikkuFunction extends CorePikkuFunction<In, Out, any, any, any> = CorePikkuFunction<In, Out>, PikkuFunctionSessionless extends CorePikkuFunctionSessionless<In, Out, any, any, any> = CorePikkuFunctionSessionless<In, Out>, PikkuPermission extends CorePikkuPermission<In, any, any> = CorePikkuPermission<In, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = (CoreHTTPFunction & {
     route: R;
     method: HTTPMethod;
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
@@ -177,7 +177,7 @@ export interface PikkuHTTPResponse<Out = unknown> {
 /**
  * Single route configuration - supports all wireHTTP options
  */
-export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any> = CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPRouteBaseConfig & {
+export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any> = CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = HTTPRouteBaseConfig & {
     method: HTTPMethod;
     route: string;
     func: CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware>;
@@ -188,7 +188,7 @@ export type HTTPRouteConfig<PikkuFunction extends CorePikkuFunction<any, any, an
 /**
  * Group-level configuration applied to all routes
  */
-export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
+export type HTTPRoutesGroupConfig<PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any, any, any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>> = {
     basePath?: string;
     tags?: string[];
     auth?: boolean;

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

@@ -4,6 +4,13 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     /**
      * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
      * Stored in the generated secrets metadata so consumers can tell when a
@@ -25,6 +32,13 @@ export type SecretDefinitionMeta = {
     description?: string;
     secretId: string;
     schema?: Record<string, unknown> | string;
+    /**
+     * Link to documentation explaining how to obtain this value — a provider's
+     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
+     * deploy UIs so a user facing a missing value has somewhere to go instead of
+     * an opaque identifier.
+     */
+    docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;
     sourceFile?: string;

package/dist/wirings/secret/validate-secret-definitions.js

@@ -34,6 +34,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     schema: def.schema,
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
+                    docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
             }
@@ -49,6 +50,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 schema: def.schema,
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
+                docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };
         }