@pikku/core 0.12.83 → 0.12.86

package/dist/types/core.types.d.ts

@@ -4,7 +4,7 @@ import type { SecretService } from '../services/secret-service.js';
 import type { SchemaService } from '../services/schema-service.js';
 import type { JWTService } from '../services/jwt-service.js';
 import type { PikkuHTTP } from '../wirings/http/http.types.js';
-import type { PikkuChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory } from '../wirings/channel/channel.types.js';
+import type { PikkuChannel } from '../wirings/channel/channel.types.js';
 import type { EventHubService } from '../wirings/channel/eventhub-service.js';
 import type { PikkuRPC } from '../wirings/rpc/rpc-types.js';
 import type { PikkuMCP } from '../wirings/mcp/mcp.types.js';
@@ -13,21 +13,22 @@ import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js';
 import type { PikkuCLI } from '../wirings/cli/cli.types.js';
 import type { PikkuWorkflowWire, WorkflowService, WorkflowServiceConfig, WorkflowStepWire } from '../wirings/workflow/workflow.types.js';
 import type { PikkuScenarioWire } from '../wirings/workflow/scenario.types.js';
-import type { PikkuBrowserWire, PikkuScenarioStepWire, ScenarioStepKind, ScenarioSurface } from '../wirings/workflow/scenario-step.types.js';
+import type { PikkuBrowserWire, PikkuScenarioStepWire } from '../wirings/workflow/scenario-step.types.js';
 import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js';
 import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js';
 import type { PikkuGateway } from '../wirings/gateway/gateway.types.js';
 import type { SchedulerService } from '../services/scheduler-service.js';
 import type { DeploymentService } from '../services/deployment-service.js';
-import type { AIStorageService } from '../services/ai-storage-service.js';
+import type { AgentStorageService } from '../services/agent-storage-service.js';
 import type { ContentService } from '../services/content-service.js';
 import type { ScenarioPersonaOf, ScenarioPersonas } from '../services/personas-service.js';
