@pikku/core 0.12.72 → 0.12.77

package/dist/wirings/scope/index.js

@@ -1,2 +1,2 @@
-export { wireScope } from './wire-scope.js';
+export { defineScope } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';

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

@@ -1,20 +1,19 @@
 /**
- * A node within a scope tree. Every node is itself a grantable scope — given
- * `admin` containing `invoices` containing `create`, all three of `admin`,
- * `admin:invoices` and `admin:invoices:create` are valid scope ids.
+ * Every node is itself a grantable scope: `admin` containing `invoices`
+ * containing `create` yields all three of `admin`, `admin:invoices` and
+ * `admin:invoices:create`.
  */
 export type CoreScopeNode = {
-    /** Short human-readable name, e.g. "Administration". */
     displayName?: string;
-    /** Longer-form description, surfaced in the console when granting. */
+    /** Surfaced in the console when granting. */
     description?: string;
     /** Nested scopes, keyed by their segment. */
     scopes?: Record<string, CoreScopeNode>;
 };
 /**
- * Scope trees to declare, keyed by their root segment. A root is just a node —
- * it is named by its key, exactly like every node beneath it. A key must not
- * contain `:` or be `*`.
+ * Scope trees keyed by their root segment — a root is named by its key exactly
+ * like every node beneath it. A key must not contain `:` or be `*`; nothing
+ * enforces that at runtime, only the build.
  */
 export type CoreScopes = Record<string, CoreScopeNode>;
 export type ScopeNodeMeta = {
@@ -31,7 +30,6 @@ export type ScopeDefinitionMeta = {
 };
 export type ScopeDefinitions = ScopeDefinitionMeta[];
 export type ScopeDefinitionsMeta = Record<string, ScopeDefinitionMeta>;
-/** A single scope, flattened out of the declared tree. */
 export type FlatScope = {
     /** Colon-delimited id, e.g. `admin:invoices:create`. */
     id: string;

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

@@ -1,24 +1,5 @@
 import type { FlatScope, ScopeDefinitions, ScopeDefinitionsMeta } from './scope.types.js';
-/**
- * Flattens declared scope trees into the full list of grantable scope ids,
- * depth-first. Every node is emitted, including intermediate ones.
- *
- * Ids are unique. A root may legitimately be declared more than once — an addon
- * and its host app both contributing the same `admin` tree, say — and
- * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
- * declarations are identical, so the second one is redundant rather than
- * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
- * object literal keyed by id (duplicates are a TypeScript error), and a
- * ScopeService syncs one row per scope instead of re-writing the same one.
- *
- * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
- * the declared set into its store.
- */
+/** Every node is emitted, intermediate ones included, depth-first. Ids are unique. */
 export declare const flattenScopeDefinitions: (definitions: ScopeDefinitions) => FlatScope[];
-/**
- * Validates declared scopes and keys them by name.
- *
- * Definitions sharing a name must be identical; a conflicting redeclaration is
- * a hard error naming both source files.
- */
+/** Definitions sharing a name must be identical; a conflicting one is a hard error. */
 export declare function validateAndBuildScopeDefinitionsMeta(definitions: ScopeDefinitions): ScopeDefinitionsMeta;

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

@@ -26,21 +26,8 @@ const flattenNodes = (nodes, prefix, out) => {
         flattenNodes(node.scopes, id, out);
     }
 };
-/**
- * Flattens declared scope trees into the full list of grantable scope ids,
- * depth-first. Every node is emitted, including intermediate ones.
- *
- * Ids are unique. A root may legitimately be declared more than once — an addon
- * and its host app both contributing the same `admin` tree, say — and
- * {@link validateAndBuildScopeDefinitionsMeta} already guarantees those
- * declarations are identical, so the second one is redundant rather than
- * conflicting. Collapsing it here keeps every consumer honest: codegen emits an
- * object literal keyed by id (duplicates are a TypeScript error), and a
- * ScopeService syncs one row per scope instead of re-writing the same one.
- *
- * Used by codegen to build the `ScopeId` union, and by a ScopeService to sync
- * the declared set into its store.
- */
+/** Every node is emitted, intermediate ones included, depth-first. Ids are unique. */
+// knowledge: decisions/internals/scope-roots-may-be-co-declared-by-an-addon-and-its-host-app.md
 export const flattenScopeDefinitions = (definitions) => {
     const out = [];
     for (const def of definitions) {
@@ -56,12 +43,7 @@ export const flattenScopeDefinitions = (definitions) => {
         return true;
     });
 };
-/**
- * Validates declared scopes and keys them by name.
- *
- * Definitions sharing a name must be identical; a conflicting redeclaration is
- * a hard error naming both source files.
- */
+/** Definitions sharing a name must be identical; a conflicting one is a hard error. */
 export function validateAndBuildScopeDefinitionsMeta(definitions) {
     const meta = {};
     for (const def of definitions) {

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

@@ -1,3 +1,3 @@
-export { wireSecret } from './secret.types.js';
+export { defineSecret } from './secret.types.js';
 export type { CoreSecret, OAuth2CredentialConfig, SecretDefinitionMeta, SecretDefinitionsMeta, SecretDefinitions, } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';

package/dist/wirings/secret/index.js

@@ -1,2 +1,2 @@
-export { wireSecret } from './secret.types.js';
+export { defineSecret } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';

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

@@ -5,25 +5,29 @@ export type CoreSecret<T = unknown> = {
     secretId: string;
     schema: T;
     /**
-     * Link to documentation explaining how to obtain this value — a provider's
-     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-     * deploy UIs so a user facing a missing value has somewhere to go instead of
-     * an opaque identifier.
+     * Where a user goes to obtain this value — a provider's API-key page, a setup
+     * guide, an internal runbook. Consoles and deploy UIs surface it beside a
+     * missing value. The same field on every credential/variable definition means
+     * the same thing.
      */
     docsUrl?: string;
+    /** Rotation cadence as a duration string, e.g. `'1d'`, `'30day'`, `'1w'`. */
+    rotationPeriod?: string;
     /**
-     * Optional rotation cadence for this secret, e.g. '1d', '30day', '1w'.
-     * Stored in the generated secrets metadata so consumers can tell when a
-     * secret was last updated and whether it is due for rotation.
+     * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
+     * `'*.notion.com'`. Omitted means unrestricted unless
+     * `config.secrets.requireAllowedHosts` is set.
      */
-    rotationPeriod?: string;
+    allowedHosts?: string[];
 };
 export type OAuth2CredentialConfig = {
+    /** Where access/refresh tokens are stored */
     tokenSecretId: string;
     authorizationUrl: string;
     tokenUrl: string;
     scopes: string[];
     pkce?: boolean;
+    /** Appended to the authorization URL's query string. */
     additionalParams?: Record<string, string>;
 };
 export type SecretDefinitionMeta = {
@@ -32,17 +36,17 @@ export type SecretDefinitionMeta = {
     description?: string;
     secretId: string;
     schema?: Record<string, unknown> | string;
-    /**
-     * Link to documentation explaining how to obtain this value — a provider's
-     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-     * deploy UIs so a user facing a missing value has somewhere to go instead of
-     * an opaque identifier.
-     */
     docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;
+    /**
+     * Hosts this secret may be sent to, e.g. `['api.notion.com']` or
+     * `'*.notion.com'`. Omitted means unrestricted unless
+     * `config.secrets.requireAllowedHosts` is set.
+     */
+    allowedHosts?: string[];
     sourceFile?: string;
 };
 export type SecretDefinitionsMeta = Record<string, SecretDefinitionMeta>;
 export type SecretDefinitions = SecretDefinitionMeta[];
-export declare const wireSecret: <T>(_config: CoreSecret<T>) => void;
+export declare const defineSecret: <T>(_config: CoreSecret<T>) => void;

package/dist/wirings/secret/secret.types.js

@@ -1 +1 @@
-export const wireSecret = (_config) => { };
+export const defineSecret = (_config) => { };

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

@@ -1,6 +1,4 @@
 import type { SecretDefinitions, SecretDefinitionsMeta } from './secret.types.js';
-export interface SchemaRefLike {
-    variableName: string;
-    sourceFile: string;
-}
+import type { SchemaRefLike } from '../../types/core.types.js';
+export type { SchemaRefLike };
 export declare function validateAndBuildSecretDefinitionsMeta(definitions: SecretDefinitions, schemaLookup: Map<string, SchemaRefLike>): SecretDefinitionsMeta;

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

@@ -1,38 +1,11 @@
 import type { CoreTrigger, CoreTriggerSource, TriggerInstance } from './trigger.types.js';
-/**
- * Registers a trigger with the Pikku framework.
- * Declares a trigger name and its target pikku function.
- * Runs everywhere. Inspector extracts at build time.
- */
 export declare const wireTrigger: (trigger: CoreTrigger) => void;
-/**
- * Registers a trigger source with the Pikku framework.
- * Provides the actual subscription function and input data.
- * Only imported in the trigger worker process.
- */
 export declare const wireTriggerSource: <TInput = unknown, TOutput = unknown>(source: CoreTriggerSource<TInput, TOutput>) => void;
-/**
- * Parameters for setting up a trigger
- */
 export type SetupTriggerParams<TInput = unknown, TOutput = unknown> = {
     name: string;
     input?: TInput;
     onTrigger: (data: TOutput) => void | Promise<void>;
 };
-/**
- * Sets up a registered trigger and starts listening for events.
- * Returns a TriggerInstance with a teardown function.
- *
- * @param name - The trigger name (must be registered via wireTrigger)
- * @param input - The input to pass to the trigger function
- * @param onTrigger - Callback invoked when the trigger fires
- */
 export declare function setupTrigger<TInput = unknown, TOutput = unknown>({ name, input, onTrigger, }: SetupTriggerParams<TInput, TOutput>): Promise<TriggerInstance>;
-/**
- * Gets all registered triggers
- */
 export declare const getRegisteredTriggers: () => Map<string, CoreTrigger<any>>;
-/**
- * Gets trigger metadata
- */
 export declare const getTriggerMeta: () => import("./trigger.types.js").TriggerMeta;

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

@@ -1,11 +1,6 @@
 import { pikkuState, getSingletonServices, getCreateWireServices, } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
 import { PikkuMissingMetaError } from '../../errors/errors.js';
-/**
- * Registers a trigger with the Pikku framework.
- * Declares a trigger name and its target pikku function.
- * Runs everywhere. Inspector extracts at build time.
- */
 export const wireTrigger = (trigger) => {
     const meta = pikkuState(null, 'trigger', 'meta');
     const triggerMeta = meta[trigger.name];
@@ -17,11 +12,7 @@ export const wireTrigger = (trigger) => {
     const triggers = pikkuState(null, 'trigger', 'triggers');
     triggers.set(trigger.name, trigger);
 };
-/**
- * Registers a trigger source with the Pikku framework.
- * Provides the actual subscription function and input data.
- * Only imported in the trigger worker process.
- */
+// knowledge: decisions/internals/trigger-declaration-is-split-from-trigger-source.md
 export const wireTriggerSource = (source) => {
     const sourceMeta = pikkuState(null, 'trigger', 'sourceMeta');
     const triggerSourceMeta = sourceMeta[source.name];
@@ -36,14 +27,6 @@ export const wireTriggerSource = (source) => {
     triggerSources.set(source.name, source);
     addFunction(triggerSourceMeta.pikkuFuncId, source.func, triggerSourceMeta.packageName);
 };
-/**
- * Sets up a registered trigger and starts listening for events.
- * Returns a TriggerInstance with a teardown function.
- *
- * @param name - The trigger name (must be registered via wireTrigger)
- * @param input - The input to pass to the trigger function
- * @param onTrigger - Callback invoked when the trigger fires
- */
 export async function setupTrigger({ name, input, onTrigger, }) {
     const singletonServices = getSingletonServices();
     const createWireServices = getCreateWireServices();
@@ -74,15 +57,9 @@ export async function setupTrigger({ name, input, onTrigger, }) {
     });
     return { name, teardown };
 }
-/**
- * Gets all registered triggers
- */
 export const getRegisteredTriggers = () => {
     return pikkuState(null, 'trigger', 'triggers');
 };
-/**
- * Gets trigger metadata
- */
 export const getTriggerMeta = () => {
     return pikkuState(null, 'trigger', 'meta');
 };

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

@@ -1,16 +1,9 @@
 import type { CommonWireMeta, CoreSingletonServices } from '../../types/core.types.js';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { CoreNodeConfig } from '../node/node.types.js';
-/**
- * The trigger interaction object passed to trigger functions via the wire.
- * Call trigger() to fire the trigger and start a new workflow/execution.
- */
 export interface PikkuTrigger<TOutput = unknown> {
     invoke: (data: TOutput) => void;
 }
-/**
- * Metadata for registered triggers stored in state.
- */
 export type TriggerMeta = Record<string, CommonWireMeta & {
     name: string;
 }>;
@@ -19,109 +12,35 @@ export type TriggerSourceMeta = Record<string, {
     pikkuFuncId: string;
     packageName?: string;
 }>;
-/**
- * A trigger function that sets up a subscription and returns a teardown function.
- * The trigger is fired via wire.trigger.invoke(data).
- *
- * @template TInput - Input type (configuration passed when wired)
- * @template TOutput - Output type produced when trigger fires
- * @template Services - Services available to the trigger
- */
 export type CorePikkuTriggerFunction<TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices> = (services: Services, input: TInput, wire: {
     trigger: {
         invoke: (data: TOutput) => void;
     };
 }) => Promise<() => void | Promise<void>>;
-/**
- * Configuration object for creating a trigger function with metadata
- */
 export type CorePikkuTriggerFunctionConfig<TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
-    /** Optional human-readable title for the trigger */
     title?: string;
-    /** Optional description of what the trigger does */
     description?: string;
-    /** Optional tags for categorization */
     tags?: string[];
-    /** The trigger function */
     func: CorePikkuTriggerFunction<TInput, TOutput, Services>;
-    /** Optional Zod schema for input validation */
     input?: InputSchema;
-    /** Optional Zod schema for output validation */
     output?: OutputSchema;
-    /** Optional node configuration */
     node?: CoreNodeConfig;
 };
-/**
- * Factory function for creating trigger functions
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const redisSubscribeTrigger = pikkuTriggerFunc<
- *   { channel: string },
- *   { message: string }
- * >(async ({ redis }, { channel }, { trigger }) => {
- *   const subscriber = redis.duplicate()
- *   await subscriber.subscribe(channel, (msg) => {
- *     trigger.invoke({ message: msg })
- *   })
- *   return () => subscriber.unsubscribe()
- * })
- *
- * // Configuration object syntax with metadata
- * export const redisSubscribeTrigger = pikkuTriggerFunc({
- *   title: 'Redis Subscribe Trigger',
- *   description: 'Listens to Redis pub/sub channel',
- *   input: z.object({ channel: z.string() }),
- *   output: z.object({ message: z.string() }),
- *   func: async ({ redis }, { channel }, { trigger }) => {
- *     const subscriber = redis.duplicate()
- *     await subscriber.subscribe(channel, (msg) => {
- *       trigger.invoke({ message: msg })
- *     })
- *     return () => subscriber.unsubscribe()
- *   }
- * })
- * ```
- */
 export declare const pikkuTriggerFunc: <TInput = unknown, TOutput = unknown, Services extends CoreSingletonServices = CoreSingletonServices, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(triggerOrConfig: CorePikkuTriggerFunction<TInput, TOutput, Services> | CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>) => CorePikkuTriggerFunctionConfig<TInput, TOutput, Services, InputSchema, OutputSchema>;
-/**
- * Core trigger definition for registration.
- *
- * @template TInput - Input type (configuration passed when wired)
- * @template TOutput - Output type
- */
 export interface CoreTrigger<PikkuFunctionConfig = any> {
-    /** Unique name for this trigger */
     name: string;
-    /** The target RPC function to invoke when the trigger fires */
     func: PikkuFunctionConfig;
-    /** Optional description */
     description?: string;
-    /** Optional tags for categorization */
     tags?: string[];
-    /** Whether this trigger is used by a graph workflow */
     graph?: true;
 }
-/**
- * Represents a trigger instance with teardown capability
- */
 export interface TriggerInstance {
     name: string;
     teardown: () => void | Promise<void>;
 }
-/**
- * A trigger source that provides the subscription function.
- * Only imported in the trigger worker process.
- *
- * @template TInput - Input type passed to the trigger function
- * @template TOutput - Output type produced when trigger fires
- */
 export type CoreTriggerSource<TInput = unknown, TOutput = unknown> = {
-    /** Must match a wireTrigger name */
+    /** Must match the name of a `wireTrigger` registration. */
     name: string;
-    /** The trigger function config that sets up the subscription */
     func: CorePikkuTriggerFunctionConfig<TInput, TOutput, CoreSingletonServices, StandardSchemaV1 | undefined, StandardSchemaV1 | undefined>;
 } & (unknown extends TInput ? {
     input?: TInput;

package/dist/wirings/trigger/trigger.types.js

@@ -1,37 +1,3 @@
-/**
- * Factory function for creating trigger functions
- * Supports both direct function and configuration object syntax
- *
- * @example
- * ```typescript
- * // Direct function syntax
- * export const redisSubscribeTrigger = pikkuTriggerFunc<
- *   { channel: string },
- *   { message: string }
- * >(async ({ redis }, { channel }, { trigger }) => {
- *   const subscriber = redis.duplicate()
- *   await subscriber.subscribe(channel, (msg) => {
- *     trigger.invoke({ message: msg })
- *   })
- *   return () => subscriber.unsubscribe()
- * })
- *
- * // Configuration object syntax with metadata
- * export const redisSubscribeTrigger = pikkuTriggerFunc({
- *   title: 'Redis Subscribe Trigger',
- *   description: 'Listens to Redis pub/sub channel',
- *   input: z.object({ channel: z.string() }),
- *   output: z.object({ message: z.string() }),
- *   func: async ({ redis }, { channel }, { trigger }) => {
- *     const subscriber = redis.duplicate()
- *     await subscriber.subscribe(channel, (msg) => {
- *       trigger.invoke({ message: msg })
- *     })
- *     return () => subscriber.unsubscribe()
- *   }
- * })
- * ```
- */
 export const pikkuTriggerFunc = (triggerOrConfig) => {
     if (typeof triggerOrConfig === 'function') {
         return { func: triggerOrConfig };

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

@@ -1,3 +1,3 @@
-export { wireVariable } from './variable.types.js';
+export { defineVariable } from './variable.types.js';
 export type { CoreVariable, VariableDefinitionMeta, VariableDefinitionsMeta, VariableDefinitions, } from './variable.types.js';
 export { validateAndBuildVariableDefinitionsMeta } from './validate-variable-definitions.js';

package/dist/wirings/variable/index.js

@@ -1,2 +1,2 @@
-export { wireVariable } from './variable.types.js';
+export { defineVariable } from './variable.types.js';
 export { validateAndBuildVariableDefinitionsMeta } from './validate-variable-definitions.js';

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

@@ -1,6 +1,4 @@
 import type { VariableDefinitions, VariableDefinitionsMeta } from './variable.types.js';
-export interface SchemaRefLike {
-    variableName: string;
-    sourceFile: string;
-}
+import type { SchemaRefLike } from '../../types/core.types.js';
+export type { SchemaRefLike };
 export declare function validateAndBuildVariableDefinitionsMeta(definitions: VariableDefinitions, schemaLookup: Map<string, SchemaRefLike>): VariableDefinitionsMeta;

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

@@ -4,12 +4,6 @@ export type CoreVariable<T = unknown> = {
     description?: string;
     variableId: string;
     schema: T;
-    /**
-     * Link to documentation explaining how to obtain this value — a provider's
-     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-     * deploy UIs so a user facing a missing value has somewhere to go instead of
-     * an opaque identifier.
-     */
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -18,15 +12,9 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
-    /**
-     * Link to documentation explaining how to obtain this value — a provider's
-     * API-key page, a setup guide, an internal runbook. Surfaced by consoles and
-     * deploy UIs so a user facing a missing value has somewhere to go instead of
-     * an opaque identifier.
-     */
     docsUrl?: string;
     sourceFile?: string;
 };
 export type VariableDefinitionsMeta = Record<string, VariableDefinitionMeta>;
 export type VariableDefinitions = VariableDefinitionMeta[];
-export declare const wireVariable: <T>(_config: CoreVariable<T>) => void;
+export declare const defineVariable: <T>(_config: CoreVariable<T>) => void;

package/dist/wirings/variable/variable.types.js

@@ -1 +1 @@
-export const wireVariable = (_config) => { };
+export const defineVariable = (_config) => { };

package/dist/wirings/virtual-user/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Virtual user module exports.
+ *
+ * A virtual user is an LLM playing a persona that signs into a *running* stage
+ * and works its API in character — non-deterministically, with a budget, and
+ * with oracles watching what comes back. It is not a test runner: nothing here
+ * asserts an expected outcome, because the point is the outcomes nobody thought
+ * to expect.
+ *
+ * Everything it needs is derived from what a pikku project already generates —
+ * the function meta becomes the catalogue, the scenario meta becomes the
+ * intents, the declared personas become the identities — so adopting it is
+ * configuration rather than authoring.
+ *
+ * The engine is transport-agnostic: the virtual user drives an
+ * {@link VirtualUserTarget}, which in production is an `HttpPersona`
+ * signed in as a real user against staging or production.
+ */
+export type { ApiCatalogueEntry, IntentRecord, IntentSource, IntentStatus, StepRecord, VirtualUserAction, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserFindingKind, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget, } from './virtual-user.types.js';
+export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
+export { runVirtualUser, rememberIds, type RunVirtualUserParams, type VirtualUserCallContext, } from './run-virtual-user.js';
+export { personaScopes, prepareVirtualUserRun, type VirtualUserPreparation, } from './prepare-virtual-user-run.js';
+export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart, VirtualUserRunStore, } from './virtual-user-run-store.js';
+export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
+export { catalogueClassification, catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
+export { reachableAgents, type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
+export { IntentStack, intentsForPersona, type IntentMove, type ScheduledTick, } from './virtual-user-intents.js';
+export { createRng, type VirtualUserRng } from './virtual-user-rng.js';
+export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
+export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/index.js

@@ -0,0 +1,10 @@
+export { PRODUCTION_DISPOSITION } from './virtual-user.types.js';
+export { runVirtualUser, rememberIds, } from './run-virtual-user.js';
+export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
+export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
+export { catalogueClassification, catalogueIndex, catalogueLookup, describeEntry, isReadOnly, reachableCatalogue, renderCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
+export { reachableAgents, } from './virtual-user-agents.js';
+export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
+export { createRng } from './virtual-user-rng.js';
+export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
+export { personaVirtualUserTarget, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/prepare-virtual-user-run.d.ts

@@ -0,0 +1,54 @@
+import type { FunctionsMeta } from '../../types/core.types.js';
+import type { WorkflowsMeta } from '../workflow/workflow.types.js';
+import type { SystemRoleDefinitions, SystemRoleDefinitionsMeta } from '../role/role.types.js';
+import { type SchemaMap } from './virtual-user-derive.js';
+import { type AgentReachability, type ReachableAgent } from './virtual-user-agents.js';
+import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js';
+/**
+ * The scopes a persona holds, resolved through its roles.
+ *
+ * Roles are the only thing a persona declares; scopes are what a function
+ * checks. Narrowing a virtual user's catalogue needs the second, so the
+ * expansion happens once, here, against the same `defineSystemRole` definitions
+ * the seed grants from.
+ */
+export declare const personaScopes: (persona: {
+    roles?: readonly string[];
+}, roleScopes: Record<string, readonly string[]>) => string[];
+/** Everything a run needs that is derived rather than decided. */
+export interface VirtualUserPreparation {
+    /** Every RPC the app exposes, narrowed to what this persona can reach. */
+    catalogue: ApiCatalogueEntry[];
+    intents: IntentSource[];
+    scopes: string[];
+    agents: ReachableAgent[];
+}
+/**
+ * Derive what a virtual user needs from what the project already generates.
+ *
+ * Shared because there are two callers with the same problem and different
+ * sources for it: `pikku persona run` reads the inspector state at build time,
+ * and the scaffolded `runVirtualUser` RPC reads `metaService` at runtime. They
+ * must agree — a persona whose catalogue is narrower over RPC than on the CLI
+ * finds different things from the same seed, which is exactly the property a
+ * seed exists to give.
+ *
+ * Nothing here is authored for the virtual user's benefit: the function meta is
+ * the catalogue, the scenario meta is the intents, and the role definitions are
+ * what turn a persona's declared roles into the scopes a function checks.
+ */
+export declare const prepareVirtualUserRun: (input: {
+    persona: {
+        roles?: readonly string[];
+    };
+    functionsMeta: FunctionsMeta;
+    schemas?: SchemaMap;
+    workflowsMeta?: WorkflowsMeta;
+    /**
+     * Either shape: the inspector holds an array, `metaService` hands back the
+     * same definitions keyed by name. Accepting both is what lets the CLI and the
+     * scaffolded RPC share this.
+     */
+    systemRoles?: SystemRoleDefinitions | SystemRoleDefinitionsMeta;
+    agentsMeta?: Readonly<Record<string, AgentReachability>>;
+}) => VirtualUserPreparation;