@pikku/core 0.12.71 → 0.12.74

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

@@ -16,7 +16,6 @@ addError(RPCNotFoundError, {
     mcpCode: -32601,
     message: 'RPC function not found.',
 });
-/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
 export class RemoteAddonConfigError extends PikkuError {
     constructor(namespace, detail) {
         super(`Remote addon '${namespace}' is misconfigured: ${detail}`);
@@ -26,7 +25,6 @@ addError(RemoteAddonConfigError, {
     status: 500,
     message: 'Remote addon is misconfigured.',
 });
-/** The hosted addon returned a non-2xx response for a remote RPC. */
 export class RemoteAddonRequestError extends PikkuError {
     httpStatus;
     constructor(namespace, fnName, status, detail) {
@@ -39,12 +37,8 @@ addError(RemoteAddonRequestError, {
     message: 'Remote addon request failed.',
 });
 import { runAIAgent, resumeAIAgentSync } from '../ai-agent/ai-agent-runner.js';
-import { streamAIAgent, resumeAIAgent } from '../ai-agent/ai-agent-stream.js';
+import { streamAIAgent, resumeAIAgent, interruptAIAgent, } from '../ai-agent/ai-agent-stream.js';
 import { wrapChannelWithAGUI } from '../ai-agent/ai-agent-agui.js';
-/**
- * Resolve a namespaced function reference to package and function names
- * Uses pikkuState to look up the namespace -> package mapping
- */
 export const resolveNamespace = (namespacedFunction) => {
     const colonIndex = namespacedFunction.indexOf(':');
     if (colonIndex === -1) {
@@ -63,15 +57,7 @@ export const resolveNamespace = (namespacedFunction) => {
         addonConfig: pkgConfig,
     };
 };
-/**
- * Resolve a bare (non-namespaced) RPC name to its pikkuFuncId, preferring
- * the caller's addon package when provided. Returns the function name plus
- * the package scope that resolved it (null = root), so callers can thread
- * the scope into runPikkuFunc without a second lookup.
- */
 const resolvePikkuFunction = (rpcName, packageName = null) => {
-    // Addon-scoped calls: try the caller's package function meta first.
-    // (RPC meta only lives in root; addon functions are registered under their package.)
     if (packageName) {
         const pkgFunctions = pikkuState(packageName, 'function', 'meta');
         const pkgMeta = pkgFunctions?.[rpcName];
@@ -102,7 +88,12 @@ const resolvePikkuFunction = (rpcName, packageName = null) => {
     }
     return { pikkuFuncId: rpcMeta, packageName: null };
 };
-// Context-aware RPC client for use within services
+/**
+ * Marks an addon RPC name that could not be resolved. Module-private on purpose:
+ * resolution failure must never be conflated with an `RPCNotFoundError` thrown by
+ * a function that already started executing, and it must never escape to callers.
+ */
+const NOT_RESOLVED = Symbol('pikku:rpc-not-resolved');
 export class ContextAwareRPCService {
     services;
     wire;
@@ -138,38 +129,18 @@ export class ContextAwareRPCService {
         const updatedWire = {
             ...this.wire,
         };
-        // Check addon namespace first (e.g. 'stripe:createCharge')
         if (funcName.includes(':')) {
-            try {
-                return await this.invokeAddonFunction(funcName, data, updatedWire);
-            }
-            catch (addonErr) {
-                if (!(addonErr instanceof RPCNotFoundError))
-                    throw addonErr;
-                // Not an addon — fall through to local lookup
+            const addonCall = this.resolveAddonFunction(funcName);
+            if (addonCall !== NOT_RESOLVED) {
+                return await this.executeAddonFunction(addonCall, data, updatedWire);
             }
         }
-        // Bare name: resolve via caller's package scope first (if any), then root.
-        // Note: intra-addon bare calls do NOT re-apply the addon's external
-        // addonConfig.auth/tags — those gates are only applied on the external
-        // 'namespace:func' boundary via invokeAddonFunction.
+        let resolved;
         try {
-            const resolved = resolvePikkuFunction(funcName, this.packageName);
-            const addonInstance = resolved.packageName
-                ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
-                : undefined;
-            return await runPikkuFunc('rpc', funcName, resolved.pikkuFuncId, {
-                auth: this.options.requiresAuth,
-                singletonServices: this.services,
-                data: () => data,
-                wire: updatedWire,
-                packageName: resolved.packageName,
-                addonInstance,
-            });
+            resolved = resolvePikkuFunction(funcName, this.packageName);
         }
         catch (e) {
             if (e instanceof RPCNotFoundError) {
-                // Fall back to deployment service (e.g. CF service binding, Lambda Invoke)
                 if (this.services.deploymentService) {
                     const session = this.wire.getSession && typeof this.wire.getSession === 'function'
                         ? await this.wire.getSession()
@@ -179,72 +150,80 @@ export class ContextAwareRPCService {
             }
             throw e;
         }
+        const addonInstance = resolved.packageName
+            ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
+            : undefined;
+        return await runPikkuFunc('rpc', funcName, resolved.pikkuFuncId, {
+            auth: this.options.requiresAuth,
+            singletonServices: this.services,
+            data: () => data,
+            wire: updatedWire,
+            packageName: resolved.packageName,
+            addonInstance,
+        });
     }
     /**
-     * Invoke a function from an addon package
-     * Addon packages register their functions in pikkuState under their package name.
-     * The function is executed using the parent services (shared singleton services).
-     * @private
+     * Resolution half of an addon RPC call: never executes anything, so an
+     * `RPCNotFoundError` thrown by the function itself can never be mistaken for
+     * an unresolvable name.
      */
-    async invokeAddonFunction(namespacedFunction, data, wire) {
-        // Resolve namespace to package name
+    resolveAddonFunction(namespacedFunction) {
         const resolved = resolveNamespace(namespacedFunction);
         if (!resolved) {
-            throw new RPCNotFoundError(namespacedFunction);
+            return NOT_RESOLVED;
         }
         const namespace = namespacedFunction.slice(0, namespacedFunction.indexOf(':'));
-        // wireRemoteAddon: the addon ships as a devDependency (types only) and its
-        // handlers run on the host — dispatch over HTTP, not through local meta.
         if (resolved.addonConfig?.remote) {
-            return this.invokeRemoteAddonFunction(namespace, resolved.function, data);
+            const addonConfig = pikkuState(null, 'addons', 'packages').get(namespace);
+            if (!addonConfig?.remote) {
+                return NOT_RESOLVED;
+            }
+            return {
+                kind: 'remote',
+                namespace,
+                fnName: resolved.function,
+                addonConfig,
+            };
         }
-        // Get the function meta from the addon package
-        // Addon packages use function meta, not RPC meta
         const addonFunctionMeta = pikkuState(resolved.package, 'function', 'meta');
         const funcMeta = addonFunctionMeta[resolved.function];
         if (!funcMeta) {
-            throw new RPCNotFoundError(namespacedFunction);
+            return NOT_RESOLVED;
         }
-        const funcName = funcMeta.pikkuFuncId || resolved.function;
-        const auth = resolved.addonConfig?.auth ?? this.options.requiresAuth;
-        const tags = [
-            ...(resolved.addonConfig?.tags ?? []),
-            ...(funcMeta.tags ?? []),
-        ];
-        // The namespace is the consumer-facing wireAddon name; it selects the
-        // per-instance singleton services and secret/variable/credential overrides.
-        const addonInstance = {
-            namespace,
-            secretOverrides: resolved.addonConfig?.secretOverrides,
-            variableOverrides: resolved.addonConfig?.variableOverrides,
-            credentialOverrides: resolved.addonConfig?.credentialOverrides,
+        return {
+            kind: 'local',
+            namespacedFunction,
+            packageName: resolved.package,
+            pikkuFuncId: funcMeta.pikkuFuncId || resolved.function,
+            auth: resolved.addonConfig?.auth ?? this.options.requiresAuth,
+            tags: [...(resolved.addonConfig?.tags ?? []), ...(funcMeta.tags ?? [])],
+            addonInstance: {
+                namespace,
+                secretOverrides: resolved.addonConfig?.secretOverrides,
+                variableOverrides: resolved.addonConfig?.variableOverrides,
+                credentialOverrides: resolved.addonConfig?.credentialOverrides,
+            },
         };
-        // Execute the function using runPikkuFunc with the addon package's state
-        // We use the parent services (this.services) since addon packages share services
-        // Pass the function's tags so tag-based middleware/permissions are applied
-        return runPikkuFunc('rpc', namespacedFunction, funcName, {
-            auth,
+    }
+    /**
+     * Execution half of an addon RPC call. Must never be called from inside a
+     * `try` that catches `RPCNotFoundError`.
+     */
+    async executeAddonFunction(addonCall, data, wire) {
+        if (addonCall.kind === 'remote') {
+            return this.invokeRemoteAddonFunction(addonCall.namespace, addonCall.fnName, data, addonCall.addonConfig);
+        }
+        return runPikkuFunc('rpc', addonCall.namespacedFunction, addonCall.pikkuFuncId, {
+            auth: addonCall.auth,
             singletonServices: this.services,
             data: () => data,
             wire,
-            packageName: resolved.package,
-            tags,
-            addonInstance,
+            packageName: addonCall.packageName,
+            tags: addonCall.tags,
+            addonInstance: addonCall.addonInstance,
         });
     }
-    /**
-     * Dispatch a `wireRemoteAddon` RPC over HTTP to the hosting service.
-     *
-     * The consumer sends the addon's own function name (not the namespaced form)
-     * to the host's `/remote/rpc/:rpcName` endpoint, authenticating as a client
-     * with the token bound in `wireRemoteAddon({ auth })`. The addon's handlers
-     * live on the host, so there is no local function meta to resolve.
-     */
-    async invokeRemoteAddonFunction(namespace, fnName, data) {
-        const cfg = pikkuState(null, 'addons', 'packages').get(namespace);
-        if (!cfg?.remote) {
-            throw new RPCNotFoundError(`${namespace}:${fnName}`);
-        }
+    async invokeRemoteAddonFunction(namespace, fnName, data, cfg) {
         const serverUrl = typeof cfg.serverUrl === 'function'
             ? await cfg.serverUrl(this.services)
             : cfg.serverUrl;
@@ -270,7 +249,6 @@ export class ContextAwareRPCService {
             body: JSON.stringify({ rpcName: remoteFn, data }),
         });
         if (!res.ok) {
-            // Best-effort body read to enrich the thrown error (mirrors postRpc).
             const detail = (await res.text().catch(() => '')).slice(0, 300);
             throw new RemoteAddonRequestError(namespace, remoteFn, res.status, detail);
         }
@@ -286,21 +264,15 @@ export class ContextAwareRPCService {
             ...wire,
         };
         if (rpcName.includes(':')) {
-            return this.invokeAddonFunction(rpcName, data, mergedWire);
+            const addonCall = this.resolveAddonFunction(rpcName);
+            if (addonCall === NOT_RESOLVED) {
+                throw new RPCNotFoundError(rpcName);
+            }
+            return this.executeAddonFunction(addonCall, data, mergedWire);
         }
+        let resolved;
         try {
-            const resolved = resolvePikkuFunction(rpcName, this.packageName);
-            const addonInstance = resolved.packageName
-                ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
-                : undefined;
-            return await runPikkuFunc('rpc', rpcName, resolved.pikkuFuncId, {
-                auth: this.options.requiresAuth,
-                singletonServices: this.services,
-                data: () => data,
-                wire: mergedWire,
-                packageName: resolved.packageName,
-                addonInstance,
-            });
+            resolved = resolvePikkuFunction(rpcName, this.packageName);
         }
         catch (e) {
             if (e instanceof RPCNotFoundError && this.services.deploymentService) {
@@ -311,6 +283,17 @@ export class ContextAwareRPCService {
             }
             throw e;
         }
+        const addonInstance = resolved.packageName
+            ? addonInstanceForNamespace(this.wire.addonNamespace, resolved.packageName)
+            : undefined;
+        return await runPikkuFunc('rpc', rpcName, resolved.pikkuFuncId, {
+            auth: this.options.requiresAuth,
+            singletonServices: this.services,
+            data: () => data,
+            wire: mergedWire,
+            packageName: resolved.packageName,
+            addonInstance,
+        });
     }
     async startWorkflow(workflowName, input, options) {
         if (!this.services.workflowService) {
@@ -370,6 +353,9 @@ export class ContextAwareRPCService {
                     getCredential: this.wire.getCredential?.bind(this.wire),
                 }, options);
             },
+            interrupt: async (runId, reason) => {
+                return interruptAIAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: this.options.sessionService });
+            },
             approve: async (runId, approvals, expectedAgentName) => {
                 const result = await resumeAIAgentSync(runId, approvals, {
                     sessionService: this.options.sessionService,
@@ -397,9 +383,7 @@ export class ContextAwareRPCService {
         return this.services.deploymentService.invoke(funcName, data, session, this.wire.traceId);
     }
 }
-// RPC Service class for the global interface
 export class PikkuRPCService {
-    // Convenience function for initializing
     getContextRPCService(services, wire, requiresAuthOrOptions, depth = 0, packageName = null) {
         const options = typeof requiresAuthOrOptions === 'object' &&
             requiresAuthOrOptions !== null
@@ -420,5 +404,4 @@ export class PikkuRPCService {
         };
     }
 }
-// Create a singleton instance
 export const rpcService = new PikkuRPCService();

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentInterruptResult } from '../ai-agent/ai-agent-interrupt.js';
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
     depth: number;
     global: boolean;
@@ -16,6 +17,12 @@ export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) =
             toolCallId: string;
             approved: boolean;
         }[], expectedAgentName?: string) => Promise<any>;
+        /** Stop an in-flight run. Needs no channel — it ends a stream rather than
+         *  continuing one — so it is reachable over a plain RPC while the stream
+         *  itself is held open elsewhere. Resolves `stopped: false` when there was
+         *  nothing left to stop, and names any tools still executing — their side
+         *  effects have already happened and are not undone by interrupting. */
+        interrupt: (runId: string, reason?: 'speech' | 'user' | 'timeout') => Promise<AgentInterruptResult>;
     };
 };
 export type RPCMeta = {
@@ -23,16 +30,10 @@ export type RPCMeta = {
     expose: boolean;
     remote?: boolean;
 };
-/**
- * Type for RPC handlers
- */
 export interface RPCHandler<Input, Output> {
     input: Input;
     output: Output;
 }
-/**
- * Resolved function reference from namespace
- */
 export interface ResolvedFunction {
     package: string;
     function: string;

package/dist/wirings/rpc/wire-addon.d.ts

@@ -1,3 +1,4 @@
+import type { CorePikkuMiddleware } from '../../types/core.types.js';
 export type WireAddonConfig = {
     name: string;
     package: string;
@@ -5,8 +6,32 @@ export type WireAddonConfig = {
     auth?: boolean;
     mcp?: boolean;
     tags?: string[];
+    /** Required of every function in the addon, on top of the function's own. */
+    scopes?: string[];
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;
     credentialOverrides?: Record<string, string>;
 };
 export declare const wireAddon: (config: WireAddonConfig) => void;
+/**
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+export declare const resolveAddonScopes: (packageName: string | null, namespace?: string) => string[];
+/**
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export declare const resolveAddonTags: (packageName: string | null, namespace?: string) => string[];
+/**
+ * True when any governing instance requires a session. `auth: false` is not
+ * honoured here — on a direct wiring it would weaken the wiring's own gate.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export declare const resolveAddonAuth: (packageName: string | null, namespace?: string) => boolean;
+/**
+ * Addon tags name middleware the *consuming app* registered, so they resolve
+ * against the root tag groups rather than the addon package's own.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export declare const resolveAddonTagMiddleware: (packageName: string | null, namespace?: string) => CorePikkuMiddleware[];

package/dist/wirings/rpc/wire-addon.js

@@ -1,10 +1,12 @@
 import { pikkuState } from '../../pikku-state.js';
+import { getTagGroups } from '../../utils.js';
 export const wireAddon = (config) => {
     pikkuState(null, 'addons', 'packages').set(config.name, {
         package: config.package,
         rpcEndpoint: config.rpcEndpoint,
         auth: config.auth,
         tags: config.tags,
+        ...(config.scopes ? { scopes: config.scopes } : {}),
         ...(config.secretOverrides
             ? { secretOverrides: config.secretOverrides }
             : {}),
@@ -16,3 +18,63 @@ export const wireAddon = (config) => {
             : {}),
     });
 };
+/**
+ * The addon configs a running function is governed by: the named instance when
+ * the caller resolved one, every instance of the package otherwise.
+ *
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+const governingAddonConfigs = (packageName, namespace) => {
+    if (!packageName) {
+        return [];
+    }
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons) {
+        return [];
+    }
+    if (namespace) {
+        const config = addons.get(namespace);
+        if (config?.package === packageName) {
+            return [config];
+        }
+    }
+    return [...addons.values()].filter((config) => config?.package === packageName);
+};
+const unionOf = (packageName, namespace, field) => {
+    const values = new Set();
+    for (const config of governingAddonConfigs(packageName, namespace)) {
+        for (const value of config[field] ?? []) {
+            values.add(value);
+        }
+    }
+    return [...values];
+};
+/**
+ * knowledge: decisions/security/addon-scopes-are-resolved-where-the-function-runs.md
+ */
+export const resolveAddonScopes = (packageName, namespace) => unionOf(packageName, namespace, 'scopes');
+/**
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonTags = (packageName, namespace) => unionOf(packageName, namespace, 'tags');
+/**
+ * True when any governing instance requires a session. `auth: false` is not
+ * honoured here — on a direct wiring it would weaken the wiring's own gate.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonAuth = (packageName, namespace) => governingAddonConfigs(packageName, namespace).some((config) => config.auth === true);
+/**
+ * Addon tags name middleware the *consuming app* registered, so they resolve
+ * against the root tag groups rather than the addon package's own.
+ *
+ * knowledge: decisions/security/addon-auth-and-tags-only-tighten.md
+ */
+export const resolveAddonTagMiddleware = (packageName, namespace) => {
+    const tags = resolveAddonTags(packageName, namespace);
+    if (tags.length === 0) {
+        return [];
+    }
+    const tagGroups = pikkuState(null, 'middleware', 'tagGroup');
+    return tags.flatMap((tag) => getTagGroups(tagGroups, tag).flat());
+};

package/dist/wirings/rpc/wire-remote-addon.d.ts

@@ -1,18 +1,5 @@
 import type { CoreServices, PikkuWire } from '../../types/core.types.js';
-/**
- * How the consumer supplies the token the hosted addon's auth expects.
- *
- * This is a CLIENT authenticating to a hosted library — NOT pikku's trusted
- * machine-to-machine mesh (which uses `PIKKU_REMOTE_SECRET`). The consumer binds
- * the addon's declared auth requirement to a local source:
- *  - `credentialId` — per-user credential, resolved via `wire.getCredential(id)`
- *  - `secretId`     — platform key, resolved via the secrets service
- *  - `resolve`      — custom escape hatch
- * Omit entirely when the addon declares its remote surface is public.
- *
- * The value is sent `Authorization: Bearer <token>` by default; a non-default
- * header is declared once by the addon (its meta), never chosen here.
- */
+/** Sent as `Authorization: Bearer <token>`; a non-default header is declared by the addon. */
 export type RemoteAddonAuth = {
     credentialId: string;
 } | {
@@ -23,25 +10,13 @@ export type RemoteAddonAuth = {
 export type WireRemoteAddonConfig = {
     /** Consumer-facing namespace, e.g. `registry` → `rpc('registry:getOpenApi')` */
     name: string;
-    /**
-     * The addon package. Installed as a **devDependency** (types only — its
-     * handlers run on the host); `pikku verify` enforces this.
-     */
+    /** Must be installed as a devDependency — `pikku verify` enforces this. */
     package: string;
-    /** Base URL of the host serving the addon's remote surface. */
     serverUrl: string | ((services: CoreServices) => string | Promise<string>);
-    /** Bind the addon's declared auth to a local source. Omit if the surface is public. */
+    /** Omit when the addon declares its remote surface public. */
     auth?: RemoteAddonAuth;
     /** Map a consumer-facing fn name → the remote fn name, when they differ (rare). */
     remoteName?: (fn: string) => string;
     tags?: string[];
 };
-/**
- * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
- *
- * Unlike `wireAddon` (which bundles the addon's functions in-process, a
- * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
- * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
- * only). See {@link RemoteAddonAuth} for how auth is bound.
- */
 export declare const wireRemoteAddon: (config: WireRemoteAddonConfig) => void;

package/dist/wirings/rpc/wire-remote-addon.js

@@ -1,12 +1,4 @@
 import { pikkuState } from '../../pikku-state.js';
-/**
- * Consume a hosted addon's `remote: true` RPCs transparently over HTTP.
- *
- * Unlike `wireAddon` (which bundles the addon's functions in-process, a
- * production dependency), `wireRemoteAddon` dispatches `rpc('name:fn')` to the
- * host at `serverUrl`, fully typed — the addon ships as a devDependency (types
- * only). See {@link RemoteAddonAuth} for how auth is bound.
- */
 export const wireRemoteAddon = (config) => {
     pikkuState(null, 'addons', 'packages').set(config.name, {
         package: config.package,

package/dist/wirings/scheduler/log-schedulers.d.ts

@@ -1,6 +1,2 @@
 import type { Logger } from '../../services/index.js';
-/**
- * Logs all the loaded scheduled tasks.
- * @param logger - A logger for logging information.
- */
 export declare const logSchedulers: (logger: Logger) => void;

package/dist/wirings/scheduler/log-schedulers.js

@@ -1,8 +1,4 @@
 import { pikkuState } from '../../pikku-state.js';
-/**
- * Logs all the loaded scheduled tasks.
- * @param logger - A logger for logging information.
- */
 export const logSchedulers = (logger) => {
     const scheduledTasks = pikkuState(null, 'scheduler', 'tasks');
     if (scheduledTasks.size === 0) {

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

@@ -4,7 +4,6 @@ import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../.
 export type RunScheduledTasksParams = {
     name: string;
     session?: CoreUserSession;
-    /** Pre-resolved trace ID */
     traceId?: string;
 };
 export declare const wireScheduler: <PikkuFunctionConfig extends CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>>(scheduledTask: CoreScheduledTask<PikkuFunctionConfig>) => void;

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

@@ -51,7 +51,6 @@ export async function runScheduledTask({ name, session, traceId, }) {
     if (!meta) {
         throw new ScheduledTaskNotFoundError(`Scheduled task meta not found: ${name}`);
     }
-    // Create the scheduled task wire object
     const wire = {
         traceId: resolvedTraceId,
         scheduledTask: {

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

@@ -1,16 +1,10 @@
 import type { CoreUserSession, CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
-/**
- * Represents metadata for scheduled tasks, including title, schedule, and documentation.
- */
 export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Record<string, CommonWireMeta & {
     name: string;
     schedule: string;
     session?: UserSession;
 }>;
-/**
- * Represents a core scheduled task.
- */
 export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<void, void>>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     name: string;
     schedule: string;
@@ -18,17 +12,10 @@ export type CoreScheduledTask<PikkuFunctionConfig = CorePikkuFunctionConfig<Core
     tags?: string[];
     middleware?: PikkuMiddleware[];
 };
-/**
- * Represents a scheduled task wire object for middleware
- * Provides information about the current scheduled task execution
- */
 export interface PikkuScheduledTask {
-    /** The name of the scheduled task being executed */
     name: string;
-    /** The cron schedule expression */
     schedule: string;
-    /** Current execution timestamp */
     executionTime: Date;
-    /** Skip the current task execution */
+    /** Never returns — throws to abort the run. */
     skip: (reason?: string) => void;
 }

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

@@ -0,0 +1,32 @@
+import type { CoreScopes } from './scope.types.js';
+/**
+ * Declares scopes. The body is a no-op that tree-shakes away — the CLI reads
+ * the call by AST and generates a `ScopeId` union, so a function referencing an
+ * undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * defineScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export declare const defineScope: (_config: CoreScopes) => void;

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

@@ -0,0 +1,31 @@
+/**
+ * Declares scopes. The body is a no-op that tree-shakes away — the CLI reads
+ * the call by AST and generates a `ScopeId` union, so a function referencing an
+ * undeclared scope fails the build.
+ *
+ * Scopes are keyed by segment at every level: a scope is named by its key, and
+ * its value describes it. Every node is grantable — the declaration below
+ * yields `admin`, `admin:invoices`, `admin:invoices:create`,
+ * `admin:invoices:void` and `billing`.
+ *
+ * @example
+ * ```typescript
+ * defineScope({
+ *   admin: {
+ *     displayName: 'Administration',
+ *     description: 'Administrative access',
+ *     scopes: {
+ *       invoices: {
+ *         description: 'Invoice management',
+ *         scopes: {
+ *           create: { description: 'Create invoices' },
+ *           void: { description: 'Void invoices' },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   billing: {},
+ * })
+ * ```
+ */
+export const defineScope = (_config) => { };

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

@@ -1,3 +1,3 @@
-export { wireScope } from './wire-scope.js';
+export { defineScope } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
 export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, } from './scope.types.js';