@pikku/core 0.12.141 → 0.12.143

package/dist/services/persona-sign-in.js

@@ -1,154 +0,0 @@
-import { deriveActorSecret } from './persona-actor-secret.js';
-import { PikkuError } from '../errors/error-handler.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';
-/**
- * A sign-in the target refused. `PikkuError`, not `Error`, so the CLI prints
- * this message alone: an expired token or a persona the stage has never seen is
- * something to go and fix, and a stack trace through the fetch internals only
- * buries the status and the body that say which one it is.
- */
-const failed = async (what, personaId, res) => {
-    const body = (await res.text().catch(() => '')).slice(0, 300);
-    return new PikkuError(`[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`.
- *
- * What is presented is the persona's own credential, derived from the root and
- * bound to their address. A run driving many personas holds the root and
- * derives as it goes; a run entitled to one persona is handed that one value
- * through a resolver and can sign in as nobody else.
- */
-export class ActorSignIn {
-    apiUrl;
-    secret;
-    signInPath;
-    constructor(apiUrl, secret, signInPath) {
-        this.apiUrl = apiUrl;
-        this.secret = secret;
-        this.signInPath = signInPath;
-    }
-    async login(jar, persona) {
-        const secret = typeof this.secret === 'function'
-            ? await this.secret(persona)
-            : await deriveActorSecret(this.secret, persona.email);
-        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,
-            }),
-        });
-        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() {
-        return {};
-    }
-}
-/**
- * The auth mount a configured sign-in path sits under, or `undefined` when it
- * names nothing recognisable.
- *
- * better-auth serves sign-in, operator sign-in and `get-session` from one
- * prefix, so an app that mounts it at `/api/auth` moves all three together and
- * says so once through `signInPath`. Reading the other two from a hardcoded
- * `/auth` on such an app 404s — and for `get-session` a 404 reads as "this
- * stage does not report roles", which silently turns off the check that tells a
- * permissions finding from seed drift.
- */
-export const authMount = (signInPath) => {
-    const mount = signInPath ? signInPath.lastIndexOf('/sign-in/') : -1;
-    return !signInPath || mount === -1 ? undefined : signInPath.slice(0, mount);
-};
-/**
- * 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, apiUrl, persona, options, extraHeaders = {}) => {
-    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,
-            actAs: { email: persona.email },
-        }),
-    });
-    if (!res.ok) {
-        throw await failed('operator sign-in', persona.id, res);
-    }
-    const setCookies = res.headers.getSetCookie?.() ?? [];
-    if (setCookies.length === 0) {
-        throw new PikkuError(`[scenario] operator sign-in for '${persona.id}' returned no session cookie`);
-    }
-    const body = (await res.json().catch(() => null));
-    const userId = body?.actAs?.userId;
-    if (!userId) {
-        throw new PikkuError(`[scenario] operator sign-in for '${persona.id}' returned no user to act as — ` +
-            'the target is running a @pikku/better-auth too old to resolve one');
-    }
-    return { setCookies, userId: String(userId) };
-};
-/**
- * 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 {
-    apiUrl;
-    options;
-    userId = null;
-    constructor(apiUrl, options) {
-        this.apiUrl = apiUrl;
-        this.options = options;
-    }
-    async login(jar, persona) {
-        const { userId } = await establishOperatorSession(jar.fetch, this.apiUrl, persona, this.options);
-        this.userId = userId;
-    }
-    headers() {
-        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/dist/wirings/actor-flow/index.d.ts

@@ -1,2 +0,0 @@
-export type { ActorFlowVerdict, ConverseOptions, TargetAgentDriver, } from './actor-flow.types.js';
-export { runConversation, type RunConversationParams, type ActorLLM, } from './run-conversation.js';

package/dist/wirings/actor-flow/run-conversation.d.ts

@@ -1,36 +0,0 @@
-import type { ActorFlowApprovalPolicy, ActorFlowVerdict, TargetAgentDriver } from './actor-flow.types.js';
-import type { ResolvedPersona } from '../../services/personas-service.js';
-import type { AgentRunnerParams, AgentStepResult } from '../../services/agent-runner-service.js';
-/** The LLM call the actor uses for its own turns/decisions/evaluation. */
-export type ActorLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>;
-export interface RunConversationParams {
-    /** The person being played — name, job title, personality. */
-    persona: ResolvedPersona;
-    /** The id they were declared under (for transcript labelling). */
-    personaId: string;
-    /** What the actor is trying to get the target agent to accomplish. */
-    task: string;
-    /** Natural-language success criterion the actor evaluates at the end. */
-    evaluate: string;
-    /** How the actor answers the target agent's tool-approval requests. */
-    approvals?: ActorFlowApprovalPolicy;
-    /** Model the actor uses for its own turns/decisions. */
-    model: string;
-    /** Hard cap on conversation turns. Default 12. */
-    maxTurns?: number;
-    /** Hard cap on tool-approval rounds within a single target turn. Default 16. */
-    maxApprovalRounds?: number;
-    /** Transport that drives the target agent (HTTP in production). */
-    target: TargetAgentDriver;
-    /** The actor's own LLM. */
-    llm: ActorLLM;
-    /** Display name of the target agent (transcript labelling). */
-    agentName: string;
-}
-/**
- * Run a conversation: an LLM-driven actor holds a real multi-turn exchange
- * with a target agent (driven via the injected transport), answers the target's
- * tool-approval requests in-persona, then evaluates whether the task was met.
- * Deterministic checks are the caller's responsibility.
- */
-export declare function runConversation(params: RunConversationParams): Promise<ActorFlowVerdict>;

