@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/src/errors.ts

@@ -0,0 +1,295 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Error envelope + code→status mapping for the platform API.
+ *
+ * Spec: `docs/API-ROUTE-CONVENTIONS.md` §4. Every 4xx/5xx response
+ * carries `{ error: { code, message, details?, requestId } }`. Codes
+ * match domain error discriminants (`unresolved-tool`,
+ * `guardrail-violation`, etc.) so the SDK's `fromWire()` can pattern-
+ * match without inspecting HTTP status.
+ */
+
+export interface WireErrorBody {
+  readonly error: WireError;
+}
+
+export interface WireError {
+  readonly code: string;
+  readonly message: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+  readonly requestId: string;
+}
+
+/**
+ * Maps a domain error `code` to the HTTP status the route layer should
+ * return. Codes not in this map fall through to `500` — the middleware
+ * treats that as a bug (unmapped code) rather than a plausible domain
+ * error. New codes MUST have a row here.
+ */
+export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
+  // 400 — bad request
+  'validation-failed': 400,
+  'unknown-field': 400,
+  'bad-input': 400,
+  'unresolved-tool': 400,
+  'unresolved-guardrail': 400,
+  'schema-validation-failed': 400,
+  // Platform hierarchy scope filter.
+  'scope-invalid': 400,
+  // 401 — auth
+  'auth-missing': 401,
+  'auth-expired': 401,
+  'auth-revoked': 401,
+  // 403
+  'permission-denied': 403,
+  // A deployment refuses tenant configuration that reaches its host
+  // (KINDGI_TENANT_HOST_ACCESS): a stdio MCP endpoint.
+  'host-access-denied': 403,
+  // 404
+  'not-found': 404,
+  'run-not-found': 404,
+  'agent-not-found': 404,
+  'conversation-not-found': 404,
+  'tool-not-found': 404,
+  'guardrail-not-found': 404,
+  'fact-not-found': 404,
+  'flow-not-found': 404,
+  // 409 — conflict
+  'already-terminal': 409,
+  'run-already-terminal': 409,
+  'run-lease-lost': 409,
+  'idempotency-key-body-mismatch': 409,
+  'hitl-required': 409,
+  'duplicate-node-id': 409,
+  'duplicate-edge-id': 409,
+  'agent-version-mismatch': 409,
+  'agent-already-registered': 409,
+  'agent-gone': 410,
+  'flow-gone': 410,
+  'policy-gone': 410,
+  'eval-suite-gone': 410,
+  'tool-gone': 410,
+  'tool-already-registered': 409,
+  'guardrail-already-registered': 409,
+  'flow-already-registered': 409,
+  'conversation-closed': 409,
+  'invalid-agent': 400,
+  'invalid-tool-definition': 400,
+  'invalid-schema': 400,
+  'unknown-effect': 400,
+  'invalid-guardrail': 400,
+  // 422 — unprocessable entity
+  'guardrail-violation': 422,
+  'agent-turn-aborted': 422,
+  'budget-exceeded': 422,
+  'output-schema-violation': 422,
+  'model-invocation-failed': 422,
+  'tool-invocation-failed': 422,
+  'capability-routing-failed': 422,
+  'runtime-not-configured': 422,
+  // A run the runtime can't start or resume yet: a flow with a node no
+  // handler is bound for, or a run shape the host's run handler doesn't
+  // support.
+  'flow-unbound': 422,
+  'flow-runs-not-supported': 422,
+  'flow-resume-not-supported': 422,
+  // `POST /v1/runs/{runId}/resume` in this release: every waitpoint
+  // belongs to an approval (decided through the approvals routes, which
+  // check the reviewer and record the decision) or to the runtime itself.
+  'run-resume-not-supported': 422,
+  // 429 — rate limit. No route in this package emits it; a rate limiter
+  // in front of the routes can.
+  'rate-limit-exceeded': 429,
+  // 500 — server
+  'internal-server-error': 500,
+  'journal-error': 500,
+  stuck: 500,
+  // Waitpoint domain: "no pending token" or "already resolved" are
+  // 409-shaped (a caller conflict with the run's current state).
+  'waitpoint-error': 409,
+  // HITL (approvals + reviewers).
+  'approval-not-found': 404,
+  'reviewer-not-found': 404,
+  'reviewer-deactivated': 409,
+  'insufficient-role': 403,
+  'approval-terminal': 409,
+  'approval-already-decided': 409,
+  'invalid-transition': 409,
+  'audit-bundle-not-found': 404,
+  'approval-not-decided': 409,
+  'export-key-error': 500,
+  'persistence-error': 500,
+  // Supervisor observations query — same discriminants.
+  'observation-not-found': 404,
+  // Provenance routes.
+  'provenance-not-found': 404,
+  'signing-not-configured': 404,
+  'signing-key-not-found': 404,
+  'signing-key-conflict': 409,
+  'signing-key-revoked': 409,
+  'signing-key-algorithm-unsupported': 400,
+  'signing-key-store-error': 500,
+  // Supervisor proposals lifecycle.
+  'proposal-not-found': 404,
+  'proposal-invalid-state-transition': 409,
+  'proposal-terminal': 409,
+  'baseline-mismatch': 422,
+  'apply-change-failed': 422,
+  'ground-layer-violation': 422,
+  'agent-not-in-registry': 422,
+  'version-already-exists': 409,
+  'invalid-new-version': 400,
+  'supervisor-header-missing': 400,
+  // Artifacts.
+  'blob-not-found': 404,
+  'blob-hash-mismatch': 400,
+  'blob-size-mismatch': 400,
+  'blob-storage-error': 500,
+  // Admin plane — capabilities + providers.
+  'capability-not-found': 404,
+  'provider-not-found': 404,
+  'provider-already-registered': 409,
+  'invalid-provider': 400,
+  // Admin plane — cost readback.
+  'cost-record-not-found': 404,
+  // Admin plane — adapters.
+  'adapter-not-found': 404,
+  // Admin plane — policies.
+  'policy-not-found': 404,
+  'policy-already-registered': 409,
+  // Admin plane — eval suites.
+  'eval-suite-not-found': 404,
+  'eval-suite-already-registered': 409,
+  // Admin plane — eval-run dispatch.
+  'eval-run-not-found': 404,
+  'eval-run-already-terminal': 409,
+  'dispatcher-not-registered': 422,
+  'dispatcher-input-invalid': 400,
+  // Interop plane — MCP endpoint registry.
+  'mcp-endpoint-not-found': 404,
+  'mcp-endpoint-already-registered': 409,
+  'invalid-mcp-endpoint': 400,
+  // Interop plane — MCP resources + prompts.
+  'mcp-resource-not-found': 404,
+  'mcp-prompt-not-found': 404,
+  'mcp-resource-read-failed': 502,
+  'mcp-prompt-get-failed': 502,
+  // Auth surface — OAuth + sessions.
+  'session-not-found': 404,
+  'session-revoked': 409,
+  // NOTE: `session-expired` is a middleware-tier auth failure (401) —
+  // the token authenticated but the session's absolute TTL has elapsed.
+  // Distinct from `auth-expired` (bearer-token expiry) so callers can
+  // tell static bearer-token expiry from session TTL.
+  'session-expired': 401,
+  'session-inactive': 401,
+  'identity-provider-not-found': 404,
+  'identity-provider-already-registered': 409,
+  'oauth-state-invalid': 400,
+  'oauth-code-exchange-failed': 422,
+  'oauth-refresh-failed': 422,
+  'oauth-refresh-not-supported': 422,
+  'invalid-provider-config': 400,
+  'auth-not-session-token': 400,
+  // OAuth redirect URIs + refresh.
+  'redirect-uri-not-allowed': 400,
+  'redirect-uri-mismatch': 400,
+  'refresh-token-invalid': 401,
+  // Admin plane — identity directory.
+  'identity-user-not-found': 404,
+  'identity-revoke-failed': 500,
+  // Signed deployments.
+  'signature-invalid': 400,
+  'signer-not-trusted': 403,
+  'image-unverifiable': 400,
+  'deployment-validation-failed': 400,
+  'deployment-not-found': 404,
+  // Compliance routes.
+  'compliance-evidence-not-found': 404,
+  'compliance-export-failed': 500,
+  // Platform hierarchy.
+  'org-not-found': 404,
+  'team-not-found': 404,
+  'project-not-found': 404,
+  'team-membership-not-found': 404,
+  'project-membership-not-found': 404,
+  'tenant-not-found': 404,
+  'tenant-config-not-found': 404,
+  'tenant-config-revision-conflict': 409,
+  'authz-denied': 403,
+  'authz-backend-unavailable': 503,
+  // A tenant policy an agent turn must apply couldn't be (its store
+  // failed, or a stored spec is invalid): the turn fails closed.
+  'tenant-policy-unavailable': 503,
+  // Env + Secrets.
+  'env-not-found': 404,
+  'secret-not-found': 404,
+  'secret-revoked': 404,
+  'secret-version-not-found': 404,
+  'scope-kind-required': 400,
+  'scope-mismatch': 400,
+  'env-name-required': 400,
+  'env-name-mismatch': 400,
+  'env-cross-scope': 400,
+  'reserved-name-prefix': 400,
+  'secret-value-too-large': 400,
+  'secret-write-conflict': 409,
+  'env-write-conflict': 409,
+  'secret-encryption-failed': 500,
+  'secret-decryption-failed': 500,
+  'secret-provider-unavailable': 503,
+  'secret-provider-unauthorized': 502,
+  'secret-provider-rate-limited': 429,
+  'secret-store-error': 500,
+  'env-store-error': 500,
+  // Trigger HTTP surface.
+  'trigger-not-found': 404,
+  'trigger-invalid-config': 400,
+  'trigger-webhook-id-conflict': 409,
+  'trigger-already-in-state': 409,
+  'trigger-register-failed': 500,
+  'trigger-update-failed': 500,
+  'trigger-lifecycle-failed': 500,
+  'webhook-signature-invalid': 401,
+  'webhook-inactive': 410,
+  'webhook-secret-missing': 500,
+  'webhook-flow-not-found': 502,
+  // Outbound webhook endpoints.
+  'webhook-endpoint-not-found': 404,
+  'webhook-delivery-not-found': 404,
+  'webhook-url-refused': 400,
+  'webhook-secret-not-found': 400,
+  'webhook-secret-too-weak': 400,
+  // Public run tokens.
+  'token-mint-failed': 500,
+} as const;
+
+/**
+ * Look up the HTTP status for a domain error code. Unmapped codes
+ * return `500` — the caller should log a warning; this indicates a
+ * mapping-table gap.
+ */
+export function statusFor(code: string): number {
+  return ERROR_CODE_TO_STATUS[code] ?? 500;
+}
+
+/** Build a wire error body from a domain error + requestId. */
+export function toWireError(
+  err: { readonly code: string; readonly message: string } & Readonly<Record<string, unknown>>,
+  requestId: string,
+): WireErrorBody {
+  const { code, message, ...rest } = err as unknown as Record<string, unknown>;
+  const detailKeys = Object.keys(rest).filter((k) => k !== 'cause');
+  const details =
+    detailKeys.length > 0 ? Object.fromEntries(detailKeys.map((k) => [k, rest[k]])) : undefined;
+  return {
+    error: {
+      code: String(code),
+      message: String(message),
+      ...(details !== undefined && { details }),
+      requestId,
+    },
+  };
+}

