@pikku/core 0.12.63 → 0.12.66

package/dist/services/meta-service.js

@@ -1,4 +1,6 @@
 import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { join } from 'node:path';
 /**
  * Node.js filesystem implementation of MetaService.
@@ -54,6 +56,54 @@ export class LocalMetaService {
             return null;
         }
     }
+    // Resolve an installed addon package's root dir from the app's node_modules.
+    // The addon packages have no main `exports` entry, so `require.resolve(pkg)`
+    // throws; instead we walk the node_modules search paths (anchored at the app
+    // root, one level above `.pikku`) and pick the first that contains the package.
+    packageRootCache = new Map();
+    resolvePackageRoot(packageName) {
+        const cached = this.packageRootCache.get(packageName);
+        if (cached !== undefined)
+            return cached;
+        let root = null;
+        try {
+            const require = createRequire(join(this.basePath, '..', 'index.js'));
+            for (const dir of require.resolve.paths(packageName) ?? []) {
+                const candidate = join(dir, packageName);
+                if (existsSync(join(candidate, 'package.json'))) {
+                    root = candidate;
+                    break;
+                }
+            }
+        }
+        catch {
+            root = null;
+        }
+        this.packageRootCache.set(packageName, root);
+        return root;
+    }
+    async readPackageFile(packageName, relativePath) {
+        const root = this.resolvePackageRoot(packageName);
+        if (!root)
+            return null;
+        try {
+            return await readFile(join(root, '.pikku', relativePath), 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    async readPackageDir(packageName, relativePath) {
+        const root = this.resolvePackageRoot(packageName);
+        if (!root)
+            return [];
+        try {
+            return await readdir(join(root, '.pikku', relativePath));
+        }
+        catch {
+            return [];
+        }
+    }
     clearCache() {
         this.httpMetaCache = null;
         this.channelsMetaCache = null;
@@ -246,7 +296,7 @@ export class LocalMetaService {
         const content = await this.readMetaJson('permissions', 'pikku-permissions-groups-meta');
         this.permissionsGroupsMetaCache = content
             ? JSON.parse(content)
-            : { definitions: {}, httpGroups: {}, tagGroups: {} };
+            : { definitions: {} };
         return this.permissionsGroupsMetaCache;
     }
     async getAgentsMeta() {

package/dist/services/queue-webhook-service.d.ts

@@ -0,0 +1,55 @@
+import type { JobOptions, QueueService } from '../wirings/queue/queue.types.js';
+import type { Logger } from './logger.js';
+import { type SendWebhookInput, type SendWebhookResult, type WebhookJobData, WebhookService } from './webhook-service.js';
+/**
+ * Default {@link WebhookService} implementation: serializes and signs the
+ * payload, then enqueues a delivery job onto the `pikku-outgoing-webhooks`
+ * queue. The signature is computed at enqueue time so the signing key never
+ * enters the queue payload; the actual HTTP POST happens in
+ * {@link pikkuWebhookWorkerFunc}, and the queue's `attempts`/`backoff`
+ * options drive retries.
+ */
+export declare class QueueWebhookService extends WebhookService {
+    protected queueService: QueueService;
+    /**
+     * The queue is a constructor dependency rather than a `getSingletonServices()`
+     * lookup so that a project wiring up outgoing webhooks without a queue fails
+     * to compile, instead of throwing on the first `send()`.
+     */
+    constructor(queueService: QueueService);
+    send(input: SendWebhookInput): Promise<SendWebhookResult>;
+    /**
+     * Build the signed job payload and its retry options — the shared work a
+     * `send()` does before enqueueing. Factored out (and `protected`) so a
+     * store-backed subclass can persist a delivery row and attach its
+     * `deliveryId` without re-implementing signing or the retry policy.
+     */
+    protected prepareDelivery(input: SendWebhookInput): Promise<{
+        jobData: WebhookJobData;
+        options: JobOptions;
+    }>;
+    /**
+     * Resolve a delivery's retry policy into queue job options, mirroring the
+     * workflow service: per-call values win over `config.webhook` defaults, an
+     * explicitly-set `retries` (including 0) is always honored, and `attempts`
+     * is ALWAYS passed so the queue can never fall back to its own default.
+     * Backoff is exponential unless a concrete `retryDelay` selects a fixed one.
+     */
+    private resolveJobOptions;
+}
+/**
+ * Queue worker for the `pikku-outgoing-webhooks` queue: POSTs the delivery to its
+ * target URL. Any non-2xx response (or network error) throws so the queue
+ * retries the job according to the `attempts`/`backoff` set at enqueue time;
+ * the queue runner logs each failed attempt.
+ *
+ * A `deliveryId` is only present when a store-backed `webhookService` (e.g.
+ * `KyselyWebhookService`) enqueued the job, so each attempt (success or failure)
+ * is persisted via `webhookService.recordAttempt` before the throw — the console
+ * delivery history reflects every try, not just the outcome. The queue-only
+ * default never sets a `deliveryId`, so its base `recordAttempt` is never hit.
+ */
+export declare function pikkuWebhookWorkerFunc(services: {
+    logger: Logger;
+    webhookService?: WebhookService;
+}, { url, body, headers, deliveryId }: WebhookJobData): Promise<void>;

