@pikku/core 0.12.71 → 0.12.74

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,27 @@
+/**
+ * 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 { runVirtualUser, rememberIds, type RunVirtualUserParams, type VirtualUserCallContext, } from './run-virtual-user.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,8 @@
+export { runVirtualUser, rememberIds, } from './run-virtual-user.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/run-virtual-user.d.ts

@@ -0,0 +1,92 @@
+import type { ResolvedPersona } from '../../services/personas-service.js';
+import type { ActorLLM } from '../actor-flow/run-conversation.js';
+import { type VirtualUserTuning } from './virtual-user-dispositions.js';
+import type { ApiCatalogueEntry, IntentSource, VirtualUserBudget, VirtualUserDisposition, VirtualUserFinding, VirtualUserRunResult, VirtualUserTally, VirtualUserTarget } from './virtual-user.types.js';
+/** What an app-specific oracle is shown about one call. */
+export interface VirtualUserCallContext {
+    rpcName: string;
+    args: unknown;
+    status: number;
+    ok: boolean;
+    body: unknown;
+    intentId?: string;
+    step: number;
+    disposition: VirtualUserDisposition;
+}
+export interface RunVirtualUserParams {
+    /** The person being run — name, job title, personality, goals. */
+    persona: ResolvedPersona;
+    /** The id they were declared under, as the intent sources refer to them. */
+    personaId: string;
+    /** How it behaves. Default `realistic`. */
+    disposition?: VirtualUserDisposition;
+    /** Per-user overrides for that disposition's dials. */
+    tuning?: VirtualUserTuning;
+    /** Every RPC the app exposes. Narrowed internally; nothing is hidden by default. */
+    catalogue: readonly ApiCatalogueEntry[];
+    /** Features and scenarios in the app's own words — never their step graphs. */
+    intents: readonly IntentSource[];
+    /** Extra goals in the user's own words, run alongside the derived intents. */
+    goals?: readonly string[];
+    /** The transport it acts through. */
+    target: VirtualUserTarget;
+    /** The user's own LLM. */
+    llm: ActorLLM;
+    model: string;
+    budget?: VirtualUserBudget;
+    /**
+     * The app's own stopping rule, given the running tally. Pikku counts steps,
+     * calls, mutations and tokens because only the engine sees them; what they
+     * cost is the app's to decide, which is why no price appears in core.
+     */
+    stop?: (tally: VirtualUserTally) => boolean | Promise<boolean>;
+    /** Fixed seed, so a run replays into the same finding. */
+    seed?: number;
+    /**
+     * Check a response against the RPC's own output schema. Supplied by the CLI
+     * from generated schemas; a mismatch means the contract and the implementation
+     * disagree, which nothing else in a normal test suite looks for.
+     */
+    validateOutput?: (rpcName: string, body: unknown) => string | null;
+    /** App-specific oracle — ownership, invariants, anything core cannot know. */
+    classify?: (context: VirtualUserCallContext) => VirtualUserFinding[] | null | undefined;
+    /** Files this user may upload. */
+    fixtures?: readonly string[];
+    /** Agents it may talk to. */
+    agents?: readonly {
+        name: string;
+        description?: string;
+    }[];
+    /** Ids and slugs remembered from an earlier run, for a `stale` user. */
+    memory?: Record<string, string>;
+    /**
+     * The scopes this persona actually holds, resolved from its roles at sign-in.
+     *
+     * Used two ways: to narrow a large catalogue to what it is entitled to reach,
+     * and as an oracle — a call whose scopes it does not hold that nonetheless
+     * succeeds is authorization drift.
+     */
+    scopes?: readonly string[];
+    /**
+     * Offer the endpoints the app marked as needing a human's approval. Off by
+     * default: those are the ones that spend money and move real traffic.
+     */
+    allowApprovalRequired?: boolean;
+    maxStepsPerIntent?: number;
+}
+/**
+ * Pull identifiers out of a response so later intents can refer to them.
+ *
+ * This is what makes a run cohesive without ever handing the user a dataflow
+ * map: it discovers that a project has an id by looking at one, the same way a
+ * person reads it off the screen.
+ */
+export declare const rememberIds: (body: unknown, into: Record<string, string>, depth?: number) => Record<string, string>;
+/**
+ * Run one virtual user against a live target until its budget runs out.
+ *
+ * The engine schedules which intent is live and the model decides what to do
+ * within it — that split is what lets a run be replayed from its seed while the
+ * work inside it stays genuinely open-ended.
+ */
+export declare const runVirtualUser: (params: RunVirtualUserParams) => Promise<VirtualUserRunResult>;