@pikku/core 0.12.86 → 0.12.88

package/CHANGELOG.md

@@ -1,3 +1,82 @@
+## 0.12.88
+
+### Patch Changes
+
+- 4712e73: fix: collect working memory from a delegate-mode parent agent
+
+  A delegating parent's `text-delta` events were dropped at the outermost output
+  channel, above the working-memory hook, so every `<working_memory>` block it
+  wrote from its first hand-off onward was discarded before anything could read
+  it. The parent's text is now routed through the working-memory hook and into a
+  sink instead of being dropped outright, so the blocks are collected while the
+  client, the thread history and user channel middleware still see nothing.
+
+  The resume path built no delegate filter at all and streamed a delegating
+  parent's text to the client after an approval; it now suppresses text the same
+  way the initial path does.
+
+  The AI SDK rejects a system message inside `messages` outright, so the working
+  memory prompt the framework injects as one failed every run that enabled
+  working memory at all. The runner now lifts system messages onto the `system`
+  option, after the agent's own instructions.
+
+- 082403f: fix(agent): make working-memory array semantics explicit
+
+  `deepMergeWorkingMemory` replaced arrays wholesale as a side effect of its
+  object-recursion guard, so nothing in the code said whether that was the
+  contract or an accident. The merge now handles arrays in an explicit,
+  documented branch. Replace is kept over append: the full state is echoed back
+  every turn, so appending would duplicate every item whenever the model re-emitted
+  the array.
+
+  `buildWorkingMemoryPrompt` now states that contract to the model rather than
+  leaving "only include changed fields" to be read as permission to send a partial
+  array. This is defensive: measured against `gpt-4.1-mini` the wording changes
+  nothing, because that model already re-emits the whole list. It is there for
+  models that do not.
+
+## 0.12.87
+
+### Patch Changes
+
+- 9687ad1: fix: hand agent middleware the singleton services its type promises
+
+  `PikkuAgentMiddlewareHooks` typed its `services` parameter as the project's full
+  wire `Services`, while every runtime call site has only ever passed the singleton
+  services. A middleware that destructured a wire service typechecked and silently
+  received `undefined`.
+
+  The hooks are now bounded by `CoreSingletonServices` in core, and the generated
+  `pikkuAgentMiddleware` defaults to `WiredSingletonServices` like the other
+  middleware definers. Nothing changes at runtime: agent middleware hooks a _run_,
+  and a run is not a request — it can start from a scheduler or a workflow with no
+  wire behind it. A tool the run calls is an ordinary function call and still gets
+  its own wire services through `runPikkuFunc`.
+
+- 2d21628: fix(kysely): claim a workflow step atomically in every SQL dialect
+
+  The workflow engine's "atomic claim" was a read-then-write guarded by
+  `withStepLock`, and `@pikku/kysely` inherited a silent pass-through for that
+  lock — so on every dialect but Postgres and MySQL a redelivered queue job could
+  claim a step another dispatch was already running, executing a side-effecting
+  step twice.
+
+  `@pikku/kysely` now claims the step with a status-guarded `UPDATE` and reads the
+  affected-row count, which is atomic in every SQL dialect without an
+  advisory-lock primitive. Relay redispatch is enabled for all Kysely dialects as
+  a result, not just Postgres and MySQL.
+
+- 985b87b: Follow through on the variable `required` → `optional` rename: regenerate the
+  core API report and update the inspector's `defineVariable` gating-flag test,
+  both of which #1369 left describing the deleted `required` flag.
+- 3a83f85: Stop re-exporting package internals through entry points
+
+  66 names reached consumers only because an `export *` in an entry point swept
+  them up. Each one is referenced solely inside its own package, so the star is
+  now an explicit named re-export listing what is genuinely public. The
+  declarations themselves are untouched — this narrows the entry point, not the
+  module.
+
 ## 0.12.86
 
 ### Patch Changes

