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

package/src/routes/runs.ts

@@ -2,11 +2,18 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import { Hono } from 'hono';
-import type { MiddlewareHandler } from 'hono';
 
 import type { AgentId } from '@kindgi/agents';
 import type { KernelRunRecord, ListRunsInput, RunBinding } from '@kindgi/runtime';
-import type { FlowId, ListScope, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
+import type {
+  FlowId,
+  ListScope,
+  ProjectId,
+  RunId,
+  ScopeSegment,
+  Semver,
+  TenantId,
+} from '@kindgi/types';
 
 import { ref } from '@kindgi/authz';
 
@@ -20,9 +27,11 @@ import type {
 import type { Authorizer } from '../middleware/authorize.js';
 import type { MintPublicRunTokenResult } from '../public-run-token.js';
 import type { AppEnv } from '../types.js';
+import { liveScopeToWire } from './live-scope-wire.js';
 import type { DecodedCursor } from './pagination.js';
 import { clampLimit, decodeCursor } from './pagination.js';
 import { parseListScope } from './scope-params.js';
+import { parseSegmentsBody } from './segments.js';
 import {
   formatSseFrame,
   isTerminalWireKind,
@@ -30,6 +39,7 @@ import {
   projectJournalEntry,
   toRunProgressEvent,
 } from './sse.js';
+import { UUID_RE, refuseMalformedUuidParam } from './uuid-param.js';
 
 const KERNEL_RUN_CHANNEL_PREFIX = 'kernel:run:';
 
@@ -61,23 +71,8 @@ const MAX_RUN_ANCESTRY = 16;
  * `POST /:runId/cancel`, `POST /:runId/resume`, `GET /:runId/stream`
  * (SSE), `GET /:runId/journal`.
  */
-/** A run id: a UUID. */
-const RUN_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-
-/**
- * A `:runId` that isn't a run id is a 400, before it reaches a query (where
- * Postgres's uuid cast would fail it as a 500).
- */
-const refuseMalformedRunId: MiddlewareHandler<AppEnv> = async (c, next) => {
-  if (RUN_ID_RE.test(c.req.param('runId') ?? '')) return next();
-  c.status(statusFor('bad-input') as never);
-  return c.json(
-    toWireError(
-      { code: 'bad-input', message: '`runId` must be a run id (a UUID)' },
-      c.get('requestId'),
-    ),
-  );
-};
+/** A `:runId` that isn't a run id is a 400 (`uuid-param.ts`). */
+const refuseMalformedRunId = refuseMalformedUuidParam('runId', 'a run id');
 
 export function runsRouter(
   binding: RunHandlerBinding,
@@ -634,6 +629,7 @@ function invokeFromBody(
     tenantId,
     ...(body.projectId !== undefined && { projectId: body.projectId }),
     input: body.input,
+    ...(body.segments !== undefined && { segments: body.segments }),
     ...(body.dryRun !== undefined && { dryRun: body.dryRun }),
     ...(body.wait !== undefined && { wait: body.wait }),
   };
@@ -681,11 +677,19 @@ function serializeRun(
         id: row.agent.id,
         version: row.agent.version,
         conversationId: row.agent.conversationId as unknown as string,
+        ...(row.agent.via !== undefined && { via: row.agent.via }),
+        ...(row.agent.liveScope !== undefined && {
+          liveScope: liveScopeToWire(row.agent.liveScope),
+        }),
       },
     }),
     ...(row.replayOf != null && { replayOf: row.replayOf as unknown as string }),
     ...(row.evalRunId != null && { evalRunId: row.evalRunId }),
     ...(row.versions != null && { versions: row.versions }),
+    ...(row.segments !== undefined &&
+      row.segments.length > 0 && {
+        segments: row.segments.map(({ key, value }) => ({ key, value })),
+      }),
   };
 }
 
@@ -777,7 +781,7 @@ function parseRunListFilter(
     return { kind: 'err', message: '`topLevel` must be `true` or `false`' };
   }
   const topLevelOnly = topLevel === 'true';
