@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/src/guardrail-binding.ts

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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;
+};

package/src/handler-binding.ts

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+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>>;
+}

package/src/hitl-binding.ts

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+//
+// HITL binding surface — types + `HitlBinding` interface consumed by
+// the approvals routes. Deployments plug in an implementation (the
+// Kindgi runtime provides one); @kindgi/api never touches HITL storage
+// directly.
+//
+
+import type { ReviewerRole } from '@kindgi/authz';
+import type {
+  ApprovalId,
+  Cursor,
+  ProjectId,
+  ProvenanceId,
+  Result,
+  ReviewerId,
+  RunId,
+  TenantId,
+  Timestamp,
+} from '@kindgi/types';
+
+// ---------- domain type surface ----------
+
+export type ApprovalStatus =
+  | 'pending'
+  | 'assigned'
+  | 'in_review'
+  | 'approved'
+  | 'rejected'
+  | 'escalated'
+  | 'expired'
+  | 'withdrawn';
+
+export type ReviewDecisionKind = 'approve' | 'reject' | 'escalate' | 'withdraw';
+
+export interface Approval {
+  readonly id: ApprovalId;
+  readonly tenantId: TenantId;
+  readonly projectId?: ProjectId;
+  readonly subjectKind: string;
+  readonly subjectRef: Readonly<Record<string, unknown>>;
+  readonly requiredRole: ReviewerRole;
+  readonly status: ApprovalStatus;
+  readonly assignedTo?: ReviewerId;
+  readonly batchKey?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly context?: Readonly<Record<string, unknown>>;
+  readonly provenanceRef?: {
+    readonly runId: RunId;
+    readonly provenanceId?: ProvenanceId;
+  };
+  readonly waitTokenId?: string;
+  readonly createdAt: Timestamp;
+  readonly updatedAt: Timestamp;
+  readonly decidedAt?: Timestamp;
+  readonly expiresAt?: Timestamp;
+}
+
+export interface ReviewDecision {
+  readonly id: string;
+  readonly tenantId: TenantId;
+  readonly approvalId: ApprovalId;
+  readonly reviewerId: ReviewerId;
+  readonly decision: ReviewDecisionKind;
+  readonly rationale?: string;
+  readonly evidence?: Readonly<Record<string, unknown>>;
+  readonly reviewerRoleAtDecision: ReviewerRole;
+  readonly decidedAt: Timestamp;
+}
+
+// ---------- method inputs / outputs ----------
+
+export interface ListApprovalsBindingInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly status?: ApprovalStatus;
+  readonly requiredRole?: ReviewerRole;
+  readonly since?: Timestamp;
+  readonly cursor?: Cursor;
+}
+
+export interface ListApprovalsBindingResult {
+  readonly approvals: readonly Approval[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface SubmitReviewBindingInput {
+  readonly tenantId: TenantId;
+  readonly approvalId: ApprovalId;
+  readonly reviewerId: ReviewerId;
+  readonly decision: ReviewDecisionKind;
+  readonly rationale?: string;
+}
+
+/**
+ * Two shapes: `terminal` — reviewer's decision terminated the approval;
+ * `escalated` — a new higher-tier approval was opened. Consumers narrow
+ * `nextApproval` via the discriminant.
+ */
+export type SubmitReviewBindingResult =
+  | { readonly kind: 'terminal'; readonly approval: Approval; readonly decision: ReviewDecision }
+  | {
+      readonly kind: 'escalated';
+      readonly approval: Approval;
+      readonly decision: ReviewDecision;
+      readonly nextApproval: Approval;
+    };
+
+/**
+ * A single review-decision row hydrated for the audit-bundle route.
+ * `null` = the approval terminated without a recorded decision (e.g.
+ * status `expired`).
+ */
+export interface ReviewDecisionRecord {
+  readonly decision: ReviewDecisionKind;
+  readonly reviewerId: ReviewerId;
+  readonly reviewerRoleAtDecision: ReviewerRole;
+  readonly decidedAt: Timestamp;
+  readonly rationale?: string;
+}
+
+// ---------- error shape ----------
+
+/**
+ * Structural error surface returned by `HitlBinding` methods.
+ * Implementations emit these codes (`approval-not-found`,
+ * `reviewer-not-found`, `reviewer-deactivated`, `insufficient-role`,
+ * `approval-terminal`, `approval-already-decided`, `invalid-transition`,
+ * `persistence-error`) — the routes pass them through to `statusFor()` /
+ * `toWireError()`, which key off the string.
+ */
+export interface HitlBindingError {
+  readonly code: string;
+  readonly message: string;
+  readonly [key: string]: unknown;
+}
+
+// ---------- binding ----------
+
+/**
+ * Approvals data-access binding. Every method takes typed inputs and
+ * returns `Promise<Result<T, HitlBindingError>>`. The implementation
+ * owns its storage, so callers never touch it directly; the Kindgi
+ * runtime provides one.
+ */
+export interface HitlBinding {
+  getApproval(
+    tenantId: TenantId,
+    approvalId: ApprovalId,
+  ): Promise<Result<Approval, HitlBindingError>>;
+
+  listApprovals(
+    input: ListApprovalsBindingInput,
+  ): Promise<Result<ListApprovalsBindingResult, HitlBindingError>>;
+
+  submitReview(
+    input: SubmitReviewBindingInput,
+  ): Promise<Result<SubmitReviewBindingResult, HitlBindingError>>;
+
+  /**
+   * Hydrate the recorded decision row for an approval — used by the
+   * audit-bundle route. Returns `null` when the approval terminated
+   * without a recorded decision (status `expired`).
+   */
+  loadReviewDecision(
+    tenantId: TenantId,
+    approvalId: ApprovalId,
+  ): Promise<Result<ReviewDecisionRecord | null, HitlBindingError>>;
+}

package/src/identity-directory-binding.ts

@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, TenantId, Timestamp, UserId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the tenant-scoped identity directory —
+ * part of the admin control plane. Closes the "who is my
+ * user" gap the session-auth flow leaves open: the session store
+ * (`SessionStoreBinding`) knows about the sessions a user has, and the
+ * identity provider (`IdentityProviderBinding`) knows how to
+ * authenticate them, but neither answers the "list every user in this
+ * tenant" / "show me a user's profile" / "revoke all a user's active
+ * sessions" question this binding covers.
+ *
+ * Registry-only over HTTP — the framework does NOT own user
+ * persistence. Deployments plug in an LDAP / SCIM / IdP-mirror /
+ * bespoke store behind this binding.
+ *
+ * Same caller-plugged pattern as every other admin-plane binding
+ * (`PolicyRegistryBinding`, `ProviderRegistryBinding`, ...).
+ *
+ * The directory is flat. Groups / roles / RBAC / invitations /
+ * audit history / LDAP+SCIM sync / impersonation are not part of this
+ * binding.
+ */
+export interface IdentityDirectoryBinding {
+  /**
+   * Look up a specific user by id. Returns `null` when unknown —
+   * the route surfaces `null` as `404 identity-user-not-found`.
+   */
+  getUser(input: IdentityGetUserInput): Promise<UserRecord | null>;
+  /**
+   * Cursor-paginated list of users in the tenant. Optional `query`
+   * is a prefix match on `displayName` — the natural filter shape
+   * for a "search users" surface. Sort order is binding-defined (e.g.
+   * ascending by `userId`).
+   */
+  listUsers(input: IdentityListUsersInput): Promise<UserCollectionPage>;
+  /**
+   * List the active (non-revoked, non-expired) sessions for a user.
+   * Implementations may return the full list; `nextCursor` is optional
+   * on the response, so an implementation can paginate without a wire
+   * change.
+   *
+   * When the user id is unknown, an empty list is returned rather
+   * than a not-found. Callers who need the distinction should call
+   * `getUser` first.
+   */
+  listSessions(input: IdentityListSessionsInput): Promise<SessionSummaryPage>;
+  /**
+   * Admin op: revoke every active session for a user. Returns the
+   * count of sessions revoked (0 when the user was already fully
+   * signed out — idempotent). Under the hood, deployments typically
+   * delegate to `SessionStoreBinding.revokeAllForUser`.
+   */
+  revokeAllSessions(input: IdentityRevokeSessionsInput): Promise<RevokeSessionsResult>;
+}
+
+export interface IdentityGetUserInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+}
+
+export interface IdentityListUsersInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Prefix match on `UserRecord.displayName`. Undefined = no filter. */
+  readonly query?: string;
+}
+
+export interface IdentityListSessionsInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+}
+
+export interface IdentityRevokeSessionsInput {
+  readonly tenantId: TenantId;
+  readonly userId: UserId;
+}
+
+/**
+ * The tenant-scoped user record on the wire. `primaryEmail` may be
+ * redacted by the binding based on tenant policy — the routes treat
+ * the field as opaque and return whatever the binding hands back.
+ * `metadata` is free-form JSON (e.g. IdP claims, provisioning source,
+ * roles).
+ */
+export interface UserRecord {
+  readonly userId: UserId;
+  readonly tenantId: TenantId;
+  readonly primaryEmail?: string;
+  readonly displayName?: string;
+  readonly createdAt: Timestamp;
+  readonly lastActiveAt?: Timestamp;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface UserCollectionPage {
+  readonly data: readonly UserRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+/**
+ * Wire-safe subset of `Session` (from `session-store-binding.ts`).
+ * Excludes the opaque provider `accessToken` / `refreshToken` — those
+ * never cross the wire, even to admins.
+ */
+export interface SessionSummary {
+  readonly sessionId: string;
+  readonly userId: UserId;
+  readonly providerId: string;
+  readonly createdAt: Timestamp;
+  readonly expiresAt: Timestamp;
+  readonly scopes: readonly string[];
+  readonly revokedAt?: Timestamp;
+}
+
+export interface SessionSummaryPage {
+  readonly data: readonly SessionSummary[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface RevokeSessionsResult {
+  readonly userId: UserId;
+  readonly revokedCount: number;
+}