@pikku/core 0.12.122 → 0.12.125

package/CHANGELOG.md

@@ -1,3 +1,61 @@
+## 0.12.125
+
+### Patch Changes
+
+- 5e93f30: Add `defineOutgoingWebhook({ event, title, description?, payload })` in `@pikku/core/webhook`. The CLI collects every exported declaration into `.pikku/webhooks/pikku-outgoing-webhooks-meta.gen.json` and `pikku-outgoing-webhooks.gen.ts`, which exports `OutgoingWebhooksMap`, `TypedWebhookService` and `typedWebhookService(service)`: `send` checks `data` against the declared payload for a declared event and accepts any other event unchanged. `MetaService.getOutgoingWebhooksMeta()` and the console addon's `outgoingWebhooksMeta` serve the declarations.
+- 5e93f30: Add `wireTriggerWebhookSource({ name, method?, route?, secret?, events, receive?, check?, setup?, teardown? })` in `#pikku/trigger`. Each source becomes a `POST /webhooks/<name>` route whose events are validated against their schemas and queued on `pikku-incoming-webhooks` through `IncomingWebhookService`; a generated worker runs the matching `wireTrigger({ name: '<source>:<event>' })` and the queue retries it on failure. `pikku webhooks status | setup | teardown --url --labelPrefix [--previous]` registers the routes with the provider and prints one JSON line per source.
+
+  `KyselyIncomingWebhookService` (with the `incoming-webhook` schema) records a receipt per event, drops a provider's redelivery of an event it already accepted, and keeps each dispatch's attempts and last error. `pikku dev` and `pikku serve` use it when a Kysely database is configured.
+
+## 0.12.124
+
+### Patch Changes
+
+- 1394385: Carry the wired instance through a `ref('ns:fn')` an app writes. The wiring is
+  the app's, so the reference arrives with no instance and the function used to
+  run against the addon's declared secrets alone — the consuming app's
+  `secretOverrides` and grants silently did not apply, and the app's own global
+  middleware was denied secrets it owns.
+
+## 0.12.123
+
+### Patch Changes
+
+- 50b59a3: Keep the agent runtime out of deployment units that hold no agent.
+
+  `ContextAwareRPCService.agent` imported `agent-rpc.ts` directly, and every unit
+  reaches that class through the function runner, so the agent runner, stream,
+  memory and AGUI modules were pinned into every bundle — 51.8 KB raw / 15.7 KB
+  gzip a unit. The facade is now resolved through state, registered by
+  `@pikku/core/agent` on import, so only a unit that actually holds an agent
+  bundles it. A unit that reaches `rpc.agent` without importing the agent entry
+  point throws rather than silently pulling the runtime back in.
+
+- 2b946e9: fix(dev): keep `import.meta` pointing at the real file in the hot-reload runner
+
+  The dev module runner transforms each user file to `cjs` before compiling it,
+  and esbuild's `cjs` output rewrites `import.meta` to an empty object. Any module
+  that resolves its own neighbours through `createRequire(import.meta.url)` —
+  sharp, onnxruntime-node, essentially every package with a native binding —
+  therefore received `undefined` and failed with `Cannot find module
+'@img/sharp-linux-x64/sharp.node' from ''`. sharp's own loader filters on
+  `MODULE_NOT_FOUND` and reports its generic "could not load the sharp module"
+  instead, so the empty referrer never appears in the error the developer sees.
+
+  `import.meta.url`, `import.meta.filename` and `import.meta.dirname` are now
+  defined to the file being run, so resolution behaves as it does under Node's
+  ESM loader.
+
+- bc488cf: fix(inspector): an explicit `auth: false` declares an exposed sessionless function public, so PKU574 no longer warns about it
+
+  A genuinely public endpoint — a published programme, a health check — had no
+  honest way to quiet PKU574: the only options were an always-true permission or
+  `permissionsInBody: true`, both of which claim a gate that does not exist. The
+  inspector now records `auth` on function meta exactly as written instead of
+  dropping `false`, and the check treats an explicit `auth: false` as the author
+  declaring the function public on purpose. A sessionless function that leaves
+  `auth` out still warns.
+
 ## 0.12.122
 
 ### Patch Changes

package/dist/dev/module-runner.js

@@ -68,6 +68,15 @@ const evaluateModule = (absPath, cache) => {
         loader: loaderFor(absPath),
         format: 'cjs',
         sourcefile: absPath,
+        // `cjs` output rewrites `import.meta` to an empty object, so a module
+        // that resolves its own neighbours through `createRequire(import.meta.url)`
+        // -- sharp, onnxruntime-node, any package with a native binding -- gets
+        // `undefined` and fails with "Cannot find module ... from ''".
+        define: {
+            'import.meta.url': JSON.stringify(pathToFileURL(absPath).href),
+            'import.meta.filename': JSON.stringify(absPath),
+            'import.meta.dirname': JSON.stringify(dirname(absPath)),
+        },
     });
     const fn = compileFunction(code, ['require', 'exports', 'module', '__filename', '__dirname'], { filename: absPath });
     const moduleObj = { exports: {} };

package/dist/function/function-meta.types.d.ts

