@pikku/core 0.12.89 → 0.12.91

package/src/services/persona-sign-in.ts

@@ -0,0 +1,284 @@
+import type { ResolvedPersona } from './personas-service.js'
+import type { ScenarioCookieJar } from '../wirings/workflow/scenario-cookie-jar.js'
+
+/**
+ * The header `resolveImpersonatedSession` reads the target user id from.
+ *
+ * A wire value rather than a shared import: the reader lives in
+ * `@pikku/services-better-auth`, which depends on core, so core cannot import
+ * it back. The two agree by protocol, the way an HTTP header always does.
+ */
+export const IMPERSONATE_USER_ID_HEADER = 'x-pikku-impersonate-user-id'
+
+/**
+ * How a persona obtains a session on the target, and what every later request
+ * needs to carry to keep acting as them.
+ *
+ * Two answers exist because the two environments have opposite trust models,
+ * not because one is a fallback for the other. See {@link ActorSignIn} and
+ * {@link OperatorSignIn}.
+ */
+export interface PersonaSignIn {
+  /**
+   * Establish a session in `jar`. Throws on failure with a message naming the
+   * persona, since a run that continues unauthenticated fails later and
+   * somewhere less informative.
+   */
+  login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void>
+  /** Headers every request after `login` must carry. */
+  headers(): Record<string, string>
+}
+
+const failed = async (
+  what: string,
+  personaId: string,
+  res: Response
+): Promise<Error> => {
+  const body = (await res.text().catch(() => '')).slice(0, 300)
+  return new Error(
+    `[scenario] ${what} failed for '${personaId}' (${res.status}): ${body}`
+  )
+}
+
+/**
+ * Sign a persona in through the Better Auth actor plugin — the local-development
+ * path.
+ *
+ * `POST /auth/sign-in/actor` upserts an `actor: true` row and mints a session
+ * for it. Passwordless by design and refused for any row not carrying that flag,
+ * so the secret can never reach a real user's account; the plugin still declines
+ * to serve the endpoint at all outside `pikku dev`.
+ */
+export class ActorSignIn implements PersonaSignIn {
+  constructor(
+    private readonly apiUrl: string,
+    private readonly secret: string,
+    private readonly signInPath: string
+  ) {}
+
+  async login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void> {
+    const res = await jar.fetch(`${this.apiUrl}${this.signInPath}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        email: persona.email,
+        name: persona.name,
+        secret: this.secret,
+      }),
+    })
+    if (!res.ok) {
+      throw await failed('persona sign-in', persona.id, res)
+    }
+    // What proves a session was established is this response setting a cookie,
+    // not the jar being non-empty — the target may have set one earlier.
+    if (res.headers.getSetCookie().length === 0) {
+      throw new Error(
+        `[scenario] persona sign-in for '${persona.id}' returned no session cookie`
+      )
+    }
+  }
+
+  headers(): Record<string, string> {
+    return {}
+  }
+}
+
+export interface OperatorSignInOptions {
+  /**
+   * The short-lived RS256 operator token, or a function that mints one. Prefer
+   * the function: tokens expire, and a long run re-logs-in after a 401.
+   */
+  token: string | (() => string | Promise<string>)
+  /**
+   * Create the persona's user row when the target has no account for that
+   * address.
+   *
+   * Off by default, which is the whole point of the deployed path: a persona is
+   * meant to be a real account somebody provisioned, and a test run that
+   * silently writes users into a live database is a side effect nobody asked
+   * for. Turn it on for throwaway stages.
+   */
+  createMissing?: boolean
+  /** Admin endpoint prefix under apiUrl. Default `/auth/admin`. */
+  adminPath?: string
+  /** Fabric operator sign-in path under apiUrl. Default `/auth/sign-in/fabric`. */
+  signInPath?: string
+}
+
+interface AdminUser {
+  id?: unknown
+  email?: unknown
+}
+
+/** What an operator handshake yields: the session, and who to act as. */
+export interface OperatorSessionResult {
+  /** `Set-Cookie` values the operator sign-in returned. */
+  setCookies: string[]
+  /** The target's own id for the persona, for the impersonation header. */
+  userId: string
+}
+
+/**
+ * Establish a Fabric operator session against `apiUrl` and resolve the target's
+ * own id for `persona`, which is what the impersonation header names.
+ *
+ * Takes the fetch to use rather than making one, because the two callers need
+ * the cookies to land in different places: an HTTP persona keeps them in its
+ * jar, a browser run plants them on a Playwright context. Both need the same
+ * handshake, and it is the kind of sequence that quietly diverges once it is
+ * written twice.
+ */
+export const establishOperatorSession = async (
+  fetchImpl: typeof fetch,
+  apiUrl: string,
+  persona: ResolvedPersona,
+  options: OperatorSignInOptions,
+  extraHeaders: Record<string, string> = {}
+): Promise<OperatorSessionResult> => {
+  const signInPath = options.signInPath ?? '/auth/sign-in/fabric'
+  const token =
+    typeof options.token === 'function' ? await options.token() : options.token
+
+  const res = await fetchImpl(`${apiUrl}${signInPath}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...extraHeaders },
+    body: JSON.stringify({ token }),
+  })
+  if (!res.ok) {
+    throw await failed('operator sign-in', persona.id, res)
+  }
+  const setCookies = res.headers.getSetCookie?.() ?? []
+  if (setCookies.length === 0) {
+    throw new Error(
+      `[scenario] operator sign-in for '${persona.id}' returned no session cookie`
+    )
+  }
+
+  // The lookup runs on the session this handshake just established, and a
+  // plain `fetch` keeps no cookies — the browser path in particular hands the
+  // jar's contents to Playwright only after this returns. Forwarding them
+  // explicitly is what keeps the admin calls authenticated for every caller.
+  const session = setCookies
+    .map((raw) => raw.split(';')[0])
+    .filter((pair): pair is string => Boolean(pair))
+    .join('; ')
+
+  const userId = await resolveUserId(fetchImpl, apiUrl, persona, options, {
+    ...extraHeaders,
+    cookie: session,
+  })
+  return { setCookies, userId }
+}
+
+/**
+ * The target's own id for this persona's address, since impersonation names a
+ * user id and a persona only knows an email.
+ *
+ * Looked up before creating, so a persona that already exists is never
+ * duplicated and the run reads as "act as this person" rather than "make one".
+ */
+const resolveUserId = async (
+  fetchImpl: typeof fetch,
+  apiUrl: string,
+  persona: ResolvedPersona,
+  options: OperatorSignInOptions,
+  extraHeaders: Record<string, string>
+): Promise<string> => {
+  const adminPath = options.adminPath ?? '/auth/admin'
+  const query = new URLSearchParams({
+    filterField: 'email',
+    filterValue: persona.email,
+    filterOperator: 'eq',
+    limit: '1',
+  })
+  const found = await fetchImpl(`${apiUrl}${adminPath}/list-users?${query}`, {
+    headers: { accept: 'application/json', ...extraHeaders },
+  })
+  if (!found.ok) {
+    throw await failed('persona lookup', persona.id, found)
+  }
+  const listed = (await found.json().catch(() => null)) as {
+    users?: AdminUser[]
+  } | null
+  const existing = listed?.users?.find((u) => u.email === persona.email)
+  if (existing?.id) {
+    return String(existing.id)
+  }
+
+  if (!options.createMissing) {
+    throw new Error(
+      `[scenario] no account on the target for persona '${persona.id}' (${persona.email}) — ` +
+        'provision it, or set createMissing on the operator credentials'
+    )
+  }
+
+  const created = await fetchImpl(`${apiUrl}${adminPath}/create-user`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...extraHeaders },
+    body: JSON.stringify({
+      email: persona.email,
+      name: persona.name,
+      // Never used and never returned: the run impersonates rather than signs
+      // in, so the account is reachable only by someone already holding an
+      // operator token. A derivable password would undo exactly that.
+      password: globalThis.crypto.randomUUID(),
+      ...(persona.roles[0] ? { role: persona.roles[0] } : {}),
+    }),
+  })
+  if (!created.ok) {
+    throw await failed('persona creation', persona.id, created)
+  }
+  const body = (await created.json().catch(() => null)) as {
+    user?: AdminUser
+  } | null
+  const id = body?.user?.id
+  if (!id) {
+    throw new Error(
+      `[scenario] creating persona '${persona.id}' returned no user id`
+    )
+  }
+  return String(id)
+}
+
+/**
+ * Sign a persona in on a DEPLOYED stage, by having a Fabric operator act as
+ * them — the path that needs no test credential to exist anywhere.
+ *
+ * `POST /auth/sign-in/fabric` verifies an RS256 token against the stage's
+ * `FABRIC_AUTH_PUBLIC_KEY` and mints a session for a synthetic operator row
+ * granted the umbrella `admin` scope. Impersonation is then a header on each
+ * request rather than a second session, and its gate is that scope — not
+ * `user.role`, which is why this works without touching the app's roles.
+ *
+ * Asymmetric throughout: the stage can verify an operator token and never mint
+ * one, so nothing in a deployed environment is worth stealing. That is the
+ * property the actor secret cannot have, and the reason these are two classes
+ * instead of one with a flag.
+ */
+export class OperatorSignIn implements PersonaSignIn {
+  private userId: string | null = null
+
+  constructor(
+    private readonly apiUrl: string,
+    private readonly options: OperatorSignInOptions
+  ) {}
+
+  async login(jar: ScenarioCookieJar, persona: ResolvedPersona): Promise<void> {
+    const { userId } = await establishOperatorSession(
+      jar.fetch,
+      this.apiUrl,
+      persona,
+      this.options
+    )
+    this.userId = userId
+  }
+
+  headers(): Record<string, string> {
+    if (!this.userId) {
+      throw new Error(
+        '[scenario] operator session has no persona to act as — login() first'
+      )
+    }
+    return { [IMPERSONATE_USER_ID_HEADER]: this.userId }
+  }
+}

