@pikku/core 0.11.1 → 0.12.0

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

@@ -1,17 +1,38 @@
 /**
- * Interface for retrieving secrets.
+ * Interface for retrieving and managing secrets.
  */
 export interface SecretService {
     /**
-     * Retrieves a secret by key.
+     * Retrieves a secret by key and parses it as JSON.
      * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
+     * @returns A promise that resolves to the parsed secret value.
+     * @throws If the secret is not found.
      */
     getSecretJSON<Return = {}>(key: string): Promise<Return>;
     /**
-     * Retrieves a secret by key.
+     * Retrieves a secret by key as a string.
      * @param key - The key of the secret to retrieve.
      * @returns A promise that resolves to the secret value.
+     * @throws If the secret is not found.
      */
     getSecret(key: string): Promise<string>;
+    /**
+     * Checks if a secret exists without throwing.
+     * @param key - The key of the secret to check.
+     * @returns A promise that resolves to true if the secret exists, false otherwise.
+     */
+    hasSecret(key: string): Promise<boolean>;
+    /**
+     * Stores a JSON value as a secret.
+     * @param key - The key to store the secret under.
+     * @param value - The JSON value to store.
+     * @returns A promise that resolves when the secret is stored.
+     */
+    setSecretJSON(key: string, value: unknown): Promise<void>;
+    /**
+     * Deletes a secret by key.
+     * @param key - The key of the secret to delete.
+     * @returns A promise that resolves when the secret is deleted.
+     */
+    deleteSecret(key: string): Promise<void>;
 }

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

@@ -0,0 +1,23 @@
+import { CoreSingletonServices, CreateWireServices, CoreServices, CoreUserSession } from '../types/core.types.js';
+/**
+ * Abstract TriggerService interface.
+ *
+ * Implementations manage trigger subscriptions — listening to external events
+ * and dispatching to RPC targets or workflow starts.
+ */
+export interface TriggerService {
+    /**
+     * Set services needed for processing triggers.
+     * Called after construction since the trigger service is created before
+     * singletonServices are fully assembled.
+     */
+    setServices(_singletonServices: CoreSingletonServices, _createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices, CoreUserSession>): void;
+    /**
+     * Start all triggers
+     */
+    start(): Promise<void>;
+    /**
+     * Stop all triggers
+     */
+    stop(): Promise<void>;
+}

package/dist/services/trigger-service.js

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

package/dist/services/typed-secret-service.d.ts

@@ -0,0 +1,30 @@
+import type { SecretService } from './secret-service.js';
+export interface CredentialStatus {
+    secretId: string;
+    name: string;
+    displayName: string;
+    isConfigured: boolean;
+    oauth2?: {
+        tokenSecretId: string;
+    };
+}
+export type CredentialMeta = {
+    name: string;
+    displayName: string;
+    oauth2?: {
+        tokenSecretId: string;
+    };
+};
+export declare class TypedSecretService<TMap = Record<string, unknown>> implements SecretService {
+    private secrets;
+    private credentialsMeta;
+    constructor(secrets: SecretService, credentialsMeta: Record<string, CredentialMeta>);
+    getSecretJSON<K extends keyof TMap & string>(key: K): Promise<TMap[K]>;
+    getSecretJSON<T = unknown>(key: string): Promise<T>;
+    getSecret(key: string): Promise<string>;
+    hasSecret(key: string): Promise<boolean>;
+    setSecretJSON<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
+    deleteSecret(key: string): Promise<void>;
+    getAllStatus(): Promise<CredentialStatus[]>;
+    getMissing(): Promise<CredentialStatus[]>;
+}

package/dist/services/typed-secret-service.js

