@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/storage/blob-routes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * HTTP routes for the filesystem cache backend.
+ *
+ * `FilesystemCacheStorage` mints signed `http://<orch>/api/v1/cache/blob/<key>?sig=<token>`
+ * URLs that the agent uses to GET cached bytes or PUT new uploads. These
+ * routes verify the HMAC token, reject path traversal, and stream content
+ * to / from disk under the configured `basePath`.
+ *
+ * The S3 backend doesn't go through these routes — it uses real pre-signed
+ * URLs against the S3 endpoint. These routes are mounted only when the
+ * filesystem backend is active (`deps.fsCache` truthy in app.ts).
+ */
+import type { Hono } from 'hono';
+export interface FsCacheRouteDeps {
+    basePath: string;
+    signingSecret: string;
+}
+/** Mount filesystem-backend cache routes onto an existing Hono app. */
+export declare function registerBlobRoutes(app: Hono, deps: FsCacheRouteDeps): void;
+//# sourceMappingURL=blob-routes.d.ts.map

package/dist/storage/filesystem.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Filesystem-backed cache storage.
+ *
+ * Mirrors the `CacheStorage` interface that `S3CacheStorage` provides, but
+ * stores blobs as files under a configured base directory. Pre-signed URLs
+ * are replaced by HMAC-signed `http://<orchUrl>/api/v1/cache/blob/...` URLs
+ * — see `sign-url.ts` for the token mechanics and `app.ts` for the route.
+ *
+ * Intended for single-host deployments and E2E sandboxes where standing up
+ * an S3-compatible service is overkill. Production should still use S3.
+ *
+ * Metadata is co-located as a sibling JSON file (`<key>.meta.json`) so the
+ * data file is byte-identical to what the agent receives over HTTP. TTL is
+ * enforced lazily on access — same model as the S3 backend.
+ */
+import type { CacheStorage } from './types.js';
+export interface FilesystemCacheStorageOptions {
+    /** Absolute path to the cache root directory. Created on first write if missing. */
+    basePath: string;
+    /** Item TTL in milliseconds. Items past TTL since lastAccessedAt are evicted. */
+    ttlMs: number;
+    /** Base URL the agent uses to reach the orchestrator (e.g., `http://orch:10143`). */
+    baseUrl: string;
+    /** Per-process HMAC secret used to sign URLs. See sign-url.ts. */
+    signingSecret: string;
+    /** Optional URL path mount point. Defaults to `/api/v1/cache/blob/`. */
+    routePrefix?: string;
+}
+export declare class FilesystemCacheStorage implements CacheStorage {
+    private readonly basePath;
+    private readonly ttlMs;
+    private readonly baseUrl;
+    private readonly signingSecret;
+    private readonly routePrefix;
+    constructor(options: FilesystemCacheStorageOptions);
+    /**
+     * Map a cache key to its on-disk path. Keys may contain `/`, which becomes a
+     * directory separator. Reject keys containing `..` segments or NUL bytes to
+     * prevent path traversal — the same defence the route layer enforces too.
+     */
+    private resolvePath;
+    /** Public for the HTTP route. The route validates the key before calling. */
+    pathFor(key: string): string;
+    private metaPath;
+    private isExpired;
+    private readMeta;
+    private writeMeta;
+    put(key: string, data: Buffer | string): Promise<void>;
+    get(key: string): Promise<Buffer | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    touch(key: string): Promise<void>;
+    getUrl(key: string): Promise<string | null>;
+    getUploadUrl(key: string): Promise<string>;
+    getInternalUploadUrl(key: string): Promise<string>;
+    initMeta(key: string): Promise<void>;
+    private signedUrl;
+    private deleteFiles;
+}
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/storage/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cache storage module.
+ *
+ * Pluggable storage backends:
+ *   - S3CacheStorage         — production / multi-host
+ *   - FilesystemCacheStorage — single-host / E2E sandbox
+ *
+ * Use createCacheStorage() to instantiate from a discriminated config.
+ */
+export type { CacheStorage, CacheStorageConfig, CacheMetadata, S3CacheStorageConfig, FilesystemCacheStorageConfig, } from './types.js';
+export { S3CacheStorage } from './s3.js';
+export { FilesystemCacheStorage } from './filesystem.js';
+export { signToken, verifyToken, generateSigningSecret } from './sign-url.js';
+export type { SignedMethod, SignedToken, VerifyResult } from './sign-url.js';
+import type { CacheStorage, CacheStorageConfig } from './types.js';
+/**
+ * Create a cache storage backend from configuration.
+ */
+export declare function createCacheStorage(config: CacheStorageConfig): CacheStorage;
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/s3.d.ts

