@pikku/core 0.12.72 → 0.12.77

package/dist/services/credential-service.d.ts

@@ -1,51 +1,14 @@
 /**
- * Interface for managing dynamic/managed credentials.
- * Used for OAuth tokens, per-user API keys, and other credentials
- * that change at runtime (as opposed to SecretService which is for
- * static, developer-configured values).
+ * Dynamic credentials — OAuth tokens, per-user API keys — that change at
+ * runtime, as opposed to `SecretService`'s static developer-configured values.
+ * Throughout, an omitted `userId` means the platform-level credential.
  */
 export interface CredentialService {
-    /**
-     * Retrieves a credential by name and optional user ID.
-     * @param name - The credential name (e.g. 'stripe', 'google-sheets').
-     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-     * @returns The credential value, or null if not found.
-     */
     get<T = unknown>(name: string, userId?: string): Promise<T | null>;
-    /**
-     * Stores a credential.
-     * @param name - The credential name.
-     * @param value - The credential value to store.
-     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-     */
     set(name: string, value: unknown, userId?: string): Promise<void>;
-    /**
-     * Deletes a credential.
-     * @param name - The credential name.
-     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-     */
     delete(name: string, userId?: string): Promise<void>;
-    /**
-     * Checks if a credential exists.
-     * @param name - The credential name.
-     * @param userId - Optional user ID for per-user credentials. Omit for platform-level.
-     */
     has(name: string, userId?: string): Promise<boolean>;
-    /**
-     * Retrieves all credentials for a user.
-     * @param userId - The user ID.
-     * @returns A record of credential name to value.
-     */
     getAll(userId: string): Promise<Record<string, unknown>>;
-    /**
-     * Lists all user IDs that have a specific credential configured.
-     * @param name - The credential name.
-     * @returns Array of user IDs.
-     */
     getUsersWithCredential(name: string): Promise<string[]>;
-    /**
-     * Lists all unique user IDs that have any credential configured.
-     * @returns Array of user IDs.
-     */
     getAllUsers(): Promise<string[]>;
 }

package/dist/services/credential-wire-service.d.ts

@@ -9,6 +9,11 @@ export declare class PikkuCredentialWireService {
     private loadPromise;
     constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined);
     private resolveName;
+    /**
+     * A credential is one of the few places vault material is meant to end up, so
+     * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+     * raw material, and storing the wrapper would make that a lie.
+     */
     set(name: string, value: unknown): void;
     get<T = unknown>(name: string): T | null | Promise<T | null>;
     getAll(): Record<string, unknown> | Promise<Record<string, unknown>>;

package/dist/services/credential-wire-service.js

