@pikku/core 0.12.80 → 0.12.83

package/dist/services/index.d.ts

@@ -1,8 +1,9 @@
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
-export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
+export { ScopedCredentialService } from './scoped-credential-service.js';
+export { PikkuSessionService, createMiddlewareSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
-export { PikkuCredentialWireService, createMiddlewareCredentialWireProps, createWireServicesCredentialWireProps, } from './credential-wire-service.js';
+export { PikkuCredentialWireService } 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';
@@ -16,11 +17,10 @@ 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 type { ContentService, SignContentKeyArgs, SignURLArgs, GetUploadURLArgs, UploadURLResult, BucketKeyArgs, WriteFileArgs, CopyFileArgs, } from './content-service.js';
-export type { ScenarioPersona, ResolvedPersona, ScenarioPersonaOf, ScenarioPersonas, ScenarioInvokeOptions, ScenarioRpcMap, ScenarioHttpResponse, } from './personas-service.js';
-export type { HttpPersonasConfig } from './http-personas.js';
+export type { ScenarioPersona, ResolvedPersona, ScenarioPersonas, } from './personas-service.js';
 export type { JWTService } from './jwt-service.js';
-export type { EmailService, EmailTemplateReference, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
-export { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptRecord, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
+export type { EmailService, SendEmailInput, SendEmailResult, SendHTMLEmailInput, SendTemplateEmailInput, SendTextEmailInput, } from './email-service.js';
+export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, type SendWebhookInput, type SendWebhookResult, type WebhookAttemptResult, type WebhookDeliveryRecord, type WebhookDeliveryWithAttempts, type WebhookJobData, type WebhookServiceConfig, } from './webhook-service.js';
 export type { Logger } from './logger.js';
 export type { SecretService, SecretValues } from './secret-service.js';
 export type { VariablesService } from './variables-service.js';
@@ -31,23 +31,22 @@ export type { TriggerService } from './trigger-service.js';
 export type { GatewayService } from './gateway-service.js';
 export type { DeploymentService, DeploymentConfig, DeploymentInfo, DeploymentServiceConfig, } from './deployment-service.js';
 export type { AIStorageService } from './ai-storage-service.js';
-export type { AIAgentRunnerParams, AIAgentRunnerResult, AIAgentStepResult, AIEmbedManyParams, AIEmbedManyResult, AIEmbedParams, AIEmbedResult, AIGenerateImageParams, AIGenerateImagePrompt, AIGenerateImageResult, AIGenerateSpeechParams, AIGenerateSpeechResult, AIProviderOptions, AIRerankParams, AIRerankResult, AITranscriptionParams, AITranscriptionResult, AIAgentRunnerService, } from './ai-agent-runner-service.js';
+export type { AIAgentRunnerParams, AIAgentRunnerResult, AIAgentStepResult, AIAgentRunnerService, } from './ai-agent-runner-service.js';
 export type { AIEmbeddingService } from './ai-embedding-service.js';
-export type { CreateRunInput, AIRunStateService, } from './ai-run-state-service.js';
-export type { CredentialStatus, CredentialMeta, } from './typed-secret-service.js';
+export type { CreateRunInput, SaveScoreInput, AIRunStateService, } from './ai-run-state-service.js';
+export type { CredentialMeta } from './typed-secret-service.js';
 export type { CredentialService } from './credential-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
-export type { CredentialStatusInfo, CredentialMetaInfo, } from './typed-credential-service.js';
-export type { VariableStatus, VariableMeta } from './typed-variables-service.js';
+export type { CredentialMetaInfo } from './typed-credential-service.js';
+export type { VariableMeta } from './typed-variables-service.js';
 export type { MetaService } from './meta-service.js';
 export type { SessionStore } from './session-store.js';
 export type { ScopeService, Role } from './scope-service.js';
-export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
 export type { IsSystemRole } from './system-role-guard.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './audit-service.js';
-export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditLogWriteInput, AuditOutcome, AuditService, AuditSource, AuditUserIdentity, ResolvedAuditConfig, } from './audit-service.js';
+export { NoopAuditService, createInvocationAudit } from './audit-service.js';
+export type { AuditConfig, AuditDurability, AuditEvent, AuditEventBatch, AuditLog, AuditService, AuditUserIdentity, 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, EmailsMeta, EmailTemplateMeta, EmailTemplateLocaleMeta, EmailTemplateAssets, } from './meta-service.js';
-export type { CoverageService, CoverageSnapshot, LineHits, ScriptCoverage, FunctionCoverage, CoverageRange, CoverageStatus, FunctionCoverageEntry, FunctionCoverageReport, CoverageFunctionMeta, } from './v8-coverage-service.js';
+export type { MCPMeta, RPCMetaRecord, ServiceMeta, ServicesMetaRecord, MiddlewareDefinitionMeta, MiddlewareInstanceMeta, GroupMeta, MiddlewareGroupsMeta, PermissionDefinitionMeta, PermissionsGroupsMeta, FunctionsMeta, FunctionMeta, MiddlewareMeta, PermissionMeta, AgentsMeta, AgentMeta, EmailsMeta, EmailTemplateMeta, } from './meta-service.js';
+export type { CoverageService, ScriptCoverage, FunctionCoverageEntry, FunctionCoverageReport, CoverageFunctionMeta, } from './v8-coverage-service.js';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, type StubCall, } from './stub-tracker.js';
 export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

