@pikku/core 0.12.79 → 0.12.82

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

@@ -142,8 +142,6 @@ export type FunctionRuntimeMeta = {
     audit?: {
         durability: AuditDurability;
     };
-    /** Keeps the full `SecretService`. Set by the inspector, read by the runner. */
-    secretBroker?: boolean;
     version?: number;
     approvalRequired?: boolean;
     approvalDescription?: string;
@@ -233,6 +231,11 @@ export interface CoreUserSession {
      * Populated by whoever builds the session — core reads them, never fetches.
      */
     scopes?: string[];
+    /**
+     * Restricts the session to functions declared `readonly`. The function runner
+     * throws `ReadonlySessionError` for anything else.
+     */
+    readonly?: boolean;
 }
 /**
  * Kept structural so core stays independent of any one auth package —
@@ -299,12 +302,17 @@ 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 | never = PikkuScenarioWire, TypedActors extends ScenarioPersonas = ScenarioPersonas> = {
+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> = {
     /** Always present — lazily initialised on first access for every function invocation */
     rpc: TypedRPC;
 } & Partial<{
     wireType: PikkuWiringTypes;
     wireId: string;
+    /**
+     * A logger scoped to this invocation, when a host attaches one. Core never
+     * sets it; services that log fall back to the singleton logger.
+     */
+    logger: Logger;
     /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
     traceId: string;
     functionId: string;

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

@@ -6,6 +6,7 @@ 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 { 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';
@@ -40,6 +41,10 @@ export interface PikkuPackageState {
             variableOverrides?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
             credentialOverrides?: Record<string, string>;
+            /** Why this instance gets the whole `SecretService` rather than one scoped to its declared secrets */
+            globalSecrets?: string;
+            /** Why this instance gets the whole `CredentialService` rather than one scoped to its declared credentials */
+            globalCredentials?: string;
             /** Set by `wireRemoteAddon`: this namespace is consumed remotely over HTTP, not bundled */
             remote?: boolean;
             /** Remote host base URL (wireRemoteAddon) — string or resolver over singleton services */
@@ -63,7 +68,7 @@ export interface PikkuPackageState {
         meta: HTTPWiringsMeta;
     };
     channel: {
-        channels: Map<string, CoreChannel<any, any>>;
+        channels: Map<string, CoreChannel<any, any, any, any, any>>;
         meta: ChannelsMeta;
     };
     scheduler: {
@@ -97,6 +102,10 @@ export interface PikkuPackageState {
     agent: {
         agents: Map<string, CoreAIAgent>;
         agentsMeta: AIAgentMeta;
+        scorers: Map<string, PikkuAIScorer>;
+        scorersMeta: ScorerMeta;
+        /** Alias -> `provider/model`, from the `models` table in pikku.config.json. */
+        modelAliases: Record<string, string>;
     };
     gateway: {
         gateways: Map<string, CoreGateway>;
@@ -141,5 +150,9 @@ export interface PikkuPackageState {
             oauth2?: boolean;
         }> | null;
         requiredParentServices: string[] | null;
+        /** The secret keys this package is allowed to read, emitted by the CLI from
+         *  what the package declares and is seen to read. `null` when the package
+         *  was never analysed, which scopes it to nothing. */
+        declaredSecrets: string[] | null;
     };
 }

package/dist/wirings/actor-flow/index.d.ts

@@ -1,2 +1,2 @@
-export type { ActorFlowApprovalPolicy, ActorFlowVerdict, ConverseOptions, TargetAgentReply, TargetPendingApproval, TargetAgentDriver, } from './actor-flow.types.js';
+export type { ActorFlowVerdict, ConverseOptions, TargetAgentDriver, } from './actor-flow.types.js';
 export { runConversation, type RunConversationParams, type ActorLLM, } from './run-conversation.js';

package/dist/wirings/actor-flow/run-conversation.js

@@ -70,12 +70,7 @@ function actorInstructions(persona, task) {
             : '',
         `Your goal in this conversation: ${task}.`,
         `Send one message at a time. Set "done" to true only once your goal is clearly accomplished, or clearly impossible.`,
-        // Every call the actor makes wants a schema'd object back, and a gateway
-        // that cannot take a JSON *schema* degrades to OpenAI's `json_object`
-        // mode — which refuses the request outright unless the word "json" appears
-        // somewhere in the prompt. Saying it once here covers all three call sites
-        // (turn, approvals, verdict), since each builds on these instructions, and
-        // it costs nothing on providers that never needed telling.
+        // knowledge: decisions/internals/the-actor-prompt-says-json-because-of-json-object-mode.md
         `Reply with json matching the schema you are given, and nothing else.`,
     ]
         .filter(Boolean)

package/dist/wirings/ai-agent/agent-rpc.d.ts

@@ -0,0 +1,15 @@
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { SessionService } from '../../services/user-session-service.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+import type { PikkuRPC } from '../rpc/rpc-types.js';
+export type AgentRPCOptions = {
+    sessionService?: SessionService<CoreUserSession>;
+};
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export declare const createAgentRPC: (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC["agent"];

package/dist/wirings/ai-agent/agent-rpc.js

@@ -0,0 +1,53 @@
+import { runAIAgent, resumeAIAgentSync } from './ai-agent-runner.js';
+import { streamAIAgent, resumeAIAgent, interruptAIAgent, } from './ai-agent-stream.js';
+import { wrapChannelWithAGUI } from './ai-agent-agui.js';
+/**
+ * `wire.rpc.agent`, implemented.
+ *
+ * Lives here rather than in `rpc-runner` so the agent surface is one file next
+ * to the runner and stream code it delegates to, instead of a wing of the RPC
+ * primitive.
+ */
+export const createAgentRPC = (wire, options) => {
+    const params = () => ({
+        sessionService: options.sessionService,
+        getCredential: wire.getCredential?.bind(wire),
+    });
+    const streamingChannel = () => {
+        const channel = wire.channel;
+        if (!channel)
+            throw new Error('No channel available for streaming');
+        return channel;
+    };
+    /** `run` and `approve` return the same shape; only the call differs. */
+    const asRunResult = (result) => ({
+        runId: result.runId,
+        result: result.object ?? result.text,
+        usage: result.usage,
+        ...(result.status === 'suspended' && {
+            status: 'suspended',
+            pendingApprovals: result.pendingApprovals,
+        }),
+    });
+    return {
+        run: async (agentName, input) => asRunResult(await runAIAgent(agentName, input, params())),
+        stream: async (agentName, input, streamOptions) => {
+            let currentRunId;
+            await streamAIAgent(agentName, input, wrapChannelWithAGUI(streamingChannel(), {
+                threadId: input.threadId,
+                getRunId: () => currentRunId,
+            }), params(), undefined, {
+                ...streamOptions,
+                onRunCreated: (runId) => {
+                    currentRunId = runId;
+                    streamOptions?.onRunCreated?.(runId);
+                },
+            });
+        },
+        resume: async (runId, input, streamOptions) => {
+            await resumeAIAgent({ runId, ...input }, wrapChannelWithAGUI(streamingChannel(), { runId }), params(), streamOptions);
+        },
+        interrupt: async (runId, reason) => interruptAIAgent({ runId, ...(reason ? { reason } : {}) }, { sessionService: options.sessionService }),
+        approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAIAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
+    };
+};

package/dist/wirings/ai-agent/ai-agent-agui.js

@@ -296,11 +296,7 @@ export function wrapChannelWithAGUI(inner, options) {
                     });
                     break;
                 }
-                // AG-UI has no event for speech, so it travels as CUSTOM like the other
-                // pikku-specific ones. Dropping it instead — which is what this did —
-                // means a voice agent reached over HTTP is inaudible: `voiceOutput`
-                // synthesizes every sentence, the provider bills for it, and nothing
-                // gets past the mapper.
+                // knowledge: decisions/internals/agent-speech-travels-as-a-custom-agui-event.md
                 case 'audio-delta': {
                     send({
                         type: 'CUSTOM',

package/dist/wirings/ai-agent/ai-agent-finalize.d.ts

@@ -0,0 +1,58 @@
+import type { AIAgentStep, AIMessage, PikkuAIMiddlewareHooks } from './ai-agent.types.js';
+import type { AIRunStateService } from '../../services/ai-run-state-service.js';
+export type RunUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    model?: string;
+};
+/**
+ * Everything a finished run produced, after all middleware has had its say.
+ *
+ * One snapshot feeds persistence and anything that grades the run, so that what
+ * a scorer is shown is exactly what was stored — including the redactions.
+ */
+export type FinalizedRun = {
+    runId: string;
+    agentName: string;
+    threadId: string;
+    resourceId?: string;
+    /** The prompt the run answered — what a scorer grades the answer against. */
+    input: string;
+    text: string;
+    steps: AIAgentStep[];
+    usage: RunUsage;
+};
+/**
+ * The prompt a run answered: the most recent user turn, which is what the model
+ * was last asked. On a resumed run the earlier turns are context, not the ask.
+ */
+export declare const lastUserMessageText: (messages: AIMessage[]) => string;
+/**
+ * Run the `modifyOutput` chain over a finished non-streaming run.
+ *
+ * Reverse order, matching the input chain: the middleware registered first
+ * wraps the others, so it sees the output last.
+ */
+export declare const applyOutputMiddleware: (aiMiddlewares: PikkuAIMiddlewareHooks[], singletonServices: any, input: {
+    text: string;
+    messages: AIMessage[];
+    steps: AIAgentStep[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}) => Promise<{
+    text: string;
+    messages: AIMessage[];
+    steps: AIAgentStep[];
+}>;
+/**
+ * The one place a run ends successfully.
+ *
+ * Every path that completes a run — streamed, non-streamed, and resumed after a
+ * tool approval — goes through here, so that anything terminal is reachable
+ * from all of them and cannot be reordered by a middleware author. Nothing here
+ * may rewrite the run: by this point the output middleware has resolved and, on
+ * the streaming path, the client already has the reply.
+ */
+export declare const finalizeAgentRun: (aiRunState: AIRunStateService, run: FinalizedRun) => Promise<void>;

package/dist/wirings/ai-agent/ai-agent-finalize.js

@@ -0,0 +1,138 @@
+import { pikkuState } from '../../pikku-state.js';
+import { scoreFinishedRun } from '../ai-scorer/ai-scorer-live.js';
+import { recordScoreSnapshot } from '../ai-scorer/ai-scorer-snapshots.js';
+/**
+ * The prompt a run answered: the most recent user turn, which is what the model
+ * was last asked. On a resumed run the earlier turns are context, not the ask.
+ */
+export const lastUserMessageText = (messages) => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message?.role !== 'user')
+            continue;
+        if (typeof message.content === 'string')
+            return message.content;
+        if (Array.isArray(message.content)) {
+            return message.content
+                .filter((part) => part.type === 'text')
+                .map((part) => part.text)
+                .join('\n');
+        }
+    }
+    return '';
+};
+const flattenToolCalls = (steps) => steps.flatMap((step) => step.toolCalls ?? []);
+/**
+ * Push a rewritten flat tool-call list back onto the steps it came from,
+ * preserving the step boundaries. A hook that adds or drops calls would make
+ * the boundaries meaningless, so a length change collapses them into the last
+ * step rather than silently mis-attributing calls to the wrong step.
+ */
+const distributeToolCalls = (steps, toolCalls) => {
+    if (toolCalls.length !== flattenToolCalls(steps).length) {
+        return steps.map((step, index) => ({
+            ...step,
+            toolCalls: index === steps.length - 1 ? toolCalls : [],
+        }));
+    }
+    let cursor = 0;
+    return steps.map((step) => {
+        if (!step.toolCalls)
+            return step;
+        const next = toolCalls.slice(cursor, cursor + step.toolCalls.length);
+        cursor += step.toolCalls.length;
+        return { ...step, toolCalls: next };
+    });
+};
+/**
+ * Run the `modifyOutput` chain over a finished non-streaming run.
+ *
+ * Reverse order, matching the input chain: the middleware registered first
+ * wraps the others, so it sees the output last.
+ */
+export const applyOutputMiddleware = async (aiMiddlewares, singletonServices, input) => {
+    let text = input.text;
+    let messages = input.messages;
+    let steps = input.steps;
+    let toolCalls = flattenToolCalls(steps);
+    for (let i = aiMiddlewares.length - 1; i >= 0; i--) {
+        const mw = aiMiddlewares[i];
+        if (!mw.modifyOutput)
+            continue;
+        const result = await mw.modifyOutput(singletonServices, {
+            text,
+            messages,
+            usage: {
+                inputTokens: input.usage.inputTokens,
+                outputTokens: input.usage.outputTokens,
+            },
+            toolCalls,
+        });
+        text = result.text;
+        messages = result.messages;
+        if (result.toolCalls) {
+            toolCalls = result.toolCalls;
+            steps = distributeToolCalls(steps, toolCalls);
+        }
+    }
+    return { text, messages, steps };
+};
+/**
+ * The one place a run ends successfully.
+ *
+ * Every path that completes a run — streamed, non-streamed, and resumed after a
+ * tool approval — goes through here, so that anything terminal is reachable
+ * from all of them and cannot be reordered by a middleware author. Nothing here
+ * may rewrite the run: by this point the output middleware has resolved and, on
+ * the streaming path, the client already has the reply.
+ */
+export const finalizeAgentRun = async (aiRunState, run) => {
+    await aiRunState.updateRun(run.runId, {
+        status: 'completed',
+        ...(run.usage.model
+            ? {
+                usage: {
+                    inputTokens: run.usage.inputTokens,
+                    outputTokens: run.usage.outputTokens,
+                    model: run.usage.model,
+                },
+            }
+            : {}),
+    });
+    // Read rather than `getSingletonServices()`: a process that never registered
+    // them grades nothing, which is not an error at the point a run has already
+    // succeeded.
+    const services = pikkuState(null, 'package', 'singletonServices');
+    if (!services)
+        return;
+    const snapshot = {
+        runId: run.runId,
+        agentName: run.agentName,
+        threadId: run.threadId,
+        ...(run.resourceId !== undefined ? { resourceId: run.resourceId } : {}),
+        input: run.input,
+        output: run.text,
+        toolCalls: run.steps.flatMap((step) => (step.toolCalls ?? []).map((call) => ({
+            name: call.name,
+            args: call.args,
+            result: call.result,
+            ...(call.error !== undefined ? { error: call.error } : {}),
+        }))),
+        usage: {
+            inputTokens: run.usage.inputTokens,
+            outputTokens: run.usage.outputTokens,
+            ...(run.usage.model !== undefined ? { model: run.usage.model } : {}),
+        },
+    };
+    // The same object a scenario grades, so an asserted score and a sampled one
+    // are the same measurement. A no-op unless a dev server turned retention on.
+    recordScoreSnapshot(snapshot);
+    // Best-effort and last: the client already has its answer, so a grading
+    // failure must not surface as a failed run.
+    try {
+        await scoreFinishedRun(snapshot, services);
+    }
+    catch (error) {
+        services.logger?.error(`[pikku] Live scoring failed for run ${run.runId}`, error);
+    }
+};

package/dist/wirings/ai-agent/ai-agent-interrupt.js

@@ -240,6 +240,7 @@ export const persistOrphanedToolResults = async (handle, storage, threadId) => {
                     : typeof entry.result === 'string'
                         ? entry.result
                         : JSON.stringify(entry.result),
+                ...(entry.error ? { error: entry.error } : {}),
             })),
             undelivered: true,
             createdAt: new Date(),

package/dist/wirings/ai-agent/ai-agent-memory.d.ts

@@ -1,5 +1,5 @@
 import type { CoreSingletonServices } from '../../types/core.types.js';
-import type { CoreAIAgent, AIAgentMemoryConfig, AIAgentInput, AIMessage } from './ai-agent.types.js';
+import type { CoreAIAgent, AIAgentMemoryConfig, AIAgentInput, AIAgentStep, AIMessage } from './ai-agent.types.js';
 import type { AIStorageService } from '../../services/ai-storage-service.js';
 import type { Logger } from '../../services/logger.js';
 import type { SchemaService } from '../../services/schema-service.js';
@@ -14,13 +14,7 @@ export declare function loadContextMessages(memoryConfig: AIAgentMemoryConfig |
 export declare function saveMessages(storage: AIStorageService | undefined, threadId: string, resourceId: string, memoryConfig: AIAgentMemoryConfig | undefined, userMessage: AIMessage | null | undefined, result: {
     text: string;
     uiSpec?: unknown;
-    steps: {
-        toolCalls?: {
-            name: string;
-            args: Record<string, unknown>;
-            result: string;
-        }[];
-    }[];
+    steps: Pick<AIAgentStep, 'toolCalls'>[];
 }): Promise<string>;
 export declare function trimMessages(messages: AIMessage[], maxTokenBudget?: number): AIMessage[];
 export declare function parseWorkingMemory(text: string): Record<string, unknown> | null;

package/dist/wirings/ai-agent/ai-agent-memory.js

@@ -2,7 +2,9 @@ import { randomUUID } from 'crypto';
 export function resolveMemoryServices(agent, singletonServices) {
     const memoryConfig = agent.memory;
     const storage = memoryConfig?.storage
-        ? singletonServices[memoryConfig.storage]
+        ? // The service is named by string in agent config, so the lookup cannot be
+            // checked — only the shape it is required to have.
+            singletonServices[memoryConfig.storage]
         : singletonServices.aiStorage;
     return { storage };
 }
@@ -100,6 +102,7 @@ export async function saveMessages(storage, threadId, resourceId, memoryConfig,
                         id: toolCallIds[i],
                         name: tc.name,
                         result: tc.result,
+                        ...(tc.error ? { error: tc.error } : {}),
                     })),
                     createdAt: new Date(),
                 });