package/dist/wirings/persona/define-personas.d.ts

@@ -1,32 +0,0 @@
-import type { CorePersonas } from './persona.types.js';
-/**
- * No-op function for declaring personas.
- * This exists purely for TypeScript type checking and will be tree-shaken.
- * The CLI extracts metadata via AST parsing and generates a `PersonaId` union
- * and a `personas.gen.json` the console and `pikku persona run` read off disk —
- * describing, listing or running one never has to load the app.
- *
- * `definePersonas` rather than `defineVirtualUsers` because declaring is not
- * running: a persona that exists only to be acted upon (the account an admin
- * bans, the colleague a document is shared with) is seeded and never run.
- *
- * Exactly one `definePersonas(...)` is allowed per codebase, so there is one
- * place to read the cast from and one place to add to. A second call — even in
- * the same file — fails the build.
- *
- * @example
- * ```typescript
- * definePersonas({
- *   susan: {
- *     name: 'Susan',
- *     jobTitle: 'Buys for a small café',
- *     roles: ['buyer'],
- *     personality: 'Hunts cheap deals. Tries three coupon codes before giving up.',
- *     goals: ['Get the weekly order in under five minutes'],
- *     disposition: 'careless',
- *     account: {},
- *   },
- * })
- * ```
- */
-export declare const definePersonas: (_config: CorePersonas) => void;

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

@@ -1,23 +0,0 @@
-export { definePersonas } from './define-personas.js';
-export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBuildPersonasMeta, verifyPersonaRoles, } from './validate-personas.js';
-export type { RoleVerification } from './validate-personas.js';
-export { personaEnvironmentErrors, personaEnvironmentRefusal, } from './persona-environments.js';
-export type { PersonaEnvironment, PersonaEnvironmentSubject, } from './persona-environments.js';
-export { personaEmail, personaEmails } from './persona-email.js';
-export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-app-scopes.js';
-export type { MailboxAllowlist, PersonaMailbox, ReceivedEmail, } from './persona-mailbox.js';
-export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions, PersonaMeta, PersonasMeta, } from './persona.types.js';
-/**
- * Signing in as a persona and talking to a stage over HTTP.
- *
- * Deliberately reached through this entry point rather than `@pikku/core/services`.
- * `HttpPersona` pulls in the actor-flow conversation runner and, through it, the
- * agent runner — none of which a production server has any use for. Exporting it
- * from the services barrel put that chain in the module graph of every app that
- * imports services, which only a bundler could remove and an unbundled Node or
- * Lambda deploy would load outright.
- */
-export { HttpPersona, createHttpPersonas, type HttpPersonasConfig, } from '../../services/http-personas.js';
-export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, type ActorSecretResolver, type PersonaSignIn, type OperatorSignInOptions, type OperatorSessionResult, authMount, } from '../../services/persona-sign-in.js';
-export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from '../../services/persona-actor-secret.js';
-export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/dist/wirings/persona/index.js