@@ -1,3 +1,4 @@
+import { isSecretValue } from '../secret-value.js';
 import { defaultPikkuUserIdResolver } from './pikku-user-id.js';
 export class PikkuCredentialWireService {
     credentialService;
@@ -14,8 +15,15 @@ export class PikkuCredentialWireService {
     resolveName(name) {
         return this.aliases?.[name] ?? name;
     }
+    /**
+     * A credential is one of the few places vault material is meant to end up, so
+     * a `SecretValue` is unwrapped here rather than rejected — `get` promises the
+     * raw material, and storing the wrapper would make that a lie.
+     */
     set(name, value) {
-        this.credentials[this.resolveName(name)] = value;
+        this.credentials[this.resolveName(name)] = isSecretValue(value)
+            ? value.reveal()
+            : value;
     }
     get(name) {
         const key = this.resolveName(name);

package/dist/services/deployment-service.d.ts

@@ -16,15 +16,9 @@ export interface DeploymentService {
     start(config: DeploymentConfig): Promise<void>;
     stop(): Promise<void>;
     /**
-     * Dispatch a remote RPC call to a function.
-     * The deployment service owns the full transport:
-     * - Resolving the target (endpoint, service binding, etc.)
-     * - Session propagation (JWT signing, headers)
-     * - The actual network call
-     *
-     * @param funcName - The function to invoke
-     * @param data - Input data for the function
-     * @param session - User session to propagate (optional)
+     * The implementation owns the whole transport: resolving the target
+     * (endpoint, service binding), propagating the session (JWT signing,
+     * headers) and making the call. Callers supply no transport detail.
      */
     invoke(funcName: string, data: unknown, session?: unknown, traceId?: string): Promise<unknown>;
 }

package/dist/services/email-service.d.ts

@@ -1,3 +1,4 @@
+import type { Safe } from '../secret-value.js';
 export interface EmailTemplateReference {
     name: string;
     locale?: string;
@@ -32,5 +33,5 @@ export interface SendEmailResult {
     messageId?: string;
 }
 export interface EmailService {
-    send(input: SendEmailInput): Promise<SendEmailResult>;
+    send<T extends SendEmailInput>(input: Safe<T>): Promise<SendEmailResult>;
 }

package/dist/services/gateway-service.d.ts

@@ -1,19 +1,4 @@
-/**
- * Abstract GatewayService interface.
- *
- * Implementations manage listener gateway lifecycle — initializing adapters
- * and delivering messages to handler functions.
- *
- * A `LocalGatewayService` starts all listeners unconditionally;
- * a distributed implementation could check leader election first.
- */
 export interface GatewayService {
-    /**
-     * Start all listener gateways
-     */
     start(): Promise<void>;
-    /**
-     * Stop all listener gateways
-     */
     stop(): Promise<void>;
 }

package/dist/services/http-personas.d.ts

@@ -0,0 +1,80 @@
+import type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, ScenarioInvokeOptions, ScenarioHttpResponse } from './personas-service.js';
+import type { ConverseOptions, ActorFlowVerdict } from '../wirings/actor-flow/actor-flow.types.js';
+export interface HttpPersonasConfig {
+    /**
+     * Base API URL of the target app, INCLUDING the HTTP prefix — e.g.
+     * `https://app.example.com/api` or `http://localhost:4000/api`. Sign-in is
+     * reached at `${apiUrl}${signInPath}` and exposed RPCs at
+     * `${apiUrl}${rpcPath}/:rpcName`.
+     */
+    apiUrl: string;
+    /**
+     * The impersonation secret. Sign-in only ever works for user rows flagged
+     * `actor: true` — knowing the secret never impersonates real users.
+     */
+    secret: string;
+    /** 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`. */
+    signInPath?: string;
+    /** Where the session (and its roles) is read back. Default `/auth/get-session`. */
+    sessionPath?: string;
+    /** Exposed-RPC path prefix under apiUrl. Default `/rpc`. */
+    rpcPath?: string;
+    /**
+     * Default model a persona thinks with when `converse(...)` is called without
+     * an explicit `model`. Its own turns/approvals/evaluation run in-process via
+     * the configured `aiAgentRunner`.
+     */
+    model?: string;
+}
+/**
+ * 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).
+ */
+export declare class HttpPersona implements ScenarioPersona {
+    readonly name: string;
+    private persona;
+    private config;
+    private jar;
+    /**
+     * Whether `login()` has succeeded since the last time the session was
+     * dropped. The jar cannot answer this — a target may set a cookie before
+     * anyone signs in, and it would then look like a session that was never
+     * established.
+     */
+    private signedIn;
+    constructor(name: string, persona: ResolvedPersona, config: HttpPersonasConfig);
+    get email(): string;
+    invoke(rpcName: string, data: unknown): Promise<unknown>;
+    invokeRaw(rpcName: string, data: unknown, options?: ScenarioInvokeOptions): Promise<ScenarioHttpResponse>;
+    converse(options: ConverseOptions): Promise<ActorFlowVerdict>;
+    /**
+     * The roles the stage says this session holds.
+     *
+     * Read from better-auth's `get-session`, which is what most pikku apps are
+     * running and where its admin plugin puts `role` — on the user, as a
+     * comma-separated list. A target that answers something else returns `null`
+     * rather than an empty list, because "this stage does not report roles" and
+     * "this person has none" call for opposite responses from the caller.
+     */
+    sessionRoles(): Promise<string[] | null>;
+    /** Start/continue the target agent's run over HTTP as this persona. */
+    private agentRun;
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    private agentApprove;
+    private postAgent;
+    private postRpc;
+    /** Drop the session, so the next call signs in again before it goes out. */
+    private signOut;
+    private login;
+}
+/**
+ * Build the injected `personas` service from the declared personas: id → lazy
+ * HTTP persona. Wire the result as the `personas` singleton service.
+ */
+export declare function createHttpPersonas(config: HttpPersonasConfig): ScenarioPersonas;

package/dist/services/http-personas.js

@@ -0,0 +1,233 @@
+import { readScenarioHttpResponse } from './personas-service.js';
+import { runConversation } from '../wirings/actor-flow/run-conversation.js';
+import { createCookieJar, } from '../wirings/workflow/scenario-cookie-jar.js';
+import { getSingletonServices } from '../pikku-state.js';
+import { AIProviderNotConfiguredError } from '../errors/errors.js';
+/**
+ * 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).
+ */
+export class HttpPersona {
+    name;
+    persona;
+    config;
+    jar;
+    /**
+     * Whether `login()` has succeeded since the last time the session was
+     * dropped. The jar cannot answer this — a target may set a cookie before
+     * anyone signs in, and it would then look like a session that was never
+     * established.
+     */
+    signedIn = false;
+    constructor(name, persona, config) {
+        this.name = name;
+        this.persona = persona;
+        this.config = config;
+        this.jar = createCookieJar(config.apiUrl);
+    }
+    get email() {
+        return this.persona.email;
+    }
+    async invoke(rpcName, data) {
+        const res = await this.invokeRaw(rpcName, data);
+        if (!res.ok) {
+            throw new Error(`[scenario] '${rpcName}' as '${this.name}' returned ${res.status}: ${res.serialized.slice(0, 300)}`);
+        }
+        return res.body;
+    }
+    async invokeRaw(rpcName, data, options) {
+        if (!this.signedIn) {
+            await this.login();
+        }
+        let res = await this.postRpc(rpcName, data, options?.headers);
+        if (res.status === 401) {
+            // Session expired mid-run — re-login once and retry.
+            this.signOut();
+            await this.login();
+            res = await this.postRpc(rpcName, data, options?.headers);
+        }
+        return readScenarioHttpResponse(res);
+    }
+    async converse(options) {
+        const { aiAgentRunner } = getSingletonServices();
+        if (!aiAgentRunner) {
+            throw new AIProviderNotConfiguredError();
+        }
+        const model = options.model ?? this.config.model;
+        if (!model) {
+            throw new Error(`[scenario] persona '${this.name}' converse needs a model — pass options.model or set 'model' on the personas service`);
+        }
+        const threadId = globalThis.crypto.randomUUID();
+        const resourceId = `persona:${this.name}`;
+        return runConversation({
+            persona: this.persona,
+            personaId: this.name,
+            agentName: options.agent,
+            task: options.task,
+            evaluate: options.evaluate,
+            approvals: options.approvals,
+            model,
+            maxTurns: options.maxTurns,
+            llm: (params) => aiAgentRunner.run(params),
+            target: {
+                run: (message) => this.agentRun(options.agent, message, threadId, resourceId),
+                approve: (runId, decisions) => this.agentApprove(options.agent, runId, decisions),
+            },
+        });
+    }
+    /**
+     * The roles the stage says this session holds.
+     *
+     * Read from better-auth's `get-session`, which is what most pikku apps are
+     * running and where its admin plugin puts `role` — on the user, as a
+     * comma-separated list. A target that answers something else returns `null`
+     * rather than an empty list, because "this stage does not report roles" and
+     * "this person has none" call for opposite responses from the caller.
+     */
+    async sessionRoles() {
+        if (!this.signedIn) {
+            await this.login();
+        }
+        const sessionPath = this.config.sessionPath ?? '/auth/get-session';
+        const res = await this.jar.fetch(`${this.config.apiUrl}${sessionPath}`);
+        if (!res.ok) {
+            return null;
+        }
+        const text = await res.text().catch(() => '');
+        if (!text) {
+            return null;
+        }
+        let payload;
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        const user = payload?.user;
+        const role = user?.role;
+        if (typeof role === 'string') {
+            return role
+                .split(',')
+                .map((name) => name.trim())
+                .filter(Boolean);
+        }
+        if (Array.isArray(role)) {
+            return role.filter((name) => typeof name === 'string');
+        }
+        // The session came back and carried a user, but no role field — that is a
+        // stage reporting "none", not a stage that cannot report.
+        return user ? [] : null;
+    }
+    /** Start/continue the target agent's run over HTTP as this persona. */
+    async agentRun(agentName, message, threadId, resourceId) {
+        const raw = await this.postAgent(`agent/${agentName}`, {
+            message,
+            threadId,
+            resourceId,
+        });
+        return normalizeAgentReply(raw);
+    }
+    /** Answer the target agent's pending approvals over HTTP and continue. */
+    async agentApprove(agentName, runId, decisions) {
+        const raw = await this.postAgent(`agent/${agentName}/approve`, {
+            runId,
+            approvals: decisions,
+        });
+        return normalizeAgentReply(raw);
+    }
+    // knowledge: decisions/internals/scenario-agent-calls-sign-in-on-401-only.md
+    async postAgent(subPath, body) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        const url = `${this.config.apiUrl}${rpcPath}/${subPath}`;
+        const send = () => this.jar.fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        let res = await send();
+        if (res.status === 401) {
+            this.signOut();
+            await this.login();
+            res = await send();
+        }
+        if (!res.ok) {
+            const text = (await res.text().catch(() => '')).slice(0, 300);
+            throw new Error(`[scenario] agent call '${subPath}' as '${this.name}' returned ${res.status}: ${text}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        return text ? JSON.parse(text) : undefined;
+    }
+    async postRpc(rpcName, data, extraHeaders) {
+        const rpcPath = this.config.rpcPath ?? '/rpc';
+        return this.jar.fetch(`${this.config.apiUrl}${rpcPath}/${rpcName}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...extraHeaders },
+            body: JSON.stringify({ data }),
+        });
+    }
+    /** Drop the session, so the next call signs in again before it goes out. */
+    signOut() {
+        this.jar.clear();
+        this.signedIn = false;
+    }
+    async login() {
+        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`);
+        }
+        this.signedIn = true;
+    }
+}
+/** Normalize an agentRun/agentApprove HTTP response into a TargetAgentReply. */
+function normalizeAgentReply(raw) {
+    const r = (raw ?? {});
+    const pending = Array.isArray(r.pendingApprovals)
+        ? r.pendingApprovals.map((p) => ({
+            toolCallId: String(p.toolCallId),
+            toolName: String(p.toolName),
+            args: p.args,
+            reason: typeof p.reason === 'string' ? p.reason : undefined,
+        }))
+        : undefined;
+    return {
+        text: typeof r.text === 'string' ? r.text : '',
+        runId: typeof r.runId === 'string' ? r.runId : '',
+        status: r.status === 'completed' || r.status === 'suspended'
+            ? r.status
+            : undefined,
+        pendingApprovals: pending,
+    };
+}
+/**
+ * Build the injected `personas` service from the declared personas: id → lazy
+ * HTTP persona. Wire the result as the `personas` singleton service.
+ */
+export function createHttpPersonas(config) {
+    const personas = {};
+    for (const [id, persona] of Object.entries(config.personas)) {
+        personas[id] = new HttpPersona(id, persona, config);
+    }
+    return personas;
+}

package/dist/services/in-memory-queue-service.d.ts

@@ -1,22 +1,8 @@
 import type { QueueService, JobOptions } from '../wirings/queue/queue.types.js';
-/**
- * In-process queue for local/dev runs. Schedules jobs on the macrotask queue
- * (setTimeout) so dispatch is genuinely asynchronous — the same timing shape as
- * a real queue — and redelivers a failed job up to `options.attempts` times with
- * backoff, so a transiently-failing workflow step recovers exactly as it would
- * on pg-boss/bullmq instead of being silently dropped on its first error.
- *
- * Payloads are JSON round-tripped on the way in, because every real backend
- * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
- * therefore never sees the caller's live object. Doing it here keeps dev
- * behaviour honest, and keeps the callers — who cannot know which backend they
- * are talking to — from having to serialise defensively.
- */
 export declare class InMemoryQueueService implements QueueService {
     readonly supportsResults = false;
     private jobCounter;
     add<T>(queueName: string, data: T, options?: JobOptions): Promise<string>;
-    /** Delay before the next redelivery, honoring the job's backoff policy. */
     private backoffDelay;
     getJob(): Promise<null>;
 }

package/dist/services/in-memory-queue-service.js

@@ -1,17 +1,5 @@
 import { runQueueJob } from '../wirings/queue/queue-runner.js';
-/**
- * In-process queue for local/dev runs. Schedules jobs on the macrotask queue
- * (setTimeout) so dispatch is genuinely asynchronous — the same timing shape as
- * a real queue — and redelivers a failed job up to `options.attempts` times with
- * backoff, so a transiently-failing workflow step recovers exactly as it would
- * on pg-boss/bullmq instead of being silently dropped on its first error.
- *
- * Payloads are JSON round-tripped on the way in, because every real backend
- * puts the job on a wire (SQS body, Redis value, jsonb column) and the worker
- * therefore never sees the caller's live object. Doing it here keeps dev
- * behaviour honest, and keeps the callers — who cannot know which backend they
- * are talking to — from having to serialise defensively.
- */
+// knowledge: decisions/internals/the-dev-queue-copies-prod-timing-and-serialization-semantics.md
 export class InMemoryQueueService {
     supportsResults = false;
     jobCounter = 0;
@@ -36,7 +24,6 @@ export class InMemoryQueueService {
             }
             catch (e) {
                 if (attemptsMade < maxAttempts) {
-                    // Transient failure — redeliver with backoff, mirroring a real queue.
                     setTimeout(runAttempt, this.backoffDelay(options?.backoff, attemptsMade));
                 }
                 else {
@@ -48,7 +35,6 @@ export class InMemoryQueueService {
         setTimeout(runAttempt, delay);
         return jobId;
     }
-    /** Delay before the next redelivery, honoring the job's backoff policy. */
     backoffDelay(backoff, attemptsMade) {
         const baseDelay = typeof backoff === 'object' ? (backoff.delay ?? 50) : 50;
         if (backoff === 'exponential' ||

package/dist/services/in-memory-trigger-service.d.ts

@@ -1,22 +1,4 @@
 import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js';
-/**
- * In-memory TriggerService implementation.
- *
- * Reads both `wireTrigger` declarations and `wireTriggerSource` registrations
- * from pikkuState. Only starts triggers that have both a declaration and a source.
- * On fire, invokes target via `ContextAwareRPCService`.
- *
- * Single owner — one process runs triggers, no distributed claiming.
- *
- * @example
- * ```typescript
- * const triggerService = new InMemoryTriggerService()
- * await triggerService.start()
- *
- * // On shutdown
- * await triggerService.stop()
- * ```
- */
 export declare class InMemoryTriggerService extends PikkuTriggerService {
     start(): Promise<void>;
 }

package/dist/services/in-memory-trigger-service.js

@@ -1,23 +1,6 @@
 import { PikkuTriggerService } from '../wirings/trigger/pikku-trigger-service.js';
 import { getSingletonServices } from '../pikku-state.js';
-/**
- * In-memory TriggerService implementation.
- *
- * Reads both `wireTrigger` declarations and `wireTriggerSource` registrations
- * from pikkuState. Only starts triggers that have both a declaration and a source.
- * On fire, invokes target via `ContextAwareRPCService`.
- *
- * Single owner — one process runs triggers, no distributed claiming.
- *
- * @example
- * ```typescript
- * const triggerService = new InMemoryTriggerService()
- * await triggerService.start()
- *
- * // On shutdown
- * await triggerService.stop()
- * ```
- */
+// knowledge: decisions/internals/local-trigger-and-gateway-services-assume-a-single-process.md
 export class InMemoryTriggerService extends PikkuTriggerService {
     async start() {
         const singletonServices = getSingletonServices();

package/dist/services/in-memory-workflow-service.d.ts

@@ -1,21 +1,6 @@
 import { PikkuWorkflowService } from '../wirings/workflow/pikku-workflow-service.js';
 import type { SerializedError } from '../types/core.types.js';
 import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunService, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from '../wirings/workflow/workflow.types.js';
-/**
- * In-memory implementation of WorkflowService for inline-only execution
- *
- * This is a lightweight workflow service that stores all state in memory.
- * It only supports inline execution (no queue workers) and is ideal for:
- * - CLI tools that need workflow-like step orchestration
- * - Testing and development
- * - Single-process applications without persistence requirements
- *
- * @example
- * ```typescript
- * const workflowService = new InMemoryWorkflowService()
- * await workflowService.startWorkflow('myWorkflow', input, { type: 'cli' }, rpc, { inline: true })
- * ```
- */
 export declare class InMemoryWorkflowService extends PikkuWorkflowService implements WorkflowRunService {
     constructor(options?: WorkflowQueueOptions);
     private sleepTimers;
@@ -65,7 +50,6 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
         failedNodeIds: string[];
         branchKeys: Record<string, string>;
     }>;
-    getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
     protected listStepStates(runId: string): Promise<Array<StepState & {
         stepName: string;
     }>>;