@@ -29,10 +29,11 @@ export type FunctionRuntimeMeta = {
     featureFlag?: string;
     expose?: boolean;
     /**
-     * A sessionless function's own `auth: true`. `sessionless` carries the
-     * baseline — a `pikkuFunc` always requires a session — and this carries the
-     * tightening a `pikkuSessionlessFunc` applies to itself. Both are needed to
-     * know whether a function is gated without running it.
+     * A sessionless function's own `auth`, as written. `sessionless` carries the
+     * baseline — a `pikkuFunc` always requires a session — and this carries what
+     * a `pikkuSessionlessFunc` declares about itself: `true` requires a session,
+     * `false` says it is public on purpose, absent says nothing. All three are
+     * needed to know whether an exposed function is gated without running it.
      */
     auth?: boolean;
     /**

package/dist/function/function-runner.js

@@ -98,6 +98,13 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
             funcMeta = pikkuState(addonTarget.packageName, 'function', 'meta')[addonTarget.localName];
             if (funcMeta) {
                 funcPackageName = addonTarget.packageName;
+                // A `ref('ns:fn')` the app wired arrives with no instance, because the
+                // wiring is the app's. Without adopting the one the namespace resolves
+                // to, the function runs with the addon's declared secrets alone — the
+                // consuming app's `secretOverrides` and grants silently do not apply,
+                // and the app's own global middleware, running inside that scope, is
+                // denied secrets it owns.
+                addonInstance = addonInstance ?? addonTarget.instance;
             }
         }
     }

package/dist/pikku-state.js

@@ -73,6 +73,8 @@ const createEmptyPackageState = () => ({
         triggerSources: new Map(),
         meta: {},
         sourceMeta: {},
+        webhookSources: new Map(),
+        webhookSourceMeta: {},
     },
     mcp: {
         resources: new Map(),

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

@@ -0,0 +1,48 @@
+import type { QueueService } from '../wirings/queue/queue.types.js';
+import { type TriggerEvent, type WebhookRequest, type WebhookSourceJob } from '../wirings/trigger/webhook-source.types.js';
+export type IncomingWebhookAttempt = {
+    trigger: string;
+    error?: string;
+};
+export type IncomingWebhookReceiptRecord = {
+    receiptId: string;
+    source: string;
+    providerEventId: string | null;
+    event: string;
+    status: 'pending' | 'delivered' | 'failed';
+    attempts: number;
+    lastError: string | null;
+    createdAt: Date;
+    deliveredAt: Date | null;
+};
+/**
+ * Queues each event a webhook source received for the
+ * `pikku-incoming-webhooks` worker, so the provider is answered once the event
+ * is safe and our own processing is retried by the queue, not by the provider.
+ *
+ * The queue is a constructor argument, as in `QueueWebhookService`: a webhook
+ * source wired without one fails to compile rather than on its first delivery.
+ */
+export declare class IncomingWebhookService {
+    protected queueService: QueueService;
+    /** How often a failing trigger is retried before the event is given up on. */
+    protected retries: number;
+    constructor(queueService: QueueService, 
+    /** How often a failing trigger is retried before the event is given up on. */
+    retries?: number);
+    /** Returns how many events were queued. A store-backed service drops ones it has already seen. */
+    accept({ source, events, }: {
+        source: string;
+        request: WebhookRequest;
+        events: TriggerEvent[];
+    }): Promise<number>;
+    /** The job id is the provider's event id under its event name, which de-duplicates on queues that honour job ids. */
+    protected enqueue(job: WebhookSourceJob): Promise<string>;
+    /** Keeps nothing by default; a store-backed service records each dispatch. */
+    recordAttempt(_receiptId: string, _attempt: IncomingWebhookAttempt): Promise<void>;
+    /** Most recent first. Empty when nothing is stored. */
+    listReceipts(_opts?: {
+        source?: string;
+        limit?: number;
+    }): Promise<IncomingWebhookReceiptRecord[]>;
+}

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

@@ -0,0 +1,46 @@
+import { DEFAULT_WEBHOOK_RETRIES } from './webhook-service.js';
+import { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, } from '../wirings/trigger/webhook-source.types.js';
+/**
+ * Queues each event a webhook source received for the
+ * `pikku-incoming-webhooks` worker, so the provider is answered once the event
+ * is safe and our own processing is retried by the queue, not by the provider.
+ *
+ * The queue is a constructor argument, as in `QueueWebhookService`: a webhook
+ * source wired without one fails to compile rather than on its first delivery.
+ */
+export class IncomingWebhookService {
+    queueService;
+    retries;
+    constructor(queueService, 
+    /** How often a failing trigger is retried before the event is given up on. */
+    retries = DEFAULT_WEBHOOK_RETRIES) {
+        this.queueService = queueService;
+        this.retries = retries;
+    }
+    /** Returns how many events were queued. A store-backed service drops ones it has already seen. */
+    async accept({ source, events, }) {
+        for (const event of events) {
+            await this.enqueue({ source, event });
+        }
+        return events.length;
+    }
+    /** The job id is the provider's event id under its event name, which de-duplicates on queues that honour job ids. */
+    async enqueue(job) {
+        const jobId = job.receiptId ??
+            (job.event.id
+                ? `${job.source}:${job.event.name}:${job.event.id}`
+                : undefined);
+        // knowledge: decisions/internals/queue-jobs-always-carry-an-explicit-attempts-count.md
+        return this.queueService.add(PIKKU_INCOMING_WEBHOOK_QUEUE_NAME, job, {
+            attempts: this.retries + 1,
+            ...(this.retries > 0 ? { backoff: 'exponential' } : {}),
+            ...(jobId ? { jobId } : {}),
+        });
+    }
+    /** Keeps nothing by default; a store-backed service records each dispatch. */
+    async recordAttempt(_receiptId, _attempt) { }
+    /** Most recent first. Empty when nothing is stored. */
+    async listReceipts(_opts) {
+        return [];
+    }
+}

package/dist/services/index.d.ts

@@ -12,6 +12,7 @@ export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js';
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 export { QueueWebhookService, pikkuWebhookWorkerFunc, } from './queue-webhook-service.js';
+export { IncomingWebhookService, type IncomingWebhookAttempt, type IncomingWebhookReceiptRecord, } from './incoming-webhook-service.js';
 export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, pikkuRemoteQueueJobFunc, pikkuRemoteScheduledJobFunc, type RemoteQueueJobData, type RemoteScheduledJobData, } from './remote-jobs.js';
 export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';

package/dist/services/index.js

@@ -12,6 +12,7 @@ export { LocalVariablesService } from './local-variables.js';
 export { ConsoleLogger, JsonConsoleLogger } from './logger-console.js';
 export { InMemoryWorkflowService } from './in-memory-workflow-service.js';
 export { QueueWebhookService, pikkuWebhookWorkerFunc, } from './queue-webhook-service.js';
+export { IncomingWebhookService, } from './incoming-webhook-service.js';
 export { REMOTE_JOBS_SECRET_HEADER, REMOTE_JOBS_SECRET_VARIABLE, REMOTE_QUEUE_JOB_PATH, REMOTE_SCHEDULER_JOB_PATH, pikkuRemoteQueueJobFunc, pikkuRemoteScheduledJobFunc, } from './remote-jobs.js';
 export { InMemoryQueueService } from './in-memory-queue-service.js';
 export { InMemoryTriggerService } from './in-memory-trigger-service.js';

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

@@ -15,6 +15,8 @@ import type { TriggerMeta, TriggerSourceMeta } from '../wirings/trigger/trigger.
 import type { SecretDefinitionsMeta } from '../wirings/secret/secret.types.js';
 import type { CredentialDefinitionsMeta } from '../wirings/credential/credential.types.js';
 import type { VariableDefinitionsMeta } from '../wirings/variable/variable.types.js';
+import type { OutgoingWebhooksMeta } from '../wirings/webhook/define-outgoing-webhook.js';
+import type { WebhookSourcesMeta } from '../wirings/trigger/webhook-source.types.js';
 import type { FunctionMeta, FunctionsMeta, PermissionMetadata } from '../function/function-meta.types.js';
 import type { MiddlewareMetadata } from '../middleware/middleware.types.js';
 import type { AgentsMeta } from '../wirings/agent/agent.types.js';
