@pikku/core 0.12.83 → 0.12.86

package/dist/wirings/http/http.types.d.ts

@@ -1,6 +1,7 @@
 import type { SerializeOptions } from 'cookie';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
+import type { CommonWireMeta } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunction, CorePikkuFunctionSessionless, CorePikkuPermission, CorePikkuFunctionConfig } from '../../function/functions.types.js';
 type ExtractHTTPWiringParams<S extends string> = S extends `${string}:${infer Param}/${infer Rest}` ? Param | ExtractHTTPWiringParams<`/${Rest}`> : S extends `${string}:${infer Param}` ? Param : never;
 export type AssertHTTPWiringParams<In, HTTPWiring extends string> = ExtractHTTPWiringParams<HTTPWiring> extends keyof In ? unknown : [
@@ -104,7 +105,6 @@ export type HTTPWiringMeta = CommonWireMeta & {
      * join wrong reads an open route as a closed one.
      */
     requiresSession?: boolean;
-    refTarget?: string;
     params?: string[];
     query?: string[];
     inputTypes?: HTTPFunctionMetaInputTypes;

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

@@ -4,4 +4,5 @@ export { logRoutes } from './log-http-routes.js';
 export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js';
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';
 export { toWebRequest, applyWebResponse } from './web-request.js';
+export { httpRouter } from './routers/http-router.js';
 export type { AssertHTTPWiringParams, CoreHTTPFunctionWiring, HTTPMethod, HTTPRouteBaseConfig, HTTPRouteContract, HTTPRouteMap, HTTPWiringsMeta, PikkuHTTP, PikkuHTTPRequest, PikkuHTTPResponse, PikkuQuery, RunHTTPWiringOptions, } from './http.types.js';

package/dist/wirings/http/index.js

@@ -4,3 +4,4 @@ export { logRoutes } from './log-http-routes.js';
 export { fetch, fetchData, wireHTTP, addHTTPMiddleware } from './http-runner.js';
 export { wireHTTPRoutes, defineHTTPRoutes } from './http-routes.js';
 export { toWebRequest, applyWebResponse } from './web-request.js';
+export { httpRouter } from './routers/http-router.js';

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -1,5 +1,5 @@
 import { parse as parseQuery } from 'picoquery';
-import { parse as parseCookie } from 'cookie';
+import { parseCookie } from 'cookie';
 import { PayloadTooLargeError, UnprocessableContentError, } from '../../errors/errors.js';
 export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
 /**

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -1,4 +1,4 @@
-import { serialize as serializeCookie } from 'cookie';
+import { stringifySetCookie } from 'cookie';
 export class PikkuFetchHTTPResponse {
     #statusCode = 200;
     #headers = new Headers();
@@ -95,7 +95,7 @@ export class PikkuFetchHTTPResponse {
         return this;
     }
     toResponse(args) {
-        const cookieHeader = Array.from(this.#cookies.entries()).map(([name, { value, flags }]) => serializeCookie(name, value, flags));
+        const cookieHeader = Array.from(this.#cookies.entries()).map(([name, { value, flags }]) => stringifySetCookie({ name, value, ...flags }, flags));
         cookieHeader.forEach((cookie) => this.#headers.append('Set-Cookie', cookie));
         return new Response(this.#body, {
             ...args,

package/dist/wirings/mcp/mcp.types.d.ts

@@ -1,5 +1,5 @@
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless, CorePikkuPermission } from '../../function/functions.types.js';
-import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../types/core.types.js';
+import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
 /** "user/{userId}/post/{postId}" => "userId" | "postId" */
 type ExtractMCPURIParams<S extends string> = S extends `${string}{${infer Param}}/${infer Rest}` ? Param | ExtractMCPURIParams<Rest> : S extends `${string}{${infer Param}}` ? Param : never;
 /** Resolves to a tuple of error strings, not `never`, so the mismatch surfaces in the type error. */

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

@@ -3,7 +3,7 @@ export { isRunnablePersona, roleMismatchMessage, runnablePersonas, validateAndBu
 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 { personaEmail, personaEmails } from './persona-email.js';
 export type { MailboxAllowlist, PersonaMailbox, ReceivedEmail, } from './persona-mailbox.js';
 export type { CorePersona, CorePersonas, PersonaAccountMeta, PersonaDefinitions, PersonaMeta, PersonasMeta, } from './persona.types.js';
 /**

package/dist/wirings/persona/index.js

@@ -1,7 +1,7 @@
 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 { personaEmail, personaEmails } from './persona-email.js';
 /**
  * Signing in as a persona and talking to a stage over HTTP.
  *

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

@@ -105,6 +105,18 @@ export type CorePersona = {
      * into a flaky suite.
      */
     runnable?: boolean;
+    /**
+     * The app this person signs into, when the product is more than one frontend.
+     *
+     * A person uses one of them — staff their app, customers theirs — and that is
+     * what decides where a browser step navigates: `/dashboard` is a different
+     * page in each, so the actor settles which one without the scenario saying.
+     * The runner takes the base url per app (`--app-url <app>=<url>`, or
+     * `appUrls` on the environment) and each actor browses against its own.
+     *
+     * Omitted is the normal case: one app, one url, nothing to say.
+     */
+    app?: string;
 };
 /** Personas to declare, keyed by id. */
 export type CorePersonas = Record<string, CorePersona>;
@@ -130,6 +142,8 @@ export type PersonaMeta = {
     /** Absent means "everywhere but production", which is resolved, not stored. */
     environments?: string[];
     runnable: boolean;
+    /** The app this person signs into; picks their base url on a browser run. */
+    app?: string;
     sourceFile?: string;
 };
 export type PersonaDefinitions = PersonaMeta[];

package/dist/wirings/queue/queue.types.d.ts

@@ -1,7 +1,7 @@
 import type { CommonWireMeta } from '../../types/core.types.js';
 import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
 import type { QueueConfigMapping } from './validate-worker-config.js';
-import type { Safe } from '../../secret-value.js';
+import type { Safe } from '../../classification/secret-value.js';
 export interface PikkuWorkerConfig {
     name?: string;
     /** Total worker concurrency. */

package/dist/wirings/queue/signed-queue-service.d.ts

@@ -1,4 +1,4 @@
-import type { Safe } from '../../secret-value.js';
+import type { Safe } from '../../classification/secret-value.js';
 import type { Logger } from '../../services/logger.js';
 import type { SecretService } from '../../services/secret-service.js';
 import type { JobOptions, QueueJob, QueueService } from './queue.types.js';

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

@@ -1,8 +1,2 @@
 export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
-export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
-export type { RemoteAddonAuthBinding } from './remote-addon-auth.js';
 export type { PikkuRPC, RPCMeta } from './rpc-types.js';
-export { wireAddon } from './wire-addon.js';
-export type { WireAddonConfig } from './wire-addon.js';
-export { wireRemoteAddon } from './wire-remote-addon.js';
-export type { WireRemoteAddonConfig, RemoteAddonAuth, } from './wire-remote-addon.js';

package/dist/wirings/rpc/index.js

@@ -1,4 +1 @@
 export { PikkuRPCService, rpcService, RPCNotFoundError, RemoteAddonConfigError, RemoteAddonRequestError, } from './rpc-runner.js';
-export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
-export { wireAddon } from './wire-addon.js';
-export { wireRemoteAddon } from './wire-remote-addon.js';

package/dist/wirings/rpc/remote-addon-auth.d.ts

@@ -1,6 +1,6 @@
 import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
 import { PikkuError } from '../../errors/error-handler.js';
-import { type SecretValue } from '../../secret-value.js';
+import { type SecretValue } from '../../classification/secret-value.js';
 export type RemoteAddonAuthBinding = {
     credentialId: string;
 } | {

package/dist/wirings/rpc/remote-addon-auth.js

@@ -1,5 +1,5 @@
 import { PikkuError, addError } from '../../errors/error-handler.js';
-import { isSecretValue } from '../../secret-value.js';
+import { isSecretValue, } from '../../classification/secret-value.js';
 export class RemoteAddonAuthError extends PikkuError {
     namespace;
     constructor(namespace, detail) {

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -52,7 +52,7 @@ export declare class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `ai-agent/agent-rpc.ts` so the agent surface is
+     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
      * one file rather than a wing of this one; a getter rather than a field so a
      * request that never touches an agent never builds it.
      */

package/dist/wirings/rpc/rpc-runner.js

@@ -1,10 +1,10 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
-import { addonInstanceForNamespace } from './addon-runner.js';
+import { addonInstanceForNamespace } from '../addon/addon-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
-import { resolveRemoteAddonToken } from './remote-addon-auth.js';
-import { createAgentRPC } from '../ai-agent/agent-rpc.js';
+import { resolveRemoteAddonToken } from '../addon/remote-addon-auth.js';
+import { createAgentRPC } from '../agent/agent-rpc.js';
 /**
  * The session for a wire: read through `getSession` when a runner attached one,
  * otherwise whatever was placed on the wire directly.
@@ -314,7 +314,7 @@ export class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `ai-agent/agent-rpc.ts` so the agent surface is
+     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
      * one file rather than a wing of this one; a getter rather than a field so a
      * request that never touches an agent never builds it.
      */

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,5 +1,5 @@
 import type { PikkuRawWire } from '../../types/core.types.js';
-import type { AgentInterruptResult } from '../ai-agent/ai-agent-interrupt.js';
+import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
     depth: number;
     global: boolean;

package/dist/wirings/rpc/wire-addon.d.ts

@@ -1,4 +1,4 @@
-import type { CorePikkuMiddleware } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 export type WireAddonConfig = {
     name: string;
     package: string;

package/dist/wirings/scheduler/scheduler.types.d.ts

@@ -1,4 +1,5 @@
-import type { CoreUserSession, CorePikkuMiddleware, CommonWireMeta } from '../../types/core.types.js';
+import type { CoreUserSession, CommonWireMeta } from '../../types/core.types.js';
+import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 import type { CorePikkuFunctionConfig, CorePikkuFunctionSessionless } from '../../function/functions.types.js';
 export type ScheduledTasksMeta<UserSession extends CoreUserSession = any> = Record<string, CommonWireMeta & {
     name: string;

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

@@ -1,3 +1,4 @@
 export { defineScope } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
 export type { CoreScopes, CoreScopeNode, FlatScope, ScopeDefinitionMeta, ScopeDefinitionsMeta, ScopeDefinitions, ScopeNodeMeta, } from './scope.types.js';
+export { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/scope/index.js

@@ -1,2 +1,3 @@
 export { defineScope } from './define-scope.js';
 export { flattenScopeDefinitions, validateAndBuildScopeDefinitionsMeta, } from './validate-scope-definitions.js';
+export { hasScopes, verifyScopes } from '../../scopes.js';

package/dist/wirings/secret/secret.types.d.ts

@@ -4,6 +4,15 @@ export type CoreSecret<T = unknown> = {
     description?: string;
     secretId: string;
     schema: T;
+    /**
+     * A secret is REQUIRED by default because `getSecret` throws when the value is
+     * missing — a deploy without it is a runtime failure waiting to happen, so the
+     * deploy gate refuses it. Mark a secret `optional` when absence is a supported
+     * state the app handles (a feature that simply stays off): the generated map
+     * emits it as an optional property and `getSecret` resolves `undefined`
+     * instead of throwing.
+     */
+    optional?: boolean;
     /**
      * Where a user goes to obtain this value — a provider's API-key page, a setup
      * guide, an internal runbook. Consoles and deploy UIs surface it beside a
@@ -36,6 +45,7 @@ export type SecretDefinitionMeta = {
     description?: string;
     secretId: string;
     schema?: Record<string, unknown> | string;
+    optional?: boolean;
     docsUrl?: string;
     oauth2?: OAuth2CredentialConfig;
     rotationPeriod?: string;

package/dist/wirings/secret/validate-secret-definitions.js

@@ -32,6 +32,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                     description: def.description,
                     secretId: def.secretId,
                     schema: def.schema,
+                    optional: def.optional,
                     oauth2: def.oauth2,
                     rotationPeriod: def.rotationPeriod,
                     allowedHosts: def.allowedHosts,
@@ -49,6 +50,7 @@ export function validateAndBuildSecretDefinitionsMeta(definitions, schemaLookup)
                 description: def.description,
                 secretId: def.secretId,
                 schema: def.schema,
+                optional: def.optional,
                 oauth2: def.oauth2,
                 rotationPeriod: def.rotationPeriod,
                 allowedHosts: def.allowedHosts,

package/dist/wirings/variable/validate-variable-definitions.js

@@ -24,6 +24,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                     description: def.description,
                     variableId: def.variableId,
                     schema: def.schema,
+                    required: def.required,
                     docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
@@ -38,6 +39,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                 description: def.description,
                 variableId: def.variableId,
                 schema: def.schema,
+                required: def.required,
                 docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };

package/dist/wirings/variable/variable.types.d.ts

@@ -4,6 +4,14 @@ export type CoreVariable<T = unknown> = {
     description?: string;
     variableId: string;
     schema: T;
+    /**
+     * A variable is OPTIONAL by default because `variables.get` returns
+     * `T | undefined` and never throws — every caller already handles absence, so
+     * a deploy gate that blocks on one contradicts the API. Mark a variable
+     * `required` for the few whose absence genuinely breaks the app; only those
+     * block a deploy.
+     */
+    required?: boolean;
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -12,6 +20,7 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
+    required?: boolean;
     docsUrl?: string;
     sourceFile?: string;
 };

package/dist/wirings/virtual-user/index.d.ts

@@ -24,6 +24,6 @@ export type { VirtualUserRunOutcome, VirtualUserRunRecord, VirtualUserRunStart,
 export { DISPOSITIONS, dispositionProfile, type DispositionProfile, type VirtualUserTuning, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
 export { type AgentReachability, type ReachableAgent, } from './virtual-user-agents.js';
-export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
+export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, type SchemaMap, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, type PersonaTargetOptions, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/index.js

@@ -3,6 +3,6 @@ export { runVirtualUser, } from './run-virtual-user.js';
 export { personaScopes, prepareVirtualUserRun, } from './prepare-virtual-user-run.js';
 export { DISPOSITIONS, dispositionProfile, } from './virtual-user-dispositions.js';
 export { catalogueClassification, catalogueLookup, isReadOnly, reachableCatalogue, unreachableCatalogue, } from './virtual-user-catalogue.js';
-export { IntentStack, intentsForPersona, } from './virtual-user-intents.js';
+export { IntentStack, intentsForPersona } from './virtual-user-intents.js';
 export { deriveCatalogue, deriveIntents, } from './virtual-user-derive.js';
 export { personaVirtualUserTarget, } from './virtual-user-target.js';

package/dist/wirings/virtual-user/prepare-virtual-user-run.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '../../types/core.types.js';
+import type { FunctionsMeta } from '../../function/function-meta.types.js';
 import type { WorkflowsMeta } from '../workflow/workflow.types.js';
 import type { SystemRoleDefinitions, SystemRoleDefinitionsMeta } from '../role/role.types.js';
 import { type SchemaMap } from './virtual-user-derive.js';

package/dist/wirings/virtual-user/prepare-virtual-user-run.js

@@ -42,7 +42,7 @@ export const prepareVirtualUserRun = (input) => {
     }
     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
+    // than declared: `CoreAgent.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 };

package/dist/wirings/virtual-user/virtual-user-agents.d.ts

@@ -2,7 +2,7 @@
  * Which of the product's agents a persona can actually talk to.
  *
  * An agent is not something a persona declares. It is something a persona
- * *reaches*, under exactly the rule an RPC is reached by: `CoreAIAgent.scopes`
+ * *reaches*, under exactly the rule an RPC is reached by: `CoreAgent.scopes`
  * is checked against the session, so a persona holding the scopes an agent
  * requires finds it in front of them, and one that does not, does not.
  *

package/dist/wirings/virtual-user/virtual-user-derive.d.ts

@@ -1,4 +1,4 @@
-import type { FunctionsMeta } from '../../types/core.types.js';
+import type { FunctionsMeta } from '../../function/function-meta.types.js';
 import type { WorkflowsMeta } from '../workflow/workflow.types.js';
 import type { ApiCatalogueEntry, IntentSource } from './virtual-user.types.js';
 /** A generated JSON schema, keyed by the name the function meta refers to. */

package/dist/wirings/workflow/graph/graph-node.d.ts

@@ -1,4 +1,4 @@
-import type { GraphNodeConfig, NextConfig, RefValue } from './workflow-graph.types.js';
+import type { ForEachConfig, ForEachMode, GraphNodeConfig, ItemFn, NextConfig, RefValue, TemplateFn } from './workflow-graph.types.js';
 export interface RPCHandler<I = any, O = any> {
     input: I;
     output: O;
@@ -19,7 +19,14 @@ export declare function createGraph<RPCMap extends Record<string, RPCHandler>>()
 type GraphNodeConfigMap<FuncMap extends Record<string, string>, RPCMap extends Record<string, RPCHandler>> = {
     [K in Extract<keyof FuncMap, string>]?: {
         next?: NextConfig<Extract<keyof FuncMap, string>>;
-        input?: (ref: <N extends Extract<keyof FuncMap, string>, P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string>(nodeId: N, path: P) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>;
+        /**
+         * Run this node once per element of an upstream array. The node's own
+         * result becomes the ordered array of per-item results.
+         */
+        forEach?: ForEachConfig<Extract<keyof FuncMap, string>>;
+        /** How the per-item instances run. Defaults to 'parallel'. */
+        mode?: ForEachMode;
+        input?: (ref: <N extends Extract<keyof FuncMap, string>, P extends keyof ComputeNodeOutputs<FuncMap, RPCMap>[N] & string>(nodeId: N, path: P) => TypedRef<ComputeNodeOutputs<FuncMap, RPCMap>[N][P]>, template: TemplateFn, $item: ItemFn) => InputWithRefs<ComputeNodeInputs<FuncMap, RPCMap>[K]>;
         onError?: Extract<keyof FuncMap, string> | Extract<keyof FuncMap, string>[];
         retries?: number;
         retryDelay?: string | number;

package/dist/wirings/workflow/graph/graph-node.js

@@ -16,6 +16,8 @@ export function createGraph() {
         for (const [nodeId, def] of Object.entries(nodes)) {
             result[nodeId] = {
                 func: funcMap[nodeId],
+                forEach: def?.forEach,
+                mode: def?.mode,
                 input: def?.input,
                 next: def?.next,
                 onError: def?.onError,

package/dist/wirings/workflow/graph/graph-runner.d.ts

@@ -7,6 +7,7 @@ export declare class ChildWorkflowStartedException extends Error {
     name: string;
     constructor(parentRunId: string, stepId: string, childRunId: string);
 }
+export declare function stripInstanceOrdinal(name: string): string;
 export declare function continueGraph(workflowService: PikkuWorkflowService, runId: string, graphName: string, overrideMeta?: WorkflowRuntimeMeta): Promise<void>;
 export declare function executeGraphStep(workflowService: PikkuWorkflowService, rpcService: any, runId: string, stepId: string, nodeId: string, rpcName: string, data: any, graphName: string): Promise<any>;
 export declare function runFromMeta(workflowService: PikkuWorkflowService, runId: string, meta: WorkflowRuntimeMeta, _rpcService: any): Promise<void>;