@pikku/core 0.12.63 → 0.12.64

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

@@ -3,7 +3,7 @@ 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, ToolApprovalRequired, ToolCredentialRequired, } from './ai-agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, createScopedChannel, resolveOwnerResourceId, agentSessionScope, assertResourceOwner, ToolApprovalRequired, ToolCredentialRequired, APPROVAL_REQUIRED, } from './ai-agent-prepare.js';
 import { resolveModelConfig } from './ai-agent-model-config.js';
 function createPersistingChannel(parent, storage, threadId) {
     let fullText = '';
@@ -213,14 +213,23 @@ export function checkForApprovals(stepResult, tools, runId) {
             approvals.push(new ToolApprovalRequired(tc.toolCallId, tc.toolName, tc.args));
             continue;
         }
+        // The approval marker is only trusted from a framework tool declared with
+        // `forwardsApproval` (the sub-agent delegating tools) AND carrying the
+        // non-forgeable `APPROVAL_REQUIRED` Symbol brand. A plain tool's output — or
+        // a delegating tool's LLM-shaped `result.object`, which an attacker can
+        // influence — is plain JSON and can never carry the Symbol, so it can never
+        // forge an approval/suspension.
+        if (!toolDef?.forwardsApproval) {
+            continue;
+        }
         const tr = stepResult.toolResults.find((r) => r.toolCallId === tc.toolCallId);
         if (tr?.result &&
             typeof tr.result === 'object' &&
-            '__approvalRequired' in tr.result) {
+            APPROVAL_REQUIRED in tr.result) {
             const r = tr.result;
             if (r.subApprovals?.length) {
                 for (const sub of r.subApprovals) {
-                    approvals.push(new ToolApprovalRequired(sub.toolCallId, r.toolName, r.args, undefined, sub.toolName, sub.args, r.agentRunId));
+                    approvals.push(new ToolApprovalRequired(sub.toolCallId, r.toolName, r.args, sub.reason, sub.toolName, sub.args, r.agentRunId));
                 }
             }
             else {
@@ -341,16 +350,32 @@ function handleCredentialRequests(requests, runId, channel, aiRunState, persisti
             suspendReason: 'credential',
             pendingApprovals,
         });
-        // Don't send credential-request SSE events — the tool result with
-        // __credentialRequired was already streamed. The frontend detects it
-        // from the tool result and shows Connect/Ignore buttons.
+        // The __credentialRequired tool result is suppressed from the stream, so
+        // credential-request events (with the runId needed for /resume) are the
+        // client's signal to show Connect/Ignore buttons — mirroring how
+        // approval-request suspensions work.
+        for (const req of requests) {
+            channel.send({
+                type: 'credential-request',
+                toolCallId: req.toolCallId,
+                toolName: req.toolName,
+                args: req.args,
+                credentialName: req.credentialName,
+                credentialType: req.credentialType,
+                connectUrl: req.connectUrl,
+                runId,
+            });
+        }
         channel.send({ type: 'done' });
         channel.close();
     })();
 }
 export async function streamAIAgent(agentName, input, channel, params, agentSessionMap, options) {
     const sessionMap = agentSessionMap ?? new Map();
-    const normalizedInput = input;
+    const normalizedInput = {
+        ...input,
+        resourceId: resolveOwnerResourceId(params, agentSessionScope(agentName), input.resourceId),
+    };
     const streamContext = { channel, options };
     // delegateState is attached after prepareAgentRun resolves the agent config
     const { agent, packageName, resolvedName, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, normalizedInput, params, sessionMap, streamContext);
@@ -408,6 +433,7 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
         createdAt: new Date(),
         updatedAt: new Date(),
     });
+    options?.onRunCreated?.(runId);
     if (storage) {
         await storage.saveMessages(threadId, [userMessage]);
     }