@@ -174,6 +176,8 @@ export interface MetaService {
     getSecretsMeta(): Promise<SecretDefinitionsMeta>;
     getCredentialsMeta(): Promise<CredentialDefinitionsMeta>;
     getVariablesMeta(): Promise<VariableDefinitionsMeta>;
+    getOutgoingWebhooksMeta(): Promise<OutgoingWebhooksMeta>;
+    getWebhookSourcesMeta(): Promise<WebhookSourcesMeta>;
     getEmailMeta(): Promise<EmailsMeta>;
     getEmailTemplateAssets(templateName: string, locale: string): Promise<EmailTemplateAssets>;
     getServicesMeta(): Promise<ServicesMetaRecord>;
@@ -184,6 +188,7 @@ export interface MetaService {
 export declare class LocalMetaService implements MetaService {
     readonly basePath: string;
     private httpMetaCache;
+    private webhookSourcesMetaCache;
     private channelsMetaCache;
     private schedulerMetaCache;
     private queueMetaCache;
@@ -204,6 +209,7 @@ export declare class LocalMetaService implements MetaService {
     private secretsMetaCache;
     private credentialsMetaCache;
     private variablesMetaCache;
+    private outgoingWebhooksMetaCache;
     private middlewareGroupsMetaCache;
     private permissionsGroupsMetaCache;
     private agentsMetaCache;
@@ -242,6 +248,8 @@ export declare class LocalMetaService implements MetaService {
     getSecretsMeta(): Promise<SecretDefinitionsMeta>;
     getCredentialsMeta(): Promise<CredentialDefinitionsMeta>;
     getVariablesMeta(): Promise<VariableDefinitionsMeta>;
+    getOutgoingWebhooksMeta(): Promise<OutgoingWebhooksMeta>;
+    getWebhookSourcesMeta(): Promise<WebhookSourcesMeta>;
     getEmailMeta(): Promise<EmailsMeta>;
     getEmailTemplateAssets(templateName: string, locale: string): Promise<EmailTemplateAssets>;
     getServicesMeta(): Promise<ServicesMetaRecord>;

package/dist/services/meta-service.js

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 export class LocalMetaService {
     basePath;
     httpMetaCache = null;
+    webhookSourcesMetaCache = null;
     channelsMetaCache = null;
     schedulerMetaCache = null;
     queueMetaCache = null;
@@ -25,6 +26,7 @@ export class LocalMetaService {
     secretsMetaCache = null;
     credentialsMetaCache = null;
     variablesMetaCache = null;
+    outgoingWebhooksMetaCache = null;
     middlewareGroupsMetaCache = null;
     permissionsGroupsMetaCache = null;
     agentsMetaCache = null;
@@ -123,6 +125,8 @@ export class LocalMetaService {
         this.secretsMetaCache = null;
         this.credentialsMetaCache = null;
         this.variablesMetaCache = null;
+        this.outgoingWebhooksMetaCache = null;
+        this.webhookSourcesMetaCache = null;
         this.middlewareGroupsMetaCache = null;
         this.permissionsGroupsMetaCache = null;
         this.agentsMetaCache = null;
@@ -375,6 +379,20 @@ export class LocalMetaService {
         this.variablesMetaCache = content ? JSON.parse(content) : {};
         return this.variablesMetaCache;
     }
+    async getOutgoingWebhooksMeta() {
+        if (this.outgoingWebhooksMetaCache)
+            return this.outgoingWebhooksMetaCache;
+        const content = await this.readFile('webhooks/pikku-outgoing-webhooks-meta.gen.json');
+        this.outgoingWebhooksMetaCache = content ? JSON.parse(content) : {};
+        return this.outgoingWebhooksMetaCache;
+    }
+    async getWebhookSourcesMeta() {
+        if (this.webhookSourcesMetaCache)
+            return this.webhookSourcesMetaCache;
+        const content = await this.readFile('webhooks/pikku-webhook-sources-meta.gen.json');
+        this.webhookSourcesMetaCache = content ? JSON.parse(content) : {};
+        return this.webhookSourcesMetaCache;
+    }
     async getEmailMeta() {
         // knowledge: decisions/internals/email-meta-is-read-uncached-because-codegen-rewrites-it-mid-session.md
         const content = await this.readFile('email/pikku-emails-meta.gen.json');

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

@@ -1,3 +1,4 @@
+import type { IncomingWebhookService } from '../services/incoming-webhook-service.js';
 import type { Logger, LogLevel } from '../services/logger.js';
 import type { VariablesService } from '../services/variables-service.js';
 import type { SecretService } from '../services/secret-service.js';
@@ -133,6 +134,8 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
      * the delivery-read methods; a store-backed implementation records history.
      */
     webhookService?: WebhookService;
+    /** Queues what webhook trigger sources receive. Required once any `wireTriggerWebhookSource` is wired. */
+    incomingWebhookService?: IncomingWebhookService;
     metaService?: MetaService;
     /**
      * Where virtual-user runs are recorded. A run is dispatched and answered for

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

@@ -1,3 +1,4 @@
+import type { CoreTriggerWebhookSource, WebhookSourcesMeta } from '../wirings/trigger/webhook-source.types.js';
 import type { CredentialOverrides } from '../wirings/credential/credential-overrides.js';
 import type { PikkuErrorConstructor, ErrorDetails } from '../errors/error-handler.js';
 import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
@@ -6,7 +7,7 @@ import type { CoreChannel, ChannelsMeta } from '../wirings/channel/channel.types
 import type { CLIMeta, CLIProgramState } from '../wirings/cli/cli.types.js';
 import type { HTTPMethod, CoreHTTPFunctionWiring, HTTPWiringsMeta } from '../wirings/http/http.types.js';
 import type { CoreMCPResource, MCPResourceMeta, MCPToolMeta, CoreMCPPrompt, MCPPromptMeta } from '../wirings/mcp/mcp.types.js';
-import type { CoreAgent, AgentsMeta } from '../wirings/agent/agent.types.js';
+import type { CoreAgent, AgentsMeta, AgentRPCFactory } from '../wirings/agent/agent.types.js';
 import type { PikkuAgentScorer, ScorerMeta } from '../wirings/agent-scorer/agent-scorer.types.js';
 import type { CoreGateway, GatewaysMeta } from '../wirings/gateway/gateway.types.js';
 import type { CoreQueueWorker, QueueWorkersMeta } from '../wirings/queue/queue.types.js';
@@ -101,6 +102,8 @@ export interface PikkuPackageState {
         triggerSources: Map<string, CoreTriggerSource>;
         meta: TriggerMeta;
         sourceMeta: TriggerSourceMeta;
+        webhookSources: Map<string, CoreTriggerWebhookSource>;
+        webhookSourceMeta: WebhookSourcesMeta;
     };
     mcp: {
         resources: Map<string, CoreMCPResource>;
@@ -116,6 +119,11 @@ export interface PikkuPackageState {
         scorersMeta: ScorerMeta;
         /** Alias -> `provider/model`, from the `models` table in pikku.config.json. */
         modelAliases: Record<string, string>;
+        /**
+         * Set by `@pikku/core/agent` on import. Absent in a deployment unit that
+         * holds no agent, which is what keeps the agent runtime out of its bundle.
+         */
+        rpcFactory?: AgentRPCFactory;
     };
     gateway: {
         gateways: Map<string, CoreGateway>;

package/dist/wirings/addon/addon-runner.js

@@ -84,6 +84,26 @@ const wrapWorkflowServiceForPackage = (service, packageName, namespace) => {
         },
     });
 };
+const scopedWebhookServices = new WeakSet();
+/** An addon names its outgoing events locally; they leave as `<instance>:<event>`. */
+const scopeWebhookService = (service, namespace) => {
+    if (scopedWebhookServices.has(service))
+        return service;
+    const scoped = new Proxy(service, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (prop !== 'send' || typeof value !== 'function')
+                return value;
+            return function (input, ...rest) {
+                return value.call(this, input?.event && !input.event.startsWith(`${namespace}:`)
+                    ? { ...input, event: `${namespace}:${input.event}` }
+                    : input, ...rest);
+            };
+        },
+    });
+    scopedWebhookServices.add(scoped);
+    return scoped;
+};
 export const getOrCreatePackageSingletonServices = async (packageName, parentServices, addonInstance) => {
     const cacheKey = addonInstance?.namespace ?? packageName;
     const cachedServices = pikkuState(cacheKey, 'package', 'singletonServices');
@@ -116,6 +136,13 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
             credentialService: new ScopedCredentialService(existingServices.credentialService, allowedNames(Object.keys(pikkuState(packageName, 'package', 'credentialsMeta') ?? {}), addonInstance?.credentialGrants, addonInstance?.credentialOverrides)),
         };
     }
+    const namespace = addonInstance?.namespace ?? findAddonNamespaceForPackage(packageName);
+    if (namespace && existingServices.webhookService) {
+        existingServices = {
+            ...existingServices,
+            webhookService: scopeWebhookService(existingServices.webhookService, namespace),
+        };
+    }
     if (!factories || !factories.createSingletonServices) {
         return existingServices;
     }
@@ -128,6 +155,9 @@ export const getOrCreatePackageSingletonServices = async (packageName, parentSer
         typeof packageServices.workflowService === 'object') {
         packageServices.workflowService = wrapWorkflowServiceForPackage(packageServices.workflowService, packageName, addonInstance?.namespace ?? null);
     }
+    if (namespace && packageServices.webhookService) {
+        packageServices.webhookService = scopeWebhookService(packageServices.webhookService, namespace);
+    }
     pikkuState(cacheKey, 'package', 'singletonServices', packageServices);
     return packageServices;
 };

package/dist/wirings/addon/wire-addon.d.ts

@@ -1,5 +1,6 @@
 import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
+import type { AddonInstance } from './addon-runner.js';
 export type WireAddonConfig = {
     /** How this instance is addressed. One package may be wired more than once, and the name is what tells the instances apart. */
     name: string;
@@ -112,6 +113,7 @@ export declare const resolveAddonAuth: (packageName: string | null, namespace?:
 export declare const resolveAddonFunctionTarget: (funcName: string, packageName: string | null) => {
     packageName: string;
     localName: string;
+    instance: AddonInstance;
 } | null;
 /**
  * Addon tags name middleware the *consuming app* registered, so they resolve

package/dist/wirings/addon/wire-addon.js

@@ -125,6 +125,12 @@ export const resolveAddonFunctionTarget = (funcName, packageName) => {
     return {
         packageName: config.package,
         localName: funcName.slice(separator + 1),
+        // The instance, not just its package: everything the consuming app lent
+        // this addon — `secretOverrides`, grants, the scoping opt-outs — hangs off
+        // here, and a caller that only learns the package runs the function with
+        // none of it. The namespace is the map key rather than a field on the
+        // stored config, so it is put back on the way out.
+        instance: { namespace, ...config },
     };
 };
 /**

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

@@ -1,10 +1,7 @@
 import type { PikkuRawWire } from '../../types/core.types.js';
-import type { SessionService } from '../../services/user-session-service.js';
-import type { CoreUserSession } from '../../types/core.types.js';
 import type { PikkuRPC } from '../rpc/rpc-types.js';
-export type AgentRPCOptions = {
-    sessionService?: SessionService<CoreUserSession>;
-};
+import type { AgentRPCOptions } from './agent.types.js';
+export type { AgentRPCOptions };
 /**
  * `wire.rpc.agent`, implemented.
  *

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

@@ -1,3 +1,4 @@
+import { pikkuState } from '../../pikku-state.js';
 import { runAgent, resumeAgentSync } from './agent-runner.js';
 import { streamAgent, resumeAgent, interruptAgent } from './agent-stream.js';
 import { wrapChannelWithAGUI } from './agent-agui.js';
@@ -51,3 +52,12 @@ export const createAgentRPC = (wire, options) => {
         approve: async (runId, approvals, expectedAgentName) => asRunResult(await resumeAgentSync(runId, approvals, { sessionService: options.sessionService }, expectedAgentName)),
     };
 };
+/**
+ * The RPC primitive offers `rpc.agent` but must not import this file — a static
+ * reference from `rpc-runner` pins the whole agent runtime into every
+ * deployment unit, including the ones that hold no agent. Registering the
+ * factory here inverts that: only a unit that imports `@pikku/core/agent` pays
+ * for it, which is the same seam the inspector already uses to decide whether
+ * a unit requires the agent services.
+ */
+pikkuState(null, 'agent', 'rpcFactory', createAgentRPC);

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

@@ -6,6 +6,19 @@ import type { AIProviderOptions } from '../../services/agent-runner-service.js';
 import type { PikkuChannel } from '../channel/channel.types.js';
 import type { CorePikkuChannelMiddleware } from '../channel/channel.types.js';
 import type { ApprovalPolicy } from '../channel/channel-rpc.js';
+import type { PikkuRawWire } from '../../types/core.types.js';
+import type { PikkuRPC } from '../rpc/rpc-types.js';
+import type { SessionService } from '../../services/user-session-service.js';
+import type { CoreUserSession } from '../../types/core.types.js';
+export type AgentRPCOptions = {
+    sessionService?: SessionService<CoreUserSession>;
+};
+/**
+ * Builds `wire.rpc.agent`. Registered by `agent-rpc.ts` when a unit imports
+ * `@pikku/core/agent`, so the RPC primitive can offer the agent surface
+ * without naming the agent runtime.
+ */
+export type AgentRPCFactory = (wire: PikkuRawWire, options: AgentRPCOptions) => PikkuRPC['agent'];
 export interface AgentThread {
     id: string;
     resourceId: string;

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

@@ -1,4 +1,11 @@
+/**
+ * Registers `wire.rpc.agent`. Imported for the side effect alone so the RPC
+ * primitive can offer the agent surface without naming the agent runtime, which
+ * would pin it into every deployment unit.
+ */
+import './agent-rpc.js';
 export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './agent-helpers.js';
+export type { AgentRPCOptions, AgentRPCFactory } from './agent.types.js';
 export { wrapChannelWithAGUI } from './agent-agui.js';
 export { runAgent, resumeAgentSync } from './agent-runner.js';
 export { resolveModelAlias } from './agent-model-config.js';

package/dist/wirings/agent/index.js

@@ -1,3 +1,9 @@
+/**
+ * Registers `wire.rpc.agent`. Imported for the side effect alone so the RPC
+ * primitive can offer the agent surface without naming the agent runtime, which
+ * would pin it into every deployment unit.
+ */
+import './agent-rpc.js';
 export { agent, agentStream, agentResume, agentApprove, agentInterrupt, } from './agent-helpers.js';
 export { wrapChannelWithAGUI } from './agent-agui.js';
 export { runAgent, resumeAgentSync } from './agent-runner.js';

package/dist/wirings/rpc/rpc-runner.d.ts

@@ -52,9 +52,12 @@ export declare class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
-     * one file rather than a wing of this one; a getter rather than a field so a
-     * request that never touches an agent never builds it.
+     * Resolved through state rather than imported: naming `agent-rpc.ts` here
+     * pinned the agent runtime — runner, stream, memory, AGUI — into every
+     * deployment unit, because every unit reaches this file through
+     * `function-runner`. `@pikku/core/agent` registers the factory on import, so
+     * a unit that holds an agent has one and a unit that does not never bundles
+     * the tree behind it.
      */
     get agent(): PikkuRPC['agent'];
     remote<In = any, Out = any>(funcName: string, data: In): Promise<Out>;

package/dist/wirings/rpc/rpc-runner.js

@@ -5,7 +5,6 @@ import { pikkuState } from '../../pikku-state.js';
 import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 import { resolveRemoteAddonToken } from '../addon/remote-addon-auth.js';
-import { createAgentRPC } from '../agent/agent-rpc.js';
 /**
  * The session for a wire: read through `getSession` when a runner attached one,
  * otherwise whatever was placed on the wire directly.
@@ -330,11 +329,18 @@ export class ContextAwareRPCService {
     /**
      * The agent facade, built on access.
      *
-     * The implementation lives in `agent/agent-rpc.ts` so the agent surface is
-     * one file rather than a wing of this one; a getter rather than a field so a
-     * request that never touches an agent never builds it.
+     * Resolved through state rather than imported: naming `agent-rpc.ts` here
+     * pinned the agent runtime — runner, stream, memory, AGUI — into every
+     * deployment unit, because every unit reaches this file through
+     * `function-runner`. `@pikku/core/agent` registers the factory on import, so
+     * a unit that holds an agent has one and a unit that does not never bundles
+     * the tree behind it.
      */
     get agent() {
+        const createAgentRPC = pikkuState(null, 'agent', 'rpcFactory');
+        if (!createAgentRPC) {
+            throw new Error('Agent runtime not available: import @pikku/core/agent in this deployment unit to use rpc.agent');
+        }
         return createAgentRPC(this.wire, this.options);
     }
     async remote(funcName, data) {

package/dist/wirings/trigger/index.d.ts

@@ -1,3 +1,7 @@
 export { wireTrigger, wireTriggerSource } from './trigger-runner.js';
+export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, subscribedWebhookEvents, } from './webhook-source-runner.js';
+export type { WebhookSourceOutcome } from './webhook-source-runner.js';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
+export type { CoreTriggerWebhookSource, TriggerEvent, WebhookCheckResult, WebhookLifecycleInput, WebhookReceiveResult, WebhookRequest, WebhookSetupResult, WebhookSourceJob, WebhookSourceMeta, WebhookSourcesMeta, WebhookSourceState, WebhookTeardownInput, WebhookTeardownResult, } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';
 export type { TriggerMeta, TriggerSourceMeta, CorePikkuTriggerFunction, CorePikkuTriggerFunctionConfig, CoreTrigger, } from './trigger.types.js';

package/dist/wirings/trigger/index.js

@@ -1,2 +1,4 @@
 export { wireTrigger, wireTriggerSource } from './trigger-runner.js';
+export { wireTriggerWebhookSource, receiveWebhookSourceRequest, dispatchWebhookSourceJob, runWebhookSourceLifecycle, subscribedWebhookEvents, } from './webhook-source-runner.js';
+export { PIKKU_INCOMING_WEBHOOK_QUEUE_NAME } from './webhook-source.types.js';
 export { PikkuTriggerService } from './pikku-trigger-service.js';

package/dist/wirings/trigger/webhook-source-runner.d.ts

@@ -0,0 +1,45 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { PikkuHTTP } from '../http/http.types.js';
+import type { CoreTriggerWebhookSource, WebhookCheckResult, WebhookSetupResult, WebhookSourceJob, WebhookSourceState, WebhookTeardownResult } from './webhook-source.types.js';
+export declare const wireTriggerWebhookSource: <Events extends Record<string, StandardSchemaV1>>(source: CoreTriggerWebhookSource<Events>) => void;
+/** The declared events some trigger is wired to: what `setup` registers with the provider. */
+export declare const subscribedWebhookEvents: (source: string) => string[];
+/**
+ * The body of a webhook source's route: `receive`, validate, and queue every
+ * event some trigger listens for. Events nobody listens for are answered and
+ * dropped, so the provider does not retry them forever.
+ */
+export declare const receiveWebhookSourceRequest: (sourceName: string, wire: {
+    http?: PikkuHTTP;
+}) => Promise<Response | {
+    received: number;
+}>;
+/** The `pikku-incoming-webhooks` worker: runs the trigger an event was queued for. Throws so the queue retries. */
+export declare const dispatchWebhookSourceJob: (job: WebhookSourceJob) => Promise<void>;
+export type WebhookSourceOutcome = {
+    source: string;
+    url: string;
+    status: WebhookCheckResult['status'] | WebhookSetupResult['status'] | WebhookTeardownResult['status'] | 'skipped' | 'failed';
+    reason?: string;
+    state?: WebhookSourceState;
+    /** The name the produced signing secret must be stored under. */
+    secretName?: string;
+    secret?: string;
+    instructions?: string;
+    error?: string;
+};
+/**
+ * Runs one lifecycle step for every webhook source, as `pikku webhooks
+ * status | setup | teardown` does at deploy. `setup` runs only where `check`
+ * does not report `ok`. One failing source does not stop the rest.
+ */
+export declare const runWebhookSourceLifecycle: ({ action, baseUrl, labelPrefix, previous, singletonServices, }: {
+    action: 'check' | 'setup' | 'teardown';
+    /** Where the app's routes are served, e.g. `https://shop.example.com/api`. */
+    baseUrl: string;
+    labelPrefix: string;
+    /** What the last `setup` returned as `state`, by source name. */
+    previous?: Record<string, WebhookSourceState>;
+    singletonServices?: CoreSingletonServices;
+}) => Promise<WebhookSourceOutcome[]>;

package/dist/wirings/trigger/webhook-source-runner.js

@@ -0,0 +1,221 @@
+import { getSingletonServices, pikkuState } from '../../pikku-state.js';
+import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { PikkuMissingMetaError } from '../../errors/errors.js';
+const LIFECYCLE = ['receive', 'check', 'setup', 'teardown'];
+export const wireTriggerWebhookSource = (source) => {
+    const meta = pikkuState(null, 'trigger', 'webhookSourceMeta')[source.name];
+    if (!meta) {
+        console.warn(`[pikku] Skipping webhook source '${source.name}' — metadata not found. Consider moving this wiring to its own file.`);
+        return;
+    }
+    const sources = pikkuState(null, 'trigger', 'webhookSources');
+    if (sources.has(source.name)) {
+        throw new Error(`Webhook source already exists: ${source.name}`);
+    }
+    sources.set(source.name, source);
+    for (const step of LIFECYCLE) {
+        const funcId = meta[step];
+        const config = source[step];
+        if (funcId && typeof config?.func === 'function') {
+            addFunction(funcId, config);
+        }
+    }
+};
+const triggerName = (source, event) => event ? `${source}:${event}` : source;
+/** The declared events some trigger is wired to: what `setup` registers with the provider. */
+export const subscribedWebhookEvents = (source) => {
+    const triggers = pikkuState(null, 'trigger', 'meta');
+    const meta = pikkuState(null, 'trigger', 'webhookSourceMeta')[source];
+    return (meta?.events ?? []).filter((event) => triggers[triggerName(source, event)]);
+};
+const getSourceMeta = (source) => {
+    const meta = pikkuState(null, 'trigger', 'webhookSourceMeta')[source];
+    if (!meta) {
+        throw new PikkuMissingMetaError(`Missing generated metadata for webhook source '${source}'`);
+    }
+    return meta;
+};
+const runSourceStep = (singletonServices, source, funcId, data) => runPikkuFunc('trigger', source, funcId, {
+    singletonServices,
+    auth: false,
+    data: () => data,
+    wire: {},
+});
+const readRequest = async (http) => {
+    const request = http?.request;
+    if (!request) {
+        throw new Error('A webhook source can only be reached over HTTP');
+    }
+    const query = {};
+    for (const [key, value] of Object.entries(request.query() ?? {})) {
+        if (value !== undefined)
+            query[key] = String(value);
+    }
+    return {
+        body: new Uint8Array(await request.arrayBuffer()),
+        headers: request.headers(),
+        method: request.method(),
+        url: request.path(),
+        query,
+    };
+};
+const validateEvents = async (source, events, logger) => {
+    const valid = [];
+    for (const event of events) {
+        const schema = source?.events?.[event.name];
+        if (!schema) {
+            valid.push(event);
+            continue;
+        }
+        const result = await schema['~standard'].validate(event.data);
+        if (result.issues) {
+            logger.warn(`Webhook source '${source.name}' dropped '${event.name}'${event.id ? ` (${event.id})` : ''}: ${result.issues.map((issue) => issue.message).join('; ')}`);
+            continue;
+        }
+        valid.push({ ...event, data: result.value });
+    }
+    return valid;
+};
+/**
+ * The body of a webhook source's route: `receive`, validate, and queue every
+ * event some trigger listens for. Events nobody listens for are answered and
+ * dropped, so the provider does not retry them forever.
+ */
+export const receiveWebhookSourceRequest = async (sourceName, wire) => {
+    const singletonServices = getSingletonServices();
+    const meta = getSourceMeta(sourceName);
+    const source = pikkuState(null, 'trigger', 'webhookSources').get(sourceName);
+    const request = await readRequest(wire.http);
+    const result = meta.receive
+        ? await runSourceStep(singletonServices, sourceName, meta.receive, request)
+        : {
+            events: [
+                {
+                    name: '',
+                    data: request.body.length
+                        ? JSON.parse(new TextDecoder().decode(request.body))
+                        : undefined,
+                },
+            ],
+        };
+    if ('respond' in result) {
+        const { status, body, headers } = result.respond;
+        const text = body === undefined
+            ? null
+            : typeof body === 'string'
+                ? body
+                : JSON.stringify(body);
+        return new Response(text, { status, headers });
+    }
+    const triggers = pikkuState(null, 'trigger', 'meta');
+    const listened = result.events.filter((event) => triggers[triggerName(sourceName, event.name)]);
+    const events = await validateEvents(source, listened, singletonServices.logger);
+    if (events.length === 0)
+        return { received: 0 };
+    const service = singletonServices.incomingWebhookService;
+    if (!service) {
+        throw new Error(`Webhook source '${sourceName}' received events but no incomingWebhookService is configured to queue them.`);
+    }
+    return {
+        received: await service.accept({ source: sourceName, request, events }),
+    };
+};
+/** The `pikku-incoming-webhooks` worker: runs the trigger an event was queued for. Throws so the queue retries. */
+export const dispatchWebhookSourceJob = async (job) => {
+    const singletonServices = getSingletonServices();
+    const name = triggerName(job.source, job.event.name);
+    const trigger = pikkuState(null, 'trigger', 'meta')[name];
+    if (!trigger) {
+        singletonServices.logger.warn(`No trigger named '${name}' is wired; dropping ${job.event.id ?? 'an event'} from '${job.source}'.`);
+        return;
+    }
+    let error;
+    try {
+        await runPikkuFunc('trigger', name, trigger.pikkuFuncId, {
+            singletonServices,
+            auth: false,
+            data: () => job.event.data,
+            wire: {},
+        });
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+        if (job.receiptId) {
+            await recordAttempt(singletonServices, job.receiptId, name, error);
+        }
+        throw e;
+    }
+    if (job.receiptId) {
+        await recordAttempt(singletonServices, job.receiptId, name);
+    }
+};
+const recordAttempt = (singletonServices, receiptId, trigger, error) => singletonServices.incomingWebhookService
+    ?.recordAttempt(receiptId, { trigger, ...(error ? { error } : {}) })
+    .catch((storeError) => singletonServices.logger.error(`Failed to record the attempt for webhook receipt ${receiptId}`, storeError));
+/**
+ * Runs one lifecycle step for every webhook source, as `pikku webhooks
+ * status | setup | teardown` does at deploy. `setup` runs only where `check`
+ * does not report `ok`. One failing source does not stop the rest.
+ */
+export const runWebhookSourceLifecycle = async ({ action, baseUrl, labelPrefix, previous = {}, singletonServices = getSingletonServices(), }) => {
+    const base = baseUrl.replace(/\/+$/, '');
+    const outcomes = [];
+    for (const meta of Object.values(pikkuState(null, 'trigger', 'webhookSourceMeta'))) {
+        const url = `${base}${meta.route}`;
+        const label = `${labelPrefix}:${meta.name}`;
+        const input = {
+            url,
+            label,
+            events: subscribedWebhookEvents(meta.name),
+            ...(previous[meta.name] ? { previous: previous[meta.name] } : {}),
+        };
+        const outcome = (status, extra = {}) => outcomes.push({ source: meta.name, url, status, ...extra });
+        try {
+            if (action === 'teardown') {
+                if (!meta.teardown) {
+                    outcome('skipped');
+                    continue;
+                }
+                const result = await runSourceStep(singletonServices, meta.name, meta.teardown, { label, ...(input.previous ? { previous: input.previous } : {}) });
+                outcome(result.status);
+                continue;
+            }
+            if (meta.check) {
+                const checked = await runSourceStep(singletonServices, meta.name, meta.check, input);
+                if (action === 'check' || checked.status === 'ok') {
+                    outcome(checked.status === 'ok' && action === 'setup'
+                        ? 'unchanged'
+                        : checked.status, checked.status === 'drifted' ? { reason: checked.reason } : {});
+                    continue;
+                }
+            }
+            else if (action === 'check') {
+                outcome('skipped');
+                continue;
+            }
+            if (!meta.setup) {
+                outcome('manual', {
+                    instructions: `Register ${url} with the provider for: ${input.events.join(', ') || 'every event'}.`,
+                });
+                continue;
+            }
+            const result = await runSourceStep(singletonServices, meta.name, meta.setup, input);
+            if (result.status === 'manual') {
+                outcome('manual', { instructions: result.instructions });
+                continue;
+            }
+            outcome(result.status, {
+                ...(result.state ? { state: result.state } : {}),
+                ...(result.secret && meta.secret
+                    ? { secretName: meta.secret, secret: result.secret }
+                    : {}),
+            });
+        }
+        catch (error) {
+            outcome('failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return outcomes;
+};

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -0,0 +1,106 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CorePikkuFunctionConfig } from '../../function/functions.types.js';
+export declare const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = "pikku-incoming-webhooks";
+/** What every trigger source produces, whichever way it arrives. */
+export type TriggerEvent<Name extends string = string, Data = unknown> = {
+    /** The provider's event type; dispatched to the trigger named `<source>:<name>`. Empty dispatches to `<source>`. */
+    name: Name;
+    /** The provider's event id, which de-duplicates redeliveries. */
+    id?: string;
+    data: Data;
+};
+/** The request exactly as it arrived: providers sign the raw bytes, not re-serialised JSON. */
+export type WebhookRequest = {
+    body: Uint8Array;
+    headers: Record<string, string>;
+    method: string;
+    url: string;
+    query: Record<string, string>;
+};
+export type WebhookReceiveResult = {
+    events: TriggerEvent[];
+}
+/** A handshake, such as Slack's `url_verification`: answered directly, nothing is dispatched. */
+ | {
+    respond: {
+        status: number;
+        body?: unknown;
+        headers?: Record<string, string>;
+    };
+};
+/** Whatever `setup` wants back on the next deploy, for providers whose endpoints cannot be found by label. */
+export type WebhookSourceState = Record<string, unknown>;
+export type WebhookLifecycleInput = {
+    /** Always this deployment's own route: nothing can point it elsewhere. */
+    url: string;
+    /** Stable across deploys of one app and stage, for providers that let endpoints be tagged and listed. */
+    label: string;
+    /** The declared events some trigger is wired to. */
+    events: string[];
+    previous?: WebhookSourceState;
+};
+export type WebhookCheckResult = {
+    status: 'ok';
+} | {
+    status: 'missing';
+} | {
+    status: 'drifted';
+    reason: string;
+};
+export type WebhookSetupResult = {
+    status: 'created' | 'updated' | 'unchanged';
+    state?: WebhookSourceState;
+    /** Only when the provider issued a new signing secret. */
+    secret?: string;
+}
+/** The provider has no API for this: `instructions` tell a person what to set by hand. */
+ | {
+    status: 'manual';
+    instructions: string;
+};
+export type WebhookTeardownInput = {
+    label: string;
+    previous?: WebhookSourceState;
+};
+export type WebhookTeardownResult = {
+    status: 'deleted' | 'absent';
+};
+type SourceFunction<In, Out> = CorePikkuFunctionConfig<any, any> & {
+    func: (services: any, data: In, wire: any) => Promise<Out>;
+};
+export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchemaV1> = Record<string, StandardSchemaV1>> = {
+    /** Triggers subscribe to `<name>:<event>`. Unique across every kind of trigger source. */
+    name: string;
+    method?: 'post' | 'put' | 'get';
+    /** Defaults to `/webhooks/<name>`. */
+    route?: string;
+    /** The secret `receive` verifies with, which `setup` produces. */
+    secret?: string;
+    /** What the source can produce. Each event's data is validated against its schema before it is queued. */
+    events?: Events;
+    /** Omitted: the JSON body is one event dispatched to the trigger named `<name>`. */
+    receive?: SourceFunction<WebhookRequest, WebhookReceiveResult>;
+    check?: SourceFunction<WebhookLifecycleInput, WebhookCheckResult>;
+    setup?: SourceFunction<WebhookLifecycleInput, WebhookSetupResult>;
+    teardown?: SourceFunction<WebhookTeardownInput, WebhookTeardownResult>;
+};
+export type WebhookSourceMeta = {
+    name: string;
+    method: 'post' | 'put' | 'get';
+    route: string;
+    secret?: string;
+    events: string[];
+    receive?: string;
+    check?: string;
+    setup?: string;
+    teardown?: string;
+};
+export type WebhookSourcesMeta = Record<string, WebhookSourceMeta>;
+/** One queued event on its way to its trigger. */
+export type WebhookSourceJob = {
+    source: string;
+    event: TriggerEvent;
+    /** Present when a store-backed service recorded the receipt. */
+    receiptId?: string;
+};
+export {};

package/dist/wirings/trigger/webhook-source.types.js

@@ -0,0 +1 @@
+export const PIKKU_INCOMING_WEBHOOK_QUEUE_NAME = 'pikku-incoming-webhooks';

package/dist/wirings/webhook/define-outgoing-webhook.d.ts

@@ -0,0 +1,28 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Safe } from '../../classification/secret-value.js';
+import type { SendWebhookInput, SendWebhookResult, WebhookService } from '../../services/webhook-service.js';
+export type CoreOutgoingWebhook<Event extends string = string, Payload extends StandardSchemaV1 = StandardSchemaV1> = {
+    event: Event;
+    title: string;
+    description?: string;
+    payload: Payload;
+};
+export type OutgoingWebhookMeta = {
+    event: string;
+    title: string;
+    description?: string;
+    payload?: Record<string, string>;
+    exportedName?: string;
+    sourceFile?: string;
+};
+export type OutgoingWebhooksMeta = Record<string, OutgoingWebhookMeta>;
+export type OutgoingWebhookPayloadOf<W> = W extends CoreOutgoingWebhook<string, infer S> ? StandardSchemaV1.InferInput<S> : never;
+export type OutgoingWebhookDataFor<TMap, Input> = Input extends {
+    event: infer Event;
+} ? Event extends keyof TMap ? {
+    data: Safe<TMap[Event]>;
+} : unknown : unknown;
+export interface TypedWebhookService<TMap = Record<string, unknown>> extends Omit<WebhookService, 'send'> {
+    send<const T extends SendWebhookInput>(input: Safe<T> & OutgoingWebhookDataFor<TMap, T>): Promise<SendWebhookResult>;
+}
+export declare const defineOutgoingWebhook: <const Event extends string, Payload extends StandardSchemaV1>(webhook: CoreOutgoingWebhook<Event, Payload>) => CoreOutgoingWebhook<Event, Payload>;

package/dist/wirings/webhook/define-outgoing-webhook.js

@@ -0,0 +1 @@
+export const defineOutgoingWebhook = (webhook) => webhook;

package/dist/wirings/webhook/index.d.ts

@@ -0,0 +1,2 @@
+export { defineOutgoingWebhook } from './define-outgoing-webhook.js';
+export type { CoreOutgoingWebhook, OutgoingWebhookDataFor, TypedWebhookService, OutgoingWebhookMeta, OutgoingWebhooksMeta, OutgoingWebhookPayloadOf, } from './define-outgoing-webhook.js';

package/dist/wirings/webhook/index.js

@@ -0,0 +1 @@
+export { defineOutgoingWebhook } from './define-outgoing-webhook.js';

package/knowledge/decisions/security/a-public-function-says-so-with-auth-false.md

@@ -0,0 +1,34 @@
+---
+type: decision
+title: A public function says so with auth: false
+description: An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
+tags: authorization, inspector, rpc
+---
+
+# A public function says so with auth: false
+
+PKU574 warns about an exposed sessionless function with no gate. Some of those
+are exactly what the author meant: a published programme, a price list, a health
+check. Before this, the only way to quiet the warning on one was a gate that
+gated nothing — an always-true permission, or `permissionsInBody: true`, which
+claims a check the body does not make. Both put a false statement into meta to
+silence a true one, and the alternative, living with the warning, teaches
+everyone to stop reading it.
+
+`auth: false` is already the field that says "no session required". Writing it
+on a `pikkuSessionlessFunc` is redundant at runtime — sessionless already means
+that — which is what makes it useful as a declaration: nobody writes it by
+accident, so its presence is the author deciding the function is public. The
+inspector now records `auth` as written (`true`, `false` or absent) instead of
+folding `false` into absent, and the check treats `false` as a gate the author
+declared, the same way it treats `permissionsInBody`.
+
+The case the warning exists for is unchanged. A sessionless function that picked
+up `expose: true` later, with nobody thinking about who may call it, has no
+`auth` at all — and still warns.
+
+**What this rules out:** a separate `public: true` flag, which would be a second
+field meaning what `auth: false` already means; reading `readonly` or the
+function's name as evidence it is safe to expose; and silencing PKU574 for every
+sessionless function, which would drop the accidental-exposure case with the
+intentional one.

package/knowledge/decisions/security/an-exposed-ungated-function-is-a-codegen-warning.md

@@ -42,7 +42,10 @@ case it would catch.
 Severity is `warn`, not `critical`. `expose: true` on an ungated sessionless
 function is legitimate for a genuinely public endpoint — a health check, a
 sign-up — so this cannot block a build without breaking correct programs. It
-fails a build only under `--fail-on-warn`.
+fails a build only under `--fail-on-warn`. And the public endpoint is not left
+warning forever: an explicit `auth: false` on a sessionless function declares it
+public on purpose and silences the check (see
+[public is declared with auth: false](./a-public-function-says-so-with-auth-false.md)).
 
 **What this rules out:** checking at boot, where the report arrives after
 deployment; checking in `pikku validate` from `.pikku` JSON, which does not

package/knowledge/decisions/security/index.md

@@ -58,6 +58,7 @@ A rule about who may do what, and which way it fails when it is unsure.
 - [A scaffolded surface is authenticated unless the config opts out in writing](scaffold-features-are-authenticated-unless-opted-out.md) — SUPERSEDED; retains why the legacy 'auth' | 'no-auth' strings are refused rather than coerced
 - [Scenario-step functions are never externally invocable over RPC](scenario-step-functions-are-never-externally-invocable.md) — rpcExposed requires expose and rejects scenarioStep, so test steps stay reachable only from inside a scenario run
 - [Scope resolution happens at the session boundary and scope sync never deletes](scope-resolution-happens-at-the-session-boundary-and-sync-never-deletes.md) — ScopeService is called when a session is built, never by the function runner, and syncScopes only ever adds — revoking is an explicit operation
+- [A public function says so with auth: false](a-public-function-says-so-with-auth-false.md) — An exposed sessionless function that writes auth: false is public on purpose and PKU574 stays quiet; one that leaves auth out still warns
 - [Self-authentication is declared, not detected](self-authentication-is-declared-not-detected.md) — A function that authorizes callers in its own body says so with selfAuthenticated; codegen never tries to infer it
 - [Signed content URLs bind the request path and verify fail-closed](signed-content-urls-bind-the-request-path.md) — A signature that only carries timestamps authorizes every asset, and a verifier with no key must refuse rather than allow
 - [Webhook bodies are signed before they are enqueued](webhook-bodies-are-signed-before-they-are-enqueued.md) — QueueWebhookService computes the HMAC at enqueue time so the signing key never travels in the queue payload

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.122",
+  "version": "0.12.125",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",
@@ -24,6 +24,7 @@
   "sideEffects": [
     "./dist/errors/errors.js",
     "./dist/wirings/addon/remote-addon-auth.js",
+    "./dist/wirings/agent/agent-rpc.js",
     "./dist/wirings/rpc/rpc-runner.js",
     "./dist/wirings/workflow/pikku-scenario-service.js",
     "./dist/wirings/workflow/workflow-approval-policy.js",
@@ -68,6 +69,7 @@
     "./persona": "./dist/wirings/persona/index.js",
     "./secret": "./dist/wirings/secret/index.js",
     "./variable": "./dist/wirings/variable/index.js",
+    "./webhook": "./dist/wirings/webhook/index.js",
     "./oauth2": "./dist/wirings/oauth2/index.js",
     "./errors": "./dist/errors/index.js",
     "./services": "./dist/services/index.js",

package/src/public-surface.json

@@ -100,9 +100,7 @@
     "reconstructStateAt"
   ],
   "./workflow/types": [],
-  "./actor-flow": [
-    "runConversation"
-  ],
+  "./actor-flow": ["runConversation"],
   "./virtual-user": [
     "DEFAULT_MAX_INTERVAL_MS",
     "DEFAULT_MIN_INTERVAL_MS",
@@ -165,9 +163,7 @@
     "wireHTTP",
     "wireHTTPRoutes"
   ],
-  "./remote": [
-    "buildRemoteHeaders"
-  ],
+  "./remote": ["buildRemoteHeaders"],
   "./queue": [
     "QueueJobDiscardedError",
     "QueueJobFailedError",
@@ -184,9 +180,15 @@
     "wireScheduler"
   ],
   "./trigger": [
+    "PIKKU_INCOMING_WEBHOOK_QUEUE_NAME",
     "PikkuTriggerService",
+    "dispatchWebhookSourceJob",
+    "receiveWebhookSourceRequest",
+    "runWebhookSourceLifecycle",
+    "subscribedWebhookEvents",
     "wireTrigger",
-    "wireTriggerSource"
+    "wireTriggerSource",
+    "wireTriggerWebhookSource"
   ],
   "./rpc": [
     "PikkuRPCService",
@@ -207,10 +209,7 @@
     "safeFetch",
     "setDefaultHostResolver"
   ],
-  "./node-host-resolver": [
-    "installNodeHostResolver",
-    "nodeHostResolver"
-  ],
+  "./node-host-resolver": ["installNodeHostResolver", "nodeHostResolver"],
   "./mcp": [
     "MCPEndpointRegistry",
     "MCPError",
@@ -297,10 +296,7 @@
     "wantsStackTrace",
     "wireCLI"
   ],
-  "./cli/command-parser": [
-    "generateCommandHelp",
-    "parseCLIArguments"
-  ],
+  "./cli/command-parser": ["generateCommandHelp", "parseCLIArguments"],
   "./cli/channel": [
     "executeCLIViaChannel",
     "executeRawCLIViaChannel",
@@ -360,10 +356,8 @@
     "deriveOAuth2AppSecrets",
     "validateAndBuildSecretDefinitionsMeta"
   ],
-  "./variable": [
-    "defineVariable",
-    "validateAndBuildVariableDefinitionsMeta"
-  ],
+  "./variable": ["defineVariable", "validateAndBuildVariableDefinitionsMeta"],
+  "./webhook": ["defineOutgoingWebhook"],
   "./oauth2": [],
   "./errors": [
     "AIProviderAuthError",
@@ -428,6 +422,7 @@
     "InMemorySessionStore",
     "InMemoryTriggerService",
     "InMemoryWorkflowService",
+    "IncomingWebhookService",
     "JsonConsoleLogger",
     "LocalCredentialService",
     "LocalEmailService",
@@ -486,19 +481,10 @@
     "subjectIdOf",
     "validateAndBuildFeatureFlagDefinitionsMeta"
   ],
-  "./services/local-meta": [
-    "LocalMetaService"
-  ],
-  "./services/v8-coverage": [
-    "V8CoverageService"
-  ],
-  "./services/istanbul-coverage": [
-    "IstanbulCoverageService"
-  ],
-  "./services/local-content": [
-    "LocalContent",
-    "signedContentPath"
-  ],
+  "./services/local-meta": ["LocalMetaService"],
+  "./services/v8-coverage": ["V8CoverageService"],
+  "./services/istanbul-coverage": ["IstanbulCoverageService"],
+  "./services/local-content": ["LocalContent", "signedContentPath"],
   "./services/local-content-request-handler": [
     "createLocalContentRequestHandler",
     "verifySignedContentRequest"
@@ -528,10 +514,7 @@
     "verifyWithKeyMaterial",
     "wrapDEK"
   ],
-  "./hmac": [
-    "hmacSha256Hex",
-    "timingSafeStringEqual"
-  ],
+  "./hmac": ["hmacSha256Hex", "timingSafeStringEqual"],
   "./state": [
     "addPackageServiceFactories",
     "getAllPackageStates",
@@ -578,13 +561,6 @@
     "getSchema",
     "validateSchema"
   ],
-  "./testing": [
-    "clearPikkuRuntimeState",
-    "defineServiceTests"
-  ],
-  "./dev": [
-    "pikkuDevReloader",
-    "reconcileAddonRegistry",
-    "reloadGeneratedMeta"
-  ]
+  "./testing": ["clearPikkuRuntimeState", "defineServiceTests"],
+  "./dev": ["pikkuDevReloader", "reconcileAddonRegistry", "reloadGeneratedMeta"]
 }