@@ -254,9 +257,39 @@ export function stripWorkingMemoryForStreaming(text) {
     }
     return output;
 }
+async function persistWorkingMemory(options, workingMemory) {
+    if (!options.storage)
+        return;
+    const existing = (await options.storage.getWorkingMemory(options.threadId, 'thread')) ?? {};
+    const merged = deepMergeWorkingMemory(existing, workingMemory);
+    if (options.schemaService && options.workingMemorySchemaName) {
+        try {
+            await options.schemaService.validateSchema(options.workingMemorySchemaName, merged);
+        }
+        catch (err) {
+            options.logger?.warn(`Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+    }
+    await options.storage.saveWorkingMemory(options.threadId, 'thread', merged);
+}
 export function createWorkingMemoryMiddleware(options) {
     return {
         modifyOutputStream: async (_services, { event, state }) => {
+            // A streamed step ends at its `usage` event, or at `done` for a model
+            // that reports no usage. That is the last moment the unstripped text is
+            // still reachable: it lives only in `state.rawText`, because the strip
+            // below runs before anything downstream — including the channel that
+            // accumulates what `modifyOutput` would later be handed.
+            if (event.type === 'usage' || event.type === 'done') {
+                const { workingMemory } = extractWorkingMemory(state.rawText ?? '');
+                state.rawText = '';
+                state.emittedVisibleText = '';
+                if (workingMemory) {
+                    await persistWorkingMemory(options, workingMemory);
+                }
+                return event;
+            }
             if (event.type !== 'text-delta')
                 return event;
             const rawText = `${state.rawText ?? ''}${event.text}`;
@@ -273,24 +306,10 @@ export function createWorkingMemoryMiddleware(options) {
                 return null;
             return { ...event, text: delta };
         },
-        modifyOutput: async (_services, { text, messages, usage }) => {
+        modifyOutput: async (_services, { text, messages }) => {
             const { workingMemory, cleanedText } = extractWorkingMemory(text);
-            if (workingMemory && options.storage) {
-                const existing = (await options.storage.getWorkingMemory(options.threadId, 'thread')) ?? {};
-                const merged = deepMergeWorkingMemory(existing, workingMemory);
-                let valid = true;
-                if (options.schemaService && options.workingMemorySchemaName) {
-                    try {
-                        await options.schemaService.validateSchema(options.workingMemorySchemaName, merged);
-                    }
-                    catch (err) {
-                        valid = false;
-                        options.logger?.warn(`Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`);
-                    }
-                }
-                if (valid) {
-                    await options.storage.saveWorkingMemory(options.threadId, 'thread', merged);
-                }
+            if (workingMemory) {
+                await persistWorkingMemory(options, workingMemory);
             }
             return {
                 text: cleanedText,

package/dist/wirings/ai-agent/ai-agent-model-config.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Resolves a model name to a concrete `provider/model`. Aliases come from the
+ * `models` table in pikku.config.json; a name containing `/` is already
+ * concrete. Read from the main package, not the calling addon's — which model
+ * a tier points at is the hosting app's decision.
+ */
+export declare const resolveModelAlias: (model: string) => string;
 export declare function resolveModelConfig(_agentName: string, agent: {
     model: string;
     temperature?: number;

package/dist/wirings/ai-agent/ai-agent-model-config.js

@@ -1,7 +1,50 @@
 // knowledge: decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md
+import { pikkuState } from '../../pikku-state.js';
+const isProviderQualified = (model) => model.includes('/');
+/** `PIKKU_MODEL_ALIASES=cheap:openai/gpt-5-mini,tool:anthropic/claude-sonnet-5` */
+const envAliases = () => {
+    const raw = process.env.PIKKU_MODEL_ALIASES;
+    if (!raw)
+        return {};
+    const aliases = {};
+    for (const entry of raw.split(',')) {
+        // First colon only — a model id may contain its own.
+        const separator = entry.indexOf(':');
+        if (separator === -1)
+            continue;
+        const alias = entry.slice(0, separator).trim();
+        const model = entry.slice(separator + 1).trim();
+        if (alias && model)
+            aliases[alias] = model;
+    }
+    return aliases;
+};
+/**
+ * Resolves a model name to a concrete `provider/model`. Aliases come from the
+ * `models` table in pikku.config.json; a name containing `/` is already
+ * concrete. Read from the main package, not the calling addon's — which model
+ * a tier points at is the hosting app's decision.
+ */
+export const resolveModelAlias = (model) => {
+    if (isProviderQualified(model))
+        return model;
+    const generated = pikkuState(null, 'agent', 'modelAliases');
+    const override = envAliases()[model];
+    const resolved = override ?? generated[model];
+    if (!resolved) {
+        const known = Object.keys({ ...generated, ...envAliases() }).sort();
+        throw new Error(`Unknown model alias '${model}'. ` +
+            (known.length
+                ? `Known aliases: ${known.join(', ')}. `
+                : `No aliases are configured. `) +
+            `Add it to the "models" table in pikku.config.json, or name a ` +
+            `provider-qualified model such as 'openai/gpt-5-mini'.`);
+    }
+    return resolved;
+};
 export function resolveModelConfig(_agentName, agent) {
     return {
-        model: agent.model,
+        model: resolveModelAlias(agent.model),
         temperature: agent.temperature,
         maxSteps: agent.maxSteps,
     };

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -1,5 +1,5 @@
 import { PikkuError } from '../../errors/error-handler.js';
-import { checkAuthPermissions, runPermissions } from '../../permissions.js';
+import { checkAuthPermissions, runPermissions, } from '../../permissions.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { ForbiddenError } from '../../errors/errors.js';
 import { verifyScopes } from '../../scopes.js';
@@ -357,6 +357,8 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     secretOverrides: capturedAddonConfig?.secretOverrides,
                                     variableOverrides: capturedAddonConfig?.variableOverrides,
                                     credentialOverrides: capturedAddonConfig?.credentialOverrides,
+                                    globalSecrets: capturedAddonConfig?.globalSecrets,
+                                    globalCredentials: capturedAddonConfig?.globalCredentials,
                                 }
                                 : undefined;
                             services = await getOrCreatePackageSingletonServices(capturedPkg, singletonServices, addonInstance);
@@ -648,10 +650,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     }
     let messages = [];
     if (storage) {
-        // A tool whose run was interrupted may still be writing its result to this
-        // thread. In voice the next turn lands within a second or two, so without
-        // this the model would load context that is missing the very thing it is
-        // about to be asked about.
+        // knowledge: decisions/internals/agent-context-waits-for-a-tool-result-still-being-written.md
         await awaitPendingInterruptNote(threadId);
         messages = await storage.getMessages(threadId, {
             lastN: memoryConfig?.lastMessages ?? 20,
@@ -660,10 +659,7 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const contextMessages = await loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema);
     const userContent = input.attachments?.length
         ? [
-            // Omitted when there is nothing to say. An attachment on its own is a
-            // real turn — a spoken one carries audio and no text at all — and an
-            // empty text part alongside it is a part providers are entitled to
-            // reject, for a caller who never wrote one.
+            // knowledge: decisions/internals/an-empty-text-part-is-omitted-from-an-agent-message.md
             ...(input.message
                 ? [{ type: 'text', text: input.message }]
                 : []),