package/dist/services/queue-webhook-service.js

@@ -0,0 +1,136 @@
+import { getSingletonServices } from '../pikku-state.js';
+import { getDurationInMilliseconds } from '../time-utils.js';
+import { safeFetch } from '../utils/safe-fetch.js';
+import { DEFAULT_WEBHOOK_RETRIES, DEFAULT_WEBHOOK_SIGNATURE_HEADER, PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, WebhookService, } from './webhook-service.js';
+/** Cap on the response body captured on a failed attempt. */
+const MAX_CAPTURED_RESPONSE_BODY = 2_000;
+/**
+ * Default {@link WebhookService} implementation: serializes and signs the
+ * payload, then enqueues a delivery job onto the `pikku-outgoing-webhooks`
+ * queue. The signature is computed at enqueue time so the signing key never
+ * enters the queue payload; the actual HTTP POST happens in
+ * {@link pikkuWebhookWorkerFunc}, and the queue's `attempts`/`backoff`
+ * options drive retries.
+ */
+export class QueueWebhookService extends WebhookService {
+    queueService;
+    /**
+     * The queue is a constructor dependency rather than a `getSingletonServices()`
+     * lookup so that a project wiring up outgoing webhooks without a queue fails
+     * to compile, instead of throwing on the first `send()`.
+     */
+    constructor(queueService) {
+        super();
+        this.queueService = queueService;
+    }
+    async send(input) {
+        const { jobData, options } = await this.prepareDelivery(input);
+        const jobId = await this.queueService.add(PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME, jobData, options);
+        return { jobId };
+    }
+    /**
+     * Build the signed job payload and its retry options — the shared work a
+     * `send()` does before enqueueing. Factored out (and `protected`) so a
+     * store-backed subclass can persist a delivery row and attach its
+     * `deliveryId` without re-implementing signing or the retry policy.
+     */
+    async prepareDelivery(input) {
+        const services = getSingletonServices();
+        const webhookConfig = services.config?.webhook;
+        const body = JSON.stringify(input.data);
+        const headers = {
+            'Content-Type': 'application/json',
+            ...(input.event ? { 'X-Pikku-Event': input.event } : {}),
+            ...input.headers,
+        };
+        let secret = input.secret;
+        if (secret === undefined && webhookConfig?.secret) {
+            // Naive read — any caching is the secret service's concern, not ours.
+            secret = await services.secrets.getSecret(webhookConfig.secret);
+            if (!secret) {
+                services.logger.error(`Webhook signing secret '${webhookConfig.secret}' (config.webhook.secret) resolved to nothing — outgoing webhooks will be sent UNSIGNED.`);
+            }
+        }
+        if (secret) {
+            const signatureHeader = webhookConfig?.signatureHeader ?? DEFAULT_WEBHOOK_SIGNATURE_HEADER;
+            headers[signatureHeader] = this.sign(secret, body);
+        }
+        const jobData = {
+            url: input.url,
+            ...(input.event ? { event: input.event } : {}),
+            body,
+            headers,
+        };
+        return { jobData, options: this.resolveJobOptions(input) };
+    }
+    /**
+     * Resolve a delivery's retry policy into queue job options, mirroring the
+     * workflow service: per-call values win over `config.webhook` defaults, an
+     * explicitly-set `retries` (including 0) is always honored, and `attempts`
+     * is ALWAYS passed so the queue can never fall back to its own default.
+     * Backoff is exponential unless a concrete `retryDelay` selects a fixed one.
+     */
+    resolveJobOptions(input) {
+        const webhookConfig = getSingletonServices().config?.webhook;
+        const retries = input.retries ?? webhookConfig?.retries ?? DEFAULT_WEBHOOK_RETRIES;
+        const retryDelay = input.retryDelay ?? webhookConfig?.retryDelay;
+        const backoff = retryDelay !== undefined && retryDelay !== 'exponential'
+            ? { type: 'fixed', delay: getDurationInMilliseconds(retryDelay) }
+            : retries > 0 || retryDelay === 'exponential'
+                ? 'exponential'
+                : undefined;
+        return { attempts: retries + 1, ...(backoff ? { backoff } : {}) };
+    }
+}
+/**
+ * Queue worker for the `pikku-outgoing-webhooks` queue: POSTs the delivery to its
+ * target URL. Any non-2xx response (or network error) throws so the queue
+ * retries the job according to the `attempts`/`backoff` set at enqueue time;
+ * the queue runner logs each failed attempt.
+ *
+ * A `deliveryId` is only present when a store-backed `webhookService` (e.g.
+ * `KyselyWebhookService`) enqueued the job, so each attempt (success or failure)
+ * is persisted via `webhookService.recordAttempt` before the throw — the console
+ * delivery history reflects every try, not just the outcome. The queue-only
+ * default never sets a `deliveryId`, so its base `recordAttempt` is never hit.
+ */
+export async function pikkuWebhookWorkerFunc(services, { url, body, headers, deliveryId }) {
+    let statusCode;
+    let responseBody;
+    let error;
+    let delivered = false;
+    let allowedHosts;
+    try {
+        allowedHosts = getSingletonServices().config?.webhook?.allowedHosts;
+    }
+    catch {
+        // Singleton services not initialised (e.g. a bare worker invocation) — fall
+        // back to the default private-host block with no allowlist.
+    }
+    try {
+        const response = await safeFetch(url, {
+            method: 'POST',
+            headers,
+            body,
+            signal: AbortSignal.timeout(30_000),
+        }, { allowedHosts });
+        statusCode = response.status;
+        delivered = response.status >= 200 && response.status < 300;
+        if (!delivered) {
+            responseBody = (await response.text().catch(() => ''))?.slice(0, MAX_CAPTURED_RESPONSE_BODY);
+            error = `Webhook delivery to ${url} failed with status ${response.status}`;
+        }
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+    }
+    if (deliveryId && services.webhookService) {
+        // Best-effort history: a store failure must not mask the delivery result.
+        await services.webhookService
+            .recordAttempt(deliveryId, { statusCode, responseBody, error, delivered })
+            .catch((storeError) => services.logger.error(`Failed to record webhook delivery attempt for ${deliveryId}`, storeError));
+    }
+    if (!delivered) {
+        throw new Error(error ?? `Webhook delivery to ${url} failed`);
+    }
+}

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