@@ -0,0 +1,68 @@
+/**
+ * S3-backed cache storage.
+ *
+ * Stores cached items in S3 with custom metadata headers for TTL tracking.
+ * Uses AWS SDK v3 modular imports -- only loaded when S3 storage is configured.
+ *
+ * Metadata storage:
+ *   x-amz-meta-created-at      -- ISO timestamp of creation
+ *   x-amz-meta-last-accessed-at -- ISO timestamp of last access
+ *
+ * TTL is enforced lazily: expired items are deleted on access.
+ * Pre-signed URLs are generated for getUrl() with 15-minute expiry.
+ */
+import type { CacheStorage } from './types.js';
+export interface S3CacheStorageOptions {
+    bucket: string;
+    prefix: string;
+    ttlMs: number;
+    region?: string;
+    /** Custom endpoint URL for S3-compatible services (e.g., SeaweedFS, LocalStack) */
+    endpoint?: string;
+    /**
+     * Separate endpoint for pre-signed URLs (upload and download).
+     * When set, pre-signed URLs use this endpoint instead of `endpoint`.
+     * Useful when the orchestrator accesses S3 on localhost but agents
+     * need a container-routable address (e.g., container DNS name).
+     */
+    externalEndpoint?: string;
+    /** Use path-style access instead of virtual-hosted-style (required for most S3-compatible services) */
+    forcePathStyle?: boolean;
+}
+export declare class S3CacheStorage implements CacheStorage {
+    private readonly client;
+    /** Separate client for pre-signed URL generation (uses externalEndpoint if configured). */
+    private readonly presignClient;
+    private readonly bucket;
+    private readonly prefix;
+    private readonly ttlMs;
+    constructor(options: S3CacheStorageOptions);
+    /** Build the full S3 object key from a cache key. */
+    private objectKey;
+    /** Check if metadata indicates an expired item. */
+    private isExpired;
+    /**
+     * Read metadata from an S3 object's custom headers.
+     * Returns null if the object doesn't exist (NoSuchKey/NotFound).
+     */
+    private readMeta;
+    /**
+     * Update metadata on an S3 object by copying it to itself.
+     * This is the standard S3 pattern for updating metadata without re-uploading data.
+     */
+    private updateMeta;
+    /** Check if an error is a "not found" error (NoSuchKey, NotFound, 404). */
+    private isNotFoundError;
+    put(key: string, data: Buffer | string): Promise<void>;
+    get(key: string): Promise<Buffer | null>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    touch(key: string): Promise<void>;
+    getUrl(key: string): Promise<string | null>;
+    getUploadUrl(key: string): Promise<string>;
+    getInternalUploadUrl(key: string): Promise<string>;
+    initMeta(key: string): Promise<void>;
+    /** Delete an S3 object. Idempotent (doesn't error if missing). */
+    private deleteObject;
+}
+//# sourceMappingURL=s3.d.ts.map

package/dist/storage/sign-url.d.ts

