@pikku/core 0.12.22 → 0.12.24

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 0.12.24
+
+### Patch Changes
+
+- c02275f: Add per-request API key override to AI agent runner
+
+  `VercelAIAgentRunner` gains an optional `providerFactory` constructor param and a `withApiKey(apiKey)` method that forks a new runner scoped to a given key without touching the global singleton.
+
+  `RunAIAgentParams` gains an optional `getCredential` accessor so callers can thread per-request credentials (e.g. a user's `AI_API_KEY` from the credential wire service) into `prepareAgentRun`. If a credential is found and the runner supports `withApiKey`, the runner is forked before the agent executes.
+
+  `AIAgentRunnerService` interface gains the optional `withApiKey?` method.
+
+- 0bd0433: Add `db.engine` and `db.pgVersion` to the CLI config types, and make local env-backed secrets fall back to raw strings when JSON parsing fails.
+
+## 0.12.23
+
+### Patch Changes
+
+- 8d09f12: Forward pikkuAgent function name to LiteLLM as request metadata for per-agent usage breakdown.
+
+  Adds an optional `agentId` field to `AIAgentRunnerParams`. The wiring layer (`runAIAgent`, `streamAIAgent`, and the resume path) sets this to the agent's registered function name before invoking the runner. `VercelAIAgentRunner` injects it into `providerOptions` as `metadata.agent_id` so LiteLLM includes it in spend logs, enabling per-agent token and cost breakdowns.
+
 ## 0.12.22
 
 ### Patch Changes

package/dist/function/function-runner.js

@@ -8,6 +8,7 @@ import { PikkuSessionService, createFunctionSessionWireProps, } from '../service
 import { ForbiddenError, ReadonlySessionError } from '../errors/errors.js';
 import { PikkuCredentialWireService, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
+import { resolveAuditConfig } from '../services/audit-service.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { closeWireServices } from '../utils.js';
 async function resolveSession(wire, singletonServices, sessionService) {
@@ -165,6 +166,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     if (!funcMeta) {
         throw new Error(`Function meta not found: ${funcName}`);
     }
+    const resolvedFunctionId = funcMeta.pikkuFuncId ?? funcName;
     // For addon packages, get or create their singleton services
     const resolvedSingletonServices = packageName
         ? await getOrCreatePackageSingletonServices(packageName, singletonServices)
@@ -192,6 +194,13 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             new PikkuCredentialWireService(resolvedSingletonServices.credentialService, resolvedWire);
         Object.assign(resolvedWire, createWireServicesCredentialWireProps(resolvedCredentialWireService));
     }
+    const resolvedAuditConfig = resolveAuditConfig(funcConfig.audit);
+    const invocationWire = resolvedWire;
+    const previousFunctionId = invocationWire.functionId;
+    const previousAudit = invocationWire.audit;
+    const previousRpcDescriptor = Object.getOwnPropertyDescriptor(invocationWire, 'rpc');
+    invocationWire.functionId = resolvedFunctionId;
+    invocationWire.audit = resolvedAuditConfig;
     // Convert tags to PermissionMetadata and merge with inheritedPermissions
     let mergedInheritedPermissions;
     if (tags && tags.length > 0) {
@@ -205,15 +214,15 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     }
     // Helper function to run permissions and execute the function
     const executeFunction = async () => {
-        await resolveSession(resolvedWire, resolvedSingletonServices, sessionService);
+        await resolveSession(invocationWire, resolvedSingletonServices, sessionService);
         if (sessionService) {
-            resolvedWire.session = sessionService.freezeInitial();
-            resolvedWire.setSession = (s) => sessionService.set(s);
-            resolvedWire.clearSession = () => sessionService.clear();
-            resolvedWire.getSession = () => sessionService.get();
-            resolvedWire.hasSessionChanged = () => sessionService.sessionChanged;
+            invocationWire.session = sessionService.freezeInitial();
+            invocationWire.setSession = (s) => sessionService.set(s);
+            invocationWire.clearSession = () => sessionService.clear();
+            invocationWire.getSession = () => sessionService.get();
+            invocationWire.hasSessionChanged = () => sessionService.sessionChanged;
         }
-        const session = resolvedWire.session;
+        const session = invocationWire.session;
         if (funcMeta.sessionless) {
             if (wiringAuth === true || funcConfig.auth === true) {
                 if (!session) {
@@ -263,22 +272,22 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 funcInheritedPermissions: funcMeta.permissions,
                 funcPermissions: funcConfig.permissions,
                 services: resolvedSingletonServices,
-                wire: resolvedWire,
+                wire: invocationWire,
                 data: actualData,
                 packageName,
             });
         }
         let wireServices;
         try {
-            wireServices = (await resolvedCreateWireServices?.(resolvedSingletonServices, resolvedWire));
+            wireServices = (await resolvedCreateWireServices?.(resolvedSingletonServices, invocationWire));
             const services = wireServices && Object.keys(wireServices).length > 0
                 ? { ...resolvedSingletonServices, ...wireServices }
                 : resolvedSingletonServices;
             const callerPackageName = packageName;
-            Object.defineProperty(resolvedWire, 'rpc', {
+            Object.defineProperty(invocationWire, 'rpc', {
                 get() {
-                    const rpc = rpcService.getContextRPCService(services, resolvedWire, { sessionService }, 0, callerPackageName);
-                    Object.defineProperty(resolvedWire, 'rpc', {
+                    const rpc = rpcService.getContextRPCService(services, invocationWire, { sessionService }, 0, callerPackageName);
+                    Object.defineProperty(invocationWire, 'rpc', {
                         value: rpc,
                         writable: true,
                         configurable: true,
@@ -288,7 +297,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 configurable: true,
                 enumerable: true,
             });
-            return await funcConfig.func(services, actualData, resolvedWire);
+            return await funcConfig.func(services, actualData, invocationWire);
         }
         finally {
             if (wireServices && Object.keys(wireServices).length > 0) {
@@ -304,7 +313,45 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         packageName,
     });
     if (allMiddleware.length > 0) {
-        return (await runMiddleware(resolvedSingletonServices, resolvedWire, allMiddleware, executeFunction));
+        try {
+            return (await runMiddleware(resolvedSingletonServices, invocationWire, allMiddleware, executeFunction));
+        }
+        finally {
+            if (previousRpcDescriptor) {
+                Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor);
+            }
+            if (previousFunctionId === undefined) {
+                delete invocationWire.functionId;
+            }
+            else {
+                invocationWire.functionId = previousFunctionId;
+            }
+            if (previousAudit === undefined) {
+                delete invocationWire.audit;
+            }
+            else {
+                invocationWire.audit = previousAudit;
+            }
+        }
+    }
+    try {
+        return (await executeFunction());
+    }
+    finally {
+        if (previousRpcDescriptor) {
+            Object.defineProperty(invocationWire, 'rpc', previousRpcDescriptor);
+        }
+        if (previousFunctionId === undefined) {
+            delete invocationWire.functionId;
+        }
+        else {
+            invocationWire.functionId = previousFunctionId;
+        }
+        if (previousAudit === undefined) {
+            delete invocationWire.audit;
+        }
+        else {
+            invocationWire.audit = previousAudit;
+        }
     }
-    return (await executeFunction());
 };

package/dist/function/functions.types.d.ts

@@ -15,7 +15,7 @@ export type ZodLike<T = any> = StandardSchemaV1<T, T>;
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Wire - The wire type, defaults to `PikkuWire<In, Out>`.
  */
-export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
+export type CorePikkuFunction<In, Out, Services extends CoreSingletonServices = CoreServices, Session extends CoreUserSession = CoreUserSession, Wire extends PikkuWire<In, Out, true, Session> = PikkuWire<In, Out, true, Session>> = (services: Services, data: In, wire: Wire) => Wire['channel'] extends null ? Promise<Out> : Promise<Out> | Promise<void>;
 /**
  * Represents a core API function that can be used without a session.
  *
@@ -32,7 +32,7 @@ export type CorePikkuFunctionSessionless<In, Out, Services extends CoreSingleton
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CorePikkuPermission<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, CoreUserSession, any, never, never> = PikkuWire<In, never, false, CoreUserSession, never, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
+export type CorePikkuPermission<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, any, any, never, never> = PikkuWire<In, never, false, any, never, never, never>> = (services: Services, data: In, wire: Wire) => Promise<boolean>;
 /**
  * Configuration object for creating a permission with metadata
  *
@@ -40,7 +40,7 @@ export type CorePikkuPermission<In = any, Services extends CoreSingletonServices
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<In, never, false, CoreUserSession>> = {
+export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, any> = PikkuWire<In, never, false, any>> = {
     /** The permission function */
     func: CorePikkuPermission<In, Services, Wire>;
     /** Optional human-readable name for the permission */
@@ -73,7 +73,7 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSingletonSe
  * })
  * ```
  */
-export declare const pikkuPermission: <In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PickRequired<PikkuWire<In, never, false, CoreUserSession>, "session"> = PickRequired<PikkuWire<In, never, false, CoreUserSession>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
+export declare const pikkuPermission: <In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PickRequired<PikkuWire<In, never, false, any>, "session"> = PickRequired<PikkuWire<In, never, false, any>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
 /**
  * A factory function that takes input and returns a permission
  * Used when permissions need configuration/input parameters
@@ -82,7 +82,7 @@ export declare const pikkuPermission: <In = any, Services extends CoreSingletonS
  * @template Services - The services type, defaults to `CoreServices`.
  * @template Session - The session type, defaults to `CoreUserSession`.
  */
-export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, CoreUserSession> = PikkuWire<In, never, false, CoreUserSession>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
+export type CorePikkuPermissionFactory<In = any, Services extends CoreSingletonServices = CoreServices, Wire extends PikkuWire<In, never, false, any> = PikkuWire<In, never, false, any>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
 /**
  * Factory function for creating permission factories
  * Use this when your permission needs configuration/input parameters
@@ -149,6 +149,9 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     readonly?: boolean;
     deploy?: 'serverless' | 'server' | 'auto';
     approvalRequired?: boolean;
+    audit?: boolean | {
+        durability?: 'best-effort' | 'transactional';
+    };
     approvalDescription?: any;
     func: PikkuFunction;
     auth?: boolean;

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export { NotFoundError } from './errors/errors.js';
 export type { EventHubService } from './wirings/channel/eventhub-service.js';
 export type { QueueService } from './wirings/queue/queue.types.js';
 export type { JWTService } from './services/jwt-service.js';
+export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './services/email-service.js';
 export type { SecretService } from './services/secret-service.js';
 export type { VariablesService } from './services/variables-service.js';
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './services/content-service.js';
@@ -31,9 +32,12 @@ export type { GatewayService } from './services/gateway-service.js';
 export type { TriggerService } from './services/trigger-service.js';
 export type { SchemaService } from './services/schema-service.js';
 export type { SessionService } from './services/user-session-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './services/audit-service.js';
+export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './services/audit-service.js';
 export type { AIAgentRunnerService } from './services/ai-agent-runner-service.js';
 export type { AIRunStateService } from './services/ai-run-state-service.js';
 export type { AIStorageService } from './services/ai-storage-service.js';
+export type { EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, MetaService, } from './services/meta-service.js';
 export type { HTTPMethod } from './wirings/http/http.types.js';
 export type { GraphNodeConfig } from './wirings/workflow/graph/workflow-graph.types.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';

package/dist/index.js

@@ -11,6 +11,7 @@ export { runMCPTool, runMCPResource, runMCPPrompt, } from './wirings/mcp/mcp-run
 export { runQueueJob } from './wirings/queue/queue-runner.js';
 export { runScheduledTask } from './wirings/scheduler/scheduler-runner.js';
 export { NotFoundError } from './errors/errors.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './services/audit-service.js';
 export { createGraph } from './wirings/workflow/graph/graph-node.js';
 export { wireAddon } from './wirings/rpc/wire-addon.js';
 export { runMiddleware, addTagMiddleware, addTagMiddleware as addMiddleware, addGlobalMiddleware, } from './middleware-runner.js';

package/dist/middleware-runner.d.ts

@@ -1,4 +1,4 @@
-import type { CoreSingletonServices, PikkuWire, CorePikkuMiddleware, CorePikkuMiddlewareGroup, PikkuWiringTypes, MiddlewareMetadata } from './types/core.types.js';
+import type { CorePikkuMiddleware, CorePikkuMiddlewareGroup, PikkuWiringTypes, MiddlewareMetadata } from './types/core.types.js';
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -16,7 +16,7 @@ import type { CoreSingletonServices, PikkuWire, CorePikkuMiddleware, CorePikkuMi
  *   async () => { return await runMain(); }
  * );
  */
-export declare const runMiddleware: <Middleware extends CorePikkuMiddleware>(services: CoreSingletonServices, wire: PikkuWire, middlewares: readonly Middleware[], main?: () => Promise<unknown>) => Promise<unknown>;
+export declare const runMiddleware: <Middleware extends CorePikkuMiddleware<any, any>>(services: Parameters<Middleware>[0], wire: Parameters<Middleware>[1], middlewares: readonly Middleware[], main?: () => Promise<unknown>) => Promise<unknown>;
 /**
  * Registers tag-scoped middleware. Applies to any wiring (HTTP, Channel,
  * Queue, Scheduler, MCP, CLI, Workflow, Agent) that carries the matching tag.

package/dist/permissions.d.ts

@@ -33,7 +33,7 @@ export declare const runPermissions: (wireType: PikkuWiringTypes, uid: string, {
     funcInheritedPermissions?: PermissionMetadata[];
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];
     services: CoreServices;
-    wire: PikkuWire<any, never, any, never, never, never>;
+    wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>;
     data: any;
     packageName?: string | null;
 }) => Promise<void>;

package/dist/services/ai-agent-runner-service.d.ts

@@ -8,6 +8,9 @@ export type AIAgentRunnerParams = {
     maxSteps: number;
     toolChoice: 'auto' | 'required' | 'none';
     outputSchema?: Record<string, unknown>;
+    /** Pikku agent function name — forwarded to the LLM proxy (LiteLLM) as
+     *  request-level metadata so usage can be broken down per agent. */
+    agentId?: string;
 };
 export type AIAgentRunnerResult = {
     text: string;
@@ -41,4 +44,7 @@ export type AIAgentStepResult = {
 export interface AIAgentRunnerService {
     stream(params: AIAgentRunnerParams, channel: AIStreamChannel): Promise<AIAgentStepResult>;
     run(params: AIAgentRunnerParams): Promise<AIAgentStepResult>;
+    /** Return a new runner that uses the given API key for every LLM call.
+     *  Optional — runners that don't support per-key scoping leave this undefined. */
+    withApiKey?(apiKey: string): AIAgentRunnerService;
 }

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

@@ -0,0 +1,50 @@
+import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core.types.js';
+export type AuditDurability = 'best-effort' | 'transactional';
+export type AuditOutcome = 'success' | 'failed' | 'denied';
+export type AuditSource = 'auto' | 'explicit';
+export type AuditConfig = boolean | {
+    durability?: AuditDurability;
+};
+export type ResolvedAuditConfig = {
+    durability: AuditDurability;
+};
+export type AuditActor = {
+    userId?: string;
+    orgId?: string;
+    pikkuUserId?: string;
+};
+export type AuditEvent = {
+    eventId?: string;
+    type: string;
+    source: AuditSource;
+    outcome?: AuditOutcome;
+    occurredAt: string;
+    functionId?: string;
+    wireType?: PikkuWiringTypes;
+    wireId?: string;
+    traceId?: string;
+    transactionId?: string | null;
+    queryId?: string | null;
+    actor?: AuditActor;
+    input?: unknown;
+    metadata?: Record<string, unknown>;
+};
+export type AuditEventBatch = AuditEvent[];
+export interface AuditService {
+    audit(event: AuditEvent): Promise<void>;
+    write?(batch: AuditEventBatch): Promise<void>;
+}
+export declare class NoopAuditService implements AuditService {
+    audit(_event: AuditEvent): Promise<void>;
+    write(_batch: AuditEventBatch): Promise<void>;
+}
+export type AuditLogWriteInput = Omit<AuditEvent, 'occurredAt'>;
+export interface AuditLog {
+    readonly config: ResolvedAuditConfig | undefined;
+    write(event: AuditLogWriteInput): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare const resolveAuditConfig: (config?: AuditConfig) => ResolvedAuditConfig | undefined;
+export declare const createInvocationAudit: (service: AuditService, wire: PikkuWire<any, any, any, CoreUserSession>) => AuditLog;
+export declare const resolveAuditActorFromWire: (wire: PikkuWire<any, any, any, CoreUserSession>) => AuditActor | undefined;

package/dist/services/audit-service.js

@@ -0,0 +1,106 @@
+export class NoopAuditService {
+    async audit(_event) { }
+    async write(_batch) { }
+}
+class DisabledInvocationAudit {
+    wire;
+    config = undefined;
+    warned = false;
+    constructor(wire) {
+        this.wire = wire;
+    }
+    async write(_event) {
+        if (!this.warned) {
+            this.warned = true;
+            this.wire.logger?.warn?.('audit.write() called for an invocation without wire.audit enabled');
+        }
+    }
+    async flush() { }
+    async close() { }
+}
+class InvocationAuditLog {
+    config;
+    service;
+    wire;
+    buffer = [];
+    constructor(config, service, wire) {
+        this.config = config;
+        this.service = service;
+        this.wire = wire;
+    }
+    async write(event) {
+        const resolved = this.resolveEvent(event);
+        if (this.config.durability === 'transactional') {
+            await this.service.audit(resolved);
+            return;
+        }
+        this.buffer.push(resolved);
+    }
+    async flush() {
+        if (this.config.durability === 'transactional' ||
+            this.buffer.length === 0) {
+            return;
+        }
+        const batch = this.buffer.splice(0, this.buffer.length);
+        const queryEvents = batch.filter((event) => event.queryId != null);
+        if (queryEvents.length === 1) {
+            queryEvents[0].queryId = null;
+        }
+        try {
+            if (this.service.write) {
+                await this.service.write(batch);
+                return;
+            }
+            for (const event of batch) {
+                await this.service.audit(event);
+            }
+        }
+        catch (error) {
+            ;
+            this.wire.logger?.warn?.('best-effort audit flush failed', error);
+        }
+    }
+    async close() {
+        await this.flush();
+    }
+    resolveEvent(event) {
+        return {
+            functionId: this.wire.functionId,
+            wireType: this.wire.wireType,
+            wireId: this.wire.wireId,
+            traceId: this.wire.traceId,
+            actor: event.actor ?? resolveAuditActorFromWire(this.wire),
+            ...event,
+            occurredAt: new Date().toISOString(),
+        };
+    }
+}
+export const resolveAuditConfig = (config) => {
+    if (config === true) {
+        return { durability: 'best-effort' };
+    }
+    if (!config) {
+        return undefined;
+    }
+    return {
+        durability: config.durability ?? 'best-effort',
+    };
+};
+export const createInvocationAudit = (service, wire) => {
+    if (!wire.audit) {
+        return new DisabledInvocationAudit(wire);
+    }
+    return new InvocationAuditLog(wire.audit, service, wire);
+};
+export const resolveAuditActorFromWire = (wire) => {
+    const session = wire.session;
+    const actor = {
+        userId: session?.userId,
+        orgId: session?.orgId,
+        pikkuUserId: wire.pikkuUserId,
+    };
+    if (!actor.userId && !actor.orgId && !actor.pikkuUserId) {
+        return undefined;
+    }
+    return actor;
+};

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

@@ -23,6 +23,7 @@ export interface GetUploadURLArgs<TBucket extends string = string> {
     fileKey: string;
     contentType: string;
     size?: number;
+    visibility?: 'private' | 'public';
 }
 /**
  * Result of minting a presigned upload URL.

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

@@ -0,0 +1,36 @@
+export interface EmailTemplateReference {
+    name: string;
+    locale?: string;
+    data?: Record<string, unknown>;
+}
+export interface BaseSendEmailInput {
+    to: string | string[];
+    from?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string | string[];
+    headers?: Record<string, string>;
+    subject?: string;
+}
+export interface SendTextEmailInput extends BaseSendEmailInput {
+    text: string;
+    html?: never;
+    template?: never;
+}
+export interface SendHTMLEmailInput extends BaseSendEmailInput {
+    html: string;
+    text?: string;
+    template?: never;
+}
+export interface SendTemplateEmailInput extends BaseSendEmailInput {
+    template: EmailTemplateReference;
+    html?: never;
+    text?: never;
+}
+export type SendEmailInput = SendTextEmailInput | SendHTMLEmailInput | SendTemplateEmailInput;
+export interface SendEmailResult {
+    messageId?: string;
+}
+export interface EmailService {
+    send(input: SendEmailInput): Promise<SendEmailResult>;
+}

package/dist/services/email-service.js

@@ -0,0 +1 @@
+export {};

package/dist/services/index.d.ts

@@ -8,6 +8,7 @@ export { TypedSecretService } from './typed-secret-service.js';
 export { PikkuCredentialWireService, createMiddlewareCredentialWireProps, createWireServicesCredentialWireProps, } from './credential-wire-service.js';
 export { TypedVariablesService } from './typed-variables-service.js';
 export { LocalSecretService } from './local-secrets.js';
+export { LocalEmailService } from './local-email-service.js';
 export { LocalCredentialService } from './local-credential-service.js';
 export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js';
@@ -18,6 +19,7 @@ export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
 export type { JWTService } from './jwt-service.js';
+export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
 export type { Logger } from './logger.js';
 export type { SecretService } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';
@@ -37,5 +39,7 @@ export type { CredentialStatusInfo, CredentialMetaInfo, } from './typed-credenti
 export type { VariableStatus, VariableMeta } from './typed-variables-service.js';
 export type { MetaService } from './meta-service.js';
 export type { SessionStore } from './session-store.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
+export type { AuditActor, AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, ResolvedAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
-export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, } from './meta-service.js';
+export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, } from './meta-service.js';

package/dist/services/index.js

@@ -8,6 +8,7 @@ export { TypedSecretService } from './typed-secret-service.js';
 export { PikkuCredentialWireService, createMiddlewareCredentialWireProps, createWireServicesCredentialWireProps, } from './credential-wire-service.js';
 export { TypedVariablesService } from './typed-variables-service.js';
 export { LocalSecretService } from './local-secrets.js';
+export { LocalEmailService } from './local-email-service.js';
 export { LocalCredentialService } from './local-credential-service.js';
 export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js';
@@ -17,4 +18,5 @@ export { InMemoryTriggerService } from './in-memory-trigger-service.js';
 export { InMemoryAIRunStateService } from './in-memory-ai-run-state-service.js';
 export { LocalGatewayService } from './local-gateway-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
+export { NoopAuditService, createInvocationAudit, resolveAuditActorFromWire, resolveAuditConfig, } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';

package/dist/services/local-content.js

@@ -64,6 +64,7 @@ export class LocalContent {
         });
     }
     async getUploadURL(args) {
+        void args.visibility;
         const fullKey = this.joinKey(args.bucket, args.fileKey);
         this.logger.debug(`Going to upload with key: ${fullKey}`);
         return {

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

@@ -0,0 +1,4 @@
+import type { EmailService, SendEmailInput, SendEmailResult } from './email-service.js';
+export declare class LocalEmailService implements EmailService {
+    send(input: SendEmailInput): Promise<SendEmailResult>;
+}

package/dist/services/local-email-service.js

@@ -0,0 +1,26 @@
+export class LocalEmailService {
+    async send(input) {
+        const payload = {
+            type: 'email',
+            message: 'this email was sent',
+            to: input.to,
+            from: input.from ?? null,
+            cc: input.cc ?? null,
+            bcc: input.bcc ?? null,
+            replyTo: input.replyTo ?? null,
+            subject: input.subject ?? null,
+        };
+        if ('template' in input && input.template) {
+            payload.template = input.template;
+        }
+        if ('html' in input && typeof input.html === 'string') {
+            payload.htmlLength = input.html.length;
+            payload.textLength = input.text?.length ?? null;
+        }
+        if ('text' in input && typeof input.text === 'string') {
+            payload.textLength = input.text.length;
+        }
+        console.info(JSON.stringify(payload));
+        return {};
+    }
+}

package/dist/services/local-secrets.d.ts

@@ -7,6 +7,7 @@ import type { VariablesService } from './variables-service.js';
 export declare class LocalSecretService implements SecretService {
     private variables;
     private localSecrets;
+    private parseSecret;
     /**
      * Creates an instance of LocalSecretService.
      */

package/dist/services/local-secrets.js

@@ -6,6 +6,15 @@ import { LocalVariablesService } from './local-variables.js';
 export class LocalSecretService {
     variables;
     localSecrets = new Map();
+    // TODO: Drop this fallback once secrets and variables expose aligned typed/raw access paths again.
+    parseSecret(raw) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
+    }
     /**
      * Creates an instance of LocalSecretService.
      */
@@ -23,12 +32,12 @@ export class LocalSecretService {
         // Check local storage first
         const localValue = this.localSecrets.get(key);
         if (localValue) {
-            return JSON.parse(localValue);
+            return this.parseSecret(localValue);
         }
         // Fall back to environment variables
         const value = await this.variables.get(key);
         if (value) {
-            return JSON.parse(value);
+            return this.parseSecret(value);
         }
         throw new Error('Requested secret not found');
     }