@@ -0,0 +1,67 @@
+import type { FlatScope } from '../wirings/scope/scope.types.js';
+/** A role: a named, admin-composed bag of scopes. */
+export interface Role {
+    name: string;
+    description?: string;
+    scopes: string[];
+}
+/**
+ * Resolves and administers the scopes granted to a user.
+ *
+ * Implementations are called at the **session boundary** — e.g. better-auth's
+ * `mapSession` — never by the function runner. The runner reads
+ * `session.scopes` and never performs I/O, which keeps it viable on Workers
+ * and Lambda. Because the session is rebuilt per request, a scope change takes
+ * effect on the next call with nothing cached and nothing to invalidate.
+ *
+ * `syncScopes` is deliberately additive: scopes are declared in code, so a
+ * removed declaration leaves an inert row rather than silently revoking a
+ * grant mid-deploy. Removal is an explicit operation (`pikku scopes prune`).
+ */
+export interface ScopeService {
+    /**
+     * Registers the declared scope set. Additive — never deletes.
+     * Called once during startup with the generated scope list.
+     */
+    syncScopes(scopes: FlatScope[]): Promise<void>;
+    /**
+     * Every scope a user holds: the union of their role-derived scopes and any
+     * scopes granted to them directly.
+     */
+    resolveScopes(userId: string): Promise<string[]>;
+    /**
+     * The scope vocabulary in the store: everything a role can be composed from.
+     *
+     * `declared: false` marks a scope that is still present but no longer
+     * declared in code — inert (no function can require it) and awaiting
+     * `pikku scopes prune`.
+     */
+    listScopes(): Promise<Array<FlatScope & {
+        declared: boolean;
+    }>>;
+    createRole(role: Role): Promise<void>;
+    deleteRole(name: string): Promise<void>;
+    setRoleScopes(name: string, scopes: string[]): Promise<void>;
+    listRoles(): Promise<Role[]>;
+    addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
+    removeUserFromRole(userId: string, role: string): Promise<void>;
+    listUserRoles(userId: string): Promise<string[]>;
+    /**
+     * Grants a scope directly to a user, outside of any role. Additive: the
+     * resolved set is the union of role-derived and directly-granted scopes.
+     */
+    addScopeToUser(userId: string, scope: string, grantedBy?: string): Promise<void>;
+    removeScopeFromUser(userId: string, scope: string): Promise<void>;
+    /** Only the scopes granted directly, not those inherited from roles. */
+    listUserScopes(userId: string): Promise<string[]>;
+    /**
+     * Scopes present in the store that are no longer declared in code, with the
+     * roles that would lose them. Powers `pikku scopes audit`.
+     */
+    findStaleScopes(): Promise<Array<{
+        scope: string;
+        roles: string[];
+    }>>;
+    /** Removes undeclared scopes, cascading them out of roles. */
+    pruneScopes(): Promise<string[]>;
+}

