@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/dist/event-bus-binding.d.ts

@@ -0,0 +1,107 @@
+import type { Result, TenantId } from '@kindgi/types';
+/**
+ * `EventBusBinding` — caller-plugged pub/sub surface for push-based event
+ * delivery. When wired, `runsRouter`'s `GET /:runId/stream` uses it
+ * instead of polling the journal every 200 ms.
+ *
+ * The API package doesn't own event-bus persistence. Deployments plug in
+ * a binding via `CreateAppInput.eventBus` (the Kindgi runtime provides a
+ * Postgres-backed one). When absent, SSE endpoints fall back to journal
+ * polling — no regression for callers who don't wire the binding.
+ *
+ * ## Semantics
+ *
+ * - **Per-tenant, per-channel FIFO.** `seq` monotonically increases per
+ *   `(tenantId, channel)` tuple. Subscribers may catch up from a specific
+ *   `sinceSeq` after reconnect.
+ * - **Durable log.** Every publish is persisted before notification;
+ *   subscribers can backfill from the log after connection loss. The
+ *   notification is a fast-path signal; the log is the source of truth.
+ * - **Tenant isolation.** The binding keeps channels per tenant and
+ *   filters log reads by tenant. A correctly-implemented binding never
+ *   delivers another tenant's events.
+ *
+ * ## Wire shape
+ *
+ * `EventPayload` is what subscribers receive. `publish` accepts only
+ * `doc` — the binding assigns `v`, `seq`, `timestamp` and fills in
+ * `channel` + `tenantId` from its arguments. Callers never build the
+ * envelope directly.
+ */
+export interface EventBusBinding {
+    /**
+     * Publish `doc` to `(tenantId, channel)`. The binding assigns a
+     * monotonic `seq` per `(tenantId, channel)`, persists the event to its
+     * log, and notifies subscribers. Returns `{ kind: 'ok' }` after the
+     * event is durable. The notification only needs to identify the new
+     * entry — subscribers read large `doc` payloads from the log (a
+     * Postgres NOTIFY payload, for example, is limited to 8000 bytes).
+     */
+    publish(tenantId: TenantId, channel: string, doc: unknown): Promise<Result<void, EventBusError>>;
+    /**
+     * Publish `docs` to `(tenantId, channel)` in order, as one write: the
+     * same as `publish` for each, with consecutive `seq`s and one
+     * notification. Optional — a publisher with a batch calls it when the
+     * binding has it.
+     */
+    publishMany?(tenantId: TenantId, channel: string, docs: readonly unknown[]): Promise<Result<void, EventBusError>>;
+    /**
+     * Subscribe to `(tenantId, channel)`. `onEvent` is invoked for each
+     * published payload in `seq` order, starting from `options.sinceSeq`
+     * (default: current tail — new events only). Returns a `Subscription`
+     * whose `unsubscribe()` tears down the underlying listener.
+     *
+     * `signal.abort()` unsubscribes atomically. Callers usually pass an
+     * AbortController tied to the SSE stream's lifetime.
+     *
+     * On connection loss the binding reconnects transparently and
+     * backfills from `lastSeen + 1` — subscribers observe no gaps.
+     * A binding whose push channel is unavailable may fall back to
+     * polling its log without breaking the subscriber contract.
+     */
+    subscribe(tenantId: TenantId, channel: string, onEvent: (payload: EventPayload) => void, signal: AbortSignal, options?: SubscribeOptions): Promise<Result<Subscription, EventBusError>>;
+}
+/** Options for `subscribe`. */
+export interface SubscribeOptions {
+    /**
+     * Deliver rows with `seq > sinceSeq` before entering push mode.
+     * When omitted, the subscriber joins at the current tail (new
+     * events only) — appropriate for a fresh SSE connect with no
+     * `Last-Event-Id`. When present, must be a non-negative integer.
+     */
+    readonly sinceSeq?: number;
+}
+/** Envelope subscribers receive on every push. */
+export interface EventPayload {
+    readonly v: 1;
+    readonly channel: string;
+    readonly tenantId: TenantId;
+    /** Monotonic sequence per `(tenantId, channel)`. Starts at 1. */
+    readonly seq: number;
+    /** ISO-8601 timestamp assigned at persist time. */
+    readonly timestamp: string;
+    /** Caller-supplied doc — the runtime shape flowing through the bus. */
+    readonly doc: unknown;
+}
+/**
+ * Handle returned from `subscribe`. Callers must `unsubscribe()` to
+ * release the underlying listener. Equivalent to aborting
+ * the `signal` passed at subscribe time — either releases the same
+ * resources.
+ */
+export interface Subscription {
+    /**
+     * Tear down the subscription. Safe to call multiple times; idempotent
+     * after the first call.
+     */
+    unsubscribe(): Promise<void>;
+}
+/** Non-transient errors from `publish` / `subscribe`. */
+export interface EventBusError {
+    readonly code: 'publish-failed' | 'subscribe-failed' | 'bad-input' | 'not-supported';
+    readonly message: string;
+    readonly cause?: unknown;
+}
+/** Envelope version — bumped only when the payload shape changes. */
+export declare const CURRENT_EVENT_BUS_ENVELOPE_VERSION: 1;
+//# sourceMappingURL=event-bus-binding.d.ts.map