package/dist/dev/hot-reload.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '../services/logger.js';
-export * from './reload-meta.js';
+export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 interface PikkuDevReloaderOptions {
     srcDirectories: string[];
     logger: Logger;

package/dist/dev/hot-reload.js

@@ -7,7 +7,7 @@ import { clearPermissionsCache } from '../permissions.js';
 import { clearChannelMiddlewareCache } from '../wirings/channel/channel-middleware-runner.js';
 import { httpRouter } from '../wirings/http/routers/http-router.js';
 import { createModuleRunner } from './module-runner.js';
-export * from './reload-meta.js';
+export { reloadGeneratedMeta, reconcileAddonRegistry } from './reload-meta.js';
 const isFunctionConfig = (value) => {
     return (typeof value === 'object' &&
         value !== null &&

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
-export * from './core.types.js';
+export type { AuthInstance, CommonWireMeta, CoreConfig, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, CreateSingletonServices, CreateWireServices, GetCredential, PikkuWire, PikkuWiringTypes, PostgresConfig, SecretlessServices, SecurityAuditIssue, SecurityAuditReport, SecurityAuditSummary, SecurityAuditUpdate, SecuritySeverity, SecurityUpdateLevel, ServerLifecycle, WireServices, } from './core.types.js';
 export type * from './state.types.js';

package/dist/types/index.js

@@ -1 +1 @@
-export * from './core.types.js';
+export {};

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

@@ -8,6 +8,17 @@ export declare function resolveMemoryServices(agent: CoreAgent, singletonService
     storage: AgentStorageService | undefined;
 };
 export declare function isWorkingMemoryEnabled(memoryConfig: AgentMemoryConfig | undefined, storage: AgentStorageService | undefined): boolean;
+/**
+ * Merges a model-emitted working memory update into the stored state.
+ *
+ * Objects merge key by key, and `null` deletes a key. Arrays are replaced
+ * wholesale — deliberately, not as a side effect of the object guard below.
+ * The full state is echoed back to the model every turn by
+ * {@link buildWorkingMemoryPrompt}, so it can always re-emit an array in full,
+ * and appending instead would duplicate every item each time it did.
+ * `buildWorkingMemoryPrompt` states this contract to the model; the two must
+ * stay in agreement.
+ */
 export declare function deepMergeWorkingMemory(existing: Record<string, unknown>, updates: Record<string, unknown>): Record<string, unknown>;
 export declare function buildWorkingMemoryPrompt(currentState: Record<string, unknown> | null, jsonSchema?: Record<string, unknown>): string;
 export declare function loadContextMessages(memoryConfig: AgentMemoryConfig | undefined, storage: AgentStorageService | undefined, input: AgentInput, workingMemoryJsonSchema?: Record<string, unknown>): Promise<AgentMessage[]>;

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

@@ -11,6 +11,17 @@ export function resolveMemoryServices(agent, singletonServices) {
 export function isWorkingMemoryEnabled(memoryConfig, storage) {
     return !!memoryConfig?.workingMemory && !!storage;
 }
+/**
+ * Merges a model-emitted working memory update into the stored state.
+ *
+ * Objects merge key by key, and `null` deletes a key. Arrays are replaced
+ * wholesale — deliberately, not as a side effect of the object guard below.
+ * The full state is echoed back to the model every turn by
+ * {@link buildWorkingMemoryPrompt}, so it can always re-emit an array in full,
+ * and appending instead would duplicate every item each time it did.
+ * `buildWorkingMemoryPrompt` states this contract to the model; the two must
+ * stay in agreement.
+ */
 export function deepMergeWorkingMemory(existing, updates) {
     const result = { ...existing };
     for (const key of Object.keys(updates)) {
@@ -21,8 +32,10 @@ export function deepMergeWorkingMemory(existing, updates) {
         if (value === null) {
             delete result[key];
         }
+        else if (Array.isArray(value)) {
+            result[key] = value;
+        }
         else if (typeof value === 'object' &&
-            !Array.isArray(value) &&
             typeof result[key] === 'object' &&
             result[key] !== null &&
             !Array.isArray(result[key])) {
@@ -56,7 +69,9 @@ export function buildWorkingMemoryPrompt(currentState, jsonSchema) {
     parts.push('When you learn new information, output a partial JSON update in <working_memory> tags. ' +
         'Only include durable facts you have actually derived or the user has confirmed. ' +
         'Do not output templates, placeholders, or narration. ' +
-        'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it.');
+        'Only include changed fields. Leave unknown fields untouched. Set a field to null to delete it. ' +
+        'Arrays are replaced, not merged: to change one, repeat every item you want to keep alongside the new ones, ' +
+        'because any item you leave out is deleted.');
     return parts.join('\n\n');
 }
 export async function loadContextMessages(memoryConfig, storage, input, workingMemoryJsonSchema) {

package/dist/wirings/agent/agent-stream.js

@@ -203,6 +203,51 @@ async function postStreamCleanup(persistingChannel, agentRunState, runId, run) {
         usage: persistingChannel.totalUsage,
     });
 }
+/**
+ * Adapts `modifyOutputStream` hooks to channel middleware, one closure per
+ * hook so each keeps its own `state` and event log for the whole run.
+ */
+const toChannelStreamMiddleware = (hooks, sharedNotes, signal) => hooks
+    .filter((mw) => mw.modifyOutputStream)
+    .map((mw) => {
+    const state = {};
+    const allEvents = [];
+    return async (services, event, next) => {
+        allEvents.push(event);
+        const result = await mw.modifyOutputStream(services, {
+            event,
+            allEvents,
+            state,
+            shared: sharedNotes,
+            // Sends downstream directly, so a hook can hand back the fast event
+            // now and push the slow one when it is ready.
+            emit: next,
+            signal,
+        });
+        if (result == null)
+            return;
+        if (Array.isArray(result)) {
+            for (const r of result)
+                await next(r);
+        }
+        else {
+            await next(result);
+        }
+    };
+});
+/**
+ * The branch a delegating parent's own spoken text is routed down once it has
+ * handed off: the same working-memory hook instances as the main chain, so the
+ * in-band `<working_memory>` blocks are still collected, ending in a sink so
+ * neither the client, the thread history, nor user channel middleware sees
+ * text the parent was supposed to keep to itself.
+ *
+ * Routing at ingress rather than dropping further down the chain keeps the
+ * decision synchronous with the send: the working-memory hook is async, so a
+ * hand-off landing mid-flight would otherwise retroactively suppress text the
+ * parent spoke before it.
+ */
+const createWorkingMemoryOnlyChannel = (channel, services, workingMemoryMiddleware) => wrapChannelWithMiddleware({ channel: { ...channel, send: () => { } } }, services, workingMemoryMiddleware).channel;
 async function runStreamStepLoop(params) {
     const { agent, runnerParams, maxSteps, agentRunner, streamChannel, channel, agentMiddlewares, } = params;
     const singletonServices = getSingletonServices();
@@ -446,13 +491,14 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
         channel.send({ type: 'done' });
         return '';
     }
+    const workingMemoryMiddleware = getWorkingMemoryMiddleware(memoryConfig, storage, {
+        threadId,
+        workingMemorySchemaName,
+        logger: singletonServices.logger,
+        schemaService: singletonServices.schema,
+    });
     const agentMiddlewares = [
-        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
-            threadId,
-            workingMemorySchemaName,
-            logger: singletonServices.logger,
-            schemaService: singletonServices.schema,
-        }),
+        ...workingMemoryMiddleware,
         ...(agent.agentMiddleware ?? []),
     ];
     // One bag per run, shared by every middleware — see PikkuAgentMiddlewareHooks.
@@ -491,43 +537,25 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
         await storage.saveMessages(threadId, [persistedUserMessage]);
     }
     warnUnstreamedOutputHooks(agentName, agentMiddlewares, singletonServices.logger);
-    const streamMiddleware = agentMiddlewares
-        .filter((mw) => mw.modifyOutputStream)
-        .map((mw) => {
-        const state = {};
-        const allEvents = [];
-        return async (services, event, next) => {
-            allEvents.push(event);
-            const result = await mw.modifyOutputStream(services, {
-                event,
-                allEvents,
-                state,
-                shared: sharedNotes,
-                // Sends downstream directly, so a hook can hand back the fast event
-                // now and push the slow one when it is ready.
-                emit: next,
-                signal: interruptHandle.signal,
-            });
-            if (result == null)
-                return;
-            if (Array.isArray(result)) {
-                for (const r of result)
-                    await next(r);
-            }
-            else {
-                await next(result);
-            }
-        };
-    });
+    const workingMemoryStreamMiddleware = toChannelStreamMiddleware(workingMemoryMiddleware, sharedNotes, interruptHandle.signal);
+    const streamMiddleware = toChannelStreamMiddleware(agent.agentMiddleware ?? [], sharedNotes, interruptHandle.signal);
     const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
     const meta = agentsMeta[resolvedName];
-    const allChannelMiddleware = combineChannelMiddleware('agent', `stream:${agentName}`, {
-        wireInheritedChannelMiddleware: meta?.channelMiddleware,
-        wireChannelMiddleware: [
-            ...(agent.channelMiddleware ?? []),
-            ...streamMiddleware,
-        ],
-    });
+    const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length;
+    const delegateState = { delegated: false };
+    if (isDelegateMode) {
+        streamContext.delegateState = delegateState;
+    }
+    const allChannelMiddleware = [
+        ...workingMemoryStreamMiddleware,
+        ...combineChannelMiddleware('agent', `stream:${agentName}`, {
+            wireInheritedChannelMiddleware: meta?.channelMiddleware,
+            wireChannelMiddleware: [
+                ...(agent.channelMiddleware ?? []),
+                ...streamMiddleware,
+            ],
+        }),
+    ];
     const persistingChannel = createPersistingChannel(channel, storage, threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
@@ -545,21 +573,19 @@ export async function streamAgent(agentName, input, channel, params, agentSessio
             return wrappedChannel.send(event);
         },
     };
-    const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length;
-    const delegateState = { delegated: false };
-    if (isDelegateMode) {
-        streamContext.delegateState = delegateState;
-    }
+    const workingMemoryOnlyChannel = isDelegateMode && workingMemoryStreamMiddleware.length > 0
+        ? createWorkingMemoryOnlyChannel(channel, singletonServices, workingMemoryStreamMiddleware)
+        : undefined;
     const outputChannel = isDelegateMode
         ? {
             ...credentialFilteredChannel,
             send: (event) => {
                 if (delegateState.delegated &&
-                    (event.type === 'text-delta' || event.type === 'reasoning-delta'))
-                    return;
+                    (event.type === 'text-delta' || event.type === 'reasoning-delta')) {
+                    return workingMemoryOnlyChannel?.send(event);
+                }
                 return credentialFilteredChannel.send(event);
             },
-            delegateState,
         }
         : credentialFilteredChannel;
     try {
@@ -880,13 +906,14 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     const allMessages = [...contextMessages, ...messages];
     const trimmedMessages = trimMessages(allMessages);
     const instructions = await buildInstructions(resolvedName, packageName);
+    const workingMemoryMiddleware = getWorkingMemoryMiddleware(memoryConfig, storage, {
+        threadId: run.threadId,
+        workingMemorySchemaName,
+        logger: singletonServices.logger,
+        schemaService: singletonServices.schema,
+    });
     const agentMiddlewares = [
-        ...getWorkingMemoryMiddleware(memoryConfig, storage, {
-            threadId: run.threadId,
-            workingMemorySchemaName,
-            logger: singletonServices.logger,
-            schemaService: singletonServices.schema,
-        }),
+        ...workingMemoryMiddleware,
         ...(agent.agentMiddleware ?? []),
     ];
     // One bag per run, shared by every middleware — see PikkuAgentMiddlewareHooks.
@@ -895,46 +922,43 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
     // knowledge: decisions/internals/a-resumed-agent-turn-is-as-interruptible-as-the-first.md
     const interruptHandle = registerInterruptibleRun(run.runId);
     warnUnstreamedOutputHooks(run.agentName, agentMiddlewares, singletonServices.logger);
-    const streamMiddleware = agentMiddlewares
-        .filter((mw) => mw.modifyOutputStream)
-        .map((mw) => {
-        const state = {};
-        const allEvents = [];
-        return async (services, event, next) => {
-            allEvents.push(event);
-            const result = await mw.modifyOutputStream(services, {
-                event,
-                allEvents,
-                state,
-                shared: sharedNotes,
-                // Sends downstream directly, so a hook can hand back the fast event
-                // now and push the slow one when it is ready.
-                emit: next,
-                signal: interruptHandle.signal,
-            });
-            if (result == null)
-                return;
-            if (Array.isArray(result)) {
-                for (const r of result)
-                    await next(r);
-            }
-            else {
-                await next(result);
-            }
-        };
-    });
-    const allChannelMiddleware = combineChannelMiddleware('agent', `stream:${run.agentName}`, {
-        wireInheritedChannelMiddleware: meta?.channelMiddleware,
-        wireChannelMiddleware: [
-            ...(agent.channelMiddleware ?? []),
-            ...streamMiddleware,
-        ],
-    });
+    const workingMemoryStreamMiddleware = toChannelStreamMiddleware(workingMemoryMiddleware, sharedNotes, interruptHandle.signal);
+    const streamMiddleware = toChannelStreamMiddleware(agent.agentMiddleware ?? [], sharedNotes, interruptHandle.signal);
+    const allChannelMiddleware = [
+        ...workingMemoryStreamMiddleware,
+        ...combineChannelMiddleware('agent', `stream:${run.agentName}`, {
+            wireInheritedChannelMiddleware: meta?.channelMiddleware,
+            wireChannelMiddleware: [
+                ...(agent.channelMiddleware ?? []),
+                ...streamMiddleware,
+            ],
+        }),
+    ];
     const persistingChannel = createPersistingChannel(channel, storage, run.threadId, singletonServices.logger);
     const wrappedChannel = allChannelMiddleware.length > 0
         ? wrapChannelWithMiddleware({ channel: persistingChannel }, singletonServices, allChannelMiddleware).channel
         : persistingChannel;
+    const isDelegateMode = agent.agentMode !== 'supervise' && meta?.agents?.length;
+    const delegateState = { delegated: false };
     const streamContext = { channel, options };
+    if (isDelegateMode) {
+        streamContext.delegateState = delegateState;
+    }
+    const workingMemoryOnlyChannel = isDelegateMode && workingMemoryStreamMiddleware.length > 0
+        ? createWorkingMemoryOnlyChannel(channel, singletonServices, workingMemoryStreamMiddleware)
+        : undefined;
+    const outputChannel = isDelegateMode
+        ? {
+            ...wrappedChannel,
+            send: (event) => {
+                if (delegateState.delegated &&
+                    (event.type === 'text-delta' || event.type === 'reasoning-delta')) {
+                    return workingMemoryOnlyChannel?.send(event);
+                }
+                return wrappedChannel.send(event);
+            },
+        }
+        : wrappedChannel;
     const resumeTools = (await buildToolDefs(params, new Map(), run.resourceId, resolvedName, packageName, streamContext, agentMiddlewares)).tools;
     const resolved = resolveModelConfig(resolvedName, agent);
     const maxSteps = resolved.maxSteps ?? 10;
@@ -959,7 +983,7 @@ async function continueAfterToolResult(run, agent, packageName, resolvedName, st
             runnerParams,
             maxSteps,
             agentRunner,
-            streamChannel: wrappedChannel,
+            streamChannel: outputChannel,
             persistingChannel,
             channel,
             agentMiddlewares,

package/dist/wirings/agent/agent.types.d.ts

@@ -1,5 +1,6 @@
 import type { CorePermissionGroup, CorePikkuPermission } from '../../function/functions.types.js';
 import type { CorePikkuMiddleware, MiddlewareMetadata } from '../../middleware/middleware.types.js';
+import type { CoreSingletonServices } from '../../types/core.types.js';
 import type { PermissionMetadata } from '../../function/function-meta.types.js';
 import type { AIProviderOptions } from '../../services/agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
@@ -169,8 +170,8 @@ export interface AgentToolDef extends Partial<ApprovalPolicy> {
      */
     forwardsApproval?: boolean;
 }
-export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, Services = any> {
-    modifyInput?: (services: Services, ctx: {
+export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown> = Record<string, unknown>, SingletonServices extends CoreSingletonServices = CoreSingletonServices> {
+    modifyInput?: (services: SingletonServices, ctx: {
         messages: AgentMessage[];
         instructions: string;
         /**
@@ -197,7 +198,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         messages: AgentMessage[];
         instructions: string;
     };
-    modifyOutputStream?: (services: Services, ctx: {
+    modifyOutputStream?: (services: SingletonServices, ctx: {
         event: AgentStreamEvent;
         allEvents: readonly AgentStreamEvent[];
         /** Private to this middleware, for this run. Cross-middleware facts go in `shared`. */
@@ -241,7 +242,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
      * and handed to anything that grades the run, and scrubbing the reply alone
      * leaves them untouched.
      */
-    modifyOutput?: (services: Services, ctx: {
+    modifyOutput?: (services: SingletonServices, ctx: {
         text: string;
         messages: AgentMessage[];
         usage: {
@@ -258,7 +259,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         messages: AgentMessage[];
         toolCalls?: NonNullable<AgentStep['toolCalls']>;
     };
-    beforeToolCall?: (services: Services, ctx: {
+    beforeToolCall?: (services: SingletonServices, ctx: {
         toolName: string;
         toolCallId: string;
         args: Record<string, unknown>;
@@ -267,7 +268,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
     } | void> | {
         args: Record<string, unknown>;
     } | void;
-    afterToolCall?: (services: Services, ctx: {
+    afterToolCall?: (services: SingletonServices, ctx: {
         toolName: string;
         toolCallId: string;
         args: Record<string, unknown>;
@@ -278,7 +279,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
     } | void> | {
         result: unknown;
     } | void;
-    afterStep?: (services: Services, ctx: {
+    afterStep?: (services: SingletonServices, ctx: {
         stepNumber: number;
         text: string;
         toolCalls: {
@@ -299,7 +300,7 @@ export interface PikkuAgentMiddlewareHooks<State extends Record<string, unknown>
         };
         finishReason: string;
     }) => Promise<void> | void;
-    onError?: (services: Services, ctx: {
+    onError?: (services: SingletonServices, ctx: {
         error: Error;
         stepNumber: number;
         messages: AgentMessage[];

package/dist/wirings/variable/validate-variable-definitions.js

@@ -24,7 +24,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                     description: def.description,
                     variableId: def.variableId,
                     schema: def.schema,
-                    required: def.required,
+                    optional: def.optional,
                     docsUrl: def.docsUrl,
                     sourceFile: def.sourceFile,
                 };
@@ -39,7 +39,7 @@ export function validateAndBuildVariableDefinitionsMeta(definitions, schemaLooku
                 description: def.description,
                 variableId: def.variableId,
                 schema: def.schema,
-                required: def.required,
+                optional: def.optional,
                 docsUrl: def.docsUrl,
                 sourceFile: def.sourceFile,
             };

package/dist/wirings/variable/variable.types.d.ts

@@ -5,13 +5,19 @@ export type CoreVariable<T = unknown> = {
     variableId: string;
     schema: T;
     /**
-     * A variable is OPTIONAL by default because `variables.get` returns
-     * `T | undefined` and never throws — every caller already handles absence, so
-     * a deploy gate that blocks on one contradicts the API. Mark a variable
-     * `required` for the few whose absence genuinely breaks the app; only those
-     * block a deploy.
+     * A variable is REQUIRED by default, and marking it `optional` is how a
+     * declaration says its absence is a supported state. Same flag, same
+     * polarity and same meaning as `CoreSecret.optional` — one word to learn
+     * rather than two with opposite senses.
+     *
+     * Defaulting to required rather than following `variables.get`'s
+     * `T | undefined` return is deliberate. That signature describes what a
+     * caller must HANDLE, not whether a deployment is correct without the value:
+     * an undefined feature flag is fine, an undefined API base URL is an outage
+     * that the type system cannot tell apart. Declaring the difference is the
+     * point of the flag, and the safe default for an undeclared one is to ask.
      */
-    required?: boolean;
+    optional?: boolean;
     docsUrl?: string;
 };
 export type VariableDefinitionMeta = {
@@ -20,7 +26,7 @@ export type VariableDefinitionMeta = {
     description?: string;
     variableId: string;
     schema?: Record<string, unknown> | string;
-    required?: boolean;
+    optional?: boolean;
     docsUrl?: string;
     sourceFile?: string;
 };

package/dist/wirings/workflow/pikku-scenario-service.d.ts

@@ -6,8 +6,8 @@ import type { ScenarioPersonas } from '../../services/personas-service.js';
 import type { ScenarioBrowserProvider, ScenarioEnvironment, ScenarioSurface } from './scenario-step.types.js';
 import type { PikkuWorkflowWire, WorkflowQueueOptions } from './workflow.types.js';
 export { addFeature, resolveFeatureScenarios } from './feature.js';
-export type * from './scenario.types.js';
-export type * from './scenario-run.types.js';
+export type { CoreFeature, CoreFeatureScenario, FeatureMeta, FeaturesMeta, PikkuBrowserWire, PikkuScenarioWire, ScenarioBrowserFailure, ScenarioBrowserProvider, ScenarioEnvironment, ScenarioStepKind, ScenarioStepMeta, ScenarioStepOptions, ScenarioStepPhase, ScenarioSurface, TestIdSelector, } from './scenario.types.js';
+export type { ScenarioArtifact, ScenarioFailureDetail, ScenarioResult, ScenarioRunRecord, ScenarioRunReport, ScenarioRunStatus, ScenarioRunStore, ScenarioRunSummary, ScenarioStepRow, } from './scenario-run.types.js';
 export { SCENARIO_SURFACES } from './scenario-step.types.js';
 export { resolveScenarioSurfaces } from './scenario-surface.js';
 export { pollUntil, type PollOptions } from './scenario-poll.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -105,12 +105,12 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      *
      * Returns nothing by default so a store that cannot express the query keeps
      * working unchanged — and, because it does not opt in, gains no re-dispatches
-     * either. A store must have an atomic `withStepLock` before overriding this,
-     * or no concurrency for one to exclude: the relay makes duplicate dispatch
-     * routine, and the claim in `executeWorkflowStepInner` is what keeps a
-     * duplicate from becoming a second execution. `kysely-postgres` and
-     * `kysely-mysql` qualify on the lock, `in-memory` on being inline and
-     * single-process; `mongodb` and `kysely-sqlite` qualify on neither.
+     * either. A store must have an atomic `claimStepForExecution` before
+     * overriding this, or no concurrency for one to exclude: the relay makes
+     * duplicate dispatch routine, and the claim is what keeps a duplicate from
+     * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
+     * status-guarded claim, `in-memory` on being inline and single-process;
+     * `mongodb` still qualifies on neither.
      */
     protected findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
         runId: string;
@@ -176,6 +176,20 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
     protected onChildWorkflowFailed(childRun: WorkflowRun, error: Error): Promise<void>;
     private runVersionMismatchFallback;
     executeWorkflowStep(runId: string, stepName: string, rpcName: string, data: any, rpcService: PikkuRPC): Promise<void>;
+    /**
+     * Take sole ownership of a step before it runs, returning the state to run
+     * under — or `null` when another dispatch already owns it.
+     *
+     * Dispatch is at-least-once by design: the relay re-dispatches steps it
+     * believes were dropped, and a queue can redeliver a job it already handed
+     * out. This is the one place that keeps a duplicate dispatch from becoming a
+     * second execution of a side-effecting step, so it is only as strong as the
+     * exclusion it is built on — and `withStepLock` excludes nothing unless the
+     * store backs it with a real primitive. A store able to express the decision
+     * as one conditional write should override this rather than reach for a lock,
+     * which is what `@pikku/kysely` does with a status-guarded `UPDATE`.
+     */
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
     private executeWorkflowStepInner;
     orchestrateWorkflow(runId: string, rpcService: PikkuRPC): Promise<void>;
     private verifyQueueService;