@kindgi/api 0.1.4-rc.4 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.4-rc.4",
+  "version": "0.1.4",
   "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": {
@@ -32,30 +32,31 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.4-rc.4",
-    "@kindgi/audit-events": "0.1.4-rc.4",
-    "@kindgi/compliance": "0.1.4-rc.4",
-    "@kindgi/authz": "0.1.4-rc.4",
-    "@kindgi/blob-binding": "0.1.4-rc.4",
-    "@kindgi/capabilities": "0.1.4-rc.4",
-    "@kindgi/crypto": "0.1.4-rc.4",
-    "@kindgi/flow": "0.1.4-rc.4",
-    "@kindgi/guardrails": "0.1.4-rc.4",
-    "@kindgi/memory": "0.1.4-rc.4",
-    "@kindgi/platform": "0.1.4-rc.4",
-    "@kindgi/provenance": "0.1.4-rc.4",
-    "@kindgi/runtime": "0.1.4-rc.4",
-    "@kindgi/policy-contract": "0.1.4-rc.4",
-    "@kindgi/schema": "0.1.4-rc.4",
-    "@kindgi/tools": "0.1.4-rc.4",
-    "@kindgi/types": "0.1.4-rc.4",
+    "@kindgi/agents": "0.1.4",
+    "@kindgi/audit-events": "0.1.4",
+    "@kindgi/compliance": "0.1.4",
+    "@kindgi/authz": "0.1.4",
+    "@kindgi/blob-binding": "0.1.4",
+    "@kindgi/capabilities": "0.1.4",
+    "@kindgi/crypto": "0.1.4",
+    "@kindgi/flow": "0.1.4",
+    "@kindgi/guardrails": "0.1.4",
+    "@kindgi/log": "0.1.4",
+    "@kindgi/memory": "0.1.4",
+    "@kindgi/platform": "0.1.4",
+    "@kindgi/provenance": "0.1.4",
+    "@kindgi/runtime": "0.1.4",
+    "@kindgi/policy-contract": "0.1.4",
+    "@kindgi/schema": "0.1.4",
+    "@kindgi/tools": "0.1.4",
+    "@kindgi/types": "0.1.4",
     "@scalar/hono-api-reference": "^0.12.2",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.4-rc.4",
-    "@kindgi/specs": "0.1.4-rc.4",
-    "@kindgi/testing": "0.1.4-rc.4",
+    "@kindgi/audit-events-inmemory": "0.1.4",
+    "@kindgi/specs": "0.1.4",
+    "@kindgi/testing": "0.1.4",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",

package/src/app.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
+import { type Logger, noopLogger } from '@kindgi/log';
 import { Scalar } from '@scalar/hono-api-reference';
 import { Hono } from 'hono';
 
@@ -63,6 +64,7 @@ import { principalMiddleware } from './middleware/principal.js';
 import { PROJECT_REF_ROUTES, refuseBadProjectId } from './middleware/project-ref.js';
 import { publicRunCorsMiddleware, publicRunRouteMatcher } from './middleware/public-run-routes.js';
 import { requestIdMiddleware } from './middleware/request-id.js';
+import { requestLogMiddleware } from './middleware/request-log.js';
 import { sigv4Middleware } from './middleware/sigv4.js';
 import { type GenerateOptions, generateOpenApiDocument } from './openapi/generate.js';
 import type { ProvenanceBinding } from './provenance-binding.js';
@@ -150,6 +152,12 @@ import type { WebhookEndpointBinding } from './webhook-endpoint-binding.js';
  * for tests.
  */
 export interface CreateAppInput {
+  /**
+   * Where the app's records go (`@kindgi/log`): the access line, logged
+   * 500s, and what routes log, each with the request's ids. Default:
+   * `noopLogger`, so an embedding app stays quiet unless it passes one.
+   */
+  readonly logger?: Logger;
   readonly resolveToken: TokenResolver;
   readonly runHandler: RunHandlerBinding;
   /**
@@ -893,7 +901,9 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
 
   // ---------- global middleware ----------
   app.use('*', requestIdMiddleware());
-  // A thrown exception: a 500 wire error with its message and request id.
+  // The request's trace context and logger, and its access line.
+  app.use('*', requestLogMiddleware(input.logger ?? noopLogger));
+  // A thrown exception: a 500 wire error with its message and request id, logged.
   app.onError(mapThrownError);
 
   // Public run tokens: checked once at startup; CORS for the two routes
@@ -968,6 +978,12 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
   // still populate the principal (cheap, and lets `can`/`check` work
   // as inspection helpers even when authorize() enforcement is off).
   v1.use('*', principalMiddleware());
+  // From here on, the request's records carry its tenant.
+  v1.use('*', async (c, next) => {
+    const tenantId = c.get('tenantId');
+    if (tenantId !== undefined) c.set('log', c.get('log').child({ tenantId }));
+    await next();
+  });
   const authorizer: Authorizer | undefined =
     input.authz !== undefined ? createAuthorizer(input.authz.authzCheckBinding) : undefined;
 

package/src/errors.ts

@@ -88,6 +88,10 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'budget-exceeded': 422,
   'output-schema-violation': 422,
   'model-invocation-failed': 422,
+  /** No registered provider satisfies the agent's capability declaration (`needs`). */
+  'capability-unsatisfiable': 422,
+  /** A tool the agent names has no version satisfying its range (or the pinned one is gone). */
+  'tool-version-unresolvable': 422,
   'tool-invocation-failed': 422,
   'capability-routing-failed': 422,
   'runtime-not-configured': 422,
@@ -287,6 +291,8 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'secret-provider-unauthorized': 502,
   'secret-provider-rate-limited': 429,
   'secret-store-error': 500,
+  /** The secret store doesn't do this by design (the dev store's rotate and revoke). */
+  'secret-operation-unsupported': 501,
   'env-store-error': 500,
   // Trigger HTTP surface.
   'trigger-not-found': 404,

package/src/handler-binding.ts

@@ -58,6 +58,12 @@ export interface RunHandlerBinding {
   resumeRun(input: ResumeRunBindingInput): Promise<RunHandlerOutcome>;
 }
 
+/** The request's W3C trace context, for the run it starts (`traceId` is kept on the run). */
+export interface RunTrace {
+  readonly traceId: string;
+  readonly spanId: string;
+}
+
 export interface ResumeRunBindingInput {
   readonly tenantId: TenantId;
   readonly runId: RunId;
@@ -101,6 +107,8 @@ export interface InvokeAgentBindingInput {
    * can't run in the background may treat `false` like `true`.
    */
   readonly wait?: boolean;
+  /** The trace context of the request starting the run: the binding records its `traceId` on the run. */
+  readonly trace?: RunTrace;
 }
 
 export interface InvokeFlowBindingInput {
@@ -122,6 +130,8 @@ export interface InvokeFlowBindingInput {
   readonly wait?: boolean;
   /** Agents and tools to run at other exact versions than the flow version's pins (`RunFlowInput.versions`). */
   readonly versions?: FlowVersionOverrides;
+  /** The trace context of the request starting the run, as for an agent run. */
+  readonly trace?: RunTrace;
 }
 
 export type RunHandlerOutcome =

package/src/index.ts

@@ -98,6 +98,7 @@ export type {
   RunHandlerBinding,
   RunHandlerFailure,
   RunHandlerOutcome,
+  RunTrace,
 } from './handler-binding.js';
 export type {
   ReviewerBinding,

package/src/middleware/error-mapper.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
+import type { Logger } from '@kindgi/log';
 import type { Context } from 'hono';
 
 import { statusFor, toWireError } from '../errors.js';
@@ -28,6 +29,8 @@ export function mapThrownError(cause: Error, c: Context): Response {
     return c.newResponse(res.body, res);
   }
   const requestId = (c.get('requestId') as string | undefined) ?? 'req-unknown';
+  // A 500 is something an operator should look at: logged, with the error.
+  (c.get('log') as Logger | undefined)?.error('unhandled error', { err: cause });
   const body = toWireError(
     {
       code: 'internal-server-error',

package/src/middleware/request-log.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type LogLevel, type Logger, formatTraceparent, traceFromHeader } from '@kindgi/log';
+import type { Context, MiddlewareHandler } from 'hono';
+import { routePath } from 'hono/route';
+
+import type { AppEnv } from '../types.js';
+
+/** Paths a client or a probe reads all the time: their lines are `debug` even when they fail to read. */
+const QUIET_PATHS: ReadonlySet<string> = new Set(['/health', '/ready', '/v1/openapi.json']);
+
+const WRITES: ReadonlySet<string> = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * The access line's level, so `info` stays readable with a console open
+ * (it polls every few seconds): a write, and every 4xx, at `info`; every
+ * 5xx at `error`; a successful read (`GET`, `HEAD`: the polling), the
+ * health and readiness probes, the spec and the console's files, and a
+ * stream's opening, at `debug`.
+ */
+export function accessLevel(c: Context<AppEnv>): LogLevel {
+  const status = c.res.status;
+  if (status >= 500) return 'error';
+  if (QUIET_PATHS.has(c.req.path) || !c.req.path.startsWith('/v1/')) return 'debug';
+  if (WRITES.has(c.req.method) || status >= 400) return 'info';
+  return 'debug';
+}
+
+/**
+ * The request's trace context and logger, then its access line.
+ *
+ *   - **Trace:** an incoming `traceparent` (a load balancer's, an API
+ *     gateway's, the caller's own app) is honoured: its trace id is kept
+ *     and the request gets its own span, a child of the caller's. A
+ *     missing or malformed one starts a fresh trace. `c.var.trace` holds
+ *     it; the response answers `traceresponse` (W3C Trace Context Level
+ *     2) next to `X-Request-Id`.
+ *   - **Logger:** `c.var.log` is a child of the app's logger with the
+ *     request's `requestId`, `traceId` and `spanId` (subsystem `http`);
+ *     routes log through it, and authentication adds `tenantId`.
+ *   - **Access line:** `METHOD route status ms`, with the route's
+ *     pattern (`/v1/runs/:runId`, never the raw path, so ids don't
+ *     multiply lines), at the level `accessLevel` gives.
+ *
+ * Mounted right after the request-id middleware.
+ */
+export function requestLogMiddleware(logger: Logger): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const started = Date.now();
+    const trace = traceFromHeader(c.req.header('traceparent'));
+    c.set('trace', trace);
+    c.set(
+      'log',
+      logger.child({
+        subsystem: 'http',
+        requestId: c.get('requestId'),
+        traceId: trace.traceId,
+        spanId: trace.spanId,
+      }),
+    );
+    try {
+      await next();
+    } finally {
+      c.header('traceresponse', formatTraceparent(trace));
+      const log = c.get('log');
+      const level = accessLevel(c);
+      if (log.isLevelEnabled(level)) {
+        // The responding route's pattern; a request no route matched ends on a wildcard.
+        const pattern = routePath(c, -1);
+        const route = pattern.endsWith('*') ? c.req.path : pattern;
+        const durationMs = Date.now() - started;
+        const stream = (c.res.headers.get('content-type') ?? '').startsWith('text/event-stream');
+        log[stream ? 'debug' : level](
+          `${c.req.method} ${route} ${c.res.status} ${durationMs}ms${stream ? ' (stream opened)' : ''}`,
+          {
+            method: c.req.method,
+            route,
+            status: c.res.status,
+            durationMs,
+            ...(c.get('tenantId') !== undefined && { tenantId: c.get('tenantId') }),
+          },
+          // The message says them: a terminal line needn't again.
+          { inMessage: ['method', 'route', 'status', 'durationMs'] },
+        );
+      }
+    }
+  };
+}

package/src/openapi/operations.ts

@@ -6082,6 +6082,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ...CommonMutationErrors,
       '403': ErrorResponse('Bearer token missing `secrets:rotate` capability.'),
       '404': ErrorResponse('Unknown secret.'),
+      '501': ErrorResponse(
+        "The store doesn't rotate (`secret-operation-unsupported`): under `kindgi dev` secrets live in the env files and have no versions; the message says what to do instead.",
+      ),
     },
   },
   {
@@ -6178,6 +6181,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '400': ErrorResponse('Missing or malformed scope / envName.'),
       '403': ErrorResponse('Bearer token missing revoke capability.'),
       '404': ErrorResponse('Unknown secret.'),
+      '501': ErrorResponse(
+        "The store doesn't revoke (`secret-operation-unsupported`): under `kindgi dev` secrets live in the env files; the message says to remove the name there.",
+      ),
     },
   },
 

package/src/openapi/schemas.ts

@@ -637,6 +637,12 @@ export const RunSchema: JsonSchema = {
       description:
         "The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.",
     },
+    traceId: {
+      type: 'string',
+      pattern: '^[0-9a-f]{32}$',
+      description:
+        "The W3C trace id of the request that started the run: the caller's (from its `traceparent`) or one the API minted. The runtime's records about the run carry it; `GET` responses answer `traceresponse` with each request's own. Absent for a run no request started, and on runs from before runs recorded it.",
+    },
     publicAccessToken: {
       type: 'string',
       description:
@@ -4010,6 +4016,28 @@ export const CapabilityCollectionPageSchema: JsonSchema = {
   },
 };
 
+/** `ModelInfo.thinking`: how a model thinks, so a judge can ask for its least. */
+export const ModelThinkingSchema: JsonSchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['mode', 'lowest'],
+  description:
+    "How the model thinks before it answers, so a call that wants as little as it allows (a judge's) gets it. Absent: it doesn't think, or nothing is known.",
+  properties: {
+    mode: {
+      type: 'string',
+      enum: ['adaptive', 'always'],
+      description: '`adaptive`: on unless turned down. `always`: on, and it can only be lowered.',
+    },
+    lowest: {
+      type: 'string',
+      minLength: 1,
+      description:
+        "The vendor's own setting for the least thinking: for Anthropic `disabled`, `between_tools` or an effort (`low`); for Gemini a thinking level (`low`, `minimal`); for OpenAI a reasoning effort (`low`, `none`).",
+    },
+  },
+};
+
 export const ProviderCostSchema: JsonSchema = {
   type: 'object',
   // Adapters widen the cost table with their own rates (Anthropic's
@@ -4061,6 +4089,12 @@ export const ModelInfoSchema: JsonSchema = {
       description:
         'Fallback cap on output tokens. Adapters that require `max_tokens` on every request (e.g. Anthropic) use this when `ModelCallInput.maxOutputTokens` is unset.',
     },
+    sampling: {
+      type: 'boolean',
+      description:
+        "Whether the model takes sampling settings (`temperature`). `false`: its API rejects a non-default value, so the call goes without one and the answer's `warnings` say so (`sampling-unsupported`). Absent: it takes them.",
+    },
+    thinking: { $ref: '#/components/schemas/ModelThinking' },
     description: {
       type: 'string',
       description: 'Short per-model description surfaced in logs.',
@@ -4098,6 +4132,12 @@ export const ProviderMetadataSchema: JsonSchema = {
       description:
         'Models this connection exposes. Non-empty. `models[i].name` must be unique within the list.',
     },
+    defaultModel: {
+      type: 'string',
+      minLength: 1,
+      description:
+        "The model to use when an agent doesn't choose: one of `models[].name`. When candidates rank equally, it comes before the provider's other models; without it, ties break by model name. A preset sets it. A runtime before 0.1.4 ignores it.",
+    },
     attributes: {
       type: 'array',
       items: { type: 'string' },
@@ -8414,6 +8454,7 @@ export const COMPONENT_SCHEMAS: ReadonlyArray<readonly [string, JsonSchema]> = [
   ['Feature', FeatureSchema],
   ['CapabilityDescriptor', CapabilityDescriptorSchema],
   ['CapabilityCollectionPage', CapabilityCollectionPageSchema],
+  ['ModelThinking', ModelThinkingSchema],
   ['ProviderCost', ProviderCostSchema],
   ['ModelInfo', ModelInfoSchema],
   ['ProviderMetadata', ProviderMetadataSchema],

package/src/routes/providers.ts

@@ -9,6 +9,7 @@ import {
   type Feature,
   type ModelInfo,
   type ProviderMetadata,
+  isModelThinking,
   validateProviderLabels,
 } from '@kindgi/capabilities';
 import type { Cursor, TenantId } from '@kindgi/types';
@@ -305,14 +306,15 @@ function serializeProvider(m: ProviderMetadata): Record<string, unknown> {
       name: model.name,
       contextWindow: model.contextWindow,
       features: model.features,
-      cost: {
-        promptUsdPer1kTokens: model.cost.promptUsdPer1kTokens,
-        completionUsdPer1kTokens: model.cost.completionUsdPer1kTokens,
-      },
+      // As stored: the base rates and any an adapter widens it with.
+      cost: { ...model.cost },
       ...(model.p95LatencyMs !== undefined && { p95LatencyMs: model.p95LatencyMs }),
       ...(model.maxOutputTokens !== undefined && { maxOutputTokens: model.maxOutputTokens }),
+      ...(model.sampling !== undefined && { sampling: model.sampling }),
+      ...(model.thinking !== undefined && { thinking: model.thinking }),
       ...(model.description !== undefined && { description: model.description }),
     })),
+    ...(m.defaultModel !== undefined && { defaultModel: m.defaultModel }),
     ...(m.attributes !== undefined && { attributes: m.attributes }),
     ...(m.description !== undefined && { description: m.description }),
     ...(m.capabilityKind !== undefined && { capabilityKind: m.capabilityKind }),
@@ -436,10 +438,20 @@ function validateProviderMetadata(
   }
   const badLabels = validateProviderLabels(b.id, b.labels);
   if (badLabels !== undefined) return { kind: 'err', error: badLabels };
+  if (b.defaultModel !== undefined && !seenNames.has(b.defaultModel as string)) {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${b.id}" defaultModel must be one of its models (${[...seenNames].join(', ')}), got ${JSON.stringify(b.defaultModel)}`,
+        reason: 'unknown-default-model',
+      },
+    };
+  }
   const value: ProviderMetadata = {
     id: b.id,
     region: b.region,
     models: validatedModels,
+    ...(b.defaultModel !== undefined && { defaultModel: b.defaultModel as string }),
     ...(b.attributes !== undefined && { attributes: b.attributes as readonly string[] }),
     ...(b.description !== undefined && { description: b.description }),
     ...(b.capabilityKind !== undefined && { capabilityKind: b.capabilityKind as string }),
@@ -527,6 +539,16 @@ function validateModelInfo(
       },
     };
   }
