@pikku/core 0.12.137 → 0.12.138

package/dist/wirings/agent/agent-prepare.js

@@ -247,7 +247,7 @@ export function createScopedChannel(parent, agentName, session) {
         },
         close: () => { },
         sendBinary: (data) => parent.sendBinary(data),
-        send: (event) => {
+        send: async (event) => {
             if (event.type === 'done')
                 return;
             if (event.type === 'approval-request') {
@@ -267,10 +267,14 @@ export function createScopedChannel(parent, agentName, session) {
                 event.type === 'tool-result' ||
                 event.type === 'usage' ||
                 event.type === 'error') {
-                parent.send({ ...event, agent: agentName, session });
+                await parent.send({
+                    ...event,
+                    agent: agentName,
+                    session,
+                });
             }
             else {
-                parent.send(event);
+                await parent.send(event);
             }
         },
         setState: (s) => parent.setState(s),
@@ -402,10 +406,12 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 needsApproval: needsApproval || undefined,
                 approvalDescriptionFn,
                 readonly: fnMeta?.readonly || undefined,
-                execute: async (toolInput) => {
+                execute: async (toolInput, options) => {
                     const wire = params.sessionService
                         ? { ...createMiddlewareSessionWireProps(params.sessionService) }
                         : {};
+                    if (options?.abortScope)
+                        wire.abortScope = options.abortScope;
                     const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
                     return rpcService.rpc(toolName, toolInput);
                 },
@@ -457,7 +463,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                             streamContext.delegateState.delegated = true;
                         }
                         const { channel } = streamContext;
-                        channel.send({
+                        await channel.send({
                             type: 'agent-call',
                             agentName: subAgentName,
                             session,
@@ -468,11 +474,11 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                             ? subChannel
                             : {
                                 ...subChannel,
-                                send: (event) => {
+                                send: async (event) => {
                                     if (event.type === 'text-delta' ||
                                         event.type === 'reasoning-delta')
                                         return;
-                                    subChannel.send(event);
+                                    await subChannel.send(event);
                                 },
                             };
                         const resultText = await streamAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
@@ -486,7 +492,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                 subApprovals: subChannel.approvals,
                             };
                         }
-                        channel.send({
+                        await channel.send({
                             type: 'agent-result',
                             agentName: subAgentName,
                             session,
@@ -544,7 +550,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 name: workflowName,
                 description: wfMeta.description || workflowName,
                 inputSchema,
-                execute: async (toolInput) => {
+                execute: async (toolInput, options) => {
                     const workflowService = singletonServices.workflowService;
                     if (!workflowService) {
                         throw new Error(`workflowService is not configured — cannot run workflow tool '${workflowName}'`);
@@ -552,6 +558,8 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                     const wire = params.sessionService
                         ? { ...createMiddlewareSessionWireProps(params.sessionService) }
                         : {};
+                    if (options?.abortScope)
+                        wire.abortScope = options.abortScope;
                     const rpcService = new ContextAwareRPCService(singletonServices, wire, { sessionService: params.sessionService });
                     return workflowService.runToCompletion(workflowName, toolInput, rpcService, { wire: { type: 'internal' } });
                 },
@@ -560,9 +568,9 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
     }
     for (const tool of tools) {
         const originalExecute = tool.execute;
-        tool.execute = async (toolInput) => {
+        tool.execute = async (toolInput, options) => {
             try {
-                return await originalExecute(toolInput);
+                return await originalExecute(toolInput, options);
             }
             catch (err) {
                 if (err?.payload?.error === 'missing_credential') {
@@ -581,7 +589,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
     if (hasToolHooks) {
         for (const tool of tools) {
             const originalExecute = tool.execute;
-            tool.execute = async (toolInput) => {
+            tool.execute = async (toolInput, options) => {
                 const toolCallId = randomUUID();
                 let args = (toolInput ?? {});
                 for (const mw of agentMiddlewares) {
@@ -600,7 +608,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                 let result;
                 let execError;
                 try {
-                    result = await originalExecute(args);
+                    result = await originalExecute(args, options);
                 }
                 catch (err) {
                     execError = err;

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

@@ -86,7 +86,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
         flush: flushStep,
         close: () => parent.close(),
         sendBinary: (data) => parent.sendBinary(data),
-        send: (event) => {
+        send: async (event) => {
             // Accumulated whether or not storage is configured: `fullText` is what
             // the client was streamed, and an interrupted run has to be able to
             // report the fragment it got through even with persistence turned off.
@@ -149,7 +149,7 @@ function createPersistingChannel(parent, storage, threadId, logger) {
                         break;
                 }
             }
-            parent.send(event);
+            await parent.send(event);
         },
         setState: (s) => parent.setState(s),
         getState: () => parent.getState(),
@@ -267,7 +267,7 @@ async function runStreamStepLoop(params) {
             if (stopped)
                 break;
         }
-        channel.send({ type: 'step-start', stepNumber: step });
+        await channel.send({ type: 'step-start', stepNumber: step });
         const stepResult = await agentRunner.stream(runnerParams, streamChannel);
         for (const mw of agentMiddlewares) {
             if (mw.afterStep) {
@@ -422,10 +422,10 @@ function handleApprovals(approvals, runId, channel, agentRunState, persistingCha
                 reason: err.reason,
                 runId,
             };
-            channel.send(approvalEvent);
+            await channel.send(approvalEvent);
         }
-        channel.send({ type: 'done' });
-        channel.close();
+        await channel.send({ type: 'done' });
+        await channel.close();
     })();
 }
 function handleCredentialRequests(requests, runId, channel, agentRunState, persistingChannel) {
@@ -446,7 +446,7 @@ function handleCredentialRequests(requests, runId, channel, agentRunState, persi
             pendingApprovals,
         });
         for (const req of requests) {
-            channel.send({
+            await channel.send({
                 type: 'credential-request',
                 toolCallId: req.toolCallId,
                 toolName: req.toolName,
@@ -457,8 +457,8 @@ function handleCredentialRequests(requests, runId, channel, agentRunState, persi
                 runId,
             });
         }
-        channel.send({ type: 'done' });
-        channel.close();
+        await channel.send({ type: 'done' });
+        await channel.close();
     })();
 }
 export async function streamAgent(agentName, input, channel, params, agentSessionMap, options) {
@@ -487,8 +487,12 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
             createdAt: new Date(),
             updatedAt: new Date(),
         });
-        channel.send({ type: 'suspended', reason: 'rpc-missing', missingRpcs });
-        channel.send({ type: 'done' });
+        await channel.send({
+            type: 'suspended',
+            reason: 'rpc-missing',
+            missingRpcs,
+        });
+        await channel.send({ type: 'done' });
         return '';
     }
     const workingMemoryMiddleware = getWorkingMemoryMiddleware(memoryConfig, storage, {
@@ -512,7 +516,7 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
     // knowledge: decisions/internals/the-transcript-event-is-sent-ahead-of-the-run.md
     const transcript = sharedNotes[SPOKEN_TRANSCRIPT];
     if (typeof transcript === 'string') {
-        channel.send({ type: 'transcript', text: transcript });
+        await channel.send({ type: 'transcript', text: transcript });
     }
     // knowledge: decisions/internals/thread-history-records-the-transcript-not-the-audio.md
     const lastModified = modifiedMessages[modifiedMessages.length - 1];
@@ -615,7 +619,7 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
         });
         // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
         await outputChannel.send({ type: 'done' });
-        channel.close();
+        await channel.close();
         return persistingChannel.fullText;
     }
     catch (err) {
@@ -631,14 +635,14 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
             if (storage) {
                 trackInterruptNote(threadId, persistOrphanedToolResults(interruptHandle, storage, threadId));
             }
-            channel.send({
+            await channel.send({
                 type: 'interrupted',
                 runId,
                 text: persistingChannel.fullText,
                 reason: interruption?.reason ?? 'user',
             });
-            channel.send({ type: 'done' });
-            channel.close();
+            await channel.send({ type: 'done' });
+            await channel.close();
             return persistingChannel.fullText;
         }
         for (const mw of agentMiddlewares) {
@@ -657,12 +661,12 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
             status: 'failed',
             errorMessage: err instanceof Error ? err.message : String(err),
         });
-        channel.send({
+        await channel.send({
             type: 'error',
             message: err instanceof Error ? err.message : String(err),
         });
-        channel.send({ type: 'done' });
-        channel.close();
+        await channel.send({ type: 'done' });
+        await channel.close();
         return persistingChannel.fullText;
     }
     finally {
@@ -763,7 +767,7 @@ export async function resumeAgent(input, channel, params, options) {
                 },
             ]);
         }
-        channel.send({
+        await channel.send({
             type: 'tool-result',
             toolCallId: input.toolCallId,
             toolName: pending.type === 'tool-call' || pending.type === 'credential-request'
@@ -774,8 +778,8 @@ export async function resumeAgent(input, channel, params, options) {
         const updatedRun = await agentRunState.getRun(run.runId);
         const remaining = updatedRun?.pendingApprovals ?? [];
         if (remaining.length > 0) {
-            channel.send({ type: 'done' });
-            channel.close();
+            await channel.send({ type: 'done' });
+            await channel.close();
             return;
         }
         await agentRunState.updateRun(run.runId, { status: 'running' });
@@ -793,7 +797,7 @@ export async function resumeAgent(input, channel, params, options) {
             throw new Error(`No pending approval on sub-agent run ${pending.agentRunId}`);
         }
         const subChannel = createScopedChannel(channel, subRun.agentName, 'resume');
-        channel.send({
+        await channel.send({
             type: 'agent-call',
             agentName: subRun.agentName,
             session: 'resume',
@@ -804,7 +808,7 @@ export async function resumeAgent(input, channel, params, options) {
             toolCallId: subPending.toolCallId,
             approved: true,
         }, subChannel, params, options);
-        channel.send({
+        await channel.send({
             type: 'agent-result',
             agentName: subRun.agentName,
             session: 'resume',
@@ -871,7 +875,7 @@ export async function resumeAgent(input, channel, params, options) {
                 },
             ]);
         }
-        channel.send({
+        await channel.send({
             type: 'tool-result',
             toolCallId: input.toolCallId,
             toolName: pending.toolName,
@@ -882,8 +886,8 @@ export async function resumeAgent(input, channel, params, options) {
     const updatedRun = await agentRunState.getRun(run.runId);
     const remaining = updatedRun?.pendingApprovals ?? [];
     if (remaining.length > 0) {
-        channel.send({ type: 'done' });
-        channel.close();
+        await channel.send({ type: 'done' });
+        await channel.close();
         return;
     }
     await agentRunState.updateRun(run.runId, { status: 'running' });
@@ -1002,7 +1006,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
         });
         // knowledge: decisions/internals/the-agent-done-event-goes-through-the-middleware-and-is-awaited.md
         await wrappedChannel.send({ type: 'done' });
-        channel.close();
+        await channel.close();
     }
     catch (err) {
         // Same reasoning as the first turn: an interrupt is not a failure, and the
@@ -1014,14 +1018,14 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             if (storage) {
                 trackInterruptNote(run.threadId, persistOrphanedToolResults(interruptHandle, storage, run.threadId));
             }
-            channel.send({
+            await channel.send({
                 type: 'interrupted',
                 runId: run.runId,
                 text: persistingChannel.fullText,
                 reason: interruption?.reason ?? 'user',
             });
-            channel.send({ type: 'done' });
-            channel.close();
+            await channel.send({ type: 'done' });
+            await channel.close();
             return;
         }
         for (const mw of agentMiddlewares) {
@@ -1040,12 +1044,12 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             status: 'failed',
             errorMessage: err instanceof Error ? err.message : String(err),
         });
-        channel.send({
+        await channel.send({
             type: 'error',
             message: err instanceof Error ? err.message : String(err),
         });
-        channel.send({ type: 'done' });
-        channel.close();
+        await channel.send({ type: 'done' });
+        await channel.close();
     }
     finally {
         interruptHandle.release();

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

@@ -1,5 +1,6 @@
 import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
+import type { AbortScope } from '../../function/abort-scope.js';
 import type { CoreSingletonServices } from '../../types/core.types.js';
 import type { PermissionMetadata } from '../../function/function-meta.types.js';
 import type { AIProviderOptions } from '../../services/agent-runner-service.js';
@@ -166,7 +167,13 @@ export interface AgentToolDef extends Partial<ApprovalPolicy> {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
-    execute: (input: unknown) => Promise<unknown>;
+    /**
+     * `options.abortScope` is supplied by the interrupt tracker and must be put
+     * on the wire of whatever this runs, so `beginChanges()` can observe it.
+     */
+    execute: (input: unknown, options?: {
+        abortScope?: AbortScope;
+    }) => Promise<unknown>;
     /**
      * Mirrors the pikku function's `readonly` flag. A read that gets interrupted
      * is discarded rather than reported: nothing changed, and by the next turn

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

@@ -47,7 +47,7 @@ export const processMessageHandlers = (services, channelConfig, channelHandler,
                 : 'the default message route';
             logger.error(`Channel ${channelConfig.name} with id ${channelHandler.getChannel().channelId} requires a session for ${routeMessage}. No session is attached to this websocket connection. Ensure auth middleware establishes a session during websocket upgrade, and configure sessionStore when the runtime needs persisted sessions.`);
             // knowledge: questions/unauthorized-channel-replies-escape-the-declared-out-type.md
-            channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
+            await channelHandler.getChannel().send(`Unauthorized for ${routeMessage}`);
             return;
         }
         const routeMeta = getRouteMeta(channelConfig.name, routingProperty, routerValue);

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

@@ -14,6 +14,10 @@ export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
     registerOnOpen(callback) {
         this.openCallBack = callback;
     }
+    // The base class declares `open(): void`; this override is intentionally
+    // async (callers already await it). Widening the exported base signature is
+    // a public API change, so the rule is suppressed for this one override.
+    // oxlint-disable-next-line typescript/no-misused-promises
     async open() {
         this.getChannel().state = 'open';
         if (this.openCallBack) {
@@ -39,7 +43,7 @@ export class PikkuLocalChannelHandler extends PikkuAbstractChannelHandler {
         if (this.getChannel().state === 'closed') {
             return;
         }
-        super.close();
+        await super.close();
         const results = await Promise.allSettled(this.closeCallbacks.map((cb) => cb()));
         for (const result of results) {
             if (result.status === 'rejected') {

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

@@ -98,7 +98,7 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     catch (e) {
                         singletonServices.logger.error(`Error handling onConnect: ${e}`);
                         const errorResponse = getErrorResponse(e);
-                        channel.send({
+                        await channel.send({
                             error: errorResponse?.message ??
                                 (isProduction() ? 'Internal server error' : e.message),
                             ...(!isProduction() && { errorName: e.constructor?.name }),
@@ -124,7 +124,7 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                     catch (e) {
                         singletonServices.logger.error(`Error handling onDisconnect: ${e}`);
                         const errorResponse = getErrorResponse(e);
-                        channel.send({
+                        await channel.send({
                             error: errorResponse?.message ??
                                 (isProduction() ? 'Internal server error' : e.message),
                             ...(!isProduction() && { errorName: e.constructor?.name }),
@@ -149,12 +149,14 @@ export const runLocalChannel = async ({ channelId, request, response, route, ski
                 catch (e) {
                     singletonServices.logger.error(e);
                     const errorResponse = getErrorResponse(e);
-                    channel.send({
+                    await channel.send({
                         error: errorResponse?.message ??
                             (isProduction() ? 'Internal server error' : e.message),
                         ...(!isProduction() && { errorName: e.constructor?.name }),
                     });
-                    setTimeout(() => channel.close(), 200);
+                    setTimeout(() => {
+                        Promise.resolve(channel.close()).catch((closeError) => singletonServices.logger.error(closeError));
+                    }, 200);
                 }
             });
             if (onBinaryMessage) {

package/dist/wirings/channel/local/local-eventhub-service.d.ts

@@ -6,6 +6,7 @@ export declare class LocalEventHubService<Data extends Record<string, any> = {}>
     subscribe<T extends keyof Data>(topic: T, channelId: string): void | Promise<void>;
     unsubscribe<T extends keyof Data>(topic: T, channelId: string): void | Promise<void>;
     publish<T extends keyof Data>(topic: T, channelId: string | null, data: Data[T], isBinary?: boolean): void | Promise<void>;
+    private deliver;
     onChannelOpened(channelHandler: PikkuChannelHandler): void;
     onChannelClosed(channelId: string): void;
 }

package/dist/wirings/channel/local/local-eventhub-service.js

@@ -17,6 +17,9 @@ export class LocalEventHubService {
         }
     }
     publish(topic, channelId, data, isBinary) {
+        return this.deliver(topic, channelId, data, isBinary);
+    }
+    async deliver(topic, channelId, data, isBinary) {
         const subscribedChannelIds = this.subscriptions.get(topic);
         if (!subscribedChannelIds) {
             return;
@@ -27,7 +30,7 @@ export class LocalEventHubService {
             const channel = this.channels.get(toChannelId);
             if (channel) {
                 try {
-                    channel.send(data, isBinary);
+                    await channel.send(data, isBinary);
                 }
                 catch {
                     this.onChannelClosed(toChannelId);

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

@@ -42,7 +42,7 @@ export async function executeCLIViaChannel({ programName, pikkuWS, args = proces
     const renderer = renderers[commandId] || defaultRenderer || defaultJSONRenderer;
     return new Promise((resolve, reject) => {
         const commandRoute = pikkuWS.getRoute('command');
-        const responseHandler = (response) => {
+        const responseHandler = async (response) => {
             if (response?.action === 'cli-control' &&
                 response?.event === 'complete') {
                 commandRoute.unsubscribe(commandId, responseHandler);
@@ -52,7 +52,12 @@ export async function executeCLIViaChannel({ programName, pikkuWS, args = proces
             }
             // A CLI channel response is rendered off-process: there are no services
             // to hand the renderer, and every CLI renderer ignores the argument.
-            renderer(null, response, undefined);
+            try {
+                await renderer(null, response, undefined);
+            }
+            catch (error) {
+                reject(error);
+            }
         };
         commandRoute.subscribe(commandId, responseHandler);
         pikkuWS.ws.addEventListener('close', () => {

package/dist/wirings/cli/channel/cli-raw-client-runner.js

@@ -35,11 +35,11 @@ export async function executeRawCLIViaChannel({ pikkuWS, args = process.argv.sli
     // event loop open.
     const runEnded = new AbortController();
     const approver = approve ?? approverForMode(mode, { signal: runEnded.signal });
-    const render = (commandId, data) => {
+    const render = async (commandId, data) => {
         const renderer = (commandId ? renderers[commandId] : undefined) ||
             defaultRenderer ||
             defaultJSONRenderer;
-        renderer(clientServices, data, undefined);
+        await renderer(clientServices, data, undefined);
     };
     return new Promise((resolve) => {
         const commandRoute = pikkuWS.getRoute('command');
@@ -88,10 +88,14 @@ export async function executeRawCLIViaChannel({ pikkuWS, args = process.argv.sli
             // echo, and rendering that would print noise between real output.
             switch (message?.action) {
                 case 'cli-output':
-                    render(message.commandId, message.data);
+                    render(message.commandId, message.data).catch((e) => {
+                        console.error(e);
+                    });
                     break;
                 case 'cli-result':
-                    render(message.commandId, message.result);
+                    render(message.commandId, message.result).catch((e) => {
+                        console.error(e);
+                    });
                     break;
                 case 'cli-help':
                     console.log(message.help);

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

@@ -255,7 +255,7 @@ export async function runCLICommand({ program, commandPath, data, singletonServi
         return result;
     }
     finally {
-        channel.close();
+        await channel.close();
     }
 }
 export const pikkuCLIRender = (renderer) => {

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

@@ -232,7 +232,7 @@ const wireWebsocketGateway = (config) => {
                 senderId: '',
                 platform: adapter.name,
                 send: async (msg) => {
-                    wire.channel?.send(msg);
+                    await wire.channel?.send(msg);
                 },
             };
         },
@@ -249,7 +249,7 @@ const wireWebsocketGateway = (config) => {
                 senderId: parsed.senderId,
                 platform: adapter.name,
                 send: async (msg) => {
-                    wire.channel?.send(msg);
+                    await wire.channel?.send(msg);
                 },
             };
             wire.gateway = gateway;
@@ -268,7 +268,7 @@ const wireWebsocketGateway = (config) => {
                 ? await runMiddleware(services, wire, gatewayMiddleware, invoke)
                 : await invoke();
             if (result && (result.text || result.richContent || result.attachments)) {
-                wire.channel?.send(result);
+                await wire.channel?.send(result);
             }
         },
     });

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

@@ -149,19 +149,19 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             const channelRef = channel;
             const channelHandler = {
                 getChannel: () => channelRef,
-                send: (data, isBinary) => {
+                send: async (data, isBinary) => {
                     if (isBinary)
-                        channelRef.sendBinary(data);
+                        await channelRef.sendBinary(data);
                     else
-                        channelRef.send(data);
+                        await channelRef.send(data);
                 },
                 sendBinary: (data) => channelRef.sendBinary(data),
             };
             singletonServices.eventHub.onChannelOpened(channelHandler);
             const originalClose = channel.close;
-            channel.close = () => {
+            channel.close = async () => {
                 singletonServices.eventHub.onChannelClosed(channelId);
-                originalClose();
+                await originalClose();
             };
         }
     }
@@ -201,7 +201,7 @@ const executeRoute = async (services, matchedRoute, http, options) => {
                 }
             }
             catch { }
-            channel?.close();
+            await channel?.close();
             return { result };
         }
         throw e;

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

@@ -43,7 +43,7 @@ export async function runScheduledTask({ name, session, traceId, }) {
     const meta = pikkuState(null, 'scheduler', 'meta')[name];
     const userSession = new PikkuSessionService(singletonServices.sessionStore);
     if (session) {
-        userSession.set(session);
+        await userSession.set(session);
     }
     if (!task) {
         throw new ScheduledTaskNotFoundError(`Scheduled task not found: ${name}`);

package/dist/wirings/scope/define-scope.d.ts

@@ -30,3 +30,22 @@ import type { CoreScopes } from './scope.types.js';
  * ```
  */
 export declare const defineScope: (_config: CoreScopes) => void;
+/**
+ * Declares scopes by id without describing them, so an app can grant a scope
+ * (`defineSystemRole`, a function's `scopes`) whose full tree belongs to an
+ * addon it has not wired. `wireAddon({ scopes })` does not declare anything: it
+ * only requires the scope of the addon's functions, and the tree itself arrives
+ * with the addon's metadata. Declaring by id lets an app grant
+ * `pikku:console` without wiring `@pikku/addon-console`, which would otherwise
+ * be the only way to make that grant valid.
+ *
+ * Each id declares that node and its ancestors. When the addon IS wired, its
+ * own description wins and this call adds nothing it does not already have; the
+ * two never conflict, unlike a second `defineScope` for the same root.
+ *
+ * @example
+ * ```typescript
+ * declareScopes(['pikku:console'])
+ * ```
+ */
+export declare const declareScopes: (_ids: string[]) => void;

package/dist/wirings/scope/define-scope.js

@@ -29,3 +29,22 @@
  * ```
  */
 export const defineScope = (_config) => { };
+/**
+ * Declares scopes by id without describing them, so an app can grant a scope
+ * (`defineSystemRole`, a function's `scopes`) whose full tree belongs to an
+ * addon it has not wired. `wireAddon({ scopes })` does not declare anything: it
+ * only requires the scope of the addon's functions, and the tree itself arrives
+ * with the addon's metadata. Declaring by id lets an app grant
+ * `pikku:console` without wiring `@pikku/addon-console`, which would otherwise
+ * be the only way to make that grant valid.
+ *
+ * Each id declares that node and its ancestors. When the addon IS wired, its
+ * own description wins and this call adds nothing it does not already have; the
+ * two never conflict, unlike a second `defineScope` for the same root.
+ *
+ * @example
+ * ```typescript
+ * declareScopes(['pikku:console'])
+ * ```
+ */
+export const declareScopes = (_ids) => { };

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

@@ -1,4 +1,4 @@
-export { defineScope } from './define-scope.js';
+export { defineScope, declareScopes } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
 export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, ScopeOrigin, } from './scope.types.js';
 export { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/scope/index.js

@@ -1,3 +1,3 @@
-export { defineScope } from './define-scope.js';
+export { defineScope, declareScopes } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
 export { hasScopes, verifyScopes } from '../../scopes.js';