-import type { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
+import type { AgentRunnerService } from '../services/agent-runner-service.js';
 import type { AIEmbeddingService } from '../services/ai-embedding-service.js';
-import type { AIRunStateService } from '../services/ai-run-state-service.js';
-import type { AgentRunService } from '../wirings/ai-agent/ai-agent.types.js';
+import type { AgentRunStateService } from '../services/agent-run-state-service.js';
+import type { AgentRunService } from '../wirings/agent/agent.types.js';
+import type { MiddlewareMetadata } from '../middleware/middleware.types.js';
+import type { PermissionMetadata } from '../function/function-meta.types.js';
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js';
-import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js';
 import type { CredentialService } from '../services/credential-service.js';
 import type { EmailService } from '../services/email-service.js';
@@ -38,152 +39,6 @@ import type { SessionStore } from '../services/session-store.js';
 import type { ScopeService } from '../services/scope-service.js';
 import type { AuditDurability, AuditLog, AuditService } from '../services/audit-service.js';
 export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent' | 'gateway';
-export interface FunctionServicesMeta {
-    optimized: boolean;
-    services: string[];
-}
-export interface FunctionWiresMeta {
-    optimized: boolean;
-    wires: string[];
-}
-export type MiddlewareMetadata = {
-    type: 'http';
-    route: string;
-} | {
-    type: 'tag';
-    tag: string;
-} | {
-    type: 'wire';
-    name: string;
-    inline?: boolean;
-};
-/**
- * A reference to a permission function, resolved by name. Function-scoped
- * only: there are no wire- or tag-level permission references.
- */
-export type PermissionMetadata = {
-    type: 'wire';
-    name: string;
-    inline?: boolean;
-};
-export type FunctionRuntimeMeta = {
-    pikkuFuncId: string;
-    inputSchemaName: string | null;
-    outputSchemaName: string | null;
-    /** Scopes the session must hold to run this function. All are required (AND). */
-    scopes?: string[];
-    expose?: boolean;
-    /**
-     * A sessionless function's own `auth: true`. `sessionless` carries the
-     * baseline — a `pikkuFunc` always requires a session — and this carries the
-     * tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to
-     * know whether a function is gated without running it.
-     */
-    auth?: boolean;
-    /**
-     * The author's declaration that this function's permission check lives in its
-     * own body. Carries no runtime effect — it records a gate codegen cannot see,
-     * so an audit is not left to guess whether a sessionless function is open.
-     * Refused unless `allow.permissionsInBody` is set in `pikku.config.json`.
-     */
-    permissionsInBody?: boolean;
-    remote?: boolean;
-    /**
-     * A step RPC: invoked by name only from a scenario run and refused
-     * everywhere else, so it is never network-callable.
-     */
-    scenarioStep?: boolean;
-    /**
-     * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
-     * so it is held back from the app bootstrap and from every deployed unit.
-     */
-    scenario?: boolean;
-    mcp?: boolean;
-    readonly?: boolean;
-    deploy?: 'serverless' | 'server' | 'auto';
-    sessionless?: boolean;
-    /** When true, workflow steps calling this function are dispatched via the queue. No queue service configured is a hard error. */
-    workflowQueued?: boolean;
-    /** Retry count when this function is used as a workflow step. */
-    workflowRetries?: number;
-    /** Timeout when this function is used as a workflow step (e.g. '30s', '5m'). */
-    workflowTimeout?: string;
-    /**
-     * Scenario steps only: which surfaces this step declares a binding for.
-     *
-     * The reporter derives coverage from this — a `then` with no binding for the
-     * surface the run targeted was never actually witnessed there, which is a gap
-     * worth counting rather than excusing.
-     */
-    scenarioStepSurfaces?: ScenarioSurface[];
-    /**
-     * Scenario steps only: who acts. Absent means `persona` — the ordinary step,
-     * and the only kind that existed before the other two.
-     *
-     * A `platform` or `addon` step is the app or a third-party system acting, and
-     * it must never reach a virtual user's catalogue. That is not tidiness: a
-     * virtual user that can invoke "Stripe's webhook arrives" can forge its own
-     * payment success, and every finding downstream of that is worthless.
-     */
-    scenarioStepKind?: ScenarioStepKind;
-    /** Addon steps only: the addon whose system acts — `wireAddon`'s `name`. */
-    scenarioStepAddon?: string;
-    /** Scenario steps only: the prose a reporter renders, with `{placeholders}` filled from the step's recorded input. */
-    scenarioStepTemplate?: string;
-    /**
-     * The function's `audit` config, resolved — `audit: true` reads as
-     * `{ durability: 'best-effort' }`. Absent means the function records nothing:
-     * `auditLog.write()` from an unmarked function is dropped with a warning, so
-     * this is the only place a reader can see which functions have a trail at all
-     * without running them.
-     *
-     * Informational. The runner resolves audit from the live function config, not
-     * from here, so meta and runtime cannot disagree about whether audit is on.
-     */
-    audit?: {
-        durability: AuditDurability;
-    };
-    version?: number;
-    approvalRequired?: boolean;
-    approvalDescription?: string;
-    implementationHash?: string;
-    contractHash?: string;
-    inputHash?: string;
-    outputHash?: string;
-};
-export type FunctionMeta = FunctionRuntimeMeta & Partial<{
-    name: string;
-    /** `remote`: a contract with no local body, answered by a connected client. */
-    functionType: 'user' | 'inline' | 'helper' | 'remote';
-    funcWrapper: string;
-    services: FunctionServicesMeta;
-    wires: FunctionWiresMeta;
-    inputs: string[] | null;
-    outputs: string[] | null;
-    middleware: MiddlewareMetadata[];
-    permissions: PermissionMetadata[];
-    isDirectFunction: boolean;
-    sourceFile: string;
-    exportedName: string;
-    /** File containing the handler body when it differs from sourceFile (imported handlers) */
-    bodySourceFile?: string;
-    /** 1-indexed first line of the handler body (verbose meta; coverage mapping) */
-    bodyStart: number;
-    /** 1-indexed last line of the handler body (verbose meta; coverage mapping) */
-    bodyEnd: number;
-} & CommonWireMeta>;
-export type FunctionsRuntimeMeta = Record<string, FunctionRuntimeMeta>;
-export type FunctionsMeta = Record<string, FunctionMeta>;
-export type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-export type JSONPrimitive = string | number | boolean | null | undefined;
-export type JSONValue = JSONPrimitive | JSONValue[] | {
-    [key: string]: JSONValue;
-};
-export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
-export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>;
-export type RequireAtLeastOne<T> = {
-    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
-}[keyof T];
 /**
  * Runtime pool tuning for the Postgres adapter. The connection string stays
  * the flat `postgresUrl` config field — the contract the CLI's db commands read.
@@ -259,11 +114,11 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     eventHub?: EventHubService<Record<string, any>>;
     schedulerService?: SchedulerService;
     deploymentService?: DeploymentService;
-    aiStorage?: AIStorageService;
+    agentStorage?: AgentStorageService;
     content?: ContentService;
-    aiAgentRunner?: AIAgentRunnerService;
+    agentRunner?: AgentRunnerService;
     aiEmbedding?: AIEmbeddingService;
-    aiRunState?: AIRunStateService;
+    agentRunState?: AgentRunStateService;
     agentRunService?: AgentRunService;
     workflowRunService?: WorkflowRunService;
     credentialService?: CredentialService;
@@ -303,7 +158,20 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      */
     auth?: () => Promise<AuthInstance>;
 }