+  const extraRates = costExtraRates(cost as unknown as Record<string, unknown>);
+  if (extraRates === undefined) {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${providerId}" model "${m.name}" cost table's other rates must be non-negative numbers, or objects of them (e.g. longContext: { thresholdTokens, promptUsdPer1kTokens, completionUsdPer1kTokens })`,
+        reason: 'invalid-cost',
+      },
+    };
+  }
   if (m.p95LatencyMs !== undefined) {
     if (typeof m.p95LatencyMs !== 'number' || m.p95LatencyMs < 0) {
       return {
@@ -553,6 +575,24 @@ function validateModelInfo(
       };
     }
   }
+  if (m.sampling !== undefined && typeof m.sampling !== 'boolean') {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${providerId}" model "${m.name}" sampling must be true or false`,
+        reason: 'invalid-sampling',
+      },
+    };
+  }
+  if (m.thinking !== undefined && !isModelThinking(m.thinking)) {
+    return {
+      kind: 'err',
+      error: {
+        message: `provider "${providerId}" model "${m.name}" thinking must be { mode: 'adaptive' | 'always', lowest: <the vendor's setting> }`,
+        reason: 'invalid-thinking',
+      },
+    };
+  }
   if (m.description !== undefined && typeof m.description !== 'string') {
     return {
       kind: 'err',
@@ -567,16 +607,52 @@ function validateModelInfo(
     contextWindow: m.contextWindow,
     features: m.features as readonly Feature[],
     cost: {
+      ...extraRates,
       promptUsdPer1kTokens: cost.promptUsdPer1kTokens,
       completionUsdPer1kTokens: cost.completionUsdPer1kTokens,
-    },
+    } as ModelInfo['cost'],
     ...(m.p95LatencyMs !== undefined && { p95LatencyMs: m.p95LatencyMs }),
     ...(m.maxOutputTokens !== undefined && { maxOutputTokens: m.maxOutputTokens }),
+    ...(m.sampling !== undefined && { sampling: m.sampling }),
+    ...(m.thinking !== undefined && {
+      thinking: { mode: m.thinking.mode, lowest: m.thinking.lowest },
+    }),
     ...(m.description !== undefined && { description: m.description }),
   };
   return { kind: 'ok', value };
 }
 