-  if (parentRunId !== undefined && !RUN_ID_RE.test(parentRunId)) {
+  if (parentRunId !== undefined && !UUID_RE.test(parentRunId)) {
     return { kind: 'err', message: '`parentRunId` must be a run id (a UUID)' };
   }
   if (parentRunId !== undefined && topLevelOnly) {
@@ -849,6 +853,7 @@ type ParsedStartRunBody =
       readonly agentId: AgentId;
       readonly agentVersion?: Semver;
       readonly projectId?: ProjectId;
+      readonly segments?: readonly ScopeSegment[];
       readonly input: unknown;
       readonly dryRun?: boolean;
       readonly wait?: boolean;
@@ -858,6 +863,7 @@ type ParsedStartRunBody =
       readonly flowId: FlowId;
       readonly flowVersion?: Semver;
       readonly projectId?: ProjectId;
+      readonly segments?: readonly ScopeSegment[];
       readonly input: unknown;
       readonly dryRun?: boolean;
       readonly wait?: boolean;
@@ -893,6 +899,11 @@ function parseStartRunBody(
   const options = parseStartOptions(b.options);
   if (options.kind === 'err') return options;
   const { dryRun, wait } = options.value;
+  const parsedSegments = parseSegmentsBody(b.segments);
+  if (parsedSegments.kind === 'err') {
+    return { kind: 'err', error: { code: 'bad-input', message: parsedSegments.message } };
+  }
+  const { segments } = parsedSegments;
   if (hasAgent) {
     const agentVersion = b.agentVersion;
     if (agentVersion !== undefined && typeof agentVersion !== 'string') {
@@ -915,6 +926,7 @@ function parseStartRunBody(
         agentId: b.agent as AgentId,
         ...(agentVersion !== undefined && { agentVersion: agentVersion as Semver }),
         ...(agentProjectIdRaw !== undefined && { projectId: agentProjectIdRaw as ProjectId }),
+        ...(segments !== undefined && { segments }),
         input: b.input,
         ...(dryRun !== undefined && { dryRun }),
         ...(wait !== undefined && { wait }),
@@ -942,6 +954,7 @@ function parseStartRunBody(
       flowId: b.flow as FlowId,
       ...(flowVersion !== undefined && { flowVersion: flowVersion as Semver }),
       ...(projectId !== undefined && { projectId: projectId as ProjectId }),
+      ...(segments !== undefined && { segments }),
       input: b.input,
       ...(dryRun !== undefined && { dryRun }),
       ...(wait !== undefined && { wait }),

package/src/routes/secrets.ts

@@ -160,6 +160,7 @@ export function secretsRouter(options: SecretsRouterOptions): Hono<AppEnv> {
     });
     return c.json({
       data: page.data.map(serializeSecretRecord),
+      hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
   });
@@ -232,6 +233,7 @@ export function secretsRouter(options: SecretsRouterOptions): Hono<AppEnv> {
     });
     return c.json({
       data: page.data.map(serializeVersion),
+      hasMore: page.nextCursor !== undefined,
       ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor as unknown as string }),
     });
   });

package/src/routes/segments.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ScopeSegment } from '@kindgi/types';
+
+/** A segment key: lowercase, like an identifier (`company`, `contact-role`). */
+const SEGMENT_KEY_RE = /^[a-z][a-z0-9_-]{0,63}$/;
+const MAX_SEGMENTS = 8;
+const MAX_VALUE_LENGTH = 256;
+
+type Parsed =
+  | { readonly kind: 'ok'; readonly segments?: readonly ScopeSegment[] }
+  | { readonly kind: 'err'; readonly message: string };
+
+function checked(segments: readonly ScopeSegment[], field: string): Parsed {
+  if (segments.length === 0) return { kind: 'ok' };
+  if (segments.length > MAX_SEGMENTS) {
+    return { kind: 'err', message: `\`${field}\` takes at most ${MAX_SEGMENTS} segments` };
+  }
+  const seen = new Set<string>();
+  for (const { key, value } of segments) {
+    if (!SEGMENT_KEY_RE.test(key)) {
+      return {
+        kind: 'err',
+        message: `\`${field}\`: a segment key is lowercase letters, digits, - and _ (starting with a letter); got "${key}"`,
+      };
+    }
+    if (seen.has(key))
+      return { kind: 'err', message: `\`${field}\`: the key "${key}" appears twice` };
+    seen.add(key);
+    if (value.length === 0 || value.length > MAX_VALUE_LENGTH) {
+      return {
+        kind: 'err',
+        message: `\`${field}\`: a segment value is 1–${MAX_VALUE_LENGTH} characters (key "${key}")`,
+      };
+    }
+  }
+  return { kind: 'ok', segments };
+}
+
+/**
+ * A run's or a pin's segment path from a JSON body: an ordered list of
+ * `{key, value}`, coarse to fine (e.g. `company` then `role`).
+ */
+export function parseSegmentsBody(raw: unknown, field = 'segments'): Parsed {
+  if (raw === undefined) return { kind: 'ok' };
+  if (!Array.isArray(raw)) {
+    return {
+      kind: 'err',
+      message: `\`${field}\` must be an array of {key, value}, coarse to fine`,
+    };
+  }
+  const segments: ScopeSegment[] = [];
+  for (const item of raw) {
+    const { key, value } = (item ?? {}) as { key?: unknown; value?: unknown };
+    if (typeof key !== 'string' || typeof value !== 'string') {
+      return { kind: 'err', message: `\`${field}\`: each segment is {key: string, value: string}` };
+    }
+    segments.push({ key, value });
+  }
+  return checked(segments, field);
+}
+
+/** The same from a query: repeated `segment=key:value`, in order. */
+export function parseSegmentsQuery(values: readonly string[]): Parsed {
+  const segments: ScopeSegment[] = [];
+  for (const raw of values) {
+    const colon = raw.indexOf(':');
+    if (colon <= 0) {
+      return { kind: 'err', message: `\`segment\` is key:value; got "${raw}"` };
+    }
+    segments.push({ key: raw.slice(0, colon), value: raw.slice(colon + 1) });
+  }
+  return checked(segments, 'segment');
+}