package/dist/services/index.js

@@ -1,8 +1,9 @@
 export { LogLevel } from './logger.js';
 export { ScopedSecretService } from './scoped-secret-service.js';
-export { PikkuSessionService, createMiddlewareSessionWireProps, createFunctionSessionWireProps, } from './user-session-service.js';
+export { ScopedCredentialService } from './scoped-credential-service.js';
+export { PikkuSessionService, createMiddlewareSessionWireProps, } from './user-session-service.js';
 export { TypedSecretService } from './typed-secret-service.js';
-export { PikkuCredentialWireService, createMiddlewareCredentialWireProps, createWireServicesCredentialWireProps, } from './credential-wire-service.js';
+export { PikkuCredentialWireService } 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';
@@ -15,10 +16,9 @@ export { InMemoryQueueService } from './in-memory-queue-service.js';
 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 { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
+export { DEFAULT_WEBHOOK_RETRIES, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
 export { TypedCredentialService } from './typed-credential-service.js';
-export { assertRoleIsMutable, assertRoleNameAvailable, roleLockReason, } from './system-role-guard.js';
-export { NoopAuditService, createInvocationAudit, resolveAuditConfig, resolveAuditUserIdentityFromWire, } from './audit-service.js';
+export { NoopAuditService, createInvocationAudit } from './audit-service.js';
 export { InMemorySessionStore } from './in-memory-session-store.js';
 export { StubTracker, createStubProxy, getStubTracker, isTestRun, stub, spy, } from './stub-tracker.js';
 export { SecretHostNotAllowedError, assertSecretAllowedForHost, } from './secret-host-binding.js';

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

@@ -5,7 +5,8 @@ import type { ScheduledTasksMeta } from '../wirings/scheduler/scheduler.types.js
 import type { QueueWorkersMeta } from '../wirings/queue/queue.types.js';
 import type { CLIMeta } from '../wirings/cli/cli.types.js';
 import type { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
-import type { FeaturesMeta, WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
+import type { WorkflowsMeta } from '../wirings/workflow/workflow.types.js';
+import type { FeaturesMeta } from '../wirings/workflow/scenario.types.js';
 import type { ResolvedPersona } from './personas-service.js';
 import type { SystemRoleDefinitionsMeta } from '../wirings/role/role.types.js';
 import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.types.js';

package/dist/services/scoped-credential-service.d.ts

@@ -0,0 +1,21 @@
+import type { CredentialService } from './credential-service.js';
+/**
+ * A `CredentialService` narrowed to the credentials a package declared.
+ *
+ * Unlike `ScopedSecretService` this stays writable — an addon refreshing its
+ * own OAuth token is the normal case. What it cannot do is reach a credential
+ * it never declared, or enumerate the app's users.
+ */
+export declare class ScopedCredentialService implements CredentialService {
+    private credentials;
+    private allowedNames;
+    constructor(credentials: CredentialService, allowedNames: Set<string>);
+    private assertAllowed;
+    get<T = unknown>(name: string, userId?: string): Promise<T | null>;
+    set(name: string, value: unknown, userId?: string): Promise<void>;
+    delete(name: string, userId?: string): Promise<void>;
+    has(name: string, userId?: string): Promise<boolean>;
+    getAll(userId: string): Promise<Record<string, unknown>>;
+    getUsersWithCredential(name: string): Promise<string[]>;
+    getAllUsers(): Promise<string[]>;
+}

package/dist/services/scoped-credential-service.js

@@ -0,0 +1,53 @@
+/**
+ * A `CredentialService` narrowed to the credentials a package declared.
+ *
+ * Unlike `ScopedSecretService` this stays writable — an addon refreshing its
+ * own OAuth token is the normal case. What it cannot do is reach a credential
+ * it never declared, or enumerate the app's users.
+ */
+export class ScopedCredentialService {
+    credentials;
+    allowedNames;
+    constructor(credentials, allowedNames) {
+        this.credentials = credentials;
+        this.allowedNames = allowedNames;
+    }
+    assertAllowed(name) {
+        if (!this.allowedNames.has(name)) {
+            throw new Error(`Access denied to credential: ${name}`);
+        }
+    }
+    async get(name, userId) {
+        this.assertAllowed(name);
+        return this.credentials.get(name, userId);
+    }
+    async set(name, value, userId) {
+        this.assertAllowed(name);
+        return this.credentials.set(name, value, userId);
+    }
+    async delete(name, userId) {
+        this.assertAllowed(name);
+        return this.credentials.delete(name, userId);
+    }
+    async has(name, userId) {
+        this.assertAllowed(name);
+        return this.credentials.has(name, userId);
+    }
+    async getAll(userId) {
+        const all = await this.credentials.getAll(userId);
+        const scoped = {};
+        for (const name of this.allowedNames) {
+            if (name in all) {
+                scoped[name] = all[name];
+            }
+        }
+        return scoped;
+    }
+    async getUsersWithCredential(name) {
+        this.assertAllowed(name);
+        return this.credentials.getUsersWithCredential(name);
+    }
+    async getAllUsers() {
+        throw new Error('Access denied: enumerating users is not allowed in a scoped credential service');
+    }
+}

package/dist/testing/service-tests/ai-storage-service-tests.js

@@ -168,6 +168,82 @@ export const defineAiStorageServiceTests = (name, aiStorageService) => {
             assert.ok(runs.length >= 1);
             assert.ok(runs.every((r) => r.threadId === thread.id));
         });
+        test('saveScore and getScores', async () => {
+            const thread = await storage.createThread('resource-score');
+            const now = new Date();
+            const runId = await storage.createRun({
+                agentName: 'scored-agent',
+                threadId: thread.id,
+                resourceId: 'resource-score',
+                status: 'completed',
+                usage: { inputTokens: 10, outputTokens: 5, model: 'test' },
+                createdAt: now,
+                updatedAt: now,
+            });
+            await storage.saveScore({
+                runId,
+                scorerName: 'tool-error-rate',
+                score: 1,
+            });
+            await storage.saveScore({
+                runId,
+                scorerName: 'helpfulness',
+                score: 0.75,
+                reason: 'answered the question but skipped the fee',
+                metadata: { subScores: { accuracy: 0.9 }, judgeTokens: 412 },
+            });
+            const scores = await storage.getScores(runId);
+            assert.equal(scores.length, 2);
+            const byName = new Map(scores.map((s) => [s.scorerName, s]));
+            const clean = byName.get('tool-error-rate');
+            assert.ok(clean);
+            assert.equal(clean.score, 1);
+            assert.equal(clean.reason, undefined);
+            assert.equal(clean.metadata, undefined);
+            const helpful = byName.get('helpfulness');
+            assert.ok(helpful);
+            // A fractional score has to survive the round trip: an integer column
+            // would quietly turn every grade into 0 or 1.
+            assert.equal(helpful.score, 0.75);
+            assert.equal(helpful.reason, 'answered the question but skipped the fee');
+            assert.deepEqual(helpful.metadata, {
+                subScores: { accuracy: 0.9 },
+                judgeTokens: 412,
+            });
+            assert.ok(helpful.createdAt instanceof Date);
+        });
+        test('a re-grade appends rather than replacing the grade that was acted on', async () => {
+            const thread = await storage.createThread('resource-regrade');
+            const now = new Date();
+            const runId = await storage.createRun({
+                agentName: 'regraded-agent',
+                threadId: thread.id,
+                resourceId: 'resource-regrade',
+                status: 'completed',
+                usage: { inputTokens: 1, outputTokens: 1, model: 'test' },
+                createdAt: now,
+                updatedAt: now,
+            });
+            await storage.saveScore({ runId, scorerName: 'helpfulness', score: 0.2 });
+            await storage.saveScore({ runId, scorerName: 'helpfulness', score: 0.8 });
+            const scores = await storage.getScores(runId);
+            assert.equal(scores.length, 2);
+            assert.deepEqual(scores.map((s) => s.score), [0.2, 0.8]);
+        });
+        test('getScores is empty for a run nothing graded', async () => {
+            const thread = await storage.createThread('resource-ungraded');
+            const now = new Date();
+            const runId = await storage.createRun({
+                agentName: 'ungraded-agent',
+                threadId: thread.id,
+                resourceId: 'resource-ungraded',
+                status: 'completed',
+                usage: { inputTokens: 1, outputTokens: 1, model: 'test' },
+                createdAt: now,
+                updatedAt: now,
+            });
+            assert.deepEqual(await storage.getScores(runId), []);
+        });
         test('resolveApproval', async () => {
             const thread = await storage.createThread('resource-8');
             const now = new Date();

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

@@ -11,7 +11,8 @@ import type { PikkuMCP } from '../wirings/mcp/mcp.types.js';
 import type { PikkuScheduledTask } from '../wirings/scheduler/scheduler.types.js';
 import type { PikkuQueue, QueueService } from '../wirings/queue/queue.types.js';
 import type { PikkuCLI } from '../wirings/cli/cli.types.js';
-import type { PikkuWorkflowWire, PikkuScenarioWire, WorkflowService, WorkflowServiceConfig, WorkflowStepWire } from '../wirings/workflow/workflow.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 { PikkuGraphWire } from '../wirings/workflow/graph/workflow-graph.types.js';
 import type { PikkuTrigger } from '../wirings/trigger/trigger.types.js';
@@ -142,8 +143,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;

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

@@ -6,10 +6,12 @@ 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';
-import type { CoreWorkflow, CoreFeature, WorkflowsRuntimeMeta } from '../wirings/workflow/workflow.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 { CorePikkuChannelMiddleware } from '../wirings/channel/channel.types.js';
@@ -40,6 +42,14 @@ export interface PikkuPackageState {
             variableOverrides?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
             credentialOverrides?: Record<string, string>;
+            /** Secrets the host lends this instance, named as the addon reads them */
+            secretGrants?: string[];
+            /** Credentials the host lends this instance, named as the addon reads them */
+            credentialGrants?: 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 */
@@ -97,6 +107,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 +155,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/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

@@ -102,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(),
                 });
@@ -256,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}`;
@@ -275,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;