@pikku/core 0.12.89 → 0.12.91

package/src/ecosystem-tier-removed.test.ts

@@ -0,0 +1,69 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const skipped = new Set([
+  'node_modules',
+  'dist',
+  '.pikku',
+  '.next',
+  'build',
+  '.git',
+  '.deploy',
+  'coverage',
+])
+
+const collectSourceFiles = (
+  directory: string,
+  out: string[] = []
+): string[] => {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!skipped.has(entry.name)) {
+        collectSourceFiles(join(directory, entry.name), out)
+      }
+    } else if (/\.(ts|tsx|js|mjs|mts|cts)$/.test(entry.name)) {
+      out.push(join(directory, entry.name))
+    }
+  }
+  return out
+}
+
+/**
+ * A stale compiled `.test.js` next to this file would otherwise read as an
+ * offender of its own scan, which is how a sibling removal guard in this
+ * directory reports a phantom failure on a dirty tree. Comparing paths with
+ * the extension dropped excludes this file and its build artifacts without
+ * excluding a neighbour that merely shares the prefix.
+ */
+const withoutExtension = (file: string): string =>
+  file.replace(/\.(ts|tsx|js|mjs|mts|cts)$/, '')
+
+/**
+ * The `@pikku/core/ecosystem/*` tier was deleted in favour of one door per
+ * name. Nothing resolves those specifiers any more, but a dead one is easy to
+ * miss: a type-only import is erased before it can fail at runtime, and the
+ * service packages exclude `**\/*.test.ts` from their tsconfig, so neither the
+ * test run nor `yarn tsc` reports it.
+ */
+describe('the ecosystem entry-point tier is gone', () => {
+  test('no source file imports from @pikku/core/ecosystem', () => {
+    const self = withoutExtension(fileURLToPath(import.meta.url))
+    const offenders = collectSourceFiles(repoRoot)
+      .filter(
+        (file) =>
+          withoutExtension(file) !== self &&
+          /@pikku\/core\/ecosystem/.test(readFileSync(file, 'utf-8'))
+      )
+      .map((file) => relative(repoRoot, file))
+    assert.deepEqual(
+      offenders,
+      [],
+      `@pikku/core/ecosystem imports found in:\n${offenders.join('\n')}`
+    )
+  })
+})

package/src/public-surface.json