@@ -0,0 +1,40 @@
+export class TypedSecretService {
+    secrets;
+    credentialsMeta;
+    constructor(secrets, credentialsMeta) {
+        this.secrets = secrets;
+        this.credentialsMeta = credentialsMeta;
+    }
+    async getSecretJSON(key) {
+        return this.secrets.getSecretJSON(key);
+    }
+    async getSecret(key) {
+        return this.secrets.getSecret(key);
+    }
+    async hasSecret(key) {
+        return this.secrets.hasSecret(key);
+    }
+    async setSecretJSON(key, value) {
+        return this.secrets.setSecretJSON(key, value);
+    }
+    async deleteSecret(key) {
+        return this.secrets.deleteSecret(key);
+    }
+    async getAllStatus() {
+        const results = [];
+        for (const [secretId, meta] of Object.entries(this.credentialsMeta)) {
+            results.push({
+                secretId,
+                name: meta.name,
+                displayName: meta.displayName,
+                isConfigured: await this.secrets.hasSecret(secretId),
+                oauth2: meta.oauth2,
+            });
+        }
+        return results;
+    }
+    async getMissing() {
+        const all = await this.getAllStatus();
+        return all.filter((c) => !c.isConfigured);
+    }
+}

package/dist/services/typed-variables-service.d.ts

@@ -0,0 +1,27 @@
+import type { VariablesService } from './variables-service.js';
+export interface VariableStatus {
+    variableId: string;
+    name: string;
+    displayName: string;
+    isConfigured: boolean;
+}
+export type VariableMeta = {
+    name: string;
+    displayName: string;
+};
+export declare class TypedVariablesService<TMap = Record<string, unknown>> implements VariablesService {
+    private variables;
+    private variablesMeta;
+    constructor(variables: VariablesService, variablesMeta: Record<string, VariableMeta>);
+    get(name: keyof TMap & string): Promise<string | undefined> | string | undefined;
+    get(name: string): Promise<string | undefined> | string | undefined;
+    getJSON<K extends keyof TMap & string>(name: K): Promise<TMap[K] | undefined> | TMap[K] | undefined;
+    getJSON<T = unknown>(name: string): Promise<T | undefined> | T | undefined;
+    getAll(): Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
+    set(name: string, value: string): Promise<void> | void;
+    setJSON(name: string, value: unknown): Promise<void> | void;
+    has(name: string): Promise<boolean> | boolean;
+    delete(name: string): Promise<void> | void;
+    getAllStatus(): Promise<VariableStatus[]>;
+    getMissing(): Promise<VariableStatus[]>;
+}

package/dist/services/typed-variables-service.js

@@ -0,0 +1,46 @@
+export class TypedVariablesService {
+    variables;
+    variablesMeta;
+    constructor(variables, variablesMeta) {
+        this.variables = variables;
+        this.variablesMeta = variablesMeta;
+    }
+    get(name) {
+        return this.variables.get(name);
+    }
+    getJSON(name) {
+        return this.variables.getJSON(name);
+    }
+    getAll() {
+        return this.variables.getAll();
+    }
+    set(name, value) {
+        return this.variables.set(name, value);
+    }
+    setJSON(name, value) {
+        return this.variables.setJSON(name, value);
+    }
+    has(name) {
+        return this.variables.has(name);
+    }
+    delete(name) {
+        return this.variables.delete(name);
+    }
+    async getAllStatus() {
+        const results = [];
+        const all = await this.variables.getAll();
+        for (const [variableId, meta] of Object.entries(this.variablesMeta)) {
+            results.push({
+                variableId,
+                name: meta.name,
+                displayName: meta.displayName,
+                isConfigured: all[variableId] !== undefined,
+            });
+        }
+        return results;
+    }
+    async getMissing() {
+        const all = await this.getAllStatus();
+        return all.filter((v) => !v.isConfigured);
+    }
+}

package/dist/services/user-session-service.d.ts

@@ -22,3 +22,16 @@ export declare class PikkuSessionService<UserSession extends CoreUserSession> im
     clear(): void | Promise<void> | undefined;
     get(): Promise<UserSession> | UserSession | undefined;
 }