@@ -447,6 +473,22 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;
+    // Tool results carrying the __credentialRequired marker must never reach
+    // the client or persisted history: the run suspends with credential-request
+    // events instead (mirroring approvals), and leaving the tool call
+    // unresulted is what lets the client resume it after connecting.
+    const credentialFilteredChannel = {
+        ...wrappedChannel,
+        send: (event) => {
+            if (event.type === 'tool-result' &&
+                event.result !== null &&
+                typeof event.result === 'object' &&
+                '__credentialRequired' in event.result) {
+                return;
+            }
+            wrappedChannel.send(event);
+        },
+    };
     // In delegate mode (default), suppress parent's text from reaching the client
     // AFTER a sub-agent has been called. If the parent responds directly (no delegation),
     // its text goes through normally. Sub-agent text bypasses this path entirely
@@ -458,16 +500,16 @@ export async function streamAIAgent(agentName, input, channel, params, agentSess
     }
     const outputChannel = isDelegateMode
         ? {
-            ...wrappedChannel,
+            ...credentialFilteredChannel,
             send: (event) => {
                 if (delegateState.delegated &&
                     (event.type === 'text-delta' || event.type === 'reasoning-delta'))
                     return;
-                wrappedChannel.send(event);
+                credentialFilteredChannel.send(event);
             },
             delegateState,
         }