package/dist/event-bus-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-binding.d.ts","sourceRoot":"","sources":["../src/event-bus-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;IAEjG;;;;;OAKG;IACH,WAAW,CAAC,CACV,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,OAAO,EAAE,GACvB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC;IAExC;;;;;;;;;;;;;OAaG;IACH,SAAS,CACP,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,EACxC,MAAM,EAAE,WAAW,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,CAAC;CACjD;AAED,+BAA+B;AAC/B,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,WAAW,GAAG,eAAe,CAAC;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,qEAAqE;AACrE,eAAO,MAAM,kCAAkC,EAAG,CAAU,CAAC"}

package/dist/event-bus-binding.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/** Envelope version — bumped only when the payload shape changes. */
+export const CURRENT_EVENT_BUS_ENVELOPE_VERSION = 1;
+//# sourceMappingURL=event-bus-binding.js.map

package/dist/event-bus-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus-binding.js","sourceRoot":"","sources":["../src/event-bus-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AA4HjC,qEAAqE;AACrE,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAU,CAAC"}

package/dist/flow-binding.d.ts

@@ -0,0 +1,194 @@
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Flow } from '@kindgi/flow';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, FlowId, ProjectId, TenantId } from '@kindgi/types';
+/**
+ * Caller-plugged surface for the flow catalog. Mirrors
+ * `AgentRegistryBinding` 1:1 — the API package does NOT own registry
+ * persistence. Deployments wire an in-memory `Map`-backed store — or a
+ * durable pack-backed store — through this binding.
+ *
+ * Publish is data-as-code: the route validates the wire body via
+ * `loadFlow(...)` from `@kindgi/flow` before calling; the binding
+ * receives a well-formed `Flow`. Handler-as-code uploads (a flow
+ * carrying inline node handlers) are not supported.
+ *
+ * Every method is tenant-scoped: callers pass `tenantId` explicitly so
+ * multi-tenant deployments can partition storage without exposing the
+ * scoping inside the API package.
+ *
+ * Cursors are opaque — the binding chooses its encoding (index-based,
+ * `id@version`, ISO timestamps). The API layer only validates that a
+ * cursor round-trips as a string; it never inspects the payload.
+ */
+export interface FlowRegistryBinding {
+    /**
+     * Cursor-paginated list of flows (latest version per id, sorted by
+     * flow id ascending). Optional `nameFilter` is a prefix match on the
+     * flow id — the runtime uses dotted namespaces (`ingest.contract-pdf`),
+     * so prefix matching is the natural filter shape.
+     */
+    list(input: FlowListInput): Promise<FlowPage>;
+    /**
+     * Latest version of the given flow id, or `null` if unknown. The
+     * route surfaces `null` as `404 flow-not-found`.
+     */
+    get(input: FlowGetInput): Promise<Flow | null>;
+    /**
+     * Specific `(flowId, version)` lookup, or `null` if unknown.
+     * Returns tombstoned versions too — provenance paths need to
+     * resolve historical run references.
+     */
+    getVersion(input: FlowGetVersionInput): Promise<Flow | null>;
+    /**
+     * Head-row existence check. Lets `GET /v1/flows/{id}` distinguish
+     * `410 gone` (identity exists, no active version) from `404 not-
+     * found` (never registered).
+     */
+    headExists(input: FlowGetInput): Promise<boolean>;
+    /**
+     * Cursor-paginated list of versions for a specific flow id. Sort
+     * order is binding-defined (for example ascending semver). Returns an empty page (no error) when the id
+     * is unknown — the route flips that to `404` via a prior `get`.
+     */
+    listVersions(input: FlowListVersionsInput): Promise<FlowPage>;
+    /**
+     * Publish a validated flow definition. The API route validates
+     * shape via `loadFlow(...)` before calling — the binding receives a
+     * well-formed `Flow`. Bindings MAY reject with `already-registered`
+     * when the same `(flowId, version)` is re-published; the route maps
+     * that to `409`.
+     */
+    publish(input: FlowPublishInput): Promise<FlowPublishOutcome>;
+    /**
+     * Soft-tombstone a specific `(flowId, version)`. When this leaves
+     * NO active versions, the flow has no latest version — it enters the
+     * derived "retired" state (GET returns 410 gone).
+     * Publish of a new version reactivates.
+     */
+    unregister(input: FlowUnregisterInput): Promise<FlowUnregisterOutcome>;
+    /**
+     * Un-tombstone a specific `(flowId, version)`. Recomputes the flow's
+     * latest version. Restores manifest bytes verbatim (semver
+     * hygiene). Idempotent.
+     */
+    reinstateVersion(input: FlowReinstateVersionInput): Promise<FlowReinstateVersionOutcome>;
+}
+export interface FlowListInput {
+    readonly tenantId: TenantId;
+    readonly limit: number;
+    readonly cursor?: Cursor;
+    /** Prefix match on `Flow.id`. Undefined = no filter. */
+    readonly nameFilter?: string;
+    /**
+     * Narrow the list to a specific scope. Absent = no scope narrow
+     * (return every row in the tenant the caller can see — admin/audit
+     * default).
+     *
+     * Content-scoped semantics (this binding):
+     * - `{ kind: 'project', projectId }` — rows in that project.
+     * - `{ kind: 'org', orgId }` — rows in every project belonging to
+     *   that org.
+     * - `{ kind: 'tenant', tenantId }` — every row in the tenant.
+     *
+     * Content rows always belong to a project, so `inherit` has no
+     * effect here.
+     */
+    readonly scope?: Scope;
+    /**
+     * `false` = literal-at-this-scope only (admin/audit view).
+     * `true` (default) = inheritance walk (user-facing view).
+     * No-op for content-scoped bindings (rows only exist at
+     * project-level — there is no upward hierarchy to walk). Kept for
+     * uniformity: scope-aware bindings share one filter shape across the
+     * SDK and OpenAPI schemas.
+     */
+    readonly inherit?: boolean;
+}
+export interface FlowGetInput {
+    readonly tenantId: TenantId;
+    readonly flowId: FlowId;
+}
+export interface FlowGetVersionInput {
+    readonly tenantId: TenantId;
+    readonly flowId: FlowId;
+    readonly version: string;
+}
+export interface FlowListVersionsInput {
+    readonly tenantId: TenantId;
+    readonly flowId: FlowId;
+    readonly limit: number;
+    readonly cursor?: Cursor;
+}
+export interface FlowPublishInput {
+    readonly tenantId: TenantId;
+    /**
+     * Project the flow is published into. REQUIRED. Callers that
+     * don't naturally know a projectId
+     * (deployment route) resolve the tenant's Default via
+     * `projectBinding.getDefault(tenantId)` at THEIR layer and thread
+     * the resolved id here — the storage adapter never silently falls
+     * back to Default.
+     */
+    readonly projectId: ProjectId;
+    readonly flow: Flow;
+    /**
+     * REQUIRED. Called inside the binding's write transaction after the
+     * head + version rows are inserted, receiving the FGA subject id
+     * (business `flowId`). Returns the `TupleIntent[]` to enqueue in
+     * the same tx — typically `tuplesForCreate({kind:'flow', ...})`.
+     * See `AgentPublishInput.enqueueTuples` for the design rationale.
+     */
+    readonly enqueueTuples: TupleEnqueueHook;
+}
+export interface FlowUnregisterInput {
+    readonly tenantId: TenantId;
+    readonly flowId: FlowId;
+    readonly version: string;
+}
+export interface FlowReinstateVersionInput {
+    readonly tenantId: TenantId;
+    readonly flowId: FlowId;
+    readonly version: string;
+}
+export interface FlowPage {
+    readonly data: readonly Flow[];
+    readonly nextCursor?: Cursor;
+}
+export type FlowPublishOutcome = {
+    readonly kind: 'ok';
+    readonly flowId: FlowId;
+    readonly version: string;
+} | {
+    readonly kind: 'already-registered';
+    readonly flowId: FlowId;
+    readonly version: string;
+} | {
+    /**
+     * The caller-supplied `projectId` does not resolve to a real
+     * project row in this tenant. Distinct from
+     * `already-registered` so callers can surface a clean error (the
+     * flows route answers `400 bad-input`) rather than the
+     * misleading `already-registered` fallback. Implementations
+     * detect a missing project at publish time (a SQL store typically
+     * from its foreign-key violation).
+     */
+    readonly kind: 'project-not-found';
+    readonly flowId: FlowId;
+    readonly version: string;
+    readonly projectId: ProjectId;
+};
+export type FlowUnregisterOutcome = {
+    readonly unregistered: boolean;
+};
+export type FlowReinstateVersionOutcome = {
+    readonly kind: 'ok';
+    readonly flowId: FlowId;
+    readonly version: string;
+    readonly wasTombstoned: boolean;
+} | {
+    readonly kind: 'not-found';
+    readonly flowId: FlowId;
+    readonly version: string;
+};
+//# sourceMappingURL=flow-binding.d.ts.map