@@ -1,19 +0,0 @@
-export { definePersonas } from './define-personas.js';
-export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBuildPersonasMeta, verifyPersonaRoles, } from './validate-personas.js';
-export { personaEnvironmentErrors, personaEnvironmentRefusal, } from './persona-environments.js';
-export { personaEmail, personaEmails } from './persona-email.js';
-export { APP_SCOPE_ROOT, appScopeId, buildAppScopeDefinition, } from './persona-app-scopes.js';
-/**
- * Signing in as a persona and talking to a stage over HTTP.
- *
- * Deliberately reached through this entry point rather than `@pikku/core/services`.
- * `HttpPersona` pulls in the actor-flow conversation runner and, through it, the
- * agent runner — none of which a production server has any use for. Exporting it
- * from the services barrel put that chain in the module graph of every app that
- * imports services, which only a bundler could remove and an unbundled Node or
- * Lambda deploy would load outright.
- */
-export { HttpPersona, createHttpPersonas, } from '../../services/http-personas.js';
-export { ActorSignIn, OperatorSignIn, establishOperatorSession, IMPERSONATE_USER_ID_HEADER, authMount, } from '../../services/persona-sign-in.js';
-export { ACTOR_ROOT_SECRET_MIN_LENGTH, ACTOR_SECRET_INFO, ACTOR_SECRET_NAME, actorSecretSubject, deriveActorSecret, verifyActorSecret, } from '../../services/persona-actor-secret.js';
-export { postScenarioJson, readScenarioHttpResponse, } from '../../services/personas-service.js';

package/knowledge/decisions/internals/actor-flow-conversations-seed-a-hidden-kickoff-message.md

@@ -1,23 +0,0 @@
----
-type: decision
-title: An actor conversation starts from a seeded kickoff message
-description: The actor's first turn needs a non-empty message list because providers reject an empty prompt; the seed is an instruction and stays out of the transcript
-tags: actor-flow
----
-
-# An actor conversation starts from a seeded kickoff message
-
-`runConversation` in
-`packages/core/src/wirings/actor-flow/run-conversation.ts` primes
-`actorMessages` with a single user message telling the persona to begin, before
-the first turn is generated.
-
-The actor speaks first, so at that point there is nothing for it to reply to —
-and LLM providers reject a completion request with no messages. The seed is
-addressed to the actor rather than to the target agent, which is why it is never
-pushed onto `transcript`: it is scaffolding, not something the simulated user
-said, and including it would corrupt the transcript the final evaluation reads.
-
-**What this rules out:** starting from an empty `actorMessages` array, folding
-the kickoff into the persona instructions where a provider may weight it
-differently, and pushing the seed into the transcript for symmetry.

package/knowledge/decisions/internals/actor-flow-verdicts-are-llm-self-evaluations.md

@@ -1,25 +0,0 @@
----
-type: decision
-title: An actor-flow verdict is the persona's self-evaluation, not an assertion
-description: The engine returns what the actor judged plus the transcript; deterministic checks stay with the caller
-tags: actor-flow
----
-
-# An actor-flow verdict is the persona's self-evaluation, not an assertion
-
-`runConversation` ends by asking the persona LLM whether the `evaluate`
-criterion was met and returns that as `ActorFlowVerdict` — `passed`, `reasoning`
-and the full `transcript`
-(`packages/core/src/wirings/actor-flow/`). Nothing in the engine inspects the
-system the agent acted on.
-
-The verdict is deliberately soft because the thing it judges is soft: whether a
-conversation accomplished a natural-language task. Deterministic checks — that a
-row was written, that an email went out — belong to the caller, which already
-holds the actor and can `actor.invoke(...)` after the conversation returns. The
-`reasoning` and `transcript` fields exist so a soft failure is debuggable rather
-than merely red.
-
-**What this rules out:** having `runConversation` assert or throw on a failed
-verdict, and adding deterministic post-conditions to `ConverseOptions` instead of
-running them at the call site.