package/src/types/core.types.ts

@@ -41,6 +41,7 @@ import type { AgentRunService } from '../wirings/agent/agent.types.js'
 import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
 import type { PermissionMetadata } from '../function/function-meta.types.js'
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js'
+import type { VirtualUserScheduleStore } from '../wirings/virtual-user/virtual-user-schedule-store.js'
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
@@ -173,6 +174,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
    * {@link VirtualUserRunStore}.
    */
   virtualUserRunStore?: VirtualUserRunStore
+  /**
+   * Each persona's cadence, for apps that want their virtual users to keep
+   * going without being asked. Separate from the run store on purpose: wiring
+   * nothing is how an app says it only wants the runs it starts itself.
+   */
+  virtualUserScheduleStore?: VirtualUserScheduleStore
   /** V8 precise-coverage collector (`pikku dev --coverage` only) */
   coverageService?: CoverageService
   audit?: AuditService

package/src/wirings/persona/index.ts

@@ -45,6 +45,15 @@ export {
   createHttpPersonas,
   type HttpPersonasConfig,
 } from '../../services/http-personas.js'
+export {
+  ActorSignIn,
+  OperatorSignIn,
+  establishOperatorSession,
+  IMPERSONATE_USER_ID_HEADER,
+  type PersonaSignIn,
+  type OperatorSignInOptions,
+  type OperatorSessionResult,
+} from '../../services/persona-sign-in.js'
 export {
   postScenarioJson,
   readScenarioHttpResponse,

package/src/wirings/rpc/rpc-runner.test.ts

@@ -596,6 +596,106 @@ describe('ContextAwareRPCService.rpcWithWire', () => {
       ['missingRpc', { value: 2 }, { userId: 'user-2' }, 'trace-3'],
     ])
   })