package/src/eval-run-binding.ts

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { AgentId } from '@kindgi/agents';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, FlowId, ProjectId, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
+
+import type { EvalKind } from './eval-suite-binding.js';
+
+/**
+ * Caller-plugged surface for the evaluation-run data plane — the
+ * companion to the eval-suite registry that closes the loop by adding
+ * *execution*.
+ * Same pattern as every other admin binding: the API package does NOT
+ * own persistence. Deployments wire this binding to a runtime that
+ * dispatches per `EvalSuite.kind` (see `eval-run-dispatcher.ts` for
+ * the reference accuracy dispatcher).
+ *
+ * The wire shape mirrors the run surface. A durable implementation can
+ * make every `EvalRun` a specialized run (started with `runGraph`),
+ * inheriting durability, replay, and cancel semantics while adding
+ * eval-specific fields (`suiteId`, `suiteVersion`, `kind`, `result`);
+ * the in-process reference in `eval-run-dispatcher.ts` keeps runs in
+ * memory.
+ *
+ * `result` is kind-specific opaque JSON on the wire. For the
+ * `accuracy` reference dispatcher it is
+ * `{ passCount, totalCount, meanScore, perCase[] }`; other kinds define
+ * their own shapes.
+ */
+export interface EvalRunBinding {
+  /**
+   * Start a new eval run against a specific suite id (the dispatcher
+   * resolves the suite version internally — bindings MAY reject with
+   * `suite-not-found` when the suiteId is unknown for the tenant).
+   */
+  start(input: EvalRunStartInput): Promise<EvalRunStartOutcome>;
+  /**
+   * Fetch a single eval run by id, or `null` if unknown. The route
+   * surfaces `null` as `404 eval-run-not-found`.
+   */
+  get(input: EvalRunGetInput): Promise<EvalRun | null>;
+  /**
+   * Cursor-paginated list of eval runs. Optional filters — see
+   * `EvalRunFilter`. Sort order is fixed: `startedAt` descending, id
+   * descending as tie-breaker (same shape as `/v1/runs`).
+   */
+  list(input: EvalRunListInput): Promise<EvalRunPage>;
+  /**
+   * Cancel an eval run. Returns `{ cancelled: true }` on success;
+   * `{ cancelled: false, reason: 'not-found' | 'already-terminal' }`
+   * otherwise — the route flips each `reason` to the appropriate
+   * 4xx status.
+   */
+  cancel(input: EvalRunCancelInput): Promise<EvalRunCancelOutcome>;
+}
+
+/**
+ * How the caller identifies the eval subject on `start`. Exactly one
+ * of `agentRef` / `flowRef` MUST be supplied — the route enforces
+ * that mutual exclusion before calling the binding.
+ */
+export interface AgentRef {
+  readonly agentId: AgentId;
+  readonly version?: Semver;
+}
+export interface FlowRef {
+  readonly flowId: FlowId;
+  readonly version?: Semver;
+}
+
+/**
+ * Terminal statuses match the run vocabulary. `pending` is a
+ * pre-execution state a dispatcher MAY use if it queues the run
+ * before starting it; the reference in-process dispatcher goes
+ * straight to `running`.
+ */
+export const EVAL_RUN_STATUSES = [
+  'pending',
+  'running',
+  'completed',
+  'failed',
+  'cancelled',
+] as const;
+export type EvalRunStatus = (typeof EVAL_RUN_STATUSES)[number];
+
+/**
+ * Wire shape for a single evaluation run. `result` is kind-specific
+ * opaque JSON (accuracy writes `{ passCount, totalCount, meanScore,
+ * perCase[] }`; other kinds define their own shapes). `error`
+ * carries the failure message when `status === 'failed'`.
+ */
+export interface EvalRun {
+  readonly runId: RunId;
+  readonly tenantId: TenantId;
+  readonly suiteId: string;
+  readonly suiteVersion: string;
+  readonly kind: EvalKind;
+  readonly agentRef?: AgentRef;
+  readonly flowRef?: FlowRef;
+  readonly status: EvalRunStatus;
+  readonly dryRun: boolean;
+  readonly startedAt: Timestamp;
+  readonly completedAt?: Timestamp;
+  readonly result?: Readonly<Record<string, unknown>>;
+  readonly error?: string;
+  readonly correlationId?: string;
+}
+
+export interface EvalRunFilter {
+  readonly suiteId?: string;
+  readonly status?: EvalRunStatus;
+  readonly agentId?: AgentId;
+  readonly flowId?: FlowId;
+  readonly from?: Timestamp;
+  readonly to?: Timestamp;
+}
+
+export interface EvalRunStartInput {
+  readonly tenantId: TenantId;
+  /**
+   * Content-scope anchor. REQUIRED — every
+   * eval-run row is anchored to a project. The caller resolves this at
+   * ITS layer; storage adapters treat a missing / bogus id as a
+   * `project-not-found` outcome. No silent fallback to a tenant Default here.
+   */
+  readonly projectId: ProjectId;
+  readonly suiteId: string;
+  readonly agentRef?: AgentRef;
+  readonly flowRef?: FlowRef;
+  readonly dryRun?: boolean;
+  readonly correlationId?: string;
+}
+
+/**
+ * `start` outcomes. `ok` returns the newly-minted `runId`; other
+ * shapes carry the domain error the route flips to a 4xx.
+ */
+export type EvalRunStartOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly runId: RunId;
+      readonly dryRunPreview?: Readonly<Record<string, unknown>>;
+    }
+  | { readonly kind: 'suite-not-found'; readonly suiteId: string }
+  | { readonly kind: 'dispatcher-not-registered'; readonly evalKind: EvalKind }
+  | { readonly kind: 'dispatcher-input-invalid'; readonly message: string }
+  | {
+      /**
+       * The caller-supplied `projectId` does not resolve to a real
+       * project row in this tenant. Distinct from
+       * `dispatcher-input-invalid` so the route can surface a clean
+       * 4xx with the offending id rather than a generic dispatcher
+       * error.
+       */
+      readonly kind: 'project-not-found';
+      readonly projectId: ProjectId;
+    };
+
+export interface EvalRunGetInput {
+  readonly tenantId: TenantId;
+  readonly runId: RunId;
+}
+
+export interface EvalRunListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly filter?: EvalRunFilter;
+  /**
+   * 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 EvalRunPage {
+  readonly data: readonly EvalRun[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface EvalRunCancelInput {
+  readonly tenantId: TenantId;
+  readonly runId: RunId;
+}
+
+export type EvalRunCancelOutcome =
+  | { readonly kind: 'ok' }
+  | { readonly kind: 'not-found' }
+  | { readonly kind: 'already-terminal'; readonly status: EvalRunStatus };