@@ -0,0 +1,45 @@
+/**
+ * HMAC-signed URL tokens for the filesystem cache backend.
+ *
+ * Pre-signed S3 URLs are not available for filesystem storage, so the
+ * filesystem backend mints HMAC-SHA256 tokens that the orchestrator's HTTP
+ * blob route verifies before serving / writing a file. Token shape:
+ *
+ *   `${expiresUnixMs}.${hexSig}`
+ *
+ * Signature input: `${method}:${key}:${expiresUnixMs}` with HMAC-SHA256 keyed
+ * by a per-orchestrator-process secret (random 32-byte hex at boot, persists
+ * for the lifetime of the process). Tokens become invalid on orchestrator
+ * restart — fine for the filesystem backend's E2E / single-host use case.
+ */
+/** Default URL lifetime: 1 hour (matches S3 backend's PUT-URL lifetime). */
+export declare const DEFAULT_SIGN_URL_TTL_MS: number;
+export type SignedMethod = 'GET' | 'PUT';
+/**
+ * Generate a fresh per-process signing secret. Caller stores it on the
+ * orchestrator config object so the same value is used for sign + verify.
+ */
+export declare function generateSigningSecret(): string;
+export interface SignedToken {
+    /** Encoded token string (`${expiresMs}.${sig}`) ready to drop into a URL. */
+    token: string;
+    /** Expiry timestamp in unix ms — exposed for tests and logging. */
+    expiresMs: number;
+}
+/**
+ * Mint a signed token for the given (method, key, expiry) triple.
+ */
+export declare function signToken(secret: string, method: SignedMethod, key: string, ttlMs?: number): SignedToken;
+export type VerifyResult = {
+    ok: true;
+    expiresMs: number;
+} | {
+    ok: false;
+    reason: 'malformed' | 'expired' | 'bad-signature';
+};
+/**
+ * Verify a token. Constant-time signature compare on hex digest length;
+ * rejects malformed shapes and expired tokens up-front.
+ */
+export declare function verifyToken(secret: string, method: SignedMethod, key: string, token: string): VerifyResult;
+//# sourceMappingURL=sign-url.d.ts.map