-export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
+/**
+ * Reads a single credential. The first signature resolves the value type from
+ * the project's generated `CredentialsMap`; the second keeps a name the map
+ * does not know callable with an explicit type.
+ *
+ * `TCredentials` is unconstrained because the generated map is an interface,
+ * which has no implicit index signature and so cannot satisfy
+ * `Record<string, unknown>`.
+ */
+export type GetCredential<TCredentials = Record<string, unknown>> = {
+    <K extends keyof TCredentials & string>(name: K): TCredentials[K] | null | Promise<TCredentials[K] | null>;
+    <T = unknown>(name: string): T | null | Promise<T | null>;
+};
+export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boolean = false, UserSession extends CoreUserSession = CoreUserSession, TypedRPC extends PikkuRPC = PikkuRPC, IsChannel extends true | null = null, MCPTools extends string | never = never, TypedWorkflow extends PikkuWorkflowWire | never = PikkuWorkflowWire, TriggerOutput = unknown, TypedScenario extends PikkuScenarioWire<any> | never = PikkuScenarioWire<any>, TypedActors extends ScenarioPersonas = ScenarioPersonas, TypedCredentials = Record<string, unknown>> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
 } & Partial<{
@@ -327,8 +195,18 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     workflow: TypedWorkflow;
     scenario: TypedScenario;
     actors: TypedActors;
+    /**
+     * The persona this step runs as, injected by the runner.
+     *
+     * Required on a `browser` binding, which cannot be provisioned without one,
+     * and on any binding whose step declares `actor: true`. A step that declares
+     * neither has no `actor` on its wire at all rather than an optional one —
+     * a pure assertion has nobody to be, and `attemptsSignIn` deliberately posts
+     * credentials instead of reusing an actor's session.
+     */
+    actor: ScenarioPersonaOf<TypedActors>;
     /** Present on every scenario step invocation */
-    scenarioStep: PikkuScenarioStepWire<ScenarioPersonaOf<TypedActors>>;
+    scenarioStep: PikkuScenarioStepWire;
     /** Present only when the runner provisioned a browser for this step */
     browser: PikkuBrowserWire;
     workflowStep: WorkflowStepWire;
@@ -345,7 +223,7 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     /** Set a credential value (available in middleware) */
     setCredential: (name: string, value: unknown) => void;
     /** Get a single credential by name — lazy-loads from CredentialService on first call, sync thereafter */
-    getCredential: <T = unknown>(name: string) => T | null | Promise<T | null>;
+    getCredential: GetCredential<TypedCredentials>;
     /** Get all resolved credentials — lazy-loads from CredentialService on first call, sync thereafter */
     getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
     audit: {
@@ -368,27 +246,6 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
 }>;
 /** Wire as constructed by runners, before the function runner lazily adds `rpc`. */
 export type PikkuRawWire = Omit<PikkuWire, 'rpc'>;
-export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wires: PikkuWire, next: () => Promise<void>) => Promise<void>;
-/**
- * Execution order: `highest` runs first (outermost in the onion), `lowest`
- * runs last, closest to the function.
- */
-export type MiddlewarePriority = 'highest' | 'high' | 'medium' | 'low' | 'lowest';
-export type CorePikkuMiddlewareConfig<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = {
-    func: CorePikkuMiddleware<SingletonServices, UserSession>;
-    name?: string;
-    description?: string;
-    /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
-    priority?: MiddlewarePriority;
-};
-export type CorePikkuMiddlewareFactory<In = any, SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (input: In) => CorePikkuMiddleware<SingletonServices, UserSession>;
-export type CorePikkuMiddlewareGroup<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = Array<CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareFactory<any, SingletonServices, UserSession>>;
-export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession>(middleware: CorePikkuMiddleware<SingletonServices, UserSession> | CorePikkuMiddlewareConfig<SingletonServices, UserSession>) => CorePikkuMiddleware<SingletonServices, UserSession>;
-export declare const pikkuMiddlewareFactory: <In = any>(factory: CorePikkuMiddlewareFactory<In>) => CorePikkuMiddlewareFactory<In>;
-export declare const pikkuChannelMiddleware: <SingletonServices extends CoreSingletonServices = CoreSingletonServices, Event = unknown>(middleware: CorePikkuChannelMiddleware<SingletonServices, Event>) => CorePikkuChannelMiddleware<SingletonServices, Event>;
-export declare const pikkuChannelMiddlewareFactory: <In = any>(factory: CorePikkuChannelMiddlewareFactory<In>) => CorePikkuChannelMiddlewareFactory<In>;
-export type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
-export declare const pikkuAIMiddleware: <State extends Record<string, unknown> = Record<string, unknown>, SingletonServices extends CoreSingletonServices = CoreSingletonServices>(hooks: PikkuAIMiddlewareHooks<State, SingletonServices>) => PikkuAIMiddlewareHooks<State, SingletonServices>;
 export type CoreServices<SingletonServices = CoreSingletonServices> = SingletonServices;
 /** Strips `secrets` from a services type. */
 export type SecretlessServices<Services> = Omit<Services, 'secrets'>;
