@pikku/core 0.12.72 → 0.12.74

package/dist/wirings/queue/validate-worker-config.js

@@ -1,28 +1,16 @@
-/**
- * Validates worker configuration using a mapping table
- * This provides a flexible, maintainable way to validate configurations
- * across different queue implementations
- *
- * @param config - The worker configuration to validate
- * @param configMapping - The mapping table defining supported/unsupported configurations
- * @returns Validation result with applied, ignored, warnings, and fallbacks
- */
 export function validateWorkerConfig(configMapping, config = {}) {
     const applied = {};
     const ignored = {};
     const warnings = [];
     const fallbacks = {};
-    // Process each configuration property
     for (const [key, value] of Object.entries(config)) {
         if (value === undefined)
             continue;
         const configKey = key;
-        // Check if it's a supported configuration
         if (configKey in configMapping.supported) {
             applied[configKey] = value;
             continue;
         }
-        // Check if it's a fallback configuration
         if (configKey in configMapping.fallbacks) {
             const fallbackMapping = configMapping.fallbacks[configKey];
             applied[configKey] = value;
@@ -30,14 +18,12 @@ export function validateWorkerConfig(configMapping, config = {}) {
             warnings.push(`${key}: ${fallbackMapping.reason}. ${fallbackMapping.explanation}`);
             continue;
         }
-        // Check if it's an unsupported configuration
         if (configKey in configMapping.unsupported) {
             ignored[configKey] = value;
             const mapping = configMapping.unsupported[configKey];
             warnings.push(`${key}: ${mapping.reason}. ${mapping.explanation}`);
             continue;
         }
-        // Unknown configuration
         ignored[configKey] = value;
         warnings.push(`${key}: Unknown configuration option for this queue implementation`);
     }

package/dist/wirings/role/define-system-role.d.ts

@@ -0,0 +1,32 @@
+import type { CoreSystemRoles } from './role.types.js';
+/**
+ * No-op function for declaring system roles.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `SystemRoleName`
+ * union, so a persona naming an undeclared role fails the build.
+ *
+ * A system role is a role that ships with the product: the console may grant
+ * it, but cannot rename, re-scope or delete it. Roles an admin composes in the
+ * console are unaffected and are not declared here.
+ *
+ * Removal is deliberately not destructive. Deleting a declaration leaves the
+ * row in the store, marked undeclared and inert, until `pikku roles prune` —
+ * the same additive contract `defineScope` has, and for the same reason: a
+ * mid-deploy revocation is not something a code edit should be able to cause.
+ *
+ * @example
+ * ```typescript
+ * defineSystemRole({
+ *   buyer: {
+ *     displayName: 'Buyer',
+ *     description: 'Can browse the catalogue and place orders',
+ *     scopes: ['catalogue:read', 'orders:create'],
+ *   },
+ *   admin: {
+ *     description: 'Everything',
+ *     scopes: ['admin'],
+ *   },
+ * })
+ * ```
+ */
+export declare const defineSystemRole: (_config: CoreSystemRoles) => void;

package/dist/wirings/role/define-system-role.js

@@ -0,0 +1,31 @@
+/**
+ * No-op function for declaring system roles.
+ * This exists purely for TypeScript type checking and will be tree-shaken.
+ * The CLI extracts metadata via AST parsing and generates a `SystemRoleName`
+ * union, so a persona naming an undeclared role fails the build.
+ *
+ * A system role is a role that ships with the product: the console may grant
+ * it, but cannot rename, re-scope or delete it. Roles an admin composes in the
+ * console are unaffected and are not declared here.
+ *
+ * Removal is deliberately not destructive. Deleting a declaration leaves the
+ * row in the store, marked undeclared and inert, until `pikku roles prune` —
+ * the same additive contract `defineScope` has, and for the same reason: a
+ * mid-deploy revocation is not something a code edit should be able to cause.
+ *
+ * @example
+ * ```typescript
+ * defineSystemRole({
+ *   buyer: {
+ *     displayName: 'Buyer',
+ *     description: 'Can browse the catalogue and place orders',
+ *     scopes: ['catalogue:read', 'orders:create'],
+ *   },
+ *   admin: {
+ *     description: 'Everything',
+ *     scopes: ['admin'],
+ *   },
+ * })
+ * ```
+ */
+export const defineSystemRole = (_config) => { };

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

@@ -0,0 +1,3 @@
+export { defineSystemRole } from './define-system-role.js';
+export { flattenSystemRoleDefinitions, validateAndBuildSystemRoleDefinitionsMeta, } from './validate-role-definitions.js';
+export type { CoreSystemRole, CoreSystemRoles, SystemRole, SystemRoleDefinitionMeta, SystemRoleDefinitions, SystemRoleDefinitionsMeta, } from './role.types.js';

package/dist/wirings/role/index.js

@@ -0,0 +1,2 @@
+export { defineSystemRole } from './define-system-role.js';
+export { flattenSystemRoleDefinitions, validateAndBuildSystemRoleDefinitionsMeta, } from './validate-role-definitions.js';

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

@@ -0,0 +1,43 @@
+/**
+ * A system role: a named set of scopes that ships with the product.
+ *
+ * System roles are declared in code, which is what separates them from the
+ * roles an admin composes in the console. The distinction is the one AWS draws
+ * between managed and customer-managed policies — a system role is part of the
+ * application's surface, so the console may show and grant it but must not
+ * rename, re-scope or delete it.
+ */
+export type CoreSystemRole = {
+    /** Short human-readable name, e.g. "Buyer". */
+    displayName?: string;
+    /** Longer-form description, surfaced in the console when granting. */
+    description?: string;
+    /**
+     * The scopes this role grants. Every id must be declared with
+     * `defineScope` — the inspector fails the build otherwise, so a role cannot
+     * quietly grant a scope that no function checks.
+     */
+    scopes: string[];
+};
+/**
+ * System roles to declare, keyed by name. A key must be non-empty and must not
+ * contain `:` — that separator belongs to scopes, and a role that looks like a
+ * scope id is a role nobody reads correctly.
+ */
+export type CoreSystemRoles = Record<string, CoreSystemRole>;
+export type SystemRoleDefinitionMeta = {
+    name: string;
+    displayName?: string;
+    description?: string;
+    scopes: string[];
+    sourceFile?: string;
+};
+export type SystemRoleDefinitions = SystemRoleDefinitionMeta[];
+export type SystemRoleDefinitionsMeta = Record<string, SystemRoleDefinitionMeta>;
+/** A declared system role, ready to sync into a scope store. */
+export type SystemRole = {
+    name: string;
+    displayName?: string;
+    description?: string;
+    scopes: string[];
+};

package/dist/wirings/role/role.types.js

@@ -0,0 +1 @@
+export {};

package/dist/wirings/role/validate-role-definitions.d.ts

@@ -0,0 +1,21 @@
+import type { SystemRole, SystemRoleDefinitions, SystemRoleDefinitionsMeta } from './role.types.js';
+/**
+ * The declared roles as a flat list, deduplicated by name.
+ *
+ * A role may legitimately be declared more than once — an addon and its host
+ * app both contributing `admin`, say — and
+ * {@link validateAndBuildSystemRoleDefinitionsMeta} has already guaranteed
+ * those declarations are identical, so the second is redundant rather than
+ * conflicting. Collapsing here keeps codegen (which emits an object literal
+ * keyed by name) and a ScopeService (which syncs one row per role) honest.
+ */
+export declare const flattenSystemRoleDefinitions: (definitions: SystemRoleDefinitions) => SystemRole[];
+/**
+ * Validates declared system roles and keys them by name.
+ *
+ * Definitions sharing a name must grant the same scope set; a conflicting
+ * redeclaration is a hard error naming both source files. Order within
+ * `scopes` is not significant — two declarations listing the same scopes
+ * differently are the same role.
+ */
+export declare function validateAndBuildSystemRoleDefinitionsMeta(definitions: SystemRoleDefinitions): SystemRoleDefinitionsMeta;

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

@@ -0,0 +1,71 @@
+const SEPARATOR = ':';
+const assertRoleName = (name) => {
+    if (name.length === 0) {
+        throw new Error('A system role is declared with an empty name.');
+    }
+    if (name.includes(SEPARATOR)) {
+        throw new Error(`System role '${name}' contains the '${SEPARATOR}' separator. ` +
+            `'${SEPARATOR}' delimits scope ids; a role named like a scope reads as one.`);
+    }
+};
+/**
+ * The declared roles as a flat list, deduplicated by name.
+ *
+ * A role may legitimately be declared more than once — an addon and its host
+ * app both contributing `admin`, say — and
+ * {@link validateAndBuildSystemRoleDefinitionsMeta} has already guaranteed
+ * those declarations are identical, so the second is redundant rather than
+ * conflicting. Collapsing here keeps codegen (which emits an object literal
+ * keyed by name) and a ScopeService (which syncs one row per role) honest.
+ */
+export const flattenSystemRoleDefinitions = (definitions) => {
+    const seen = new Set();
+    const out = [];
+    for (const def of definitions) {
+        if (seen.has(def.name)) {
+            continue;
+        }
+        seen.add(def.name);
+        out.push({
+            name: def.name,
+            displayName: def.displayName,
+            description: def.description,
+            scopes: [...def.scopes],
+        });
+    }
+    return out;
+};
+/**
+ * Validates declared system roles and keys them by name.
+ *
+ * Definitions sharing a name must grant the same scope set; a conflicting
+ * redeclaration is a hard error naming both source files. Order within
+ * `scopes` is not significant — two declarations listing the same scopes
+ * differently are the same role.
+ */
+export function validateAndBuildSystemRoleDefinitionsMeta(definitions) {
+    const meta = {};
+    for (const def of definitions) {
+        assertRoleName(def.name);
+        const existing = meta[def.name];
+        if (existing) {
+            const sameScopes = JSON.stringify([...existing.scopes].sort()) ===
+                JSON.stringify([...def.scopes].sort());
+            if (!sameScopes) {
+                throw new Error(`System role '${def.name}' is declared with different scopes.\n` +
+                    `  First declaration: ${existing.sourceFile ?? 'unknown'}\n` +
+                    `  Second declaration: ${def.sourceFile ?? 'unknown'}\n` +
+                    `Roles sharing a name must grant the same scopes.`);
+            }
+            continue;
+        }
+        meta[def.name] = {
+            name: def.name,
+            displayName: def.displayName,
+            description: def.description,
+            scopes: [...def.scopes],
+            sourceFile: def.sourceFile,
+        };
+    }
+    return meta;
+}

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

@@ -1,28 +1,9 @@
 import type { CoreSingletonServices } from '../../types/core.types.js';
-/**
- * A single wired addon instance: a namespace (wireAddon `name`) plus the
- * per-instance name-aliases that remap the logical names the addon reads to
- * the actual project secret/variable/credential names.
- */
 export type AddonInstance = {
     namespace: string;
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;
     credentialOverrides?: Record<string, string>;
 };
-/**
- * Get or create singleton services for an addon instance.
- * Services are cached in pikkuState to avoid recreation on each call.
- *
- * @param packageName - The addon package name
- * @param parentServices - The parent/caller's singleton services (used as base)
- * @param addonInstance - The wired instance whose overrides shape the services
- * @returns The instance's singleton services
- */
 export declare const getOrCreatePackageSingletonServices: (packageName: string, parentServices: CoreSingletonServices, addonInstance?: AddonInstance) => Promise<CoreSingletonServices>;
-/**
- * Build the addon instance descriptor (namespace + per-instance overrides) for
- * a bare intra-addon call, using the namespace currently executing on the wire.
- * Returns undefined unless that namespace maps to the resolved package.
- */
 export declare const addonInstanceForNamespace: (namespace: string | undefined, expectedPackage: string) => AddonInstance | undefined;

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

@@ -1,8 +1,4 @@
 import { pikkuState } from '../../pikku-state.js';
-/**
- * Wrap a SecretService so that the logical secret names an addon reads are
- * remapped to the actual project secret names via the instance's overrides.
- */
 const aliasSecretService = (secrets, overrides) => {
     const map = (key) => overrides[key] ?? key;
     return {
@@ -22,10 +18,6 @@ const aliasSecretService = (secrets, overrides) => {
         },
     };
 };
-/**
- * Wrap a VariablesService so that the logical variable names an addon reads
- * are remapped to the actual project variable names via the instance's overrides.
- */
 const aliasVariablesService = (variables, overrides) => {
     const map = (name) => overrides[name] ?? name;
     return {
@@ -51,10 +43,6 @@ const aliasVariablesService = (variables, overrides) => {
         delete: (name) => variables.delete(map(name)),
     };
 };
-/**
- * Find the consumer-defined namespace (from wireAddon) for a given addon package.
- * Returns null if the package isn't registered as an addon.
- */
 const findAddonNamespaceForPackage = (packageName) => {
     const addons = pikkuState(null, 'addons', 'packages');
     if (!addons)
@@ -65,18 +53,6 @@ const findAddonNamespaceForPackage = (packageName) => {
     }
     return null;
 };
-/**
- * Wrap a workflow service so that bare workflow names passed from inside an
- * addon function are auto-prefixed with the addon's consumer-facing namespace.
- * Without this, `runToCompletion('myWorkflow')` from inside an addon misses
- * the workflow registered under the addon's package scope and throws
- * WorkflowNotFoundError — forcing addons to hardcode their consumer-defined
- * namespace, which couples the addon to its caller.
- *
- * Explicit `'ns:name'` and bare names that already exist in root meta are
- * unaffected; only bare names that would otherwise miss resolution get
- * prefixed.
- */
 const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
     return new Proxy(service, {
         get(target, prop, receiver) {
@@ -84,8 +60,6 @@ const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
                 const original = Reflect.get(target, prop, receiver);
                 return function (name, ...rest) {
                     if (typeof name === 'string' && !name.includes(':')) {
-                        // Prefer the known instance namespace; fall back to the
-                        // package's sole namespace when invoked without an instance.
                         const ns = namespace ?? findAddonNamespaceForPackage(packageName);
                         if (ns) {
                             name = `${ns}:${name}`;
@@ -98,19 +72,7 @@ const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
         },
     });
 };
-/**
- * Get or create singleton services for an addon instance.
- * Services are cached in pikkuState to avoid recreation on each call.
- *
- * @param packageName - The addon package name
- * @param parentServices - The parent/caller's singleton services (used as base)
- * @param addonInstance - The wired instance whose overrides shape the services
- * @returns The instance's singleton services
- */
 export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
-    // Cache per instance (namespace), not per package, so two instances of one
-    // package get separate services built with their own overrides. A bare
-    // package-scoped call (no instance) falls back to per-package caching.
     const cacheKey = addonInstance?.namespace ?? packageName;
     const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices');
     if (cachedServices) {
@@ -118,12 +80,8 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
     }
     const factories = pikkuState(packageName, 'package', 'factories');
     if (!factories || !factories.createSingletonServices) {
-        // No factories registered, use parent services
         return parentServices;
     }
-    // Apply this instance's secret/variable overrides by aliasing the resolver
-    // services the addon reads from, so its createSingletonServices resolves
-    // instance-specific secrets/variables.
     let existingServices = parentServices;
     if (addonInstance?.secretOverrides && parentServices.secrets) {
         existingServices = {
@@ -137,15 +95,11 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
             variables: aliasVariablesService(parentServices.variables, addonInstance.variableOverrides),
         };
     }
-    // Create config for the package (use parent config if no factory)
     let config = existingServices.config;
     if (factories.createConfig) {
         config = await factories.createConfig(existingServices.variables);
     }
-    // Create singleton services for the package, passing parent services as existing
     const packageServices = await factories.createSingletonServices(config, existingServices);
-    // Wrap workflowService so that bare names used inside the addon's functions
-    // resolve to workflows registered under the addon's package scope.
     if (packageServices.workflowService &&
         typeof packageServices.workflowService === 'object') {
         packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName, addonInstance?.namespace ?? null);
@@ -153,11 +107,6 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
     pikkuState(cacheKey, 'package', 'singletonServices', packageServices);
     return packageServices;
 };
-/**
- * Build the addon instance descriptor (namespace + per-instance overrides) for
- * a bare intra-addon call, using the namespace currently executing on the wire.
- * Returns undefined unless that namespace maps to the resolved package.
- */
 export const addonInstanceForNamespace = (namespace, expectedPackage) => {
     if (!namespace)
         return undefined;

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

@@ -1,9 +1,5 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
-/**
- * How a `wireRemoteAddon` consumer supplies the token the hosted addon expects.
- * This is a CLIENT authenticating to a hosted library — not the trusted mesh.
- */
 export type RemoteAddonAuthBinding = {
     credentialId: string;
 } | {
@@ -11,16 +7,9 @@ export type RemoteAddonAuthBinding = {
 } | {
     resolve: (services: CoreServices, wire: PikkuRawWire) => string | Promise<string>;
 };
-/** The addon's auth was bound but the source produced no token — fail closed. */
 export declare class RemoteAddonAuthError extends PikkuError {
     readonly namespace: string;
     constructor(namespace: string, detail: string);
 }
-/**
- * Resolve the bearer token for a remote addon call from the consumer's bound
- * source. Returns `null` only when no auth is bound (a public surface).
- *
- * Security: the resolved token is never logged or traced; per-user credentials
- * are read via the wire (scoped to `pikkuUserId`); an empty result fails closed.
- */
+/** Returns `null` only when no auth is bound; an empty resolved token throws. */
 export declare function resolveRemoteAddonToken(auth: RemoteAddonAuthBinding | undefined, services: CoreServices, wire: PikkuRawWire, namespace: string): Promise<string | null>;

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

@@ -1,5 +1,4 @@
 import { PikkuError, addError } from '../../errors/error-handler.js';
-/** The addon's auth was bound but the source produced no token — fail closed. */
 export class RemoteAddonAuthError extends PikkuError {
     namespace;
     constructor(namespace, detail) {
@@ -11,16 +10,9 @@ addError(RemoteAddonAuthError, {
     status: 401,
     message: 'Remote addon authentication could not be resolved.',
 });
-/**
- * Resolve the bearer token for a remote addon call from the consumer's bound
- * source. Returns `null` only when no auth is bound (a public surface).
- *
- * Security: the resolved token is never logged or traced; per-user credentials
- * are read via the wire (scoped to `pikkuUserId`); an empty result fails closed.
- */
+/** Returns `null` only when no auth is bound; an empty resolved token throws. */
 export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
     if (!auth) {
-        // No auth bound → the addon declares its remote surface public.
         return null;
     }
     let token;

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

@@ -7,21 +7,15 @@ export declare class RPCNotFoundError extends PikkuError {
     readonly rpcName: string;
     constructor(rpcName: string);
 }
-/** A `wireRemoteAddon` namespace is missing a usable `serverUrl`. */
 export declare class RemoteAddonConfigError extends PikkuError {
     constructor(namespace: string, detail: string);
 }
-/** The hosted addon returned a non-2xx response for a remote RPC. */
 export declare class RemoteAddonRequestError extends PikkuError {
     readonly httpStatus: number;
     constructor(namespace: string, fnName: string, status: number, detail: string);
 }
 import type { AIAgentInput } from '../ai-agent/ai-agent.types.js';
 import type { StreamAIAgentOptions } from '../ai-agent/ai-agent-prepare.js';
-/**
- * Resolve a namespaced function reference to package and function names
- * Uses pikkuState to look up the namespace -> package mapping
- */
 export declare const resolveNamespace: (namespacedFunction: string) => ResolvedFunction | null;
 export declare class ContextAwareRPCService {
     private services;
@@ -35,20 +29,16 @@ export declare class ContextAwareRPCService {
     rpcExposed(funcName: string, data: any): Promise<any>;
     rpc<In = any, Out = any>(funcName: string, data: In): Promise<Out>;
     /**
-     * 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.
      */
-    private invokeAddonFunction;
+    private resolveAddonFunction;
     /**
-     * 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.
+     * Execution half of an addon RPC call. Must never be called from inside a
+     * `try` that catches `RPCNotFoundError`.
      */
+    private executeAddonFunction;
     private invokeRemoteAddonFunction;
     rpcWithWire<In = any, Out = any>(rpcName: string, data: In, wire: PikkuRawWire): Promise<Out>;
     startWorkflow<In = any>(workflowName: string, input: In, options?: {
@@ -89,6 +79,7 @@ export declare class ContextAwareRPCService {
             toolCallId: string;
             approved: boolean;
         }, options?: StreamAIAgentOptions) => Promise<void>;
+        interrupt: (runId: string, reason?: "speech" | "user" | "timeout") => Promise<import("../ai-agent/ai-agent-interrupt.js").AgentInterruptResult>;
         approve: (runId: string, approvals: {
             toolCallId: string;
             approved: boolean;
@@ -119,7 +110,9 @@ export declare class PikkuRPCService<Services extends CoreServices, TypedRPC = P
 }
 export declare const rpcService: PikkuRPCService<import("../../types/core.types.js").CoreSingletonServices<{
     logLevel?: import("../../services/logger.js").LogLevel;
-    secrets?: {};
+    secrets?: {
+        requireAllowedHosts?: boolean;
+    };
     workflow?: import("../workflow/workflow.types.js").WorkflowServiceConfig;
     webhook?: import("../../services/webhook-service.js").WebhookServiceConfig;
     postgres?: import("../../types/core.types.js").PostgresConfig;