package/knowledge/decisions/internals/validate-checks-personas-through-a-shared-module.md

@@ -1,43 +0,0 @@
----
-type: decision
-title: Both validators check personas through one shared module, and a persona counts from either the meta or the source
-description: workspace validate and fabric validate are separate implementations, so the persona/actor/knowledge checks live in persona-checks.ts and are called by both — and a persona is counted from the generated meta or a definePersonas() source scan, whichever answers first
-tags: cli, validate, scenarios, personas
----
-
-# Both validators check personas through one shared module, and a persona counts from either the meta or the source
-
-`pikku workspace validate` and `pikku fabric validate` read like one command
-with a flag. They are not. They are two implementations that walk the same
-project and duplicate about eighteen findings between them verbatim —
-`functions-dir-missing` exists twice, character for character, in two files.
-Fabric adds the deploy-shaped checks (themes, frontends, the Cloudflare
-adapter, the `.gitignore` contract); workspace adds the local-development ones
-(`dev.db`, the auth migrations).
-
-So a check written into either one is a check half the projects never run. An
-app that never deploys through fabric only ever sees workspace validate; an app
-that does sees fabric validate in CI. The persona checks are the kind that only
-pay off when nobody remembers to ask for them, which means they had to be in
-both. Rather than duplicate them a nineteenth time, they live in
-`persona-checks.ts` and both validators call `runPersonaChecks`. Merging the
-two validators outright is the better fix and a much larger one; this does not
-block it.
-
-**A persona counts from either source, and either alone is wrong at a
-predictable moment.** The generated `pikku-personas-meta.gen.json` is empty on
-a fresh clone where codegen has not run, so trusting only it means a warning
-that fires on every new checkout — and a validator that cries wolf gets muted,
-after which it never says anything worth hearing. A source scan for
-`definePersonas(` cannot see personas an addon contributed. Declared by either
-counts as declared.
-
-**Everything here is `warn`, never `error`.** A project with no personas is
-under-tested, not broken, and `validate` gating a deploy on it would make the
-first thing anyone does with the check be to remove it. `knowledge-empty` stays
-at the `info` the shared `@pikku/knowledge` package already assigned it rather
-than being raised to match — the severity belongs to that package.
-
-**What this rules out:** duplicating the checks into both validators;
-adding them to only one; deriving the persona count from the generated meta
-alone; failing a build over a missing persona.

package/knowledge/decisions/security/actor-sign-in-only-works-for-actor-flagged-users.md

@@ -1,31 +0,0 @@
----
-type: decision
-title: Actor sign-in only works for actor-flagged users
-description: An actor credential mints sessions for user rows flagged actor and nothing else, so holding one never impersonates a real user
-tags: services
----
-
-# Actor sign-in only works for actor-flagged users
-
-`HttpPersonasConfig.secret` (`packages/core/src/services/http-personas.ts`) is
-what `ActorSignIn.login` presents: it POSTs `{ email, name, secret }` to
-`/auth/sign-in/actor` and gets back a session. That looks like a master key, and
-it deliberately is not one — for two independent reasons.
-
-The first is the flag. The Better Auth actor plugin on the other end upserts and
-signs in only user rows flagged `actor: true`. Presenting a credential with a
-real customer's email does not mint that customer's session — it is refused. The
-`actor` flag also flows into the minted session, so audits and analytics can tell
-scenario traffic from human traffic after the fact.
-
-The second is that a credential is not shared. What is presented is derived from
-the root `SCENARIO_ACTOR_SECRET` and the address it signs in as — see
-[an actor credential is derived per persona](an-actor-credential-is-derived-per-persona.md) —
-so the blast radius of a leaked credential is one synthetic account, not the
-synthetic actor population.
-
-**What this rules out:** widening the sign-in endpoint to accept any email "so
-scenarios can test as a real user", and treating an actor credential as
-equivalent to a session-signing key. It also rules out dropping the `actor` flag
-from the minted session — the audit trail's ability to separate synthetic from
-real activity depends on it.

