@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/package.json

@@ -1,7 +1,79 @@
 {
   "name": "@kindgi/api",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Placeholder so a trusted publisher can be attached. Releases are published from https://github.com/kindgi/kindgi-sdk with provenance; use 0.1.0 or later.",
+  "version": "0.1.1",
+  "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/kindgi/kindgi-sdk.git" }
-}
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kindgi/kindgi-sdk.git",
+    "directory": "packages/api"
+  },
+  "homepage": "https://github.com/kindgi/kindgi-sdk/tree/main/packages/api#readme",
+  "bugs": {
+    "url": "https://github.com/kindgi/kindgi-sdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./openapi.json": "./openapi.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "scripts",
+    "README.md",
+    "openapi.json"
+  ],
+  "dependencies": {
+    "@kindgi/agents": "0.1.1",
+    "@kindgi/audit-events": "0.1.1",
+    "@kindgi/compliance": "0.1.1",
+    "@kindgi/authz": "0.1.1",
+    "@kindgi/blob-binding": "0.1.1",
+    "@kindgi/capabilities": "0.1.1",
+    "@kindgi/crypto": "0.1.1",
+    "@kindgi/flow": "0.1.1",
+    "@kindgi/guardrails": "0.1.1",
+    "@kindgi/memory": "0.1.1",
+    "@kindgi/platform": "0.1.1",
+    "@kindgi/provenance": "0.1.1",
+    "@kindgi/runtime": "0.1.1",
+    "@kindgi/policy-contract": "0.1.1",
+    "@kindgi/schema": "0.1.1",
+    "@kindgi/tools": "0.1.1",
+    "@kindgi/types": "0.1.1",
+    "@scalar/hono-api-reference": "^0.12.2",
+    "drizzle-orm": "^0.36.4",
+    "hono": "^4.6.14"
+  },
+  "devDependencies": {
+    "@kindgi/audit-events-inmemory": "0.1.1",
+    "@kindgi/specs": "0.1.1",
+    "@kindgi/testing": "0.1.1",
+    "@types/aws4": "^1.11.6",
+    "@types/node": "^22.10.5",
+    "aws4": "^1.13.2",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen:openapi": "tsc -p tsconfig.build.json && node scripts/emit-openapi.mjs",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/scripts/emit-openapi.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+// Emits `openapi.json` (this package's root) from the built `@kindgi/api`
+// route + schema registry. The file ships with the package and is exported
+// as `@kindgi/api/openapi.json` — SDK codegen and other consumers resolve
+// it by package name, never by repo path. Kept as a pure `.mjs` script (no
+// tsx dep) — mirrors `@kindgi/specs`' `scripts/validate.mjs`.
+//
+// Usage: `pnpm --filter @kindgi/api gen:openapi`.
+// The npm script builds first so the imported dist is always fresh.
+// `tests/openapi-artifact.test.ts` fails when the committed file is stale.
+
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+const DIST_ENTRY = join(PACKAGE_ROOT, 'dist', 'index.js');
+const OUTPUT_PATH = join(PACKAGE_ROOT, 'openapi.json');
+
+if (!existsSync(DIST_ENTRY)) {
+  console.error(
+    `error: expected built entry at ${DIST_ENTRY}. Run \`pnpm --filter @kindgi/api build\` first, or use \`pnpm --filter @kindgi/api gen:openapi\` which chains both.`,
+  );
+  process.exit(1);
+}
+
+const { generateOpenApiDocument } = await import(DIST_ENTRY);
+const doc = generateOpenApiDocument();
+
+await writeFile(OUTPUT_PATH, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+
+const pathCount = Object.keys(doc.paths).length;
+const opCount = Object.values(doc.paths).reduce(
+  (sum, methods) => sum + Object.keys(methods).length,
+  0,
+);
+console.log(
+  `wrote ${OUTPUT_PATH} — ${pathCount} paths, ${opCount} operations, ${Object.keys(doc.components.schemas).length} schemas`,
+);

package/src/adapter-binding.ts

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the adapter catalog — part of the admin
+ * control plane. Read-only + smoke-test-only
+ * over HTTP: tenants + operators see every adapter the deployment
+ * wired at boot time and probe each one for liveness.
+ *
+ * Adapters are the concrete bridges the runtime uses to talk to
+ * outside systems: model providers, embedding providers, blob storage,
+ * sandbox providers, eval judges. Each adapter package
+ * (the filesystem blob adapter, the inprocess sandbox adapter,
+ * `@kindgi/adapter-model-in-process`, `@kindgi/adapter-model-openai-compat`,
+ * the local embedding adapter, the AJV eval-judge adapter, ...)
+ * exports a factory + optional metadata; the deployment aggregates the
+ * ones it actually wired into an `AdapterRegistryBinding`.
+ *
+ * ## Why read-only + test-only
+ *
+ * Adapter lifecycle (register / unregister / reconfigure) is a
+ * **deployment concern**, not a runtime one. The runtime learns about
+ * adapters at `CreateAppInput` time; if a deployment wants to change
+ * what's wired it restarts the process with different config. This
+ * mirrors the pattern used elsewhere in the framework where lifecycle
+ * state is deployment-owned (bucket allocation in S3, key store for
+ * signing). HTTP-driven adapter reconfigure would require the runtime
+ * to accept live reconfiguration, which it does not.
+ *
+ * ## Wire shape discipline
+ *
+ * `AdapterInfo.config` is REDACTED — no secrets on the wire. A binding
+ * MAY expose non-sensitive routing hints (`{ region: 'us-east-1' }`)
+ * but MUST NOT surface API keys, endpoints, credentials, or any
+ * material that could be used to impersonate the adapter. The binding
+ * is authoritative on what counts as safe to expose per adapter kind.
+ *
+ * ## Probe semantics
+ *
+ * `test(...)` runs a kind-specific smoke probe against the adapter.
+ * Probe failures return an `AdapterTestOutcome` with `ok: false` — not
+ * an error. A failed probe is a valid observation about the adapter's
+ * state, not a server error. The route surfaces `AdapterTestOutcome`
+ * as HTTP 200 either way; a 5xx would indicate the probe machinery
+ * itself broke (which is legitimately a server error).
+ *
+ * ### Default probes by adapter kind
+ *
+ *  - `blob`: write 32 random bytes → read back → verify hash → delete.
+ *  - `sandbox`: create a context-isolated (or `none`) sandbox → run
+ *    `1 + 1 === 2` → verify result → destroy.
+ *  - `model` / `model-provider`: minimal completion with
+ *    `[{ role: 'user', content: 'ping' }]` and `maxTokens: 1` — verify
+ *    the provider returns a well-shaped response.
+ *  - `embedding`: embed the string `'ping'` — verify the vector length
+ *    matches the advertised dimension.
+ *  - `eval-judge`: run a trivial pass-through eval — verify success.
+ *
+ * Adapter authors MAY accept a caller-supplied `input` on `test(...)`
+ * for more elaborate probes; when absent the binding falls back to
+ * the default above.
+ *
+ * Every method is tenant-scoped. Cursors are opaque — the binding
+ * chooses its encoding. The API layer only validates round-trip as a
+ * string; it never inspects the payload.
+ */
+export interface AdapterRegistryBinding {
+  /**
+   * Cursor-paginated list of adapters the deployment has wired.
+   * Optional filters narrow to a specific `kind` or `status`.
+   */
+  list(input: AdapterListInput): Promise<AdapterPage>;
+  /**
+   * Fetch a single adapter by id, or `null` when unknown. The route
+   * surfaces `null` as `404 adapter-not-found`.
+   */
+  get(input: AdapterGetInput): Promise<AdapterInfo | null>;
+  /**
+   * Run the kind-specific smoke probe. Returns `null` when the id is
+   * unknown — the route surfaces that as `404 adapter-not-found`.
+   * Otherwise returns an `AdapterTestOutcome` (which itself carries
+   * `ok: true | false` — failed probes are data, not errors).
+   */
+  test(input: AdapterTestInput): Promise<AdapterTestOutcome | null>;
+}
+
+/**
+ * Closed set of adapter kinds the framework knows about. New kinds
+ * require an additive schema update — we enumerate rather than accept
+ * an open string so wire consumers (UIs, command-line tools) can render
+ * kind-specific columns without guessing.
+ *
+ * `model-provider` is distinct from `model` for adapters that wrap a
+ * remote provider gateway (a hosted API or a self-hosted inference
+ * server) vs. adapters that host the model in-process.
+ */
+export type AdapterKind =
+  | 'model'
+  | 'model-provider'
+  | 'embedding'
+  | 'blob'
+  | 'sandbox'
+  | 'eval-judge';
+
+export const ADAPTER_KINDS: readonly AdapterKind[] = [
+  'model',
+  'model-provider',
+  'embedding',
+  'blob',
+  'sandbox',
+  'eval-judge',
+];
+
+/**
+ * Adapter status the wire surface exposes. `active` = wired and
+ * last-observed healthy. `degraded` = wired but the binding has seen
+ * recent failures / partial capability loss. `error` = wired but
+ * unusable (e.g. auth material missing at boot). The binding is
+ * authoritative on how it derives the value.
+ */
+export type AdapterStatus = 'active' | 'degraded' | 'error';
+
+export const ADAPTER_STATUSES: readonly AdapterStatus[] = ['active', 'degraded', 'error'];
+
+/**
+ * Wire shape for a single wired adapter. Deployments produce this
+ * from whatever data structure they use to hold their adapter set —
+ * commonly the `describe()` output on the adapter factory plus a
+ * status field the deployment tracks itself.
+ */
+export interface AdapterInfo {
+  /** Stable id chosen by the deployment (e.g. `'sandbox-primary'`). */
+  readonly adapterId: string;
+  readonly kind: AdapterKind;
+  /** Package name that owns the implementation (e.g. `'@kindgi/adapter-model-in-process'`). */
+  readonly name: string;
+  /** Semver of the wired package. */
+  readonly version: string;
+  /**
+   * Kind-specific capability tags. Free-form strings scoped by kind —
+   * e.g. `['context-isolated']` for a sandbox adapter, `['tool-use', 'streaming']`
+   * for a model adapter, `['multipart-upload']` for blob storage.
+   */
+  readonly capabilities: readonly string[];
+  /**
+   * Redacted routing hints only. No secrets. Absent when the binding
+   * has nothing safe to expose.
+   */
+  readonly config?: Readonly<Record<string, unknown>>;
+  readonly status: AdapterStatus;
+  /** Human-readable reason accompanying `degraded` / `error` status. */
+  readonly statusReason?: string;
+}
+
+export interface AdapterListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly filter?: AdapterListFilter;
+}
+
+export interface AdapterListFilter {
+  readonly kind?: AdapterKind;
+  readonly status?: AdapterStatus;
+}
+
+export interface AdapterPage {
+  readonly data: readonly AdapterInfo[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface AdapterGetInput {
+  readonly tenantId: TenantId;
+  readonly adapterId: string;
+}
+
+export interface AdapterTestInput {
+  readonly tenantId: TenantId;
+  readonly adapterId: string;
+  /**
+   * Optional kind-specific probe input. When absent the binding runs
+   * the default probe documented in the interface JSDoc above. Shape
+   * is intentionally open so bindings can extend the probe surface
+   * per kind without a schema change.
+   */
+  readonly input?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Result of a probe run. `ok: false` is a valid observation — the
+ * route serialises it as HTTP 200 either way.
+ *
+ * `probe` is kind-specific data (e.g. `{ vectorLength: 384 }` for an
+ * embedding probe, `{ latencyMs: 42, completion: '2' }` for a model
+ * probe). Consumers should not depend on its exact shape — the UI
+ * treats it as a diagnostic bag to render as JSON.
+ */
+export interface AdapterTestOutcome {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  readonly probe: Readonly<Record<string, unknown>>;
+}

package/src/agent-binding.ts

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Agent, AgentId } from '@kindgi/agents';
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, ProjectId, Semver, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the agent catalog. Same shape as
+ * `TokenAdmin` / `ReviewerBinding` / `RunHandlerBinding`: the API
+ * package does NOT own registry persistence. Deployments wire a
+ * runtime `AgentRegistry` (from `@kindgi/agents`) — or a durable
+ * pack-backed store — through this binding.
+ *
+ * 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 AgentRegistryBinding {
+  /**
+   * Cursor-paginated list of agents (latest version per id, sorted by
+   * agent id ascending). Optional `nameFilter` is a prefix match on the
+   * agent id — the runtime uses dotted namespaces (`acme.*`), so
+   * prefix matching is the natural filter shape.
+   */
+  list(input: AgentListInput): Promise<AgentPage>;
+  /**
+   * Latest version of the given agent id, or `null` if unknown. The
+   * route surfaces `null` as `404 agent-not-found`.
+   */
+  get(input: AgentGetInput): Promise<Agent | null>;
+  /**
+   * Specific `(agentId, version)` lookup, or `null` if unknown.
+   * Returns tombstoned versions too (unlike `list` / `get` which
+   * filter them) — the specific-version lookup is used by provenance
+   * paths that need to resolve historical run references.
+   */
+  getVersion(input: AgentGetVersionInput): Promise<Agent | null>;
+  /**
+   * Head-row existence check. Returns `true` iff the agent id has been
+   * registered in the tenant (regardless of whether any versions are
+   * active). Lets `GET /v1/agents/{id}` distinguish
+   * `410 gone` (identity exists, no active version) from `404 not-
+   * found` (never registered) — `.get(...)` returns `null` in both
+   * cases.
+   */
+  headExists(input: AgentGetInput): Promise<boolean>;
+  /**
+   * Cursor-paginated list of versions for a specific agent id. Sort
+   * order is binding-defined; the built-in in-memory registry sorts
+   * 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: AgentListVersionsInput): Promise<AgentPage>;
+  /**
+   * Publish a validated agent definition. The API route validates
+   * shape via `defineAgent(...)` before calling — the binding receives
+   * a well-formed `Agent`. Bindings MAY reject with `already-registered`
+   * when the same `(agentId, version)` is re-published; the route
+   * maps that to `409`.
+   */
+  publish(input: AgentPublishInput): Promise<AgentPublishOutcome>;
+  /**
+   * Soft-tombstone a specific `(agentId, version)`. Returns
+   * `{ unregistered: true }` on success; `{ unregistered: false }`
+   * when the version was unknown OR already tombstoned — the route
+   * flips the latter to `404`. Head row is preserved; when this
+   * unregister leaves NO active versions, the agent has no latest
+   * version — it enters the derived "retired" state
+   * (GET returns 410 gone) but the identity persists. Publish of a
+   * new version reactivates.
+   */
+  unregister(input: AgentUnregisterInput): Promise<AgentUnregisterOutcome>;
+  /**
+   * Un-tombstone a specific `(agentId, version)` — clears the
+   * version's tombstone and recomputes the agent's latest version
+   * across active versions. Restores the version's
+   * manifest bytes verbatim (semver hygiene: reinstate never mutates
+   * the manifest). Idempotent: reinstating an active version is a
+   * no-op. `{ kind: 'not-found' }` when the version was never
+   * published.
+   */
+  reinstateVersion(input: AgentReinstateVersionInput): Promise<AgentReinstateVersionOutcome>;
+}
+
+export interface AgentListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Prefix match on `Agent.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 AgentGetInput {
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+}
+
+export interface AgentGetVersionInput {
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  readonly version: Semver;
+}
+
+export interface AgentListVersionsInput {
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+}
+
+export interface AgentPublishInput {
+  readonly tenantId: TenantId;
+  /**
+   * Project the agent is published into. REQUIRED. Callers that
+   * don't naturally know a projectId
+   * (e.g. the deployments 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 agent: Agent;
+  /**
+   * REQUIRED. Called inside the binding's write transaction after the
+   * head + version rows are inserted, receiving the FGA subject id
+   * (the business `agentId`). Returns the
+   * `TupleIntent[]` to enqueue in the same tx — typically
+   * `tuplesForCreate({kind:'agent', id, tenantId, projectId}, creatorUserId)`.
+   *
+   * Required, not opt-in: a binding that cannot enqueue tuples must fail
+   * loudly rather than silently skip.
+   */
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+export interface AgentUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  readonly version: Semver;
+  // No enqueueTuples hook. `unregister` soft-tombstones a version and
+  // recomputes the latest version; the head row is PRESERVED, so the
+  // agent identity persists in FGA as a retired entity. A method that
+  // fully removed the identity would take an `enqueueTuples` parameter
+  // for the `tuplesForDelete(...)` cleanup.
+}
+
+export interface AgentReinstateVersionInput {
+  readonly tenantId: TenantId;
+  readonly agentId: AgentId;
+  readonly version: Semver;
+}
+
+export interface AgentPage {
+  readonly data: readonly Agent[];
+  readonly nextCursor?: Cursor;
+}
+
+export type AgentPublishOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly agentId: AgentId;
+      readonly version: Semver;
+    }
+  | {
+      readonly kind: 'already-registered';
+      readonly agentId: AgentId;
+      readonly version: Semver;
+    }
+  | {
+      /**
+       * 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
+       * agents 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 agentId: AgentId;
+      readonly version: Semver;
+      readonly projectId: ProjectId;
+    };
+
+export type AgentUnregisterOutcome = {
+  readonly unregistered: boolean;
+};
+
+export type AgentReinstateVersionOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly agentId: AgentId;
+      readonly version: Semver;
+      /** `false` when the version was already active (idempotent no-op). */
+      readonly wasTombstoned: boolean;
+    }
+  | {
+      readonly kind: 'not-found';
+      readonly agentId: AgentId;
+      readonly version: Semver;
+    };