@kindgi/api 0.1.4-rc.3 → 0.1.4-rc.5

package/dist/middleware/request-log.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { formatTraceparent, traceFromHeader } from '@kindgi/log';
+import { routePath } from 'hono/route';
+/** Paths a client or a probe reads all the time: their lines are `debug` even when they fail to read. */
+const QUIET_PATHS = new Set(['/health', '/ready', '/v1/openapi.json']);
+const WRITES = 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) {
+    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) {
+    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'] });
+            }
+        }
+    };
+}
+//# sourceMappingURL=request-log.js.map

package/dist/middleware/request-log.js.map

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

package/dist/openapi/operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/openapi/operations.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAO,MAAM,cAAc,CAAC;AAEpD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,sBAAsB,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;QAC5B;;;;;WAKG;QACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,wDAAwD;QACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;KACvE,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC5D;AA0lCD,eAAO,MAAM,UAAU,EAAE,SAAS,aAAa,EA22KrC,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D"}
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/openapi/operations.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAO,MAAM,cAAc,CAAC;AAEpD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,sBAAsB,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;QAC5B;;;;;WAKG;QACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAC9B,wDAAwD;QACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;KACvE,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;CAC5D;AA0lCD,eAAO,MAAM,UAAU,EAAE,SAAS,aAAa,EAs3KrC,CAAC;AAEX,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/openapi/operations.js

@@ -1657,7 +1657,7 @@ export const OPERATIONS = [
         openapiPath: '/v1/agents/{agentId}/promotions',
         operationId: 'agents.promotions.create',
         summary: 'Make a version live for a scope',
-        description: "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.",
+        description: "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.\n\nA pin in place skips the gate: when the scope has no live version of its own and already serves exactly `version` (from a scope above, or as the latest), pinning it there changes nothing any run gets, so it is promoted (`201`) with one passing `pinInPlace` check, no comparison and no approval, its reason starting `pin-in-place`. It is re-checked as it is written; if the scope moved meanwhile, `409 promotion-superseded`: check again.",
         tags: ['agents'],
         security: 'bearer',
         parameters: [AgentIdPathParam, IdempotencyKeyParam],
@@ -1670,7 +1670,7 @@ export const OPERATIONS = [
             },
             ...CommonMutationErrors,
             '404': ErrorResponse('The version is not registered, or was unregistered; or the eval run is not found.'),
-            '409': ErrorResponse("`promotion-superseded`: the scope's live version changed while the gate ran; check again."),
+            '409': ErrorResponse("`promotion-superseded`: the scope's live version changed while the gate ran; check again. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first."),
             '422': ErrorResponse('`gate-failed`: the gate refused it. `details.checks` has every check; the refusal is recorded (`details.promotionId`).'),
             '501': ErrorResponse("`promotion-gate-unsupported`: a gate policy applies, and the deployment can't record a gated promotion."),
         },
@@ -1758,7 +1758,7 @@ export const OPERATIONS = [
             '201': { description: 'Gate policy published.', schema: ref('GatePolicy') },
             ...CommonMutationErrors,
             '400': ErrorResponse('Validation failed (see `details.issues`).'),
-            '409': ErrorResponse('`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: nothing covering the scope is pinned, so a published version would go live there ungated; pin a version for the scope, or one above it, first.'),
+            '409': ErrorResponse('`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: the scope has no live version of its own; a gated scope holds its own pin (a pin above it is not enough, since a promotion there would change this scope ungated), so pin a version for the scope first.'),
         },
     },
     {
@@ -1838,6 +1838,7 @@ export const OPERATIONS = [
             '200': { description: 'The reinstated version.', schema: ref('GatePolicy') },
             ...CommonMutationErrors,
             '404': ErrorResponse('No such version.'),
+            '409': ErrorResponse('`gate-policy-scope-taken`: another policy gates the agent for the scope now (`details.heldBy`). `gate-policy-scope-unpinned`: the scope has no live version of its own; pin one first.'),
         },
     },
     {
@@ -1893,7 +1894,7 @@ export const OPERATIONS = [
             '200': { description: 'Rolled back.', schema: ref('Promotion') },
             ...CommonMutationErrors,
             '404': ErrorResponse('`toVersion` is not registered, or was unregistered.'),
-            '409': ErrorResponse('The scope has no pin, or no earlier version to go back to.'),
+            '409': ErrorResponse('`not-pinned`: the scope has no pin of its own. `nothing-to-roll-back`: no earlier version to go back to. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.'),
         },
     },
     {
@@ -1910,7 +1911,7 @@ export const OPERATIONS = [
         responses: {
             '200': { description: 'Unpinned.', schema: ref('Promotion') },
             ...CommonMutationErrors,
-            '409': ErrorResponse('`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: unpinning would leave a scope a gate policy applies to on the latest version, where publishing goes live ungated.'),
+            '409': ErrorResponse('`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: the scope has a gate policy of its own, and a gated scope keeps its own pin; unregister the policy first, or roll back instead. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.'),
         },
     },
     // ---------- flows ----------
@@ -5493,6 +5494,7 @@ export const OPERATIONS = [
             ...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."),
         },
     },
     {
@@ -5587,6 +5589,7 @@ export const OPERATIONS = [
             '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."),
         },
     },
     // ---------- schedules (trigger surface) ----------