package/dist/flow-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-binding.d.ts","sourceRoot":"","sources":["../src/flow-binding.ts"],"names":[],"mappings":"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"}

package/dist/flow-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=flow-binding.js.map

package/dist/flow-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-binding.js","sourceRoot":"","sources":["../src/flow-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/guardrail-binding.d.ts

@@ -0,0 +1,138 @@
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Guardrail } from '@kindgi/guardrails';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, GuardrailId, ProjectId, TenantId } from '@kindgi/types';
+/**
+ * Caller-plugged surface for the guardrail catalog. Same shape as
+ * `AgentRegistryBinding` / `ToolRegistryBinding`: the API package does
+ * NOT own registry persistence.
+ *
+ * The surface is metadata-only: a `Guardrail` references a `check` id
+ * whose implementation lives server-side (a pure function in the
+ * runtime's `CheckRegistry`). The wire body is a full `Guardrail` shape
+ * (id + kind + check-id + action); the actual check implementation must
+ * already be registered with the runtime. Check code is not uploaded
+ * over this surface.
+ *
+ * Every method is tenant-scoped: callers pass `tenantId` explicitly so
+ * multi-tenant deployments can partition storage without exposing the
+ * scoping inside the API package.
+ *
+ * Cursors are opaque — the binding chooses its encoding. The API layer
+ * only validates that a cursor round-trips as a string; it never
+ * inspects the payload.
+ */
+export interface GuardrailRegistryBinding {
+    /**
+     * Cursor-paginated list of guardrails sorted by id ascending.
+     * Optional `nameFilter` is a prefix match on the guardrail id —
+     * guardrails often use dotted namespaces (`acme.no-fabricated-quotes`),
+     * so prefix matching is the natural filter shape.
+     */
+    list(input: GuardrailListInput): Promise<GuardrailPage>;
+    /**
+     * The guardrail for the given id, or `null` if unknown. The route
+     * surfaces `null` as `404 guardrail-not-found`.
+     */
+    get(input: GuardrailGetInput): Promise<Guardrail | null>;
+    /**
+     * Register a validated guardrail spec. The API route validates shape
+     * via `validateGuardrailSpec(...)` before calling — the binding
+     * receives a well-formed `Guardrail`. Bindings MAY reject with
+     * `already-registered` when the same id is re-registered; the route
+     * maps that to `409`.
+     */
+    register(input: GuardrailRegisterInput): Promise<GuardrailRegisterOutcome>;
+    /**
+     * Remove a guardrail by id. Returns `{ unregistered: true }` on
+     * success; `{ unregistered: false }` when the id was unknown — the
+     * route flips the latter to `404`.
+     */
+    unregister(input: GuardrailUnregisterInput): Promise<GuardrailUnregisterOutcome>;
+}
+export interface GuardrailListInput {
+    readonly tenantId: TenantId;
+    readonly limit: number;
+    readonly cursor?: Cursor;
+    /** Prefix match on `Guardrail.id`. Undefined = no filter. */
+    readonly nameFilter?: string;
+    /**
+     * Narrow the list to a specific scope. Absent = no scope narrow
+     * (return every row in the tenant the caller can see — admin/audit
+     * default).
+     *
+     * Content-scoped semantics (this binding):
+     * - `{ kind: 'project', projectId }` — rows in that project.
+     * - `{ kind: 'org', orgId }` — rows in every project belonging to
+     *   that org.
+     * - `{ kind: 'tenant', tenantId }` — every row in the tenant.
+     *
+     * Content rows always belong to a project, so `inherit` has no
+     * effect here.
+     */
+    readonly scope?: Scope;
+    /**
+     * `false` = literal-at-this-scope only (admin/audit view).
+     * `true` (default) = inheritance walk (user-facing view).
+     * No-op for content-scoped bindings (rows only exist at
+     * project-level — there is no upward hierarchy to walk). Kept for
+     * uniformity: scope-aware bindings share one filter shape.
+     */
+    readonly inherit?: boolean;
+}
+export interface GuardrailGetInput {
+    readonly tenantId: TenantId;
+    readonly guardrailId: GuardrailId;
+}
+export interface GuardrailRegisterInput {
+    readonly tenantId: TenantId;
+    /**
+     * Project the guardrail is registered into. REQUIRED. Callers that
+     * don't naturally know a projectId
+     * (deployment route) resolve the tenant's Default via
+     * `projectBinding.getDefault(tenantId)` at THEIR layer and thread
+     * the resolved id here — the storage adapter never silently falls
+     * back to Default.
+     */
+    readonly projectId: ProjectId;
+    readonly guardrail: Guardrail;
+    /**
+     * REQUIRED. Called inside the binding's write tx after row insert,
+     * receiving the business `guardrailId`. Returns tuples for the tx.
+     * See `AgentPublishInput.enqueueTuples` for the design rationale.
+     */
+    readonly enqueueTuples: TupleEnqueueHook;
+}
+export interface GuardrailUnregisterInput {
+    readonly tenantId: TenantId;
+    readonly guardrailId: GuardrailId;
+}
+export interface GuardrailPage {
+    readonly data: readonly Guardrail[];
+    readonly nextCursor?: Cursor;
+}
+export type GuardrailRegisterOutcome = {
+    readonly kind: 'ok';
+    readonly guardrailId: GuardrailId;
+} | {
+    readonly kind: 'already-registered';
+    readonly guardrailId: GuardrailId;
+} | {
+    /**
+     * The caller-supplied `projectId` does not resolve to a real
+     * project row in this tenant. Distinct from
+     * `already-registered` so the route + deployment guardrails-loop
+     * can surface a clean `400 bad-input` (per their own error
+     * contracts) rather than the misleading `already-registered`
+     * fallback. Database-backed implementations typically detect this
+     * from the foreign-key violation; in-memory implementations check
+     * the project id explicitly at register time.
+     */
+    readonly kind: 'project-not-found';
+    readonly guardrailId: GuardrailId;
+    readonly projectId: ProjectId;
+};
+export type GuardrailUnregisterOutcome = {
+    readonly unregistered: boolean;
+};
+//# sourceMappingURL=guardrail-binding.d.ts.map