package/dist/storage/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Cache storage abstraction for the orchestrator.
+ *
+ * Provides a pluggable backend interface for storing and retrieving
+ * cached data (compiled workflow bundles, etc.). Implementations
+ * must handle TTL-based expiry via lastAccessedAt timestamps.
+ *
+ * Backends:
+ *   - `S3CacheStorage` for production / multi-host deployments
+ *   - `FilesystemCacheStorage` for single-host / E2E sandboxes
+ */
+/**
+ * Metadata tracked alongside each cached item.
+ * Used for TTL-based expiry (based on lastAccessedAt).
+ */
+export interface CacheMetadata {
+    /** ISO timestamp of when the item was first stored */
+    createdAt: string;
+    /** ISO timestamp of when the item was last accessed (read or touched) */
+    lastAccessedAt: string;
+}
+/**
+ * Pluggable cache storage interface.
+ *
+ * All operations are async. Implementations must handle TTL-based expiry:
+ * an item is considered expired when (now - lastAccessedAt) > ttlMs.
+ * Expired items are cleaned up lazily on access.
+ */
+export interface CacheStorage {
+    /** Store a value under the given key. Overwrites if key already exists. */
+    put(key: string, data: Buffer | string): Promise<void>;
+    /** Retrieve a value by key. Returns null if not found or expired. */
+    get(key: string): Promise<Buffer | null>;
+    /** Check if a key exists and is not expired, without retrieving data. */
+    has(key: string): Promise<boolean>;
+    /** Delete a key. Returns true if the key existed (even if expired). */
+    delete(key: string): Promise<boolean>;
+    /** Update lastAccessedAt to now, refreshing the TTL. No-op if key doesn't exist. */
+    touch(key: string): Promise<void>;
+    /**
+     * Get a pre-signed download URL for the cached item.
+     * Returns null if not found or expired.
+     */
+    getUrl(key: string): Promise<string | null>;
+    /**
+     * Generate a pre-signed PUT URL for direct agent upload.
+     * Uses the external endpoint (container-routable) when configured.
+     */
+    getUploadUrl(key: string): Promise<string>;
+    /**
+     * Generate a pre-signed PUT URL using the internal endpoint.
+     * Use this when the uploader is on the host (e.g., CLI uploads),
+     * not in a container. Falls back to getUploadUrl() when no
+     * external endpoint is configured.
+     */
+    getInternalUploadUrl(key: string): Promise<string>;
+    /**
+     * Set initial metadata on an object that was uploaded via pre-signed URL.
+     * Pre-signed PUT URLs cannot carry custom metadata, so this must be called
+     * after the agent confirms upload via cache.upload.complete.
+     * Sets created-at and last-accessed-at to now.
+     */
+    initMeta(key: string): Promise<void>;
+}
+import type { SharedS3Config } from '@kici-dev/shared';
+/**
+ * S3 backend config. Extends the generic `SharedS3Config` from
+ * `@kici-dev/shared` with the cache-specific `ttlMs` knob.
+ */
+export type S3CacheStorageConfig = SharedS3Config & {
+    type: 's3';
+    ttlMs: number;
+};
+/**
+ * Filesystem backend config. Stores blobs as files under `basePath` and
+ * mints HMAC-signed `http://baseUrl<routePrefix>...` URLs that the
+ * orchestrator's `/api/v1/cache/blob/*` route verifies before serving.
+ *
+ * Intended for single-host / E2E sandboxes where standing up an
+ * S3-compatible service is overkill.
+ */
+export interface FilesystemCacheStorageConfig {
+    type: 'filesystem';
+    /** Absolute path to the cache root directory. */
+    basePath: string;
+    /** Item TTL in milliseconds. */
+    ttlMs: number;
+    /** Base URL the agent uses to reach the orchestrator. */
+    baseUrl: string;
+    /** Per-process HMAC secret used to sign URLs. */
+    signingSecret: string;
+}
+/**
+ * Configuration for creating a cache storage backend. Discriminated union
+ * keyed on `type` so new backends slot in without breaking consumers.
+ */
+export type CacheStorageConfig = S3CacheStorageConfig | FilesystemCacheStorageConfig;
+//# sourceMappingURL=types.d.ts.map

package/dist/webhook/dedup.d.ts

@@ -0,0 +1,44 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * Delivery ID deduplication cache with dual-layer storage:
+ * 1. In-memory Set for hot-path performance (last 10,000 IDs)
+ * 2. Database persistence via dedup_cache table for durability
+ *
+ * In Hybrid mode, the same webhook may arrive both via WS relay and
+ * direct ingestion -- the dedup cache ensures each is processed once.
+ */
+export declare class DedupCache {
+    private readonly db;
+    private readonly memoryCache;
+    private readonly insertionOrder;
+    constructor(db: Kysely<Database>);
+    /**
+     * Check if a delivery ID has already been processed.
+     * Checks in-memory cache first (fast path), then DB.
+     */
+    exists(deliveryId: string): Promise<boolean>;
+    /**
+     * Mark a delivery ID as processed.
+     * Inserts into both in-memory cache and database with 24h TTL.
+     * Idempotent -- duplicate marks are silently ignored.
+     */
+    mark(deliveryId: string): Promise<void>;
+    /**
+     * Remove expired entries from the database.
+     * Also trims the in-memory cache to MAX_MEMORY_CACHE_SIZE.
+     *
+     * @returns Number of expired entries deleted from database
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Add a delivery ID to the in-memory cache, maintaining insertion order.
+     */
+    private addToMemoryCache;
+    /**
+     * Trim the in-memory cache to MAX_MEMORY_CACHE_SIZE entries,
+     * removing the oldest entries first.
+     */
+    private trimMemoryCache;
+}
+//# sourceMappingURL=dedup.d.ts.map

package/dist/webhook/event-log.d.ts