@@ -458,13 +315,6 @@ export interface SecurityAuditReport {
     updates: SecurityAuditUpdate[];
     summary: SecurityAuditSummary;
 }
-export interface SerializedError {
-    message: string;
-    stack?: string;
-    code?: string;
-    expected?: boolean;
-    [key: string]: any;
-}
 /**
  * A generated schema's declaration site, used by the credential/secret/variable
  * definition validators to point conflicting definitions at their source.

package/dist/types/core.types.js

@@ -1,19 +1 @@
-export const pikkuMiddleware = (middleware) => {
-    if (typeof middleware === 'function')
-        return middleware;
-    const func = middleware.func;
-    if (middleware.priority) {
-        func.__priority = middleware.priority;
-    }
-    return func;
-};
-export const pikkuMiddlewareFactory = (factory) => {
-    return factory;
-};
-export const pikkuChannelMiddleware = (middleware) => {
-    return middleware;
-};
-export const pikkuChannelMiddlewareFactory = (factory) => {
-    return factory;
-};
-export const pikkuAIMiddleware = (hooks) => hooks;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './core.types.js';
+export type * from './state.types.js';

package/dist/types/index.js

@@ -0,0 +1 @@
+export * from './core.types.js';

package/dist/types/state.types.d.ts

@@ -5,15 +5,17 @@ import type { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types
 import type { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js';
 import type { HTTPMethod, CoreHTTPFunctionWiring, HTTPWiringsMeta } from '../wirings/http/http.types.js';
 import type { CoreMCPResource, MCPResourceMeta, MCPToolMeta, CoreMCPPrompt, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
-import type { CoreAIAgent, AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js';
-import type { PikkuAIScorer, ScorerMeta } from '../wirings/ai-scorer/ai-scorer.types.js';
+import type { CoreAgent, AgentsMeta } from '../wirings/agent/agent.types.js';
+import type { PikkuAgentScorer, ScorerMeta } from '../wirings/agent-scorer/agent-scorer.types.js';
 import type { CoreGateway, GatewaysMeta } from '../wirings/gateway/gateway.types.js';
 import type { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CoreScheduledTask, ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js';
 import type { CoreWorkflow, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
 import type { CoreFeature } from '../wirings/workflow/scenario.types.js';
 import type { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
-import type { FunctionsMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
+import type { CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
+import type { FunctionsMeta } from '../function/function-meta.types.js';
+import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup } from '../middleware/middleware.types.js';
 import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
 export interface PikkuPackageState {
     function: {
@@ -105,9 +107,9 @@ export interface PikkuPackageState {
         promptsMeta: MCPPromptMeta;
     };
     agent: {
-        agents: Map<string, CoreAIAgent>;
-        agentsMeta: AIAgentMeta;
-        scorers: Map<string, PikkuAIScorer>;
+        agents: Map<string, CoreAgent>;
+        agentsMeta: AgentsMeta;
+        scorers: Map<string, PikkuAgentScorer>;
         scorersMeta: ScorerMeta;
         /** Alias -> `provider/model`, from the `models` table in pikku.config.json. */
         modelAliases: Record<string, string>;