package/dist/services/scope-service.js

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

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

@@ -18,6 +18,14 @@ export type CredentialMeta = {
 export declare class TypedSecretService<TMap = Record<string, unknown>> implements SecretService {
     private secrets;
     private credentialsMeta;
+    /**
+     * In-process cache of resolved secrets, so callers can read naively without
+     * re-hitting the underlying service on every call. Only successful reads are
+     * cached (a miss throws and isn't stored); `setSecret`/`deleteSecret`
+     * invalidate the key. No TTL — a secret rotated out-of-band won't refresh
+     * until restart (see pikkujs/pikku#964).
+     */
+    private cache;
     constructor(secrets: SecretService, credentialsMeta: Record<string, CredentialMeta>);
     getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>;
     getSecret<T = string>(key: string): Promise<T>;

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

@@ -1,24 +1,59 @@
 export class TypedSecretService {
     secrets;
     credentialsMeta;
+    /**
+     * In-process cache of resolved secrets, so callers can read naively without
+     * re-hitting the underlying service on every call. Only successful reads are
+     * cached (a miss throws and isn't stored); `setSecret`/`deleteSecret`
+     * invalidate the key. No TTL — a secret rotated out-of-band won't refresh
+     * until restart (see pikkujs/pikku#964).
+     */
+    cache = new Map();
     constructor(secrets, credentialsMeta) {
         this.secrets = secrets;
         this.credentialsMeta = credentialsMeta;
     }
     async getSecret(key) {
-        return this.secrets.getSecret(key);
+        if (this.cache.has(key)) {
+            return this.cache.get(key);
+        }
+        const value = await this.secrets.getSecret(key);
+        this.cache.set(key, value);
+        return value;
     }
     async hasSecret(key) {
+        if (this.cache.has(key)) {
+            return true;
+        }
         return this.secrets.hasSecret(key);
     }
     async setSecret(key, value) {
-        return this.secrets.setSecret(key, value);
+        await this.secrets.setSecret(key, value);
+        this.cache.delete(key);
     }
     async deleteSecret(key) {
-        return this.secrets.deleteSecret(key);
+        await this.secrets.deleteSecret(key);
+        this.cache.delete(key);
     }
     async getSecrets(keys) {
-        return this.secrets.getSecrets(keys);
+        const result = {};
+        const missing = [];
+        for (const key of keys) {
+            if (this.cache.has(key)) {
+                result[key] = this.cache.get(key);
+            }
+            else {
+                missing.push(key);
+            }
+        }
+        if (missing.length > 0) {
+            const fetched = await this.secrets.getSecrets(missing);
+            for (const [key, value] of Object.entries(fetched)) {
+                this.cache.set(key, value);
+                result[key] = value;
+            }
+        }
+        return result;
     }
     async getAllStatus() {
         const results = [];

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

@@ -0,0 +1,140 @@
+export interface SendWebhookInput {
+    /** The endpoint the webhook is delivered to via HTTP POST. */
+    url: string;
+    /** Optional event name, sent as the `X-Pikku-Event` header. */
+    event?: string;
+    /** The payload, JSON-serialized into the request body. */
+    data: unknown;
+    /** Extra headers merged over the defaults. */
+    headers?: Record<string, string>;
+    /**
+     * Raw HMAC signing key for this delivery. Overrides the config-level
+     * secret. When present, the body is signed into the signature header.
+     */
+    secret?: string;
+    /** Retry count for failed deliveries. Overrides `config.webhook.retries`. */
+    retries?: number;
+    /**
+     * Delay between retries (`30000` or `'30s'`). A concrete value selects a
+     * fixed backoff; when omitted, backoff is exponential.
+     */
+    retryDelay?: string | number;
+    /**
+     * Organization this delivery belongs to. Persisted by a store-backed
+     * implementation (e.g. `KyselyWebhookService`) so deliveries can be
+     * queried per org; ignored by the queue-only default.
+     */
+    organizationId?: string;
+}
+export interface SendWebhookResult {
+    jobId: string;
+}
+export interface WebhookServiceConfig {
+    /** Default retry count for failed deliveries. */
+    retries?: number;
+    /** Default delay between retries; omitted means exponential backoff. */
+    retryDelay?: string | number;
+    /**
+     * Name of a secret (resolved through the secret service) used as the
+     * default HMAC signing key for all outgoing webhooks.
+     */
+    secret?: string;
+    /**
+     * Header the body signature is sent in. Defaults to
+     * {@link DEFAULT_WEBHOOK_SIGNATURE_HEADER}.
+     */
+    signatureHeader?: string;
+    /**
+     * SSRF allowlist of hostnames outgoing webhooks may be delivered to. When set,
+     * a delivery target must be on this list. When omitted, obvious private and
+     * internal hosts (loopback, private ranges, cloud metadata) are blocked and
+     * all other public hosts are permitted.
+     */
+    allowedHosts?: string[];
+}
+export interface WebhookJobData {
+    url: string;
+    event?: string;
+    body: string;
+    headers: Record<string, string>;
+    /**
+     * Delivery-record id, present when a store-backed implementation enqueued
+     * the job. The worker keys its per-attempt records off this (it doubles as
+     * the queue `jobId`), so it's stable across retries.
+     */
+    deliveryId?: string;
+}
+/** Outcome of one delivery attempt, recorded against a delivery. */
+export interface WebhookAttemptResult {
+    /** HTTP status of the response, absent if the request never completed. */
+    statusCode?: number;
+    /** Response body (truncated) — captured on failure for debugging. */
+    responseBody?: string;
+    /** Network/timeout error message, when the request threw. */
+    error?: string;
+    /** Whether this attempt was a 2xx success. */
+    delivered: boolean;
+}
+/** A persisted webhook delivery, as surfaced to the console. */
+export interface WebhookDeliveryRecord {
+    deliveryId: string;
+    organizationId: string | null;
+    url: string;
+    event: string | null;
+    status: 'pending' | 'delivered' | 'failed';
+    attempts: number;
+    createdAt: Date;
+    updatedAt: Date;
+    deliveredAt: Date | null;
+}
+/** A single persisted delivery attempt. */
+export interface WebhookAttemptRecord {
+    attemptId: string;
+    deliveryId: string;
+    attemptNumber: number;
+    statusCode: number | null;
+    responseBody: string | null;
+    error: string | null;
+    createdAt: Date;
+}
+/** A delivery with its full attempt history. */
+export interface WebhookDeliveryWithAttempts {
+    delivery: WebhookDeliveryRecord;
+    attempts: WebhookAttemptRecord[];
+}
+export declare const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = "pikku-outgoing-webhooks";
+export declare const DEFAULT_WEBHOOK_SIGNATURE_HEADER = "X-Pikku-Signature";
+/** Fallback when neither the per-call nor `config.webhook.retries` is set. */
+export declare const DEFAULT_WEBHOOK_RETRIES = 3;
+/**
+ * Outgoing webhook delivery. {@link QueueWebhookService} is the default
+ * implementation; apps can extend this to deliver directly, or through a
+ * provider such as Svix.
+ */
+export declare abstract class WebhookService {
+    abstract send(input: SendWebhookInput): Promise<SendWebhookResult>;
+    /**
+     * Sign a body with HMAC-SHA256, producing the signature header value
+     * (e.g. `sha256=abc123...`).
+     */
+    protected sign(secret: string, body: string): string;
+    /**
+     * Verify a signature produced by {@link WebhookService.sign} — for
+     * receivers, which share the signing scheme.
+     */
+    verify(secret: string, signature: string, body: string): boolean;
+    /**
+     * Record a delivery attempt and roll the delivery's status/attempt-count
+     * forward, keyed by the delivery id carried in {@link WebhookJobData}. The
+     * default queue-only service keeps no history, so this throws — a store-backed
+     * implementation (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides it.
+     */
+    recordAttempt(_deliveryId: string, _result: WebhookAttemptResult): Promise<void>;
+    /** List deliveries, most recent first, optionally scoped to an org. */
+    listDeliveries(_opts?: {
+        organizationId?: string;
+        limit?: number;
+    }): Promise<WebhookDeliveryRecord[]>;
+    /** A single delivery with its attempt history, or null if unknown. */
+    getDelivery(_deliveryId: string): Promise<WebhookDeliveryWithAttempts | null>;
+}

package/dist/services/webhook-service.js

@@ -0,0 +1,44 @@
+import { NotImplementedError } from '../errors/errors.js';
+import { hmacSha256Hex, timingSafeStringEqual } from '../utils/hmac.js';
+export const PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME = 'pikku-outgoing-webhooks';
+export const DEFAULT_WEBHOOK_SIGNATURE_HEADER = 'X-Pikku-Signature';
+/** Fallback when neither the per-call nor `config.webhook.retries` is set. */
+export const DEFAULT_WEBHOOK_RETRIES = 3;
+/**
+ * Outgoing webhook delivery. {@link QueueWebhookService} is the default
+ * implementation; apps can extend this to deliver directly, or through a
+ * provider such as Svix.
+ */
+export class WebhookService {
+    /**
+     * Sign a body with HMAC-SHA256, producing the signature header value
+     * (e.g. `sha256=abc123...`).
+     */
+    sign(secret, body) {
+        return `sha256=${hmacSha256Hex(secret, body)}`;
+    }
+    /**
+     * Verify a signature produced by {@link WebhookService.sign} — for
+     * receivers, which share the signing scheme.
+     */
+    verify(secret, signature, body) {
+        return timingSafeStringEqual(this.sign(secret, body), signature);
+    }
+    /**
+     * Record a delivery attempt and roll the delivery's status/attempt-count
+     * forward, keyed by the delivery id carried in {@link WebhookJobData}. The
+     * default queue-only service keeps no history, so this throws — a store-backed
+     * implementation (e.g. `KyselyWebhookService` in `@pikku/kysely`) overrides it.
+     */
+    recordAttempt(_deliveryId, _result) {
+        throw new NotImplementedError('webhook delivery persistence is not configured');
+    }
+    /** List deliveries, most recent first, optionally scoped to an org. */
+    listDeliveries(_opts) {
+        throw new NotImplementedError('webhook delivery persistence is not configured');
+    }
+    /** A single delivery with its attempt history, or null if unknown. */
+    getDelivery(_deliveryId) {
+        throw new NotImplementedError('webhook delivery persistence is not configured');
+    }
+}

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

@@ -22,6 +22,13 @@ export interface WorkflowService {
     withRunLock<T>(id: string, fn: () => Promise<T>): Promise<T>;
     close(): Promise<void>;
     resumeWorkflow(runId: string): Promise<void>;
+    /**
+     * Record a human decision against a `workflow.approval()` gate and wake the
+     * run. 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. `reason` addresses the gate's first reach.
+     */
+    approveStep(runId: string, reason: string, decision: unknown): Promise<void>;
     startWorkflow<I>(name: string, input: I, wire: WorkflowRunWire, rpcService: any, options?: {
         inline?: boolean;
         startNode?: string;

package/dist/testing/service-tests.js

@@ -742,6 +742,43 @@ export function defineServiceTests(config) {
                 const threads = await agentService.listThreads();
                 assert.ok(Array.isArray(threads));
             });
+            if (services.aiStorageService) {
+                const storageFactory = services.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);