+/**
+ * The rates a cost table carries beyond the two base ones: an adapter
+ * widens it with its own (Anthropic's prompt-cache multipliers, Gemini's
+ * cached-prompt share, a long-context tier), each a non-negative number
+ * or one level of an object of them. Returned as given, or `undefined`
+ * when one isn't, so a registration keeps what its adapter prices with.
+ */
+function costExtraRates(
+  cost: Readonly<Record<string, unknown>>,
+): Record<string, number | Record<string, number>> | undefined {
+  const isRate = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+  const out: Record<string, number | Record<string, number>> = {};
+  for (const [key, value] of Object.entries(cost)) {
+    if (key === 'promptUsdPer1kTokens' || key === 'completionUsdPer1kTokens') continue;
+    if (isRate(value)) {
+      out[key] = value;
+    } else if (
+      typeof value === 'object' &&
+      value !== null &&
+      !Array.isArray(value) &&
+      Object.keys(value).length > 0 &&
+      Object.values(value).every(isRate)
+    ) {
+      out[key] = { ...(value as Record<string, number>) };
+    } else {
+      return undefined;
+    }
+  }
+  return out;
+}
+
 /**
  * Parse the optional `adapter_config` on the register request body: a
  * flat object of string, number or boolean values. Credentials don't

package/src/routes/runs.ts

@@ -23,6 +23,7 @@ import type {
   RunHandlerBinding,
   RunHandlerFailure,
   RunHandlerOutcome,
+  RunTrace,
 } from '../handler-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { MintPublicRunTokenResult } from '../public-run-token.js';
@@ -161,7 +162,13 @@ export function runsRouter(
       return c.json(toWireError(parsed.error, requestId));
     }
 
-    const invocation = await invokeFromBody(binding, tenantId, parsed.value);
+    const trace = c.get('trace');
+    const invocation = await invokeFromBody(
+      binding,
+      tenantId,
+      parsed.value,
+      trace !== undefined ? { traceId: trace.traceId, spanId: trace.spanId } : undefined,
+    );
 
     if (invocation.kind === 'err') {
       c.status(statusFor(invocation.error.code) as never);
@@ -624,9 +631,11 @@ function invokeFromBody(
   binding: RunHandlerBinding,
   tenantId: TenantId,
   body: ParsedStartRunBody,
+  trace?: RunTrace,
 ): Promise<RunHandlerOutcome> {
   const common = {
     tenantId,
+    ...(trace !== undefined && { trace }),
     ...(body.projectId !== undefined && { projectId: body.projectId }),
     input: body.input,
     ...(body.segments !== undefined && { segments: body.segments }),
@@ -690,6 +699,7 @@ function serializeRun(
       row.segments.length > 0 && {
         segments: row.segments.map(({ key, value }) => ({ key, value })),
       }),
+    ...(row.traceId != null && { traceId: row.traceId }),
   };
 }
 

package/src/secrets-binding.ts

@@ -305,4 +305,9 @@ export type SecretError =
       readonly message: string;
       readonly currentVersion: number;
     }
+  /**
+   * The store doesn't do this by design (the dev store keeps no versions to
+   * rotate and no revocation): the message says what to do instead.
+   */
+  | { readonly code: 'secret-operation-unsupported'; readonly message: string }
   | { readonly code: 'secret-store-error'; readonly message: string; readonly cause?: unknown };

package/src/types.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { Principal, ReviewerRole } from '@kindgi/authz';
+import type { Logger, TraceContext } from '@kindgi/log';
 import type { ApiTokenId, RunId, SessionId, TenantId, UserId } from '@kindgi/types';
 
 /**
@@ -11,6 +12,14 @@ import type { ApiTokenId, RunId, SessionId, TenantId, UserId } from '@kindgi/typ
 export interface AppEnv {
   Variables: {
     requestId: string;
+    /**
+     * The request's logger (`requestLogMiddleware`): the app's, with the
+     * request's `requestId`, `traceId` and `spanId`, and its `tenantId`
+     * once authenticated. Routes log through it.
+     */
+    log: Logger;
+    /** The request's W3C trace context: the caller's trace when it sent a valid `traceparent`. */
+    trace: TraceContext;
     /** Set by `bearerAuthMiddleware` on authenticated routes. */
     tenantId: TenantId;
     /**