+export declare function createMiddlewareSessionWireProps<UserSession extends CoreUserSession>(session: SessionService<UserSession>): {
+    session: UserSession | Promise<UserSession> | undefined;
+    setSession: (s: UserSession) => void;
+    getSession: () => UserSession | Promise<UserSession> | undefined;
+    hasSessionChanged: () => boolean;
+};
+export declare function createFunctionSessionWireProps<UserSession extends CoreUserSession>(session: SessionService<UserSession>): {
+    session: UserSession | undefined;
+    setSession: (s: UserSession) => void | Promise<void>;
+    clearSession: () => void | Promise<void>;
+    getSession: () => UserSession | Promise<UserSession> | undefined;
+    hasSessionChanged: () => boolean;
+};

package/dist/services/user-session-service.js

@@ -43,3 +43,20 @@ export class PikkuSessionService {
         return this.session;
     }
 }
+export function createMiddlewareSessionWireProps(session) {
+    return {
+        session: session.get(),
+        setSession: (s) => session.setInitial(s),
+        getSession: () => session.get(),
+        hasSessionChanged: () => session.sessionChanged,
+    };
+}
+export function createFunctionSessionWireProps(session) {
+    return {
+        session: session.freezeInitial(),
+        setSession: (s) => session.set(s),
+        clearSession: () => session.clear(),
+        getSession: () => session.get(),
+        hasSessionChanged: () => session.sessionChanged,
+    };
+}

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

@@ -1,4 +1,9 @@
 export interface VariablesService {
     get: (name: string) => Promise<string | undefined> | string | undefined;
+    getJSON: <T = unknown>(name: string) => Promise<T | undefined> | T | undefined;
     getAll: () => Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
+    set: (name: string, value: string) => Promise<void> | void;
+    setJSON: (name: string, value: unknown) => Promise<void> | void;
+    has: (name: string) => Promise<boolean> | boolean;
+    delete: (name: string) => Promise<void> | void;
 }

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

@@ -0,0 +1,43 @@
+import { SerializedError, CoreSingletonServices, CreateWireServices, CoreConfig } from '../types/core.types.js';
+import { WorkflowRun, WorkflowRunWire, StepState, WorkflowStatus } from '../wirings/workflow/workflow.types.js';
+/**
+ * Interface for workflow orchestration
+ * Handles workflow execution, replay, orchestration logic, and run-level state
+ */
+export interface WorkflowService {
+    createRun(workflowName: string, input: any, inline: boolean, graphHash: string, wire: WorkflowRunWire): Promise<string>;
+    getRun(id: string): Promise<WorkflowRun | null>;
+    getRunHistory(runId: string): Promise<Array<StepState & {
+        stepName: string;
+    }>>;
+    updateRunStatus(id: string, status: WorkflowStatus, output?: any, error?: SerializedError): Promise<void>;
+    withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    resumeWorkflow(runId: string): Promise<void>;
+    setServices(singletonServices: CoreSingletonServices, createWireServices: CreateWireServices | undefined, config: CoreConfig): void;
+    startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
+        inline?: boolean;
+        startNode?: string;
+    }): Promise<{
+        runId: string;
+    }>;
+    runWorkflowJob(runId: string, rpcService: any): Promise<void>;
+    orchestrateWorkflow(runId: string, rpcService: any): Promise<void>;
+    executeWorkflowSleepCompleted(runId: string, stepId: string): Promise<void>;
+    insertStepState(runId: string, stepName: string, rpcName: string, data: any, stepOptions?: {
+        retries?: number;
+        retryDelay?: string | number;
+    }): Promise<StepState>;
+    getStepState(runId: string, stepName: string): Promise<StepState>;
+    setStepRunning(stepId: string): Promise<void>;
+    setStepScheduled(stepId: string): Promise<void>;
+    setStepResult(stepId: string, result: any): Promise<void>;
+    setStepError(stepId: string, error: Error): Promise<void>;
+    createRetryAttempt(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    executeWorkflowStep(runId: string, stepName: string, rpcName: string | null, data: any, rpcService: any): Promise<void>;
+    upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    getWorkflowVersion(name: string, graphHash: string): Promise<{
+        graph: any;
+        source: string;
+    } | null>;
+}

package/dist/services/workflow-service.js

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

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