@@ -97,21 +97,27 @@
   "./workflow/types": [],
   "./actor-flow": ["runConversation"],
   "./virtual-user": [
+    "DEFAULT_MAX_INTERVAL_MS",
+    "DEFAULT_MIN_INTERVAL_MS",
     "DISPOSITIONS",
     "IntentStack",
     "PRODUCTION_DISPOSITION",
+    "STALE_RUN_AFTER_MS",
     "catalogueClassification",
     "catalogueLookup",
     "deriveCatalogue",
     "deriveIntents",
     "dispositionProfile",
     "intentsForPersona",
+    "isDue",
     "isReadOnly",
+    "nextRunAt",
     "personaScopes",
     "personaVirtualUserTarget",
     "prepareVirtualUserRun",
     "reachableCatalogue",
     "runVirtualUser",
+    "tickVirtualUserSchedules",
     "unreachableCatalogue"
   ],
   "./channel/local": [
@@ -266,9 +272,13 @@
     "validateAndBuildSystemRoleDefinitionsMeta"
   ],
   "./persona": [
+    "ActorSignIn",
     "HttpPersona",
+    "IMPERSONATE_USER_ID_HEADER",
+    "OperatorSignIn",
     "createHttpPersonas",
     "definePersonas",
+    "establishOperatorSession",
     "isRunnablePersona",
     "personaEmail",
     "personaEmails",

package/src/services/http-personas-converse.test.ts

@@ -17,6 +17,7 @@ const startAgentTarget = async () => {
   let logins = 0
   let authRequired = false
   let approvalsSeen: unknown[] = []
+  let firstAgentRequestAuthed: boolean | null = null
   const server: Server = createServer((req, res) => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
@@ -37,6 +38,11 @@ const startAgentTarget = async () => {
       }
 
       const isAgentRoute = req.url?.startsWith('/api/rpc/agent/')
+      if (isAgentRoute && firstAgentRequestAuthed === null) {
+        firstAgentRequestAuthed = (req.headers.cookie ?? '').includes(
+          'session='
+        )
+      }
       if (
         isAgentRoute &&
         authRequired &&
@@ -85,10 +91,13 @@ const startAgentTarget = async () => {
     apiUrl: `http://127.0.0.1:${port}/api`,
     loginCount: () => logins,
     approvalsSeen: () => approvalsSeen,
+    /** Whether the very first agent call carried a session, not merely that one was minted. */
+    firstAgentRequestAuthed: () => firstAgentRequestAuthed,
     reset: (opts?: { authRequired?: boolean }) => {
       agentRuns = 0
       logins = 0
       approvalsSeen = []
+      firstAgentRequestAuthed = null
       authRequired = opts?.authRequired ?? false
     },
   }
@@ -180,8 +189,13 @@ describe('HttpPersona.converse', async () => {
     assert.deepEqual(target.approvalsSeen(), [
       [{ toolCallId: 'tc1', approved: true }],
     ])
-    // No-auth agent → converse never signs in (lazy login).
-    assert.equal(target.loginCount(), 0)
+    // Signed in even though the agent route is public: a thread minted under a
+    // fresh anonymous id per request belongs to nobody, so turn two comes back
+    // as somebody else's. A persona is a real account either way — and it is
+    // the *first* call that has to carry the session, which a login count
+    // alone would not show.
+    assert.equal(target.loginCount(), 1)
+    assert.equal(target.firstAgentRequestAuthed(), true)
   })
 
   test('signs in lazily and retries once when an agent route returns 401', async () => {

package/src/services/http-personas.ts

@@ -16,6 +16,12 @@ import {
   createCookieJar,
   type ScenarioCookieJar,
 } from '../wirings/workflow/scenario-cookie-jar.js'
+import {
+  ActorSignIn,
+  OperatorSignIn,
+  type OperatorSignInOptions,
+  type PersonaSignIn,
+} from './persona-sign-in.js'
 import { getSingletonServices } from '../pikku-state.js'
 import { AIProviderNotConfiguredError } from '../errors/errors.js'
 
@@ -30,8 +36,19 @@ export interface HttpPersonasConfig {
   /**
    * The impersonation secret. Sign-in only ever works for user rows flagged
    * `actor: true` — knowing the secret never impersonates real users.
+   *
+   * The local-development credential. A deployed stage has none, and passes
+   * {@link HttpPersonasConfig.operator} instead.
+   */
+  secret?: string
+  /**
+   * Fabric operator credentials, for signing personas into a DEPLOYED stage.
+   *
+   * Mutually exclusive with {@link HttpPersonasConfig.secret}: the operator
+   * path acts as the persona through an admin session rather than logging in as
+   * them, so no test credential has to exist on the target at all.
    */
-  secret: string
+  operator?: OperatorSignInOptions
   /** Persona id → the declaration with its address filled in. */
   personas: Record<string, ResolvedPersona>
   /** Sign-in path under apiUrl. Default: the actor plugin's `/auth/sign-in/actor`. */
@@ -49,12 +66,13 @@ export interface HttpPersonasConfig {
 }
 
 /**
- * Default HTTP-backed persona. Signs in lazily on first invoke via the Better
- * Auth actor plugin (`POST /auth/sign-in/actor` with `{ email, secret }` —
- * the plugin upserts the actor-flagged user row and mints a session whose
- * `actor` flag flows into audits/analytics). Holds the session cookies for
- * its lifetime; a 401 mid-run re-logs-in once (long health-check runs can
- * outlive a session).
+ * Default HTTP-backed persona. Signs in lazily on first invoke, holds the
+ * session cookies for its lifetime, and re-logs-in once on a 401 mid-run (long
+ * health-check runs can outlive a session).
+ *
+ * How it signs in depends on the target, and the two ways are not
+ * interchangeable — see {@link ActorSignIn} for local development and
+ * {@link OperatorSignIn} for a deployed stage.
  */
 export class HttpPersona implements ScenarioPersona {
   private jar: ScenarioCookieJar
@@ -65,6 +83,7 @@ export class HttpPersona implements ScenarioPersona {
    * established.
    */
   private signedIn = false
+  private signIn: PersonaSignIn
 
   constructor(
     readonly name: string,
@@ -72,6 +91,19 @@ export class HttpPersona implements ScenarioPersona {
     private config: HttpPersonasConfig
   ) {
     this.jar = createCookieJar(config.apiUrl)
+    if (config.operator) {
+      this.signIn = new OperatorSignIn(config.apiUrl, config.operator)
+    } else if (config.secret) {
+      this.signIn = new ActorSignIn(
+        config.apiUrl,
+        config.secret,
+        config.signInPath ?? '/auth/sign-in/actor'
+      )
+    } else {
+      throw new Error(
+        `[scenario] persona '${name}' has no way to sign in — set 'secret' for a dev target or 'operator' for a deployed one`
+      )
+    }
   }
 
   get email(): string {
@@ -111,6 +143,14 @@ export class HttpPersona implements ScenarioPersona {
     if (!agentRunner) {
       throw new AIProviderNotConfiguredError()
     }
+    // Signed in here rather than left to postAgent's 401 retry, which a public
+    // agent route never triggers. An unowned thread is minted under a fresh
+    // anonymous id per request, so turn one succeeds and turn two is refused as
+    // somebody else's — and a persona is a real account with real credentials,
+    // so there is no case where conversing as nobody is the intent.
+    if (!this.signedIn) {
+      await this.login()
+    }
     const model = options.model ?? this.config.model
     if (!model) {
       throw new Error(
@@ -153,7 +193,9 @@ export class HttpPersona implements ScenarioPersona {
       await this.login()
     }
     const sessionPath = this.config.sessionPath ?? '/auth/get-session'
-    const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`)
+    const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`, {
+      headers: this.signIn.headers(),
+    })
     if (!res.ok) {
       return null
     }
@@ -218,7 +260,10 @@ export class HttpPersona implements ScenarioPersona {
     const send = () =>
       this.jar.fetch(url, {
         method: 'POST',
-        headers: { 'content-type': 'application/json' },
+        headers: {
+          'content-type': 'application/json',
+          ...this.signIn.headers(),
+        },
         body: JSON.stringify(body),
       })
 
@@ -247,7 +292,11 @@ export class HttpPersona implements ScenarioPersona {
     const rpcPath = this.config.rpcPath ?? '/rpc'
     return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
       method: 'POST',
-      headers: { 'content-type': 'application/json', ...extraHeaders },
+      headers: {
+        'content-type': 'application/json',
+        ...this.signIn.headers(),
+        ...extraHeaders,
+      },
       body: JSON.stringify({ data }),
     })
   }
@@ -259,29 +308,7 @@ export class HttpPersona implements ScenarioPersona {
   }
 
   private async login(): Promise<void> {
-    const signInPath = this.config.signInPath ?? '/auth/sign-in/actor'
-    const res = await this.jar.fetch(`${this.config.apiUrl}${signInPath}`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        email: this.persona.email,
-        name: this.persona.name,
-        secret: this.config.secret,
-      }),
-    })
-    if (!res.ok) {
-      const body = (await res.text().catch(() => '')).slice(0, 300)
-      throw new Error(
-        `[scenario] persona sign-in failed for '${this.name}' (${res.status}): ${body}`
-      )
-    }
-    // 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 '${this.name}' returned no session cookie`
-      )
-    }
+    await this.signIn.login(this.jar, this.persona)
     this.signedIn = true
   }
 }

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

@@ -0,0 +1,209 @@
+import { describe, test, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createServer, type Server } from 'node:http'
+
+import { createHttpPersonas } from './http-personas.js'
+import { establishOperatorSession } from './persona-sign-in.js'
+
+const OPERATOR_TOKEN = 'operator.jwt.token'
+
+/**
+ * Minimal deployed stage: the fabric plugin's sign-in, the admin plugin's
+ * user endpoints, and an RPC route that reports back who it was addressed as.
+ */
+const startStage = async (seeded: Array<{ id: string; email: string }>) => {
+  const users = [...seeded]
+  let created = 0
+  const server: Server = createServer((req, res) => {
+    const chunks: Buffer[] = []
+    req.on('data', (c) => chunks.push(c))
+    req.on('end', () => {
+      const body = chunks.length
+        ? JSON.parse(Buffer.concat(chunks).toString())
+        : {}
+      const url = new URL(req.url ?? '/', 'http://stage.invalid')
+
+      if (url.pathname === '/api/auth/sign-in/fabric') {
+        if (body.token !== OPERATOR_TOKEN) {
+          res.writeHead(401).end(JSON.stringify({ message: 'bad token' }))
+          return
+        }
+        res.setHeader('set-cookie', ['session=operator; Path=/; HttpOnly'])
+        res.writeHead(200).end(JSON.stringify({ token: 'operator' }))
+        return
+      }
+
+      // The admin plugin refuses an unauthenticated caller, and saying so here
+      // is the point: a handshake that dropped the operator session between
+      // sign-in and lookup would otherwise pass this stage happily.
+      if (url.pathname.startsWith('/api/auth/admin/')) {
+        if (!/(^|;\s*)session=operator(;|$)/.test(req.headers.cookie ?? '')) {
+          res.writeHead(401).end(JSON.stringify({ message: 'no session' }))
+          return
+        }
+      }
+
+      if (url.pathname === '/api/auth/admin/list-users') {
+        const wanted = url.searchParams.get('filterValue')
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(
+            JSON.stringify({ users: users.filter((u) => u.email === wanted) })
+          )
+        return
+      }
+
+      if (url.pathname === '/api/auth/admin/create-user') {
+        created++
+        const user = { id: `made-${created}`, email: body.email }
+        users.push(user)
+        res
+          .writeHead(200, { 'content-type': 'application/json' })
+          .end(JSON.stringify({ user, sawPassword: Boolean(body.password) }))
+        return
+      }
+
+      if (url.pathname.startsWith('/api/rpc/')) {
+        res.writeHead(200, { 'content-type': 'application/json' }).end(
+          JSON.stringify({
+            actingAs: req.headers['x-pikku-impersonate-user-id'] ?? null,
+            cookie: req.headers.cookie ?? '',
+          })
+        )
+        return
+      }
+
+      res.writeHead(404).end()
+    })
+  })
+  await new Promise<void>((resolve) => server.listen(0, resolve))
+  const port = (server.address() as { port: number }).port
+  return {
+    apiUrl: `http://127.0.0.1:${port}/api`,
+    server,
+    get createdCount() {
+      return created
+    },
+  }
+}
+
+const persona = (email: string) => ({
+  id: 'customer',
+  name: 'Customer',
+  email,
+  roles: ['client'],
+  goals: [],
+  tags: [],
+  runnable: true,
+})
+
+describe('operator persona sign-in', () => {
+  const servers: Server[] = []
+  after(() => servers.forEach((s) => s.close()))
+
+  test('acts as an existing account rather than signing in as it', async () => {
+    const stage = await startStage([
+      { id: 'user-7', email: 'customer@personas.invalid' },
+    ])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: { token: OPERATOR_TOKEN },
+      personas: { customer: persona('customer@personas.invalid') },
+    })
+
+    const result = (await personas.customer!.invoke('whoami', {})) as {
+      actingAs: string | null
+      cookie: string
+    }
+    assert.equal(result.actingAs, 'user-7')
+    assert.match(result.cookie, /session=operator/)
+    assert.equal(stage.createdCount, 0)
+  })
+
+  test('refuses a persona the stage has no account for', async () => {
+    const stage = await startStage([])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: { token: OPERATOR_TOKEN },
+      personas: { customer: persona('ghost@personas.invalid') },
+    })
+
+    await assert.rejects(
+      () => personas.customer!.invoke('whoami', {}),
+      /no account on the target for persona 'customer'/
+    )
+    assert.equal(stage.createdCount, 0)
+  })
+
+  test('provisions the account only when told to', async () => {
+    const stage = await startStage([])
+    servers.push(stage.server)
+
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: { token: OPERATOR_TOKEN, createMissing: true },
+      personas: { customer: persona('fresh@personas.invalid') },
+    })
+
+    const result = (await personas.customer!.invoke('whoami', {})) as {
+      actingAs: string | null
+    }
+    assert.equal(result.actingAs, 'made-1')
+    assert.equal(stage.createdCount, 1)
+  })
+
+  test('mints the operator session from a token factory', async () => {
+    const stage = await startStage([
+      { id: 'user-9', email: 'lazy@personas.invalid' },
+    ])
+    servers.push(stage.server)
+
+    let minted = 0
+    const personas = createHttpPersonas({
+      apiUrl: stage.apiUrl,
+      operator: {
+        token: () => {
+          minted++
+          return OPERATOR_TOKEN
+        },
+      },
+      personas: { customer: persona('lazy@personas.invalid') },
+    })
+
+    await personas.customer!.invoke('whoami', {})
+    assert.equal(minted, 1)
+  })
+
+  test('carries the operator session into the admin lookup', async () => {
+    const stage = await startStage([{ id: 'user-9', email: 'susan@acme.test' }])
+    servers.push(stage.server)
+
+    // Plain fetch keeps no cookies, which is the browser provider's situation:
+    // it plants them on a Playwright context only once this has returned.
+    const { userId } = await establishOperatorSession(
+      fetch,
+      stage.apiUrl,
+      persona('susan@acme.test'),
+      { token: OPERATOR_TOKEN }
+    )
+    assert.equal(userId, 'user-9')
+  })
+
+  test('a persona with neither credential is refused at construction', async () => {
+    const stage = await startStage([])
+    servers.push(stage.server)
+
+    assert.throws(
+      () =>
+        createHttpPersonas({
+          apiUrl: stage.apiUrl,
+          personas: { customer: persona('nobody@personas.invalid') },
+        }),
+      /has no way to sign in/
+    )
+  })
+})