+
+  test('a missing namespaced rpc still reaches deploymentService through rpcWithWire', async () => {
+    const remoteCalls: unknown[][] = []
+    pikkuState(null, 'addons', 'packages').set('stripe', {
+      package: '@addon/stripe',
+    } as never)
+
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      { traceId: 'trace-addon-wire' } as never,
+      {}
+    )
+
+    const result = await service.rpcWithWire(
+      'stripe:missingFunc',
+      { value: 3 },
+      { custom: 'wire' } as never
+    )
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(remoteCalls, [
+      ['stripe:missingFunc', { value: 3 }, undefined, 'trace-addon-wire'],
+    ])
+  })
+
+  test('an unknown namespace still falls through to the local/remote lookup', async () => {
+    const remoteCalls: unknown[][] = []
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      { traceId: 'trace-ns-wire' } as never,
+      {}
+    )
+
+    const result = await service.rpcWithWire(
+      'unknownNs:someFunc',
+      { value: 1 },
+      { custom: 'wire' } as never
+    )
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(remoteCalls, [
+      ['unknownNs:someFunc', { value: 1 }, undefined, 'trace-ns-wire'],
+    ])
+  })
+
+  test('the deployment fallback runs under the wire the caller passed, not the ambient one', async () => {
+    const remoteCalls: unknown[][] = []
+    const service = new ContextAwareRPCService(
+      createServices({
+        deploymentService: {
+          invoke: async (...args: unknown[]) => {
+            remoteCalls.push(args)
+            return { remote: true }
+          },
+        },
+      }),
+      {
+        traceId: 'ambient-trace',
+        session: { userId: 'ambient-user' },
+      } as never,
+      {}
+    )
+
+    const result = await service.rpcWithWire(
+      'unknownNs:someFunc',
+      { value: 1 },
+      {
+        traceId: 'caller-trace',
+        session: { userId: 'caller-user' },
+      } as never
+    )
+
+    assert.deepEqual(result, { remote: true })
+    assert.deepEqual(
+      remoteCalls,
+      [
+        [
+          'unknownNs:someFunc',
+          { value: 1 },
+          { userId: 'caller-user' },
+          'caller-trace',
+        ],
+      ],
+      'the remote hop ran under the ambient wire, so an explicit wire is honoured locally but dropped across the deployment boundary'
+    )
+  })
 })
 
 describe('ContextAwareRPCService.startWorkflow', () => {

package/src/wirings/rpc/rpc-runner.ts

@@ -393,10 +393,13 @@ export class ContextAwareRPCService {
 
     if (rpcName.includes(':')) {
       const addonCall = this.resolveAddonFunction(rpcName)
-      if (addonCall === NOT_RESOLVED) {
-        throw new RPCNotFoundError(rpcName)
+      if (addonCall !== NOT_RESOLVED) {
+        return await this.executeAddonFunction<In, Out>(
+          addonCall,
+          data,
+          mergedWire
+        )
       }
-      return this.executeAddonFunction<In, Out>(addonCall, data, mergedWire)
     }
 
     let resolved: { pikkuFuncId: string; packageName: string | null }
@@ -404,12 +407,12 @@ export class ContextAwareRPCService {
       resolved = resolvePikkuFunction(rpcName, this.packageName)
     } catch (e) {
       if (e instanceof RPCNotFoundError && this.services.deploymentService) {
-        const session = await resolveWireSession(this.wire)
+        const session = await resolveWireSession(mergedWire)
         return this.services.deploymentService.invoke(
           rpcName,
           data,
           session,
-          this.wire.traceId
+          mergedWire.traceId
         ) as Promise<Out>
       }
       throw e

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

@@ -18,7 +18,10 @@
  */
 export type {
   ApiCatalogueEntry,
+  IntentRecord,
   IntentSource,
+  StepRecord,
+  VirtualUserBudget,
   VirtualUserDisposition,
   VirtualUserFinding,
   VirtualUserRunResult,
@@ -40,6 +43,21 @@ export type {
   VirtualUserRunStart,
   VirtualUserRunStore,
 } from './virtual-user-run-store.js'
+export type {
+  VirtualUserScheduleInput,
+  VirtualUserScheduleRecord,
+  VirtualUserScheduleStore,
+} from './virtual-user-schedule-store.js'
+export {
+  DEFAULT_MAX_INTERVAL_MS,
+  DEFAULT_MIN_INTERVAL_MS,
+  isDue,
+  nextRunAt,
+  STALE_RUN_AFTER_MS,
+  tickVirtualUserSchedules,
+  type VirtualUserTickParams,
+  type VirtualUserTickResult,
+} from './virtual-user-schedule.js'
 export {
   DISPOSITIONS,
   dispositionProfile,

package/src/wirings/virtual-user/virtual-user-agents.test.ts

@@ -4,16 +4,13 @@ import { reachableAgents } from './virtual-user-agents.js'
 
 const AGENTS = {
   'router-agent': {
-    name: 'router-agent',
     description: 'Routes requests to the right domain agent',
   },
   'social-poster': {
-    name: 'social-poster',
     description: 'Drafts and schedules posts',
     scopes: ['content:write'],
   },
   'refund-agent': {
-    name: 'refund-agent',
     scopes: ['billing:write'],
   },
 }
@@ -58,7 +55,14 @@ describe('reachableAgents', () => {
     assert.deepEqual(refund, { name: 'refund-agent' })
   })
 
-  test('falls back to the declaration key when an agent has no name', () => {
+  test('offers the registration key, not the display name the agent declares', () => {
+    assert.deepEqual(
+      reachableAgents({ adminAgent: { description: 'Runs the place' } }),
+      [{ name: 'adminAgent', description: 'Runs the place' }]
+    )
+  })
+
+  test('an agent carrying nothing but a key is still offered under it', () => {
     assert.deepEqual(reachableAgents({ orphan: {} }), [{ name: 'orphan' }])
   })
 

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

@@ -16,7 +16,6 @@ import { hasScopes } from '../../scopes.js'
 
 /** The part of an agent's meta this needs. */
 export interface AgentReachability {
-  name?: string
   description?: string
   scopes?: readonly string[]
   auth?: boolean
@@ -29,7 +28,13 @@ export interface ReachableAgent {
 }
 
 /**
- * The agents to offer, keyed by the name they are declared under.
+ * The agents to offer, named by the key they are registered under.
+ *
+ * That key is the export's own name, which is what `addAgent` stores and what
+ * `resolveAgent` looks up. The `name` an agent declares in its config is a
+ * display label and is frequently something else entirely — offering that one
+ * hands the persona a name the server cannot resolve, and the run dies on a
+ * 500 the moment it takes the offer.
  *
  * Like {@link reachableCatalogue}, this narrows *what is offered* and never
  * what is enforced: the server decides who may talk to what, and an agent
@@ -52,6 +57,6 @@ export const reachableAgents = (
       return hasScopes(agent.scopes, scopes)
     })
     .map(([id, agent]) => ({
-      name: agent.name ?? id,
+      name: id,
       ...(agent.description ? { description: agent.description } : {}),
     }))

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

@@ -1,4 +1,6 @@
 import type {
+  IntentRecord,
+  StepRecord,
   VirtualUserDisposition,
   VirtualUserFinding,
   VirtualUserTally,
@@ -39,6 +41,16 @@ export interface VirtualUserRunRecord {
    */
   memory: Record<string, string>
   findings: VirtualUserFinding[]
+  /**
+   * What the user set out to do and how far each one got, which is the spine a
+   * transcript hangs off — the steps alone are a list of calls with no account
+   * of what they were for.
+   *
+   * Small and bounded, so it rides on the run row rather than in a table of its
+   * own: a run has as many intents as the app has scenarios, and every read of
+   * the run wants them.
+   */
+  intents: IntentRecord[]
   tally: VirtualUserTally | null
   /** Which budget or stopping rule ended the run. */
   stoppedBy: string | null
@@ -69,6 +81,16 @@ export interface VirtualUserRunOutcome {
   tally: VirtualUserTally
   memory: Record<string, string>
   stoppedBy: string | null
+  intents: readonly IntentRecord[]
+  /**
+   * Every turn the run took. Kept because a finding is an assertion until you
+   * can see what the user did before it, and because a run that found nothing
+   * is only readable as work through its steps.
+   *
+   * Stored apart from the run — see {@link VirtualUserRunStore.steps} — so
+   * listing runs does not drag a budget's worth of turns along with it.
+   */
+  steps: readonly StepRecord[]
 }
 
 /**
@@ -95,4 +117,15 @@ export interface VirtualUserRunStore {
     limit?: number
     offset?: number
   }): Promise<VirtualUserRunRecord[]>
+  /**
+   * One run's turns, in the order they happened.
+   *
+   * Its own call rather than a field on the record: a run at a 500-step budget
+   * carries more transcript than every other column put together, and `list`
+   * would pay for it on every row.
+   */
+  steps(
+    runId: string,
+    options?: { limit?: number; offset?: number }
+  ): Promise<StepRecord[]>
 }