@@ -0,0 +1,83 @@
+import { EventLogStatus, EventLogSource } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { LogStorage } from '../reporting/log-storage.js';
+import type { WebhookInfo } from './handler.js';
+/** Configuration for the writer. */
+export interface EventLogWriterOptions {
+    /** Soft cap in bytes for payload upload (default 5 MB). */
+    maxPayloadBytes: number;
+}
+/**
+ * Outcome metadata recorded alongside the delivery row.
+ *
+ * Most fields are optional and default to safe values — callers in the early
+ * branches (duplicate, dedup) only know the routing-level metadata; later
+ * branches (processed, lockfile_missing, failed) carry richer outcome data.
+ */
+export interface EventLogOutcome {
+    /** Resolved tenant ID. Required (the table is org-scoped). */
+    orgId: string;
+    /** Where the delivery arrived. */
+    source: EventLogSource;
+    /** Outcome status. */
+    status: EventLogStatus;
+    /** Workflows matched by trigger evaluation (default 0). */
+    matchedCount?: number;
+    /** owner/repo extracted from payload (when available). */
+    repoIdentifier?: string | null;
+    /** Best-effort ref/branch (when extractable). */
+    ref?: string | null;
+    /** First run spawned by this delivery. */
+    runId?: string | null;
+    /** Failure reason when status='failed'. */
+    errorMessage?: string | null;
+}
+/**
+ * Pre-computed payload representation. Letting callers serialize once and
+ * pass both the bytes and the JSON shape avoids double-stringify in the
+ * hot path. The writer hashes the bytes, gzips them, and uploads.
+ */
+export interface PayloadBytes {
+    /** UTF-8 encoded raw body bytes (what Platform hashed). */
+    raw: Buffer;
+}
+/**
+ * Build a `PayloadBytes` from the parsed webhook payload object. Uses
+ * `JSON.stringify` with no formatting — same shape Platform uses to compute
+ * its hash on the relay path (Platform actually hashes the inbound HTTP body
+ * directly; for relay-replayed webhooks the orchestrator only ever sees the
+ * parsed object, so we re-stringify deterministically and hash that).
+ *
+ * For DIRECT ingress paths (orchestrator HTTP endpoint) callers SHOULD pass
+ * the raw HTTP body buffer instead — that matches Platform's hash byte-for-
+ * byte for the same delivery in mixed-mode setups.
+ */
+export declare function payloadFromObject(payload: unknown): PayloadBytes;
+/**
+ * Build a `PayloadBytes` from a raw HTTP body string (direct ingress).
+ */
+export declare function payloadFromRawBody(body: string): PayloadBytes;
+export declare class EventLogWriter {
+    private readonly db;
+    private readonly logStorage;
+    private readonly opts;
+    constructor(db: Kysely<Database>, logStorage: LogStorage, opts: EventLogWriterOptions);
+    /**
+     * Build the canonical object-storage key for a delivery's payload.
+     * Exposed so the cleanup job can compute keys for deletion without
+     * calling back into the writer instance.
+     */
+    static payloadKey(orgId: string, deliveryId: string): string;
+    /**
+     * Record a delivery outcome.
+     *
+     * Idempotent on `(org_id, delivery_id)`: if a row already exists (e.g. the
+     * pipeline already wrote a `received` row before this `processed` follow-up),
+     * the existing row is updated with the new outcome metadata. The
+     * payload_key / hash / size fields are NOT overwritten on update — those
+     * come from the original delivery's body.
+     */
+    record(info: WebhookInfo, payload: PayloadBytes, outcome: EventLogOutcome): Promise<void>;
+}
+//# sourceMappingURL=event-log.d.ts.map