package/dist/utils.d.ts

@@ -9,3 +9,16 @@ export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) =>
 export declare const stopSingletonServices: () => Promise<void>;
 /** Wrap server lifecycle hooks so the inspector can discover them. */
 export declare const pikkuServerLifecycle: <SS extends CoreSingletonServices = CoreSingletonServices>(lifecycle: ServerLifecycle<SS>) => ServerLifecycle<SS>;
+export type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+export type JSONPrimitive = string | number | boolean | null | undefined;
+export type JSONValue = JSONPrimitive | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export type PickRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type PickOptional<T, K extends keyof T> = Partial<T> & Pick<T, K>;
+export type RequireAtLeastOne<T> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<keyof T, K>>>;
+}[keyof T];
+export { getDurationInMilliseconds, getRelativeTimeOffset, getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
+export type { RelativeTimeInput } from './time-utils.js';
+export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';

package/dist/utils.js

@@ -98,3 +98,5 @@ export const stopSingletonServices = async () => {
 };
 /** Wrap server lifecycle hooks so the inspector can discover them. */
 export const pikkuServerLifecycle = (lifecycle) => lifecycle;
+export { getDurationInMilliseconds, getRelativeTimeOffset, getRelativeTimeOffsetFromNow, parseDurationString, } from './time-utils.js';
+export { formatVersionedId, isVersionedId, parseVersionedId, } from './version.js';

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

@@ -1,8 +1,8 @@
 import type { ActorFlowApprovalPolicy, ActorFlowVerdict, TargetAgentDriver } from './actor-flow.types.js';
 import type { ResolvedPersona } from '../../services/personas-service.js';
-import type { AIAgentRunnerParams, AIAgentStepResult } from '../../services/ai-agent-runner-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: AIAgentRunnerParams) => Promise<AIAgentStepResult>;
+export type ActorLLM = (params: AgentRunnerParams) => Promise<AgentStepResult>;
 export interface RunConversationParams {
     /** The person being played — name, job title, personality. */
     persona: ResolvedPersona;

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

@@ -0,0 +1,17 @@
+import type { CoreSingletonServices } from '../../types/core.types.js';
+export type AddonInstance = {
+    namespace: string;
+    secretOverrides?: Record<string, string>;
+    variableOverrides?: Record<string, string>;
+    credentialOverrides?: Record<string, string>;
+    /** Set by the consuming app: secrets it lends this instance, as the addon names them. */
+    secretGrants?: string[];
+    /** Set by the consuming app: credentials it lends this instance, as the addon names them. */
+    credentialGrants?: string[];
+    /** Set by the consuming app to opt this instance out of secret scoping. */
+    globalSecrets?: string;
+    /** Set by the consuming app to opt this instance out of credential scoping. */
+    globalCredentials?: string;
+};
+export declare const getOrCreatePackageSingletonServices: (packageName: string, parentServices: CoreSingletonServices, addonInstance?: AddonInstance) => Promise<CoreSingletonServices>;
+export declare const addonInstanceForNamespace: (namespace: string | undefined, expectedPackage: string) => AddonInstance | undefined;

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

@@ -0,0 +1,150 @@
+import { pikkuState } from '../../pikku-state.js';
+import { ScopedSecretService } from '../../services/scoped-secret-service.js';
+import { ScopedCredentialService } from '../../services/scoped-credential-service.js';
+/**
+ * What the addon declared, plus what the host lent it. Scoping runs outside the
+ * aliaser, so every name here is the one the addon reads — which is why an
+ * override's *key* grants, and its value does not.
+ */
+const allowedNames = (declared, grants, overrides) => new Set([
+    ...(declared ?? []),
+    ...(grants ?? []),
+    ...Object.keys(overrides ?? {}),
+]);
+const aliasSecretService = (secrets, overrides) => {
+    const map = (key) => overrides[key] ?? key;
+    return {
+        getSecret: (key) => secrets.getSecret(map(key)),
+        hasSecret: (key) => secrets.hasSecret(map(key)),
+        setSecret: (key, value) => secrets.setSecret(map(key), value),
+        deleteSecret: (key) => secrets.deleteSecret(map(key)),
+        getSecrets: async (keys) => {
+            const result = await secrets.getSecrets(keys.map(map));
+            const out = {};
+            for (const logical of keys) {
+                const real = map(logical);
+                if (real in result)
+                    out[logical] = result[real];
+            }
+            return out;
+        },
+    };
+};
+const aliasVariablesService = (variables, overrides) => {
+    const map = (name) => overrides[name] ?? name;
+    return {
+        get: (name) => variables.get(map(name)),
+        getVariables: (names) => {
+            const result = variables.getVariables(names.map(map));
+            const remap = (r) => {
+                const out = {};
+                for (const logical of names) {
+                    const real = map(logical);
+                    if (real in r)
+                        out[logical] = r[real];
+                }
+                return out;
+            };
+            return result instanceof Promise
+                ? result.then(remap)
+                : remap(result);
+        },
+        getAll: () => variables.getAll(),
+        set: (name, value) => variables.set(map(name), value),
+        has: (name) => variables.has(map(name)),
+        delete: (name) => variables.delete(map(name)),
+    };
+};
+const findAddonNamespaceForPackage = (packageName) => {
+    const addons = pikkuState(null, 'addons', 'packages');
+    if (!addons)
+        return null;
+    for (const [namespace, cfg] of addons.entries()) {
+        if (cfg?.package === packageName)
+            return namespace;
+    }
+    return null;
+};
+const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
+    return new Proxy(service, {
+        get(target, prop, receiver) {
+            if (prop === 'startWorkflow' || prop === 'runToCompletion') {
+                const original = Reflect.get(target, prop, receiver);
+                return function (name, ...rest) {
+                    if (typeof name === 'string' && !name.includes(':')) {
+                        const ns = namespace ?? findAddonNamespaceForPackage(packageName);
+                        if (ns) {
+                            name = `${ns}:${name}`;
+                        }
+                    }
+                    return original.call(this, name, ...rest);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+};
+export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
+    const cacheKey = addonInstance?.namespace ?? packageName;
+    const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices');
+    if (cachedServices) {
+        return cachedServices;
+    }
+    const factories = pikkuState(packageName, 'package', 'factories');
+    let existingServices = parentServices;
+    if (addonInstance?.secretOverrides && parentServices.secrets) {
+        existingServices = {
+            ...existingServices,
+            secrets: aliasSecretService(parentServices.secrets, addonInstance.secretOverrides),
+        };
+    }
+    if (addonInstance?.variableOverrides && parentServices.variables) {
+        existingServices = {
+            ...existingServices,
+            variables: aliasVariablesService(parentServices.variables, addonInstance.variableOverrides),
+        };
+    }
+    if (!addonInstance?.globalSecrets && existingServices.secrets) {
+        existingServices = {
+            ...existingServices,
+            secrets: new ScopedSecretService(existingServices.secrets, allowedNames(pikkuState(packageName, 'package', 'declaredSecrets'), addonInstance?.secretGrants, addonInstance?.secretOverrides)),
+        };
+    }
+    if (!addonInstance?.globalCredentials && existingServices.credentialService) {
+        existingServices = {
+            ...existingServices,
+            credentialService: new ScopedCredentialService(existingServices.credentialService, allowedNames(Object.keys(pikkuState(packageName, 'package', 'credentialsMeta') ?? {}), addonInstance?.credentialGrants, addonInstance?.credentialOverrides)),
+        };
+    }
+    if (!factories || !factories.createSingletonServices) {
+        return existingServices;
+    }
+    let config = existingServices.config;
+    if (factories.createConfig) {
+        config = await factories.createConfig(existingServices.variables);
+    }
+    const packageServices = await factories.createSingletonServices(config, existingServices);
+    if (packageServices.workflowService &&
+        typeof packageServices.workflowService === 'object') {
+        packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName, addonInstance?.namespace ?? null);
+    }
+    pikkuState(cacheKey, 'package', 'singletonServices', packageServices);
+    return packageServices;
+};
+export const addonInstanceForNamespace = (namespace, expectedPackage) => {
+    if (!namespace)
+        return undefined;
+    const cfg = pikkuState(null, 'addons', 'packages').get(namespace);
+    if (!cfg || cfg.package !== expectedPackage)
+        return undefined;
+    return {
+        namespace,
+        secretOverrides: cfg.secretOverrides,
+        variableOverrides: cfg.variableOverrides,
+        credentialOverrides: cfg.credentialOverrides,
+        secretGrants: cfg.secretGrants,
+        credentialGrants: cfg.credentialGrants,
+        globalSecrets: cfg.globalSecrets,
+        globalCredentials: cfg.globalCredentials,
+    };
+};

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

@@ -0,0 +1,6 @@
+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';
+export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';
+export type { RemoteAddonAuthBinding } from './remote-addon-auth.js';

package/dist/wirings/addon/index.js

@@ -0,0 +1,3 @@
+export { wireAddon } from './wire-addon.js';
+export { wireRemoteAddon } from './wire-remote-addon.js';
+export { resolveRemoteAddonToken, RemoteAddonAuthError, } from './remote-addon-auth.js';

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

@@ -0,0 +1,16 @@
+import type { CoreServices, PikkuRawWire } from '../../types/core.types.js';
+import { PikkuError } from '../../errors/error-handler.js';
+import { type SecretValue } from '../../classification/secret-value.js';
+export type RemoteAddonAuthBinding = {
+    credentialId: string;
+} | {
+    secretId: string;
+} | {
+    resolve: (services: CoreServices, wire: PikkuRawWire) => string | SecretValue<string> | Promise<string | SecretValue<string>>;
+};
+export declare class RemoteAddonAuthError extends PikkuError {
+    readonly namespace: string;
+    constructor(namespace: string, detail: string);
+}
+/** Returns `null` only when no auth is bound; an empty resolved token throws. */
+export declare function resolveRemoteAddonToken(auth: RemoteAddonAuthBinding | undefined, services: CoreServices, wire: PikkuRawWire, namespace: string): Promise<string | null>;

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

@@ -0,0 +1,39 @@
+import { PikkuError, addError } from '../../errors/error-handler.js';
+import { isSecretValue, } from '../../classification/secret-value.js';
+export class RemoteAddonAuthError extends PikkuError {
+    namespace;
+    constructor(namespace, detail) {
+        super(`Remote addon '${namespace}' auth could not be resolved: ${detail}`);
+        this.namespace = namespace;
+    }
+}
+addError(RemoteAddonAuthError, {
+    status: 401,
+    message: 'Remote addon authentication could not be resolved.',
+});
+/** Returns `null` only when no auth is bound; an empty resolved token throws. */
+export async function resolveRemoteAddonToken(auth, services, wire, namespace) {
+    if (!auth) {
+        return null;
+    }
+    let token;
+    if ('credentialId' in auth) {
+        if (typeof wire.getCredential !== 'function') {
+            throw new RemoteAddonAuthError(namespace, `credentialId '${auth.credentialId}' requires a wire with credential access`);
+        }
+        token = await wire.getCredential(auth.credentialId);
+    }
+    else if ('secretId' in auth) {
+        token = await services.secrets.getSecret(auth.secretId);
+    }
+    else if (typeof auth.resolve === 'function') {
+        token = await auth.resolve(services, wire);
+    }
+    // The wire is where a secret is meant to end up, so unwrap it here rather
+    // than at each branch — `resolve` and `getCredential` may hand one back too.
+    const resolved = isSecretValue(token) ? token.reveal() : token;
+    if (resolved === null || resolved === undefined || resolved === '') {
+        throw new RemoteAddonAuthError(namespace, 'resolved token was empty');
+    }
+    return String(resolved);
+}