package/knowledge/decisions/security/an-actor-credential-is-derived-per-persona.md

@@ -1,42 +0,0 @@
----
-type: decision
-title: An actor credential is derived per persona
-description: What a caller presents to the actor endpoint is HKDF-derived from the root secret and the address it signs in as, so one credential opens one persona
-tags: services
----
-
-# An actor credential is derived per persona
-
-`SCENARIO_ACTOR_SECRET` is a root, not a password. What a caller presents to
-`/auth/sign-in/actor` is `deriveActorSecret(root, email)`
-(`packages/core/src/services/persona-actor-secret.ts`) — an HKDF-expanded
-HMAC-SHA256 over the lowercased address, on the same key-material primitives
-everything else in core signs with. The endpoint does not store or look anything
-up: it re-derives the expected value for whichever address is being signed in as
-and compares. A credential minted for one persona is refused for every other.
-
-The root itself is not accepted as a credential, and a root shorter than 32
-characters refuses the endpoint outright rather than deriving weak credentials
-from it. The server-side warning names the problem; what the client is told does
-not.
-
-Derivation rather than a per-persona secrets table because there is then nothing
-to store, provision, or keep in sync — the target already holds the root, and
-rotating it invalidates every credential at once.
-
-This is what lets a holder be handed less than everything:
-
-- The browser switcher gets no credential at all. It used to be handed
-  `VITE_DEV_ACTOR_SECRETS`, one per persona; it now names a persona by id at
-  `/sign-in/persona`, which the server gates with the actor opt-in and the
-  `devSwitcher` flag, so a bundle holds nothing worth taking.
-- A run can be given `PIKKU_PERSONA_SECRETS` (`id=secret,…`, minted with
-  `pikku persona secret`) instead of the root, and then it can sign in as those
-  personas and no others. Asking for one outside the list throws naming the
-  persona rather than falling back to the root.
-
-**What this rules out:** accepting the root as a credential at the endpoint,
-putting the root in any client bundle, and comparing a presented credential
-against a stored one. It also rules out per-persona secrets that are generated
-randomly and written down — the derivation is the reason there is nothing to
-provision.

package/knowledge/decisions/security/pikku-carries-actor-scopes-as-data-and-the-app-grants-them.md

@@ -1,26 +0,0 @@
----
-type: decision
-title: Pikku carries actor scopes as data and the app grants them
-description: scopes and roles on a ScenarioActorConfig are transported, never applied — the app's own seed reads them back and performs the grant
-tags: services
----
-
-# Pikku carries actor scopes as data and the app grants them
-
-`ScenarioActorConfig.scopes` and `.roles`
-(`packages/core/src/services/scenario-actors-service.ts`) come from
-`pikku.config.json` and are carried through to `scenarioActorConfigs`. Nothing in
-core reads them to grant anything. The app's seed reads them back off that config
-and performs the grants itself.
-
-Core cannot do the granting: which scope store exists, whether roles have been
-created, and what a role means are all the application's own. Worse, a framework
-that granted scopes would be a framework that can escalate an actor's privileges
-from a config file — the one place where a scenario author would least expect a
-security decision to take effect. Keeping the fields inert makes the grant an act
-the app performs deliberately, in code it owns, against a store it wired.
-
-**What this rules out:** teaching `createHttpScenarioActors` (or any core service)
-to call `ScopeService.addScopeToUser` / `addUserToRole` from these fields, and
-treating a scope listed on an actor config as evidence that the actor holds it.
-If a scenario fails on a missing scope, the fix is in the app's seed, not here.