@pikku/core 0.12.78 → 0.12.80

package/dist/middleware/remote-auth.js

@@ -1,6 +1,15 @@
 import { UnauthorizedError } from '../errors/errors.js';
 import { pikkuMiddleware } from '../types/core.types.js';
 import { assertStrongKeyMaterial, decryptWithKeyMaterial, REMOTE_SESSION_INFO, } from '../crypto-utils.js';
+const REMOTE_RPC_PREFIX = '/remote/rpc/';
+/**
+ * Whether this request targets the remote-RPC surface. Compared case-insensitively
+ * because the router matches routes that way (path-to-regexp defaults to
+ * `sensitive: false`), so `/Remote/RPC/fn` reaches the same handler as
+ * `/remote/rpc/fn`. A case-sensitive check here let a case-varied path slip
+ * past the trust gate and the token's `fn` binding while still being dispatched.
+ */
+const isRemoteRpcPath = (path) => path.toLowerCase().startsWith(REMOTE_RPC_PREFIX);
 export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }, { http, setSession }, next) => {
     if (!http?.request || !secrets) {
         return next();
@@ -10,7 +19,7 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
         secret = (await secrets.getSecret('PIKKU_REMOTE_SECRET')).reveal();
     }
     catch {
-        if (http.request.path().startsWith('/remote/rpc/')) {
+        if (isRemoteRpcPath(http.request.path())) {
             throw new UnauthorizedError();
         }
         return next();
@@ -38,8 +47,10 @@ export const pikkuRemoteAuthMiddleware = pikkuMiddleware(async ({ secrets, jwt }
     if (payload?.aud !== 'pikku-remote') {
         throw new UnauthorizedError();
     }
-    if (payload?.fn && http.request.path().startsWith('/remote/rpc/')) {
-        const fn = decodeURIComponent(http.request.path().slice('/remote/rpc/'.length));
+    if (payload?.fn && isRemoteRpcPath(http.request.path())) {
+        // The prefix length is the same in any case, so slicing the raw path
+        // keeps the requested function name in its original case for the compare.
+        const fn = decodeURIComponent(http.request.path().slice(REMOTE_RPC_PREFIX.length));
         if (fn && payload.fn !== fn) {
             throw new UnauthorizedError();
         }

package/dist/permissions.d.ts

@@ -1,20 +1,18 @@
 import type { CoreServices, CoreUserSession, PikkuWire } from './types/core.types.js';
+import type { PikkuRPC } from './wirings/rpc/rpc-types.js';
+/**
+ * The wire a permission function sees. `Out = never` denies it `channel.send`.
+ *
+ * knowledge: decisions/security/a-permission-gets-a-wire-it-cannot-reply-on.md
+ */
+export type PermissionWire = PikkuWire<any, never, false, any, PikkuRPC, never, never>;
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
 export declare const addGlobalPermission: (permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
-/**
- * @deprecated Tag-level permissions were removed in #972 — permissions are now
- * function-scoped only (declare them on the function via `pikkuFunc({ permissions })`).
- * This throwing stub exists solely so the pinned bootstrap CLI (which still
- * generates an `addTagPermission` wrapper) can resolve the import at build time;
- * it is never called. Delete once `PIKKU_CLI_VERSION` in the CLI build is bumped
- * past the release that removes tag permissions.
- */
-export declare const addTagPermission: (_tag: string, _permissions: CorePermissionGroup | CorePikkuPermission[], _packageName?: string | null) => never;
 export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];
     services: CoreServices;
-    wire: PikkuWire<any, never, any, CoreUserSession, never, never, never>;
+    wire: PermissionWire;
     data: any;
     packageName?: string | null;
     /** What the non-global gate is called in debug logs, e.g. 'function', 'agent'. */

package/dist/permissions.js

@@ -40,17 +40,6 @@ export const addGlobalPermission = (permissions, packageName = null) => {
     clearPermissionsCache();
     return permissions;
 };
-/**
- * @deprecated Tag-level permissions were removed in #972 — permissions are now
- * function-scoped only (declare them on the function via `pikkuFunc({ permissions })`).
- * This throwing stub exists solely so the pinned bootstrap CLI (which still
- * generates an `addTagPermission` wrapper) can resolve the import at build time;
- * it is never called. Delete once `PIKKU_CLI_VERSION` in the CLI build is bumped
- * past the release that removes tag permissions.
- */
-export const addTagPermission = (_tag, _permissions, _packageName = null) => {
-    throw new Error('addTagPermission was removed in #972 — tag-level permissions no longer exist. Declare permissions on the function definition instead: pikkuFunc({ permissions }).');
-};
 const bucket = (packageName) => pikkuState(packageName, 'permissions', 'global') ?? [];
 /**
  * Global permissions in effect for a function, root ones first.

package/dist/pikku-state.js

@@ -1,10 +1,17 @@
 const PIKKU_STATE_KEY = Symbol.for('@pikku/core/state');
+/**
+ * State is parked on `globalThis` under a registered symbol so separate copies
+ * of @pikku/core in one process share it. Typed once here rather than at each
+ * access.
+ */
+const stateHost = globalThis;
 export const getAllPackageStates = () => {
-    if (!globalThis[PIKKU_STATE_KEY]) {
-        ;
-        globalThis[PIKKU_STATE_KEY] = new Map();
+    let states = stateHost[PIKKU_STATE_KEY];
+    if (!states) {
+        states = new Map();
+        stateHost[PIKKU_STATE_KEY] = states;
     }
-    return globalThis[PIKKU_STATE_KEY];
+    return states;
 };
 export const pikkuState = (packageName, type, content, value) => {
     const resolvedPackageName = packageName ?? '__main__';
@@ -120,7 +127,7 @@ export const initializePikkuState = (packageName) => {
 export const resetPikkuState = () => {
     // Error definitions come from module-import side effects that never re-run.
     const existingErrors = getAllPackageStates().get('__main__')?.misc.errors;
-    globalThis[PIKKU_STATE_KEY] = new Map();
+    stateHost[PIKKU_STATE_KEY] = new Map();
     initializePikkuState('__main__');
     if (existingErrors) {
         const mainState = getAllPackageStates().get('__main__');

package/dist/schema.js

@@ -98,6 +98,40 @@ export const coerceTopLevelDataFromSchema = (schemaName, data, packageName = nul
         }
     }
 };
+/**
+ * Drops object properties whose value is literally `undefined`.
+ *
+ * JSON Schema has no way to describe such a property, and the validator refuses
+ * the whole instance rather than reporting it — `{ a: undefined }` throws
+ * "Instances of \"undefined\" type are not supported" instead of validating.
+ *
+ * That matters because whether a payload can contain one depends on how the
+ * call travelled. Over HTTP `JSON.stringify` drops these keys before the
+ * request is built, so they never arrive. Dispatched in-process — an inline
+ * workflow step calling an RPC — the object is handed over as-is, and
+ * `{ retries: data.maybeRetries }` with the field omitted by the caller is
+ * enough to kill the step. Normalising here makes the two paths agree, and an
+ * explicitly-undefined *required* field now reports as the missing property it
+ * is rather than as an internal error.
+ *
+ * Deliberately not a JSON round-trip: `coerceTopLevelDataFromSchema` puts real
+ * `Date` instances on the data first, and stringifying would flatten them back
+ * to strings the validator has never been given.
+ */
+const stripUndefinedValues = (value) => {
+    if (Array.isArray(value))
+        return value.map(stripUndefinedValues);
+    if (value === null || typeof value !== 'object')
+        return value;
+    // Only plain objects: a Date, Map or class instance is data, not a bag of
+    // properties to be rewritten.
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .map(([key, entry]) => [key, stripUndefinedValues(entry)]));
+};
 export const validateSchema = async (logger, schemaService, schemaName, data, packageName = null) => {
     if (schemaService) {
         if (!schemaName) {
@@ -118,6 +152,6 @@ export const validateSchema = async (logger, schemaService, schemaName, data, pa
             throw new MissingSchemaError(`Schema '${schemaName}' not found. Ensure schema generation has been run.`);
         }
         await schemaService.compileSchema(key, schema);
-        await schemaService.validateSchema(key, data ?? {});
+        await schemaService.validateSchema(key, stripUndefinedValues(data ?? {}));
     }
 };

package/dist/services/ai-run-state-service.d.ts

@@ -5,7 +5,13 @@ export interface AIRunStateService {
     updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>;
     getRun(runId: string): Promise<AgentRunState | null>;
     getRunsByThread(threadId: string): Promise<AgentRunState[]>;
-    resolveApproval(toolCallId: string, status: 'approved' | 'denied'): Promise<void>;
+    /**
+     * Claims an approval: removes it from the run's pending list and records the
+     * decision, as one atomic step. Returns whether THIS caller made the claim —
+     * concurrent approvals of the same tool call produce exactly one `true`, and
+     * only that caller may run the tool.
+     */
+    resolveApproval(toolCallId: string, status: 'approved' | 'denied'): Promise<boolean>;
     findRunByToolCallId(toolCallId: string): Promise<{
         run: AgentRunState;
         approval: PendingApproval;

package/dist/services/in-memory-ai-run-state-service.d.ts

@@ -7,7 +7,7 @@ export declare class InMemoryAIRunStateService implements AIRunStateService {
     updateRun(runId: string, updates: Partial<AgentRunState>): Promise<void>;
     getRun(runId: string): Promise<AgentRunState | null>;
     getRunsByThread(threadId: string): Promise<AgentRunState[]>;
-    resolveApproval(toolCallId: string, status: 'approved' | 'denied'): Promise<void>;
+    resolveApproval(toolCallId: string, status: 'approved' | 'denied'): Promise<boolean>;
     findRunByToolCallId(toolCallId: string): Promise<{
         run: AgentRunState;
         approval: PendingApproval;

package/dist/services/in-memory-ai-run-state-service.js

@@ -25,10 +25,11 @@ export class InMemoryAIRunStateService {
                 if (approval) {
                     run.pendingApprovals = run.pendingApprovals.filter((a) => a.toolCallId !== toolCallId);
                     run.updatedAt = new Date();
-                    return;
+                    return true;
                 }
             }
         }
+        return false;
     }
     async findRunByToolCallId(toolCallId) {
         for (const run of this.runs.values()) {

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

@@ -29,6 +29,16 @@ export declare class InMemoryWorkflowService extends PikkuWorkflowService implem
     protected setStepErrorImpl(stepId: string, error: Error): Promise<void>;
     protected setStepChildRunIdImpl(stepId: string, childRunId: string): Promise<void>;
     protected createRetryAttemptImpl(failedStepId: string, status: 'pending' | 'running'): Promise<StepState>;
+    /**
+     * Safe to opt in despite the pass-through `withStepLock`: this service wires
+     * no queues and runs every step inline in one process, so the relay's
+     * redundant dispatch has no second holder to race with. See
+     * knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+     */
+    protected findUndispatchedSteps(before: Date, limit: number): Promise<Array<{
+        runId: string;
+        stepId: string;
+    }>>;
     protected findStalledRunIds(before: Date, limit: number): Promise<string[]>;
     listRuns(options?: {
         workflowName?: string;

package/dist/services/in-memory-workflow-service.js

@@ -74,6 +74,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         const step = {
             stepId,
             status: 'pending',
+            rpcName,
             attemptCount: 1,
             retries: stepOptions?.retries,
             retryDelay: stepOptions?.retryDelay,
@@ -177,6 +178,7 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         const newStep = {
             stepId: newStepId,
             status,
+            rpcName: failedStep.rpcName,
             attemptCount: failedStep.attemptCount + 1,
             retries: failedStep.retries,
             retryDelay: failedStep.retryDelay,
@@ -199,6 +201,29 @@ export class InMemoryWorkflowService extends PikkuWorkflowService {
         this.stepHistory.set(runId, history);
         return newStep;
     }
+    /**
+     * Safe to opt in despite the pass-through `withStepLock`: this service wires
+     * no queues and runs every step inline in one process, so the relay's
+     * redundant dispatch has no second holder to race with. See
+     * knowledge: decisions/internals/the-in-memory-workflow-service-is-inline-only-and-single-process.md
+     */
+    async findUndispatchedSteps(before, limit) {
+        const undispatched = [];
+        for (const [runId, run] of this.runs) {
+            if (run.status !== 'running')
+                continue;
+            for (const step of this.stepHistory.get(runId) ?? []) {
+                if (step.status !== 'pending')
+                    continue;
+                if (step.updatedAt >= before)
+                    continue;
+                undispatched.push({ runId, stepId: step.stepId });
+                if (undispatched.length >= limit)
+                    return undispatched;
+            }
+        }
+        return undispatched;
+    }
     async findStalledRunIds(before, limit) {
         const stalled = [];
         for (const [runId, run] of this.runs) {

package/dist/services/local-content-request-handler.d.ts

@@ -26,4 +26,25 @@ export type LocalContentRequestHandlerOptions = {
      */
     getJWT: () => JWTService | undefined;
 };
+export type SignedContentVerification = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    body: string;
+};
+/**
+ * Verifies a signed content URL — the one function that decides whether a
+ * signed read or a signed upload is genuine.
+ *
+ * Exported and shared so the runtimes that serve content (the core handler here,
+ * the node server, the express adapter) verify identically. They used to each
+ * carry their own copy, which is how the express upload path ended up with no
+ * check at all: one copy can rot or be forgotten in isolation.
+ *
+ * `onMissingJWT` is called at most where the caller wants to log the
+ * misconfiguration once; a signed request with no verifier is treated as
+ * invalid, never as trusted.
+ */
+export declare const verifySignedContentRequest: (requestUrl: URL, jwt: JWTService | undefined, onMissingJWT?: () => void) => Promise<SignedContentVerification>;
 export declare const createLocalContentRequestHandler: ({ content, logger, getJWT, }: LocalContentRequestHandlerOptions) => LocalContentRequestHandler;

package/dist/services/local-content-request-handler.js

@@ -36,69 +36,88 @@ const text = (status, body) => new Response(body, {
     status,
     headers: { 'content-type': 'text/plain; charset=utf-8' },
 });
+/**
+ * Verifies a signed content URL — the one function that decides whether a
+ * signed read or a signed upload is genuine.
+ *
+ * Exported and shared so the runtimes that serve content (the core handler here,
+ * the node server, the express adapter) verify identically. They used to each
+ * carry their own copy, which is how the express upload path ended up with no
+ * check at all: one copy can rot or be forgotten in isolation.
+ *
+ * `onMissingJWT` is called at most where the caller wants to log the
+ * misconfiguration once; a signed request with no verifier is treated as
+ * invalid, never as trusted.
+ */
+export const verifySignedContentRequest = async (requestUrl, jwt, onMissingJWT) => {
+    const signedAtValue = requestUrl.searchParams.get('signedAt');
+    const expiresAtValue = requestUrl.searchParams.get('expiresAt');
+    const notBeforeValue = requestUrl.searchParams.get('notBefore');
+    const signature = requestUrl.searchParams.get('signature');
+    if (!signedAtValue || !expiresAtValue) {
+        return { ok: false, status: 403, body: 'Signed URL required' };
+    }
+    const signedAt = Number(signedAtValue);
+    const expiresAt = Number(expiresAtValue);
+    const notBefore = notBeforeValue == null ? undefined : Number(notBeforeValue);
+    if (!Number.isFinite(signedAt) ||
+        !Number.isFinite(expiresAt) ||
+        (notBefore != null && !Number.isFinite(notBefore))) {
+        return { ok: false, status: 403, body: 'Invalid signed URL' };
+    }
+    const now = Date.now();
+    if (now > expiresAt || (notBefore != null && now < notBefore)) {
+        return { ok: false, status: 403, body: 'Signed URL expired' };
+    }
+    if (!jwt) {
+        onMissingJWT?.();
+        return { ok: false, status: 403, body: 'Invalid signed URL' };
+    }
+    if (!signature) {
+        return { ok: false, status: 403, body: 'Signed URL signature required' };
+    }
+    try {
+        const payload = await jwt.decode(signature);
+        // Every claim is compared, the path included: without it a signature
+        // minted for one asset would read any other.
+        if (payload.signedAt !== signedAt ||
+            payload.expiresAt !== expiresAt ||
+            payload.notBefore !== notBefore ||
+            payload.path !== signedContentPath(requestUrl.pathname)) {
+            return { ok: false, status: 403, body: 'Invalid signed URL' };
+        }
+    }
+    catch {
+        return { ok: false, status: 403, body: 'Invalid signed URL' };
+    }
+    return { ok: true };
+};
 export const createLocalContentRequestHandler = ({ content, logger, getJWT, }) => {
     // Logged at most once. An unverifiable request is attacker-triggerable, so
     // this reports a startup misconfiguration rather than per-request news.
     let loggedMissingJWT = false;
-    const validateSignedAssetRequest = async (requestUrl) => {
-        const signedAtValue = requestUrl.searchParams.get('signedAt');
-        const expiresAtValue = requestUrl.searchParams.get('expiresAt');
-        const notBeforeValue = requestUrl.searchParams.get('notBefore');
-        const signature = requestUrl.searchParams.get('signature');
-        if (!signedAtValue || !expiresAtValue) {
-            return { ok: false, status: 403, body: 'Signed URL required' };
-        }
-        const signedAt = Number(signedAtValue);
-        const expiresAt = Number(expiresAtValue);
-        const notBefore = notBeforeValue == null ? undefined : Number(notBeforeValue);
-        if (!Number.isFinite(signedAt) ||
-            !Number.isFinite(expiresAt) ||
-            (notBefore != null && !Number.isFinite(notBefore))) {
-            return { ok: false, status: 403, body: 'Invalid signed URL' };
-        }
-        const now = Date.now();
-        if (now > expiresAt || (notBefore != null && now < notBefore)) {
-            return { ok: false, status: 403, body: 'Signed URL expired' };
-        }
-        const jwt = getJWT();
-        if (!jwt) {
-            if (!loggedMissingJWT) {
-                loggedMissingJWT = true;
-                logger.error('pikku: refusing signed asset reads — no JWTService is available to verify them. Pass `contentSigningJWT` (the same service LocalContent signs with) or expose it as `singletonServices.jwt`.');
-            }
-            return { ok: false, status: 403, body: 'Invalid signed URL' };
-        }
-        if (!signature) {
-            return { ok: false, status: 403, body: 'Signed URL signature required' };
-        }
-        try {
-            const payload = await jwt.decode(signature);
-            // Every claim is compared, the path included: without it a signature
-            // minted for one asset would read any other.
-            if (payload.signedAt !== signedAt ||
-                payload.expiresAt !== expiresAt ||
-                payload.notBefore !== notBefore ||
-                payload.path !== signedContentPath(requestUrl.pathname)) {
-                return { ok: false, status: 403, body: 'Invalid signed URL' };
-            }
-        }
-        catch {
-            return { ok: false, status: 403, body: 'Invalid signed URL' };
+    const validateSignedAssetRequest = (requestUrl) => verifySignedContentRequest(requestUrl, getJWT(), () => {
+        if (loggedMissingJWT)
+            return;
+        loggedMissingJWT = true;
+        logger.error('pikku: refusing signed asset reads — no JWTService is available to verify them. Pass `contentSigningJWT` (the same service LocalContent signs with) or expose it as `singletonServices.jwt`.');
+    });
+    const handleUpload = async (request, requestUrl, pathname) => {
+        // Uploads are presigned exactly like reads: getUploadURL mints a signed URL
+        // and this verifies it before writing. Without this an unauthenticated PUT
+        // could write arbitrary bytes to any key under the content root — the write
+        // side had none of the signature checking the read side has always had.
+        const signed = await validateSignedAssetRequest(requestUrl);
+        if (!signed.ok) {
+            return text(signed.status, signed.body);
         }
-        return { ok: true };
-    };
-    const handleUpload = async (request, pathname) => {
         const key = contentKey(pathname, content.uploadUrlPrefix);
         const targetPath = toTargetPath(content.localFileUploadPath, key);
         if (!targetPath) {
             return text(400, 'Invalid path');
         }
         const maxBytes = parseSizeLimit(content.sizeLimit ?? '1mb');
-        // Counted as it arrives and abandoned the moment it goes over, so an
-        // oversized upload costs the limit rather than its own size — `arrayBuffer()`
-        // would have to hold all of it first, which hands an unauthenticated caller
-        // a way to spend the server's memory. Mirrors node-http-server's
-        // `readRequestBody`, which aborts the same way.
+        // knowledge: decisions/security/an-upload-is-counted-as-it-arrives-not-buffered-then-measured.md
         const chunks = [];
         let bytesRead = 0;
         const reader = request.body?.getReader();
@@ -165,7 +184,7 @@ export const createLocalContentRequestHandler = ({ content, logger, getJWT, }) =
         const pathname = decodeURIComponent(requestUrl.pathname);
         if (request.method === 'PUT' &&
             matchesPrefix(pathname, content.uploadUrlPrefix)) {
-            return handleUpload(request, pathname);
+            return handleUpload(request, requestUrl, pathname);
         }
         if ((request.method === 'GET' || request.method === 'HEAD') &&
             matchesPrefix(pathname, content.assetUrlPrefix)) {

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

@@ -28,6 +28,12 @@ export declare class LocalContent implements ContentService {
     private signParams;
     signURL(args: SignURLArgs): Promise<string>;
     signContentKey(args: SignContentKeyArgs): Promise<string>;
+    /**
+     * Presigned upload, mirroring the read side: the URL carries a short-lived,
+     * path-bound signature that {@link createLocalContentRequestHandler} verifies
+     * before writing. An unsigned upload URL cannot be verified, and the handler
+     * now refuses one — so this must sign, or every upload 403s.
+     */
     getUploadURL(args: GetUploadURLArgs): Promise<UploadURLResult>;
     writeFile(args: WriteFileArgs): Promise<boolean>;
     copyFile(args: CopyFileArgs): Promise<boolean>;

package/dist/services/local-content.js

@@ -27,6 +27,8 @@ export const signedContentPath = (urlOrPath) => {
         return pathname;
     }
 };
+/** How long a presigned upload URL stays valid. Short, like an S3 PUT URL. */
+const UPLOAD_URL_TTL_MS = 15 * 60 * 1000;
 export class LocalContent {
     config;
     logger;
@@ -90,13 +92,24 @@ export class LocalContent {
             dateGreaterThan: args.dateGreaterThan,
         });
     }
+    /**
+     * Presigned upload, mirroring the read side: the URL carries a short-lived,
+     * path-bound signature that {@link createLocalContentRequestHandler} verifies
+     * before writing. An unsigned upload URL cannot be verified, and the handler
+     * now refuses one — so this must sign, or every upload 403s.
+     */
     async getUploadURL(args) {
         void args.visibility;
         const fullKey = this.joinKey(args.bucket, args.fileKey);
         this.logger.debug(`Going to upload with key: ${fullKey}`);
+        const uploadUrl = await this.signURL({
+            url: `${this.config.uploadUrlPrefix}/${fullKey}`,
+            dateLessThan: new Date(Date.now() + UPLOAD_URL_TTL_MS),
+        });
         return {
-            uploadUrl: `${this.config.uploadUrlPrefix}/${fullKey}`,
+            uploadUrl,
             assetKey: fullKey,
+            uploadMethod: 'PUT',
         };
     }
     async writeFile(args) {

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

@@ -1,4 +1,4 @@
-import type { SerializedError } from '../types/core.types.js';
+import type { CoreUserSession, SerializedError } from '../types/core.types.js';
 import type { WorkflowRun, WorkflowPlannedStep, WorkflowRunWire, WorkflowRunStatus, StepState, WorkflowStatus, WorkflowVersionStatus } from '../wirings/workflow/workflow.types.js';
 import type { RunTimeline, ReconstructedRunState } from '../wirings/workflow/run-timeline.js';
 export interface WorkflowService {
@@ -21,8 +21,10 @@ export interface WorkflowService {
     /**
      * The payload is stored as given and validated on replay inside the workflow
      * body, so an invalid one re-closes the gate rather than failing the run.
+     *
+     * The session must belong to the run's owner — see `assertWorkflowRunOwner`.
      */
-    approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
+    approveStep(runId: string, reason: string, decision: unknown, session?: CoreUserSession): Promise<void>;
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
         inline?: boolean;
         startNode?: string;

package/dist/testing/service-tests/agent-run-service-tests.d.ts

@@ -0,0 +1,10 @@
+import type { ServiceTestConfig } from '../service-tests.js';
+/** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
+export declare const defineAgentRunServiceTests: (name: string, agentRunService: NonNullable<ServiceTestConfig["services"]["agentRunService"]>, 
+/**
+ * Thread-ownership is a property of the two services together — the run
+ * service lists what the storage service owns — so that half of the suite
+ * only runs when a backend supplies both. Passed explicitly rather than
+ * closed over, so the dependency is visible in the signature.
+ */
+aiStorageService?: ServiceTestConfig["services"]["aiStorageService"]) => void;

package/dist/testing/service-tests/agent-run-service-tests.js

@@ -0,0 +1,72 @@
+import { describe, test, before } from 'node:test';
+import assert from 'node:assert/strict';
+/** Conformance suite for `agentRunService`. Runs only when a backend supplies one. */
+export const defineAgentRunServiceTests = (name, agentRunService, 
+/**
+ * Thread-ownership is a property of the two services together — the run
+ * service lists what the storage service owns — so that half of the suite
+ * only runs when a backend supplies both. Passed explicitly rather than
+ * closed over, so the dependency is visible in the signature.
+ */
+aiStorageService) => {
+    const factory = agentRunService;
+    describe(`AgentRunService [${name}]`, () => {
+        let agentService;
+        before(async () => {
+            agentService = await factory();
+        });
+        test('listThreads', async () => {
+            const threads = await agentService.listThreads();
+            assert.ok(Array.isArray(threads));
+        });
+        if (aiStorageService) {
+            const storageFactory = aiStorageService;
+            // The `owners` constraint is what keeps the generated thread-management
+            // functions from leaking across tenants: a caller may only list threads
+            // owned by one of their session principals, matching the
+            // `principal:sub-partition` composition resolveOwnerResourceId writes.
+            test('listThreads scopes to the given owners, including sub-partitions', async () => {
+                const storage = await storageFactory();
+                await storage.createThread('owner-alice');
+                await storage.createThread('owner-alice:project-1');
+                await storage.createThread('owner-bob:secret');
+                const threads = await agentService.listThreads({
+                    owners: ['owner-alice'],
+                });
+                const ids = threads.map((t) => t.resourceId);
+                assert.ok(ids.includes('owner-alice'));
+                assert.ok(ids.includes('owner-alice:project-1'));
+                assert.ok(!ids.some((id) => id.startsWith('owner-bob')), "another owner's threads must not be listed");
+            });
+            test('listThreads with an owner does not match a lookalike prefix', async () => {
+                const storage = await storageFactory();
+                await storage.createThread('owner-al');
+                await storage.createThread('owner-alice-evil:p');
+                const threads = await agentService.listThreads({
+                    owners: ['owner-al'],
+                });
+                const ids = threads.map((t) => t.resourceId);
+                assert.ok(ids.includes('owner-al'));
+                assert.ok(!ids.includes('owner-alice-evil:p'));
+            });
+            test('listThreads with an empty owners list returns nothing', async () => {
+                const storage = await storageFactory();
+                await storage.createThread('owner-empty-check');
+                const threads = await agentService.listThreads({ owners: [] });
+                assert.deepEqual(threads, []);
+            });
+        }
+        test('getThread returns null for missing', async () => {
+            const thread = await agentService.getThread('missing-thread');
+            assert.equal(thread, null);
+        });
+        test('getDistinctAgentNames', async () => {
+            const names = await agentService.getDistinctAgentNames();
+            assert.ok(Array.isArray(names));
+        });
+        test('deleteThread returns false for missing', async () => {
+            const result = await agentService.deleteThread('missing-thread');
+            assert.equal(result, false);
+        });
+    });
+};

package/dist/testing/service-tests/ai-storage-service-tests.d.ts

@@ -0,0 +1,3 @@
+import type { ServiceTestConfig } from '../service-tests.js';
+/** Conformance suite for `aiStorageService`. Runs only when a backend supplies one. */
+export declare const defineAiStorageServiceTests: (name: string, aiStorageService: NonNullable<ServiceTestConfig["services"]["aiStorageService"]>) => void;