-        : wrappedChannel;
+        : credentialFilteredChannel;
     try {
         const loopResult = await runStreamStepLoop({
             agent,
@@ -531,6 +573,7 @@ export async function resumeAIAgent(input, channel, params, options) {
     if (!run) {
         throw new Error(`No run found for runId ${input.runId}`);
     }
+    assertResourceOwner(resolveOwnerResourceId(params, agentSessionScope(run.agentName), run.resourceId), run.resourceId, 'run');
     const pending = run.pendingApprovals?.find((p) => p.toolCallId === input.toolCallId);
     if (!pending) {
         throw new Error(`No pending approval for toolCallId ${input.toolCallId} on run ${input.runId}`);
@@ -567,6 +610,14 @@ export async function resumeAIAgent(input, channel, params, options) {
                 },
             ]);
         }
+        channel.send({
+            type: 'tool-result',
+            toolCallId: input.toolCallId,
+            toolName: pending.type === 'tool-call' || pending.type === 'credential-request'
+                ? pending.toolName
+                : pending.agentName,
+            result: denialResult,
+        });
         // Check remaining pending approvals
         const updatedRun = await aiRunState.getRun(run.runId);
         const remaining = updatedRun?.pendingApprovals ?? [];

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

@@ -100,6 +100,19 @@ export interface AIAgentOutput {
         runId: string;
     }>;
 }
+/**
+ * How an agent's threads/runs are owned and partitioned.
+ * - `'user'` (default): owner is the authenticated `session.userId`; the caller's
+ *   `resourceId` becomes a sub-partition within that user (`userId:resourceId`).
+ * - `'org'`: owner is the authenticated `session.orgId` (`orgId:resourceId`), so
+ *   threads are shared across everyone in the org. Requires a session with an org
+ *   (e.g. Better Auth's `organization` plugin) — otherwise access is denied.
+ *
+ * The trusted principal is always the prefix, so a client-supplied `resourceId`
+ * can sub-divide within the caller's own boundary but can never widen access to
+ * another user's or org's threads.
+ */
+export type SessionScope = 'user' | 'org';
 export interface AIAgentToolDef {
     name: string;
     description: string;
@@ -107,6 +120,14 @@ export interface AIAgentToolDef {
     execute: (input: unknown) => Promise<unknown>;
     needsApproval?: boolean;
     approvalDescriptionFn?: (input: unknown) => Promise<string>;
+    /**
+     * Set only by the framework on sub-agent delegating tools. Such a tool may
+     * legitimately return an `__approvalRequired` marker to forward a nested
+     * sub-agent approval. The marker is honored ONLY from a tool with this flag —
+     * a plain tool's output (which an attacker may influence) can never forge an
+     * approval request. See `checkForApprovals`.
+     */
+    forwardsApproval?: boolean;
 }
 export interface PikkuAIMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
     modifyInput?: (services: Services, ctx: {
@@ -200,8 +221,11 @@ export type CoreAIAgent<PikkuPermission = CorePikkuPermission<any, any>, PikkuMi
     goal: string;
     model: string;
     temperature?: number;
+    /** Ownership/partitioning of this agent's threads and runs. Defaults to `'user'`. */
+    sessionScope?: SessionScope;
     tools?: unknown[];
     agents?: unknown[];
+    workflows?: unknown[];
     agentMode?: 'delegate' | 'supervise';
     memory?: AIAgentMemoryConfig;
     maxSteps?: number;
@@ -267,6 +291,7 @@ export type AIStreamEvent = {
     toolName: string;
     args: unknown;
     reason?: string;
+    runId?: string;
     agent?: string;
     session?: string;
 } | {
@@ -397,9 +422,10 @@ export interface AgentRunService {
     deleteThread(threadId: string): Promise<boolean>;
     getDistinctAgentNames(): Promise<string[]>;
 }
-export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' | 'tools' | 'agents' | 'middleware' | 'channelMiddleware' | 'aiMiddleware' | 'permissions'> & {
+export type AIAgentMeta = Record<string, Omit<CoreAIAgent, 'input' | 'output' | 'tools' | 'agents' | 'workflows' | 'middleware' | 'channelMiddleware' | 'aiMiddleware' | 'permissions'> & {
     tools?: string[];
     agents?: string[];
+    workflows?: string[];
     inputSchema: string | null;
     outputSchema: string | null;
     workingMemorySchema: string | null;

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

@@ -1,4 +1,5 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { wrapChannelWithAGUI, type AGUIEvent } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
 export { voiceInput } from './voice-input.js';

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

@@ -1,4 +1,5 @@
 export { agent, agentStream, agentResume, agentApprove, } from './ai-agent-helpers.js';
+export { wrapChannelWithAGUI } from './ai-agent-agui.js';
 export { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
 export { streamAIAgent, resumeAIAgent } from './ai-agent-stream.js';
 export { voiceInput } from './voice-input.js';

package/dist/wirings/ai-agent/voice-input.d.ts

@@ -6,5 +6,6 @@ export declare const voiceInput: (config?: {
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;

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

@@ -1,4 +1,5 @@
 import { pikkuAIMiddleware } from '../../types/core.types.js';
+import { safeFetch } from '../../utils/safe-fetch.js';
 function base64ToUint8Array(base64) {
     const binary = atob(base64);
     const bytes = new Uint8Array(binary.length);
@@ -8,45 +9,8 @@ function base64ToUint8Array(base64) {
     return bytes;
 }
 const MAX_AUDIO_SIZE = 50 * 1024 * 1024;
-// Portable SSRF guard: @pikku/core runs in edge runtimes (CF Workers) with no
-// Node `dns`, so we cannot resolve hostnames to check for private targets.
-// Reject the obvious internal literals; callers wanting stricter control pass
-// an explicit `allowedAudioHosts` allowlist. (Does not defend against a public
-// hostname that resolves to a private IP / DNS rebinding — out of reach here.)
-function isPrivateHost(hostname) {
-    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
-    if (host === 'localhost' || host === '0.0.0.0' || host === '::1')
-        return true;
-    if (host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd'))
-        return true;
-    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.\d{1,3}$/);
-    if (v4) {
-        const [a, b] = [Number(v4[1]), Number(v4[2])];
-        if (a === 127 || a === 10 || a === 0)
-            return true;
-        if (a === 169 && b === 254)
-            return true; // link-local incl. cloud metadata
-        if (a === 172 && b >= 16 && b <= 31)
-            return true;
-        if (a === 192 && b === 168)
-            return true;
-    }
-    return false;
-}
 async function fetchAsUint8Array(url, allowedAudioHosts) {
-    const parsed = new URL(url);
-    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
-        throw new Error('Only HTTP(S) URLs are supported for audio');
-    }
-    if (allowedAudioHosts) {
-        if (!allowedAudioHosts.includes(parsed.hostname)) {
-            throw new Error(`Audio URL host is not allowed: ${parsed.hostname}`);
-        }
-    }
-    else if (isPrivateHost(parsed.hostname)) {
-        throw new Error(`Refusing to fetch audio from a private/internal host: ${parsed.hostname}`);
-    }
-    const response = await fetch(url);
+    const response = await safeFetch(url, {}, { allowedHosts: allowedAudioHosts });
     const contentLength = response.headers.get('content-length');
     if (contentLength && parseInt(contentLength, 10) > MAX_AUDIO_SIZE) {
         throw new Error('Audio file exceeds maximum size');

package/dist/wirings/ai-agent/voice-output.d.ts

@@ -12,6 +12,7 @@ export declare const voiceOutput: (config?: {
     logLevel?: import("../../services/logger.js").LogLevel;
     secrets?: {};
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
+    webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;
 }>>;
 export {};

package/dist/wirings/channel/channel-common.js

@@ -42,7 +42,6 @@ export const runChannelLifecycleWithMiddleware = async ({ channelConfig, meta, l
             data: () => data,
             wire,
             tags: meta.tags ?? [],
-            inheritedPermissions: meta.permissions,
             packageName: meta.packageName ?? null,
         });
     };

package/dist/wirings/channel/channel-handler.js

@@ -49,7 +49,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             return;
         }
         const routeMeta = getRouteMeta(channelConfig.name, routingProperty, routerValue);
-        const { packageName, middleware: routeInheritedMiddleware, permissions: inheritedPermissions, } = routeMeta;
+        const { packageName, middleware: routeInheritedMiddleware } = routeMeta;
         const pikkuFuncId = routeMeta.pikkuFuncId;
         // Get wire middleware: channel-level middleware + message-specific middleware
         const channelWireMiddleware = channelConfig.middleware || [];
@@ -68,7 +68,6 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
         const wireMiddleware = [...channelWireMiddleware, ...messageWireMiddleware];
         // Inherited middleware comes from metadata (tag groups, non-inline wire)
         const inheritedMiddleware = routeInheritedMiddleware || [];
-        const wirePermissions = isWrapper ? onMessage.permissions : undefined;
         // Create unique cache key that includes routing info to avoid cache collisions
         // when multiple message handlers use the same function
         const cacheKey = routingProperty
@@ -83,8 +82,6 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
             wireMiddleware,
             inheritedChannelMiddleware: channelMeta?.channelMiddleware,
             wireChannelMiddleware: wireChannelMiddleware,
-            inheritedPermissions,
-            wirePermissions,
             coerceDataFromSchema: true,
             tags: channelConfig.tags,
             sessionService: userSession,

package/dist/wirings/channel/channel-middleware-runner.d.ts

@@ -2,6 +2,18 @@ import type { CoreSingletonServices, MiddlewareMetadata, PikkuRawWire } from '..
 import type { CorePikkuChannelMiddleware } from './channel.types.js';
 export declare const addChannelMiddleware: (tag: string, middleware: CorePikkuChannelMiddleware[], packageName?: string | null) => CorePikkuChannelMiddleware[];
 export declare const clearChannelMiddlewareCache: () => void;
+/**
+ * Combine the inherited (tag/named) channel middleware with any per-run
+ * middleware for a wiring.
+ *
+ * Only the statically-resolved inherited middleware is deterministic per `uid`
+ * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
+ * an AI agent's per-invocation stream middleware holding that run's
+ * thread/session state) and MUST NOT be cached — caching it lets a later run of
+ * the same `uid` reuse an earlier run's closures, leaking that run's state (and
+ * growing memory) across invocations. It is therefore appended fresh on every
+ * call after the cached inherited slice.
+ */
 export declare const combineChannelMiddleware: (wireType: string, uid: string, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName, }?: {
     wireInheritedChannelMiddleware?: MiddlewareMetadata[];
     wireChannelMiddleware?: CorePikkuChannelMiddleware[];

package/dist/wirings/channel/channel-middleware-runner.js

@@ -16,33 +16,48 @@ export const clearChannelMiddlewareCache = () => {
         delete channelMiddlewareCache[key];
     }
 };
+/**
+ * Combine the inherited (tag/named) channel middleware with any per-run
+ * middleware for a wiring.
+ *
+ * Only the statically-resolved inherited middleware is deterministic per `uid`
+ * and safe to cache. `wireChannelMiddleware` is a per-run set of closures (e.g.
+ * an AI agent's per-invocation stream middleware holding that run's
+ * thread/session state) and MUST NOT be cached — caching it lets a later run of
+ * the same `uid` reuse an earlier run's closures, leaking that run's state (and
+ * growing memory) across invocations. It is therefore appended fresh on every
+ * call after the cached inherited slice.
+ */
 export const combineChannelMiddleware = (wireType, uid, { wireInheritedChannelMiddleware, wireChannelMiddleware, packageName = null, } = {}) => {
     const cacheKey = `${wireType}:${uid}`;
-    if (channelMiddlewareCache[cacheKey]) {
-        return channelMiddlewareCache[cacheKey];
-    }
-    const resolved = [];
-    if (wireInheritedChannelMiddleware) {
-        for (const meta of wireInheritedChannelMiddleware) {
-            if (meta.type === 'tag') {
-                const groups = getTagGroups(pikkuState(packageName, 'channelMiddleware', 'tagGroup'), meta.tag);
-                for (const group of groups) {
-                    resolved.push(...group);
+    let inherited = channelMiddlewareCache[cacheKey];
+    if (!inherited) {
+        const resolved = [];
+        if (wireInheritedChannelMiddleware) {
+            for (const meta of wireInheritedChannelMiddleware) {
+                if (meta.type === 'tag') {
+                    const groups = getTagGroups(pikkuState(packageName, 'channelMiddleware', 'tagGroup'), meta.tag);
+                    for (const group of groups) {
+                        resolved.push(...group);
+                    }
                 }
-            }
-            else if (meta.type === 'wire') {
-                const middleware = getChannelMiddlewareByName(meta.name);
-                if (middleware) {
-                    resolved.push(middleware);
+                else if (meta.type === 'wire') {
+                    const middleware = getChannelMiddlewareByName(meta.name);
+                    if (middleware) {
+                        resolved.push(middleware);
+                    }
                 }
             }
         }
+        inherited = channelMiddlewareCache[cacheKey] = freezeDedupe(resolved);
     }
-    if (wireChannelMiddleware) {
-        resolved.push(...wireChannelMiddleware);
+    if (!wireChannelMiddleware?.length) {
+        return inherited;
     }
-    channelMiddlewareCache[cacheKey] = freezeDedupe(resolved);
-    return channelMiddlewareCache[cacheKey];
+    return freezeDedupe([
+        ...inherited,
+        ...wireChannelMiddleware,
+    ]);
 };
 export function wrapChannelWithMiddleware(wire, services, middlewares) {
     if (middlewares.length === 0 || !wire.channel)

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

@@ -1,9 +1,9 @@
 import type { HTTPFunctionMetaInputTypes, PikkuHTTPRequest, PikkuHTTPResponse } from '../http/http.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
 export type BinaryData = ArrayBuffer | Uint8Array;
 export type CorePikkuChannelMiddleware<Services = any, Event = unknown> = (services: Services, event: Event, next: (event: Event | Event[] | null) => Promise<void> | void) => Promise<void> | void;
 export type CorePikkuChannelMiddlewareFactory<In = any, Services = any, Event = unknown> = (input: In) => CorePikkuChannelMiddleware<Services, Event>;
-import type { CorePermissionGroup, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
+import type { CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 export type RunChannelOptions = Partial<{
     skipUserSession: boolean;
     respondWith404: boolean;
@@ -24,7 +24,6 @@ export interface ChannelMessageMeta {
     errors?: string[];
     tags?: string[];
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
 }
 export interface ChannelMeta {
     name: string;
@@ -43,7 +42,6 @@ export interface ChannelMeta {
     errors?: string[];
     tags?: string[];
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
     channelMiddleware?: MiddlewareMetadata[];
 }
 export type ChannelsMeta = Record<string, ChannelMeta>;
@@ -61,13 +59,11 @@ export type CoreChannel<ChannelData, Channel extends string, ChannelConnect = Co
     onMessage?: ChannelFunctionMessage;
     onMessageWiring?: Record<string, Record<string, ChannelFunctionMessage | {
         func: ChannelFunctionMessage;
-        permissions?: CorePermissionGroup<PikkuPermission>;
         auth?: boolean;
         middleware?: PikkuMiddleware[];
     }>>;
     middleware?: PikkuMiddleware[];
     channelMiddleware?: Array<CorePikkuChannelMiddleware | CorePikkuChannelMiddlewareFactory>;
-    permissions?: CorePermissionGroup<PikkuPermission>;
     auth?: boolean;
     binary?: boolean | null;
     onBinaryMessage?: (services: any, data: BinaryData, channel: PikkuChannel<ChannelData, any>) => Promise<BinaryData | void> | BinaryData | void;

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

@@ -253,8 +253,6 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
             auth: false,
             inheritedMiddleware: currentCommand.middleware,
             wireMiddleware: allWireMiddleware,
-            inheritedPermissions: currentCommand.permissions,
-            wirePermissions: undefined,
             coerceDataFromSchema: true,
             tags: programData?.tags,
             wire,

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

@@ -1,4 +1,4 @@
-import type { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata, PermissionMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, CoreSingletonServices, CoreUserSession, CoreServices, MiddlewareMetadata } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuFunction, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 /**
@@ -62,7 +62,6 @@ export interface CLICommandMeta {
     tags?: string[];
     subcommands?: Record<string, CLICommandMeta>;
     middleware?: MiddlewareMetadata[];
-    permissions?: PermissionMetadata[];
     isDefault?: boolean;
 }
 /**

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

@@ -83,7 +83,6 @@ function processRouteMap(map, parentConfig) {
  * - tags: Merges (parent + child)
  * - middleware: Merges (parent runs first)
  * - auth: Inner overrides outer
- * - permissions: Inner overrides outer
  */
 function mergeGroupConfig(parent, child) {
     return {
@@ -91,7 +90,6 @@ function mergeGroupConfig(parent, child) {
         tags: [...(parent.tags || []), ...(child.tags || [])],
         middleware: [...(parent.middleware || []), ...(child.middleware || [])],
         auth: child.auth ?? parent.auth,
-        permissions: child.permissions ?? parent.permissions,
     };
 }
 /**
@@ -109,7 +107,6 @@ function registerRoute(route, groupConfig) {
             ...(groupConfig.middleware || []),
             ...(route.middleware || []),
         ],
-        permissions: route.permissions ?? groupConfig.permissions,
         contentType: route.contentType,
         timeout: route.timeout,
         headers: route.headers,

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

@@ -1,5 +1,5 @@
 import type { CoreHTTPFunctionWiring, RunHTTPWiringOptions, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse } from './http.types.js';
-import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePermissionGroup } from '../../function/functions.types.js';
+import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../../types/core.types.js';
 import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
 /**
@@ -33,35 +33,15 @@ import { PikkuFetchHTTPResponse } from './pikku-fetch-http-response.js';
  */
 export declare const addHTTPMiddleware: <PikkuMiddleware extends CorePikkuMiddleware>(pattern: string, middleware: CorePikkuMiddlewareGroup, packageName?: string | null) => CorePikkuMiddlewareGroup;
 /**
- * Registers HTTP permissions for a specific route pattern.
- *
- * This function registers permissions at runtime that will be applied to
- * HTTP routes matching the specified pattern.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addHTTPPermission('pattern', [...])`
- *
- * @template PikkuPermission The permission type.
- * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
- * @param {CorePermissionGroup | CorePikkuPermission[]} permissions - Permissions for this route pattern.
- *
- * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
- *
- * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const httpGlobalPermissions = () => addHTTPPermission('*', [
- *   authenticatedPermission,
- *   rateLimitPermission
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiPermissions = addHTTPPermission('/api/*', [
- *   adminPermission
- * ])
- * ```
+ * @deprecated HTTP-route-level permissions were removed in #972 — permissions
+ * are now function-scoped only (declare them on the function via
+ * `pikkuFunc({ permissions })`). This throwing stub exists solely so the pinned
+ * bootstrap CLI (which still generates an `addHTTPPermission` wrapper) can
+ * resolve the import at build time; it is never called. Delete once
+ * `PIKKU_CLI_VERSION` in the CLI build is bumped past the release that removes
+ * HTTP-route permissions.
  */
-export declare const addHTTPPermission: <PikkuPermission extends CorePikkuPermission>(pattern: string, permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
+export declare const addHTTPPermission: (_pattern: string, _permissions: Record<string, CorePikkuPermission | CorePikkuPermission[]> | CorePikkuPermission[]) => never;
 /**
  * Adds a new route to the global HTTP route registry.
  *

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

@@ -64,38 +64,16 @@ export const addHTTPMiddleware = (pattern, middleware, packageName = null) => {
     return middleware;
 };
 /**
- * Registers HTTP permissions for a specific route pattern.
- *
- * This function registers permissions at runtime that will be applied to
- * HTTP routes matching the specified pattern.
- *
- * For tree-shaking benefits, wrap in a factory function:
- * `export const x = () => addHTTPPermission('pattern', [...])`
- *
- * @template PikkuPermission The permission type.
- * @param {string} pattern - Route pattern (e.g., '*' for all routes, '/api/*' for specific routes).
- * @param {CorePermissionGroup | CorePikkuPermission[]} permissions - Permissions for this route pattern.
- *
- * @returns {CorePermissionGroup | CorePikkuPermission[]} The permissions (for chaining/wrapping).
- *
- * @example
- * ```typescript
- * // Recommended: tree-shakeable
- * export const httpGlobalPermissions = () => addHTTPPermission('*', [
- *   authenticatedPermission,
- *   rateLimitPermission
- * ])
- *
- * // Also works: no tree-shaking
- * export const apiPermissions = addHTTPPermission('/api/*', [
- *   adminPermission
- * ])
- * ```
+ * @deprecated HTTP-route-level permissions were removed in #972 — permissions
+ * are now function-scoped only (declare them on the function via
+ * `pikkuFunc({ permissions })`). This throwing stub exists solely so the pinned
+ * bootstrap CLI (which still generates an `addHTTPPermission` wrapper) can
+ * resolve the import at build time; it is never called. Delete once
+ * `PIKKU_CLI_VERSION` in the CLI build is bumped past the release that removes
+ * HTTP-route permissions.
  */
-export const addHTTPPermission = (pattern, permissions, packageName = null) => {
-    const httpGroups = pikkuState(packageName, 'permissions', 'httpGroup');
-    httpGroups[pattern] = permissions;
-    return permissions;
+export const addHTTPPermission = (_pattern, _permissions) => {
+    throw new Error('addHTTPPermission was removed in #972 — HTTP-route-level permissions no longer exist. Declare permissions on the function definition instead: pikkuFunc({ permissions }).');
 };
 /**
  * Adds a new route to the global HTTP route registry.
@@ -156,7 +134,6 @@ const getMatchingRoute = (requestType, requestPath) => {
             matchedPath,
             params: matchedPath.params,
             route,
-            permissions: route.permissions,
             meta: meta,
         };
     }
@@ -307,8 +284,6 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             data,
             inheritedMiddleware: meta.middleware,
             wireMiddleware: route.middleware,
-            inheritedPermissions: meta.permissions,
-            wirePermissions: route.permissions,
             coerceDataFromSchema: options.coerceDataFromSchema,
             tags: route.tags,
             wire,