package/src/routes/teams.ts

@@ -10,6 +10,7 @@ import type {
   TeamBinding,
   TeamMembership,
   TeamMembershipBinding,
+  TeamMembershipUpdateRoleOutcome,
   TeamPatch,
   TeamRole,
   TeamSpec,
@@ -19,7 +20,11 @@ import type { Cursor, OrgId, TeamId, TenantId, UserId } from '@kindgi/types';
 import { statusFor, toWireError } from '../errors.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { AppEnv } from '../types.js';
-import { orgNotFoundError, slugConflictError } from './hierarchy-errors.js';
+import {
+  membershipNotKeptInStepError,
+  orgNotFoundError,
+  slugConflictError,
+} from './hierarchy-errors.js';
 import { clampLimit } from './pagination.js';
 
 /**
@@ -57,6 +62,34 @@ export function teamsRouter(
 ): Hono<AppEnv> {
   const r = new Hono<AppEnv>();
 
+  /**
+   * Change a member's role. With an authorizer, the row and its FGA tuple
+   * change together through the tenant-hierarchy binding, or the change
+   * is refused; without one, the membership binding alone.
+   */
+  async function updateMemberRole(
+    tenantId: TenantId,
+    teamId: TeamId,
+    userId: UserId,
+    role: TeamRole,
+  ): Promise<
+    | { readonly kind: 'done'; readonly outcome: TeamMembershipUpdateRoleOutcome }
+    | { readonly kind: 'refused'; readonly error: ReturnType<typeof membershipNotKeptInStepError> }
+  > {
+    if (authorizer === undefined) {
+      return {
+        kind: 'done',
+        outcome: await membershipBinding.updateRole(tenantId, teamId, userId, role),
+      };
+    }
+    if (tenantHierarchy.updateTeamMemberRole === undefined) {
+      return { kind: 'refused', error: membershipNotKeptInStepError('updateTeamMemberRole') };
+    }
+    const res = await tenantHierarchy.updateTeamMemberRole({ tenantId, teamId, userId, role });
+    if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    return { kind: 'done', outcome: res.value };
+  }
+
   // ---------- Authorization middleware ----------
   // Full PEP surface:
   //   POST /                                    → admin on tenant
@@ -363,7 +396,19 @@ export function teamsRouter(
     const tenantId = c.get('tenantId') as TenantId;
     const teamId = c.req.param('teamId') as TeamId;
     const userId = c.req.param('userId') as UserId;
-    await membershipBinding.remove(tenantId, teamId, userId);
+    // With an authorizer, the row and its FGA tuple go together, or not
+    // at all: removing the row alone would leave the permission in place.
+    if (authorizer !== undefined) {
+      if (tenantHierarchy.removeTeamMember === undefined) {
+        const refusal = membershipNotKeptInStepError('removeTeamMember');
+        c.status(statusFor(refusal.code) as never);
+        return c.json(toWireError(refusal, c.get('requestId')));
+      }
+      const res = await tenantHierarchy.removeTeamMember({ tenantId, teamId, userId });
+      if (res.kind === 'err') throw new Error(res.error.message, { cause: res.error });
+    } else {
+      await membershipBinding.remove(tenantId, teamId, userId);
+    }
     c.status(204);
     return c.body(null);
   });
@@ -403,7 +448,12 @@ export function teamsRouter(
         ),
       );
     }
-    const outcome = await membershipBinding.updateRole(tenantId, teamId, userId, b.role);
+    const updated = await updateMemberRole(tenantId, teamId, userId, b.role);
+    if (updated.kind === 'refused') {
+      c.status(statusFor(updated.error.code) as never);
+      return c.json(toWireError(updated.error, requestId));
+    }
+    const { outcome } = updated;
     if (outcome.kind === 'team-membership-not-found') {
       c.status(statusFor('team-membership-not-found') as never);
       return c.json(

package/src/routes/uuid-param.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { MiddlewareHandler } from 'hono';
+
+import { statusFor, toWireError } from '../errors.js';
+import type { AppEnv } from '../types.js';
+
+/** A UUID, the shape of a run's and a conversation's id. */
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * A path parameter that must be a UUID: one that isn't is a 400 naming
+ * it, before it reaches a query (where Postgres's uuid cast would fail it
+ * as a 500). `what` names the id, e.g. `a run id`.
+ */
+export function refuseMalformedUuidParam(param: string, what: string): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    if (UUID_RE.test(c.req.param(param) ?? '')) return next();
+    c.status(statusFor('bad-input') as never);
+    return c.json(
+      toWireError(
+        { code: 'bad-input', message: `\`${param}\` must be ${what} (a UUID)` },
+        c.get('requestId'),
+      ),
+    );
+  };
+}