package/dist/guardrail-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail-binding.d.ts","sourceRoot":"","sources":["../src/guardrail-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACxD;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAC3E;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC,GACD;IACE;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B,CAAC;AAEN,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAChC,CAAC"}

package/dist/guardrail-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=guardrail-binding.js.map

package/dist/guardrail-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail-binding.js","sourceRoot":"","sources":["../src/guardrail-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/handler-binding.d.ts

@@ -0,0 +1,126 @@
+import type { AgentId } from '@kindgi/agents';
+import type { FlowId, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
+/**
+ * Callback the platform HTTP surface hands off to when it receives
+ * `POST /v1/runs`. The API package intentionally does NOT depend on
+ * `AgentRegistry`, `ProviderRegistry`, `ToolRegistry`, or the wiring
+ * that assembles an `InvokeAgentBindings` — the caller wires those and
+ * exposes them through this thin binding.
+ *
+ * Why: keeps `@kindgi/api` narrow (Hono + routing + error mapping)
+ * while letting deployments — a local dev server, a hosted platform, a
+ * self-hosted install — assemble the runtime dependencies however they
+ * need to. Same pattern as `TokenResolver` for auth.
+ *
+ * Both methods block until the run reaches a terminal or suspended
+ * state — unless the input's `wait` is `false`, in which case they
+ * return the `runId` as soon as the run exists. The API layer only
+ * needs the `runId` to re-read the row and respond.
+ *
+ * Domain errors are returned as `RunHandlerFailure`; the route layer
+ * maps `code` to the HTTP status via `ERROR_CODE_TO_STATUS`.
+ */
+export interface RunHandlerBinding {
+    /**
+     * Called when the request body has `{ agent: AgentId, ... }`. The
+     * binding is expected to look up the agent, build the invocation
+     * bindings, and call `invokeAgent` from `@kindgi/agents` (or an
+     * equivalent). Return the underlying `RunId` on success.
+     */
+    invokeAgent(input: InvokeAgentBindingInput): Promise<RunHandlerOutcome>;
+    /**
+     * Called when the request body has `{ flow: FlowId, ... }`. The
+     * binding is expected to resolve the flow to its `Flow` value +
+     * `HandlerRegistry` and start it with `RunBinding.runGraph`
+     * (`@kindgi/runtime`).
+     */
+    invokeFlow(input: InvokeFlowBindingInput): Promise<RunHandlerOutcome>;
+    /**
+     * Resume a suspended run — invoked after a waitpoint resolves (e.g. a
+     * reviewer's decision writes `wait.resumed`; a timeout writes
+     * `wait.cancelled`). The binding reconstructs the same flow + handler
+     * context the run started with and calls `RunBinding.resumeRun`,
+     * blocking until the run reaches its next terminal state (or the next
+     * suspension). Same runId, same conversation, same provenance record —
+     * park-and-resume preserves audit-trail continuity across HITL cycles.
+     *
+     * Returns the same shape as `invokeAgent` / `invokeFlow`: the runId
+     * on success; a `RunHandlerFailure` when the resume path errors before
+     * the run is picked up.
+     */
+    resumeRun(input: ResumeRunBindingInput): Promise<RunHandlerOutcome>;
+}
+export interface ResumeRunBindingInput {
+    readonly tenantId: TenantId;
+    readonly runId: RunId;
+}
+export interface InvokeAgentBindingInput {
+    readonly tenantId: TenantId;
+    /**
+     * Content-scope anchor. Omit → the binding
+     * resolves the tenant's Default via `projectBinding.getDefault(...)`
+     * at its own caller layer. Route callers who supply a project id in
+     * the body thread it through here.
+     */
+    readonly projectId?: ProjectId;
+    readonly agentId: AgentId;
+    /** Omit → binding chooses the latest registered version. */
+    readonly agentVersion?: Semver;
+    /**
+     * Opaque payload forwarded from the request body's `input` field.
+     * The binding is responsible for coercing this into whatever shape
+     * `invokeAgent` expects (typically `{ userMessage, conversationId?, parameters?, participantId? }`).
+     * Coercion failures should surface as `code: 'bad-input'`.
+     */
+    readonly input: unknown;
+    readonly dryRun?: boolean;
+    /**
+     * `false` → return the run id as soon as the run exists and finish it
+     * in the background (the route answers `202`; callers poll
+     * `GET /v1/runs/:runId`). Absent or `true` → return once the run
+     * reaches a terminal or suspended state. A binding that
+     * can't run in the background may treat `false` like `true`.
+     */
+    readonly wait?: boolean;
+}
+export interface InvokeFlowBindingInput {
+    readonly tenantId: TenantId;
+    readonly projectId?: ProjectId;
+    readonly flowId: FlowId;
+    readonly flowVersion?: Semver;
+    readonly input: unknown;
+    readonly dryRun?: boolean;
+    /**
+     * `false` → return the run id as soon as the run exists and finish it
+     * in the background (the route answers `202`; callers poll
+     * `GET /v1/runs/:runId`). Absent or `true` → return once the run
+     * reaches a terminal or suspended state. A binding that
+     * can't run in the background may treat `false` like `true`.
+     */
+    readonly wait?: boolean;
+}
+export type RunHandlerOutcome = {
+    readonly kind: 'ok';
+    readonly runId: RunId;
+} | {
+    readonly kind: 'err';
+    readonly error: RunHandlerFailure;
+};
+/**
+ * Domain error surfaced by the binding. `code` should be a value the
+ * error mapper knows how to translate (e.g. `agent-not-found`,
+ * `bad-input`, `unresolved-tool`, `guardrail-violation`). Unknown
+ * codes fall through to 500.
+ */
+export interface RunHandlerFailure {
+    readonly code: string;
+    readonly message: string;
+    /**
+     * The domain error's structured fields — sent as the wire error's
+     * `details`, which clients hydrate into typed errors. A binding
+     * forwards them as-is: for `guardrail-violation`, `violations` and
+     * `evaluationErrors` from `@kindgi/agents`' `GuardrailViolationError`.
+     */
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=handler-binding.d.ts.map

package/dist/handler-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-binding.d.ts","sourceRoot":"","sources":["../src/handler-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAExE;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEtE;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACtD"}

package/dist/handler-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=handler-binding.js.map

package/dist/handler-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-binding.js","sourceRoot":"","sources":["../src/handler-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}