@pikku/core 0.12.72 → 0.12.77

package/src/wirings/virtual-user/index.ts

@@ -0,0 +1,88 @@
+/**
+ * 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/src/wirings/virtual-user/prepare-virtual-user-run.test.ts

@@ -0,0 +1,115 @@
+import { test, describe } from 'node:test'
+import assert from 'node:assert/strict'
+import {
+  personaScopes,
+  prepareVirtualUserRun,
+} from './prepare-virtual-user-run.js'
+
+const ROLE_DEFINITIONS = [
+  { name: 'editor', scopes: ['docs:write', 'docs:read'] },
+  { name: 'viewer', scopes: ['docs:read'] },
+]
+
+const FUNCTIONS_META = {
+  listDocs: { pikkuFuncName: 'listDocs', services: [], expose: true },
+  deleteDoc: { pikkuFuncName: 'deleteDoc', services: [], expose: true },
+} as any
+
+describe('personaScopes', () => {
+  test('expands the roles a persona declares into the scopes functions check', () => {
+    const scopes = personaScopes(
+      { roles: ['editor'] },
+      {
+        editor: ['docs:write', 'docs:read'],
+      }
+    )
+    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
+  })
+
+  test('a persona with no roles holds no scopes', () => {
+    assert.deepEqual(personaScopes({}, { editor: ['docs:write'] }), [])
+  })
+
+  // Two roles granting the same scope is ordinary, and the catalogue narrowing
+  // downstream compares scopes as a set.
+  test('de-duplicates overlapping roles', () => {
+    const scopes = personaScopes(
+      { roles: ['editor', 'viewer'] },
+      {
+        editor: ['docs:write', 'docs:read'],
+        viewer: ['docs:read'],
+      }
+    )
+    assert.deepEqual(scopes, ['docs:read', 'docs:write'])
+  })
+
+  // An undeclared role granting everything would be the worst possible default.
+  test('an unknown role grants nothing', () => {
+    assert.deepEqual(personaScopes({ roles: ['ghost'] }, {}), [])
+  })
+})
+
+describe('prepareVirtualUserRun', () => {
+  // The CLI reads the inspector state, which holds an array; the scaffolded RPC
+  // reads metaService, which hands the same definitions back keyed by name. Both
+  // callers must land on the same scopes or the same persona and seed explore a
+  // different API depending on how the run was started.
+  test('accepts role definitions as an array or keyed by name, identically', () => {
+    const asArray = prepareVirtualUserRun({
+      persona: { roles: ['editor'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: ROLE_DEFINITIONS as any,
+    })
+    const asRecord = prepareVirtualUserRun({
+      persona: { roles: ['editor'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: {
+        editor: ROLE_DEFINITIONS[0],
+        viewer: ROLE_DEFINITIONS[1],
+      } as any,
+    })
+    assert.deepEqual(asArray.scopes, asRecord.scopes)
+    assert.deepEqual(asArray.scopes, ['docs:read', 'docs:write'])
+  })
+
+  test('derives the catalogue from the function meta', () => {
+    const { catalogue } = prepareVirtualUserRun({
+      persona: {},
+      functionsMeta: FUNCTIONS_META,
+    })
+    assert.deepEqual(catalogue.map((entry) => entry.name).sort(), [
+      'deleteDoc',
+      'listDocs',
+    ])
+  })
+
+  // An agent is reached rather than declared: its scopes are checked against the
+  // session, so a persona must find the specialists its roles unlock and no
+  // others.
+  test('narrows agents to the ones the persona s scopes reach', () => {
+    const agentsMeta = {
+      helper: { scopes: [] },
+      auditor: { scopes: ['docs:audit'] },
+    } as any
+
+    const { agents } = prepareVirtualUserRun({
+      persona: { roles: ['viewer'] },
+      functionsMeta: FUNCTIONS_META,
+      systemRoles: ROLE_DEFINITIONS as any,
+      agentsMeta,
+    })
+
+    assert.deepEqual(
+      agents.map((agent) => agent.name),
+      ['helper']
+    )
+  })
+
+  test('a project with no scenarios simply has no intents', () => {
+    const { intents } = prepareVirtualUserRun({
+      persona: {},
+      functionsMeta: FUNCTIONS_META,
+    })
+    assert.deepEqual(intents, [])
+  })
+})

package/src/wirings/virtual-user/prepare-virtual-user-run.ts

@@ -0,0 +1,95 @@
+import type { FunctionsMeta } from '../../types/core.types.js'
+import type { WorkflowsMeta } from '../workflow/workflow.types.js'
+import { flattenSystemRoleDefinitions } from '../role/validate-role-definitions.js'
+import type {
+  SystemRoleDefinitions,
+  SystemRoleDefinitionsMeta,
+} from '../role/role.types.js'
+import {
+  deriveCatalogue,
+  deriveIntents,
+  type SchemaMap,
+} from './virtual-user-derive.js'
+import {
+  reachableAgents,
+  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 const personaScopes = (
+  persona: { roles?: readonly string[] },
+  roleScopes: Record<string, readonly string[]>
+): string[] => {
+  const scopes = new Set<string>()
+  for (const role of persona.roles ?? []) {
+    for (const scope of roleScopes[role] ?? []) {
+      scopes.add(scope)
+    }
+  }
+  return [...scopes].sort()
+}
+
+/** 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 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 => {
+  const catalogue = deriveCatalogue(input.functionsMeta, input.schemas ?? {})
+  const intents = deriveIntents(input.workflowsMeta ?? {}, input.functionsMeta)
+
+  const declared = input.systemRoles ?? []
+  const roleScopes: Record<string, string[]> = {}
+  for (const role of flattenSystemRoleDefinitions(
+    Array.isArray(declared) ? declared : Object.values(declared)
+  )) {
+    roleScopes[role.name] = role.scopes
+  }
+  const scopes = personaScopes(input.persona, roleScopes)
+
+  // Gated by the same scopes as the RPCs, because an agent is reached rather
+  // than declared: `CoreAIAgent.scopes` is checked against the session, so a
+  // persona finds the specialists its roles unlock and no others.
+  const agents = reachableAgents(input.agentsMeta ?? {}, scopes)
+
+  return { catalogue, intents, scopes, agents }
+}