package/dist/webhook/generic-sources.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Generic webhook source manager.
+ *
+ * Provides CRUD operations for webhook source configurations stored in
+ * the generic_webhook_sources table. Each source defines verification method,
+ * event type extraction rules, rate limits, and header filtering.
+ */
+import { type Kysely } from 'kysely';
+import type { Database, GenericWebhookSource } from '../db/types.js';
+import type { VerificationMethod } from '../providers/generic/verification.js';
+import { type UniversalGitConfig } from '../providers/universal-git/config.js';
+/**
+ * Input for creating a new generic webhook source.
+ */
+interface CreateSourceInput {
+    orgId: string;
+    name: string;
+    verificationMethod?: VerificationMethod;
+    verificationConfig?: Record<string, unknown>;
+    eventTypeHeader?: string;
+    eventTypePath?: string;
+    idempotencyKeyHeader?: string;
+    idempotencyKeyPath?: string;
+    dedupWindowSeconds?: number;
+    maxPayloadBytes?: number;
+    allowedEvents?: string[];
+    stripHeaders?: string[];
+    rateLimitRpm?: number;
+    /** Provider implementation: 'generic' (default) or 'internal' (E2E/staging
+     *  github-shaped payload routing through InternalWebhookNormalizer). */
+    providerType?: 'generic' | 'internal';
+    /** Universal-git configuration — when set, promotes this source from a
+     *  payload-only generic webhook to a full git-aware source that can register
+     *  workflows, fetch lock files, and be cloned by agents. Validated against
+     *  `UniversalGitConfigSchema`; stored as JSONB in `generic_webhook_sources.git_config`. */
+    gitConfig?: UniversalGitConfig;
+}
+/**
+ * Input for updating an existing generic webhook source. Use `gitConfig: null`
+ * to explicitly demote a universal-git source back to a plain generic webhook
+ * (omitting the field leaves the existing config untouched).
+ */
+type UpdateSourceInput = Partial<Omit<CreateSourceInput, 'orgId' | 'gitConfig'>> & {
+    gitConfig?: UniversalGitConfig | null;
+};
+/**
+ * Generic webhook source manager.
+ *
+ * Manages CRUD operations for generic_webhook_sources table.
+ * Sources are identified by routing keys with format `generic:<orgId>:<sourceId>`.
+ */
+export declare class GenericSourceManager {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Create a new generic webhook source.
+     * Generates a routing key in format `generic:<orgId>:<sourceId>`.
+     */
+    create(input: CreateSourceInput): Promise<GenericWebhookSource>;
+    /**
+     * Get a source by ID (excludes soft-deleted sources).
+     */
+    getById(id: string): Promise<GenericWebhookSource | null>;
+    /**
+     * Get a source by routing key (excludes soft-deleted and disabled sources).
+     */
+    getByRoutingKey(routingKey: string): Promise<GenericWebhookSource | null>;
+    /**
+     * Get a source by org ID and name (unique lookup, excludes soft-deleted).
+     */
+    getByOrgAndName(orgId: string, name: string): Promise<GenericWebhookSource | null>;
+    /**
+     * List all sources for an org.
+     */
+    list(orgId: string, includeDeleted?: boolean): Promise<GenericWebhookSource[]>;
+    /**
+     * List all enabled, non-deleted sources matching a provider type.
+     *
+     * Used at orchestrator startup to register provider bundles per routing key
+     * (e.g. registering an InternalWebhookNormalizer bundle for every
+     * provider_type='internal' source so the staging stg-ha smoke test and
+     * other internal-bundle E2E harnesses can dispatch real runs through the
+     * generic endpoint without a real GitHub signature).
+     */
+    listByProviderType(providerType: 'generic' | 'internal'): Promise<GenericWebhookSource[]>;
+    /**
+     * List all enabled, non-deleted sources with a non-null `git_config`
+     * (universal-git sources). Used at orchestrator startup + config reload
+     * to register a universal-git `ProviderBundle` under each source's
+     * routing key.
+     */
+    listUniversalGitSources(): Promise<GenericWebhookSource[]>;
+    /**
+     * Update a source's configuration.
+     */
+    update(id: string, input: UpdateSourceInput): Promise<GenericWebhookSource | null>;
+    /**
+     * Soft delete a source (sets deleted_at timestamp).
+     */
+    softDelete(id: string): Promise<void>;
+    /**
+     * Hard delete a source (removes the row entirely).
+     */
+    hardDelete(id: string): Promise<void>;
+    /**
+     * Enable a source.
+     */
+    enable(id: string): Promise<void>;
+    /**
+     * Disable a source.
+     */
+    disable(id: string): Promise<void>;
+    /**
+     * Check if a request is a duplicate within the dedup window.
+     * Uses the kici_events table for idempotency checking.
+     *
+     * @param sourceId - Source ID
+     * @param idempotencyKey - Idempotency key from header or payload
+     * @returns true if this is a duplicate request
+     */
+    checkIdempotency(sourceId: string, idempotencyKey: string): Promise<boolean>;
+    /**
+     * Record an idempotency marker after successful processing.
+     * Inserts a `__dedup:<key>` event into kici_events so that
+     * checkIdempotency can detect retries within the dedup window.
+     *
+     * @param sourceId - Source ID
+     * @param idempotencyKey - Idempotency key from header or payload
+     */
+    markIdempotency(sourceId: string, idempotencyKey: string): Promise<void>;
+    /**
+     * Check if payload size is within the source's limit.
+     *
+     * @param sourceId - Source ID
+     * @param bodyLength - Length of the request body in bytes
+     * @returns Whether the payload is allowed and what the max is
+     */
+    checkPayloadSize(sourceId: string, bodyLength: number): Promise<{
+        allowed: boolean;
+        maxBytes: number;
+    }>;
+}
+/**
+ * Return the active (non-soft-deleted) generic_webhook_sources routing keys
+ * for Platform registration. Excluding soft-deleted rows is critical — if a
+ * source is recreated with the same name, Platform would otherwise see the
+ * orchestrator register both the stale routing key and the fresh one, and
+ * end up routing a subset of orchestrators to the wrong key. This matches
+ * every other query on this table that filters `deleted_at IS NULL` (see
+ * `GenericSourceManager.getById`, `.list`, `.listByProviderType`, etc.).
+ *
+ * Returns `provider_type` alongside the routing key so callers can decide
+ * whether the local orchestrator can actually serve each row. A peer that
+ * cannot serve a provider_type (e.g. an `internal` source on a peer with no
+ * `KICI_INTERNAL_PROVIDER_REPO_PATH`) MUST NOT advertise that routing key
+ * to Platform — otherwise Platform's least-loaded relay may pick that peer
+ * and the webhook is silently dropped on a pipeline that has no working
+ * lock-file fetcher.
+ */
+export declare function loadActiveGenericRoutingKeys(db: Kysely<Database>): Promise<Array<{
+    routing_key: string;
+    customer_id: string;
+    provider_type: string;
+    name: string;
+    /** Whether the row has a non-null `git_config` (universal-git source). */
+    has_git_config: boolean;
+}>>;
+export {};
+//# sourceMappingURL=generic-sources.d.ts.map

package/dist/webhook/handler.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Provider-agnostic webhook info.
+ *
+ * All provider-specific details are abstracted away. The routingKey
+ * and provider fields enable provider lookup, while the rest of the
+ * fields are universal across all webhook providers.
+ */
+import type { ProviderType } from '@kici-dev/engine';
+export interface WebhookInfo {
+    /** Routing key (e.g., "github:12345") */
+    routingKey: string;
+    /** Unique delivery ID */
+    deliveryId: string;
+    /** Provider event type (e.g., "push", "pull_request") */
+    event: string;
+    /** Action field from payload (e.g., "opened"), null if not present */
+    action: string | null;
+    /** Provider type (e.g., "github") */
+    provider: ProviderType;
+    /** Raw webhook payload */
+    payload: Record<string, unknown>;
+}
+//# sourceMappingURL=handler.d.ts.map