@@ -1,22 +1,33 @@
 import type { Logger, LogLevel } from '../services/logger.js';
 import { VariablesService } from '../services/variables-service.js';
+import { SecretService } from '../services/secret-service.js';
 import { SchemaService } from '../services/schema-service.js';
 import { JWTService } from '../services/jwt-service.js';
 import { PikkuHTTP } from '../wirings/http/http.types.js';
-import { SessionService } from '../services/user-session-service.js';
-import { PikkuChannel } from '../wirings/channel/channel.types.js';
+import { PikkuChannel, CorePikkuChannelMiddleware, CorePikkuChannelMiddlewareFactory } from '../wirings/channel/channel.types.js';
 import { PikkuRPC } from '../wirings/rpc/rpc-types.js';
 import { PikkuMCP } from '../wirings/mcp/mcp.types.js';
 import { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js';
 import { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js';
 import { PikkuCLI } from '../wirings/cli/cli.types.js';
 import { PikkuWorkflowWire, WorkflowService, WorkflowServiceConfig, WorkflowStepWire } from '../wirings/workflow/workflow.types.js';
+import type { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js';
+import { PikkuTrigger } from '../wirings/trigger/trigger.types.js';
 import { SchedulerService } from '../services/scheduler-service.js';
-export type PikkuWiringTypes = 'http' | 'scheduler' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow';
+import { DeploymentService } from '../services/deployment-service.js';
+import { AIStorageService } from '../services/ai-storage-service.js';
+import { AIAgentRunnerService } from '../services/ai-agent-runner-service.js';
+import { AIRunStateService } from '../services/ai-run-state-service.js';
+import type { PikkuAIMiddlewareHooks } from '../wirings/ai-agent/ai-agent.types.js';
+export type PikkuWiringTypes = 'http' | 'scheduler' | 'trigger' | 'channel' | 'rpc' | 'queue' | 'mcp' | 'cli' | 'workflow' | 'agent';
 export interface FunctionServicesMeta {
     optimized: boolean;
     services: string[];
 }
+export interface FunctionWiresMeta {
+    optimized: boolean;
+    wires: string[];
+}
 /**
  * Metadata for middleware at any level
  * - type: 'http' = HTTP route middleware group (references httpGroup in pikkuState)
@@ -52,16 +63,23 @@ export type PermissionMetadata = {
     inline?: boolean;
 };
 export type FunctionRuntimeMeta = {
-    pikkuFuncName: string;
+    pikkuFuncId: string;
     inputSchemaName: string | null;
     outputSchemaName: string | null;
     expose?: boolean;
-    internal?: boolean;
+    remote?: boolean;
+    mcp?: boolean;
+    sessionless?: boolean;
+    version?: number;
+    requiresApproval?: boolean;
+    contractHash?: string;
 };
 export type FunctionMeta = FunctionRuntimeMeta & Partial<{
     name: string;
+    functionType: 'user' | 'inline' | 'helper';
+    funcWrapper: string;
     services: FunctionServicesMeta;
-    usedWires: string[];
+    wires: FunctionWiresMeta;
     inputs: string[] | null;
     outputs: string[] | null;
     middleware: MiddlewareMetadata[];
@@ -124,17 +142,29 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
     logger: Logger;
     /** The variable service to be used */
     variables: VariablesService;
+    /** The secrets service to retrieve secrets */
+    secrets: SecretService;
     /** The workflow orchestrator service */
     workflowService?: WorkflowService;
     /** The queue service */
     queueService?: QueueService;
     /** The scheduler service */
     schedulerService?: SchedulerService;
+    /** The deployment service for service discovery */
+    deploymentService?: DeploymentService;
+    /** AI agent storage service (threads, messages, working memory) */
+    aiStorage?: AIStorageService;
+    /** AI agent runner service (model calls + tool loop) */
+    aiAgentRunner?: AIAgentRunnerService;
+    /** AI run state service (run lifecycle + approval persistence) */
+    aiRunState?: AIRunStateService;
 }
 /**
  * Represents different forms of wire within Pikku and the outside world.
  */
-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> = Partial<{
+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> = Partial<{
+    wireType: PikkuWiringTypes;
+    wireId: string;
     http: PikkuHTTP<In>;
     mcp: PikkuMCP<MCPTools>;
     rpc: TypedRPC;
@@ -144,8 +174,17 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
     cli: PikkuCLI;
     workflow: TypedWorkflow;
     workflowStep: WorkflowStepWire;
-    initialSession: HasInitialSession extends true ? UserSession : UserSession | undefined;
-    session: SessionService<UserSession>;
+    graph: PikkuGraphWire;
+    trigger: PikkuTrigger<TriggerOutput>;
+    session: HasInitialSession extends true ? UserSession : UserSession | undefined;
+    /** Update and persist the current session */
+    setSession: (session: CoreUserSession) => Promise<void> | void;
+    /** Clear and persist the current session */
+    clearSession: () => Promise<void> | void;
+    /** Fetch the latest session (may read from backing store) */
+    getSession: () => Promise<UserSession> | UserSession | undefined;
+    /** Whether the session was modified during this run */
+    hasSessionChanged: () => boolean;
 }>;
 /**
  * A function that can wrap an wire and be called before or after
@@ -219,6 +258,10 @@ export declare const pikkuMiddleware: <SingletonServices extends CoreSingletonSe
  * ```
  */
 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>;
 /**
  * Represents the core services used by Pikku, including singleton services.
  */
@@ -240,7 +283,8 @@ export type CreateConfig<Config extends CoreConfig, RemainingArgs extends any[]
  * Represents the documentation for a route, including summary, description, tags, and errors.
  */
 export type CommonWireMeta = {
-    pikkuFuncName: string;
+    pikkuFuncId: string;
+    title?: string;
     tags?: string[];
     summary?: string;
     description?: string;

package/dist/types/core.types.js

@@ -46,3 +46,10 @@ export const pikkuMiddleware = (middleware) => {
 export const pikkuMiddlewareFactory = (factory) => {
     return factory;
 };
+export const pikkuChannelMiddleware = (middleware) => {
+    return middleware;
+};
+export const pikkuChannelMiddlewareFactory = (factory) => {
+    return factory;
+};
+export const pikkuAIMiddleware = (hooks) => hooks;

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

@@ -0,0 +1,127 @@
+import { PikkuError, ErrorDetails } from '../errors/error-handler.js';
+import { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
+import { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js';
+import { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types.js';
+import { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js';
+import { HTTPMethod, CoreHTTPFunctionWiring, HTTPWiringsMeta } from '../wirings/http/http.types.js';
+import { CoreMCPResource, MCPResourceMeta, MCPToolMeta, CoreMCPPrompt, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
+import { CoreAIAgent, AIAgentMeta } from '../wirings/ai-agent/ai-agent.types.js';
+import { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
+import { CoreScheduledTask, ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js';
+import { CoreWorkflow, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.types.js';
+import { CoreTrigger, CoreTriggerSource, TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';
+import { FunctionsMeta, CorePikkuMiddleware, CorePikkuMiddlewareGroup, CreateConfig, CreateSingletonServices, CreateWireServices, CoreConfig, CoreSingletonServices, CoreServices, CoreUserSession } from './core.types.js';
+import type { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
+/**
+ * State structure for an individual package
+ */
+export interface PikkuPackageState {
+    function: {
+        meta: FunctionsMeta;
+        functions: Map<string, CorePikkuFunctionConfig<any, any>>;
+    };
+    rpc: {
+        meta: Record<string, string>;
+        files: Map<string, {
+            exportedName: string;
+            path: string;
+        }>;
+        /** Maps namespace aliases to package config (e.g., 'ext' -> { package: '@pikku/...', rpcEndpoint: '...' }) */
+        externalPackages: Map<string, {
+            package: string;
+            rpcEndpoint?: string;
+        }>;
+    };
+    http: {
+        middleware: Map<string, CorePikkuMiddleware<any, any>[]>;
+        permissions: Map<string, CorePermissionGroup | CorePikkuPermission[]>;
+        routes: Map<HTTPMethod, Map<string, CoreHTTPFunctionWiring<any, any, any>>>;
+        meta: HTTPWiringsMeta;
+    };
+    channel: {
+        channels: Map<string, CoreChannel<any, any>>;
+        meta: ChannelsMeta;
+    };
+    scheduler: {
+        tasks: Map<string, CoreScheduledTask>;
+        meta: ScheduledTasksMeta;
+    };
+    queue: {
+        registrations: Map<string, CoreQueueWorker>;
+        meta: QueueWorkersMeta;
+    };
+    workflows: {
+        registrations: Map<string, CoreWorkflow>;
+        meta: WorkflowsRuntimeMeta;
+    };
+    trigger: {
+        functions: Map<string, CorePikkuTriggerFunctionConfig<any, any>>;
+        triggers: Map<string, CoreTrigger>;
+        triggerSources: Map<string, CoreTriggerSource>;
+        meta: TriggerMeta;
+        sourceMeta: TriggerSourceMeta;
+    };
+    mcp: {
+        resources: Map<string, CoreMCPResource>;
+        resourcesMeta: MCPResourceMeta;
+        toolsMeta: MCPToolMeta;
+        prompts: Map<string, CoreMCPPrompt>;
+        promptsMeta: MCPPromptMeta;
+    };
+    agent: {
+        agents: Map<string, CoreAIAgent>;
+        agentsMeta: AIAgentMeta;
+    };
+    cli: {
+        meta: CLIMeta | Record<string, any>;
+        programs: Record<string, CLIProgramState>;
+    };
+    middleware: {
+        tagGroup: Record<string, CorePikkuMiddlewareGroup>;
+        httpGroup: Record<string, CorePikkuMiddlewareGroup>;
+    };
+    channelMiddleware: {
+        tagGroup: Record<string, CorePikkuChannelMiddleware[]>;
+    };
+    permissions: {
+        tagGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
+        httpGroup: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
+    };
+    misc: {
+        errors: Map<PikkuError, ErrorDetails>;
+        schemas: Map<string, any>;
+        middleware: Record<string, CorePikkuMiddleware[]>;
+        channelMiddleware: Record<string, CorePikkuChannelMiddleware[]>;
+        permissions: Record<string, CorePermissionGroup | CorePikkuPermission[]>;
+    };
+    models: {
+        config: {
+            models?: Record<string, string | {
+                model: string;
+                temperature?: number;
+                maxSteps?: number;
+            }>;
+            agentDefaults?: {
+                temperature?: number;
+                maxSteps?: number;
+            };
+            agentOverrides?: Record<string, {
+                model?: string;
+                temperature?: number;
+                maxSteps?: number;
+            }>;
+        } | null;
+    };
+    package: {
+        /** Service factory functions for external packages */
+        factories: {
+            createConfig?: CreateConfig<CoreConfig>;
+            createSingletonServices?: CreateSingletonServices<CoreConfig, CoreSingletonServices>;
+            createWireServices?: CreateWireServices<CoreSingletonServices, CoreServices, CoreUserSession>;
+        } | null;
+        /** Cached singleton services for this package */
+        singletonServices: CoreSingletonServices | null;
+        /** Absolute path to this package's .pikku directory */
+        metaDir: string | null;
+    };
+}

package/dist/types/state.types.js

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

package/dist/utils.d.ts

@@ -1,5 +1,14 @@
 import { Logger } from './services/logger.js';
-export declare const closeWireServices: (logger: Logger, wireServices: Record<string, any>) => Promise<void>;
+import { CoreSingletonServices, WireServices } from './types/core.types.js';
+export declare const closeWireServices: (logger: Logger, wireServices: WireServices) => Promise<void>;
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
+export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string) => T[];
 export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];
+/**
+ * Stop all singleton services, including external package services.
+ * External package services are stopped first, then the parent services.
+ *
+ * @param singletonServices - The parent singleton services to stop
+ */
+export declare const stopSingletonServices: (singletonServices: CoreSingletonServices) => Promise<void>;