@capybara-hq/kernel 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/agents/pending-connector-requests.d.ts

@@ -0,0 +1,77 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+/**
+ * Moves the agents' setup requests that still concern their owner (pending, or decided and not
+ * dismissed) to the new owner `owner` (an owner change: `AgentsService.reassignOwner`, member
+ * offboarding). Runs through `db` (the caller's transaction).
+ */
+export declare function retargetSetupRequests(db: KernelSchemaDb, agentIds: readonly string[], owner: string): Promise<void>;
+/** What {@link PendingConnectorRequests.openFor} receives: plain values, no transaction. */
+export interface PendingConnectorRequestArgs {
+    orgId: string;
+    agentId: string;
+    ownerAccountId: string;
+    /** The `pendingConnectors[].key`s of the new agent's version 1. */
+    keys: string[];
+}
+/** How a request ends when no key is left (ruling P4-T6-3). */
+export type PendingRequestClose = "approved" | "cancelled";
+/**
+ * The org inbox requests for an agent's pending connectors (ruling P4-7: one `connector_setup`
+ * request per agent, visible to org admins, kept unique by the partial index
+ * `catalog_requests_pending_setup_uq`). Creating an agent from a template calls {@link openFor}
+ * after the commit when the creator lacks `connectors.manage`; the agent's owner or an admin
+ * re-opens one (`PendingConnectorsService.reopen`); every definition write that changes the
+ * agent's pending connectors settles the pending request in its transaction ({@link settleIn}):
+ * the keys narrow, and with none left it closes (`approved` after a bind, `cancelled` after an
+ * edit removed them or the agent was deleted; ruling P4-T6-3). Rejecting is the org admins' (the
+ * catalog requests' decide route). No in-process state.
+ */
+export declare class PendingConnectorRequests {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, txHost: TransactionHost);
+    /**
+     * The request for a new agent, requested by its owner (ruling P4-T6-4). `args.keys` are what the
+     * create saw; {@link open} reads the agent's pending keys again under its row.
+     */
+    openFor(args: PendingConnectorRequestArgs): Promise<void>;
+    /**
+     * Opens a pending `connector_setup` request for the agent's current pending connector keys (read
+     * under the agent row, `FOR NO KEY UPDATE` as `AgentsService.lockForWrite` takes it) unless the
+     * agent has one (then that one, unchanged). Null when the agent is gone (deleted, another org)
+     * or has no pending connectors (fix round 1, item 7). Audits `catalog.requested` for a new one.
+     * Joins the caller's transaction.
+     */
+    open(a: {
+        orgId: string;
+        agentId: string;
+        requestedBy: string;
+        actor: string;
+        actorTokenId?: string | undefined;
+    }): Promise<{
+        id: string;
+        created: boolean;
+    } | null>;
+    /**
+     * The agent's new owner receives its setup request's decision (fix round 1, item 4): the pending
+     * request and the decided ones not dismissed move to `owner`. In the caller's transaction.
+     */
+    retargetIn(agentIds: readonly string[], owner: string): Promise<void>;
+    /**
+     * Settles the agent's pending request after a definition write, in the caller's transaction
+     * (it holds the agent row lock): `keys` are the agent's pending connector keys now. The request
+     * keeps the ones still pending; with none left it closes as `close`, decided by `actor` (a close
+     * the requester made themself needs no notice: it is dismissed at once). Audits
+     * `catalog.request_closed` on a close.
+     */
+    settleIn(a: {
+        orgId: string;
+        agentId: string;
+        keys: readonly string[];
+        close: PendingRequestClose;
+        actor: string;
+        actorTokenId?: string | undefined;
+    }): Promise<void>;
+}

package/dist/agents/pending-connector-requests.js

@@ -0,0 +1,215 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { randomUUID } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { audit } from "../identity/audit.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+/**
+ * Moves the agents' setup requests that still concern their owner (pending, or decided and not
+ * dismissed) to the new owner `owner` (an owner change: `AgentsService.reassignOwner`, member
+ * offboarding). Runs through `db` (the caller's transaction).
+ */
+export async function retargetSetupRequests(db, agentIds, owner) {
+    if (agentIds.length === 0)
+        return;
+    await db
+        .updateTable("catalog_requests")
+        .set({ requested_by: owner })
+        .where("kind", "=", "connector_setup")
+        .where("agent_id", "in", [...agentIds])
+        .where((eb) => eb.or([
+        eb("status", "=", "pending"),
+        eb.and([eb("status", "in", ["approved", "rejected"]), eb("dismissed_at", "is", null)]),
+    ]))
+        .execute();
+}
+/**
+ * The org inbox requests for an agent's pending connectors (ruling P4-7: one `connector_setup`
+ * request per agent, visible to org admins, kept unique by the partial index
+ * `catalog_requests_pending_setup_uq`). Creating an agent from a template calls {@link openFor}
+ * after the commit when the creator lacks `connectors.manage`; the agent's owner or an admin
+ * re-opens one (`PendingConnectorsService.reopen`); every definition write that changes the
+ * agent's pending connectors settles the pending request in its transaction ({@link settleIn}):
+ * the keys narrow, and with none left it closes (`approved` after a bind, `cancelled` after an
+ * edit removed them or the agent was deleted; ruling P4-T6-3). Rejecting is the org admins' (the
+ * catalog requests' decide route). No in-process state.
+ */
+let PendingConnectorRequests = class PendingConnectorRequests {
+    kdb;
+    txHost;
+    constructor(kdb, txHost) {
+        this.kdb = kdb;
+        this.txHost = txHost;
+    }
+    /**
+     * The request for a new agent, requested by its owner (ruling P4-T6-4). `args.keys` are what the
+     * create saw; {@link open} reads the agent's pending keys again under its row.
+     */
+    async openFor(args) {
+        await this.open({
+            orgId: args.orgId,
+            agentId: args.agentId,
+            requestedBy: args.ownerAccountId,
+            actor: args.ownerAccountId,
+        });
+    }
+    /**
+     * Opens a pending `connector_setup` request for the agent's current pending connector keys (read
+     * under the agent row, `FOR NO KEY UPDATE` as `AgentsService.lockForWrite` takes it) unless the
+     * agent has one (then that one, unchanged). Null when the agent is gone (deleted, another org)
+     * or has no pending connectors (fix round 1, item 7). Audits `catalog.requested` for a new one.
+     * Joins the caller's transaction.
+     */
+    async open(a) {
+        const t = this.kdb.db;
+        const agent = await t
+            .selectFrom("agents")
+            .select("current_version")
+            .where("id", "=", a.agentId)
+            .where("org_id", "=", a.orgId)
+            .where("deleted_at", "is", null)
+            .forNoKeyUpdate()
+            .executeTakeFirst();
+        if (!agent)
+            return null;
+        const version = await t
+            .selectFrom("agent_versions")
+            .select("definition")
+            .where("agent_id", "=", a.agentId)
+            .where("version", "=", agent.current_version)
+            .executeTakeFirstOrThrow();
+        const keys = (version.definition.pendingConnectors ?? []).map((c) => c.key);
+        if (keys.length === 0)
+            return null;
+        // a pending request decided between the conflict and the read: insert again (twice at most)
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const id = randomUUID();
+            const inserted = await t
+                .insertInto("catalog_requests")
+                .values({
+                id,
+                org_id: a.orgId,
+                item_id: null,
+                kind: "connector_setup",
+                // still written for the old NOT NULL / CHECK, never read
+                stage: "org",
+                agent_id: a.agentId,
+                pending_keys: JSON.stringify(keys),
+                requested_by: a.requestedBy,
+                note: "",
+            })
+                // the partial index of pending setup requests (a literal predicate: inference needs it)
+                .onConflict((oc) => oc
+                .column("agent_id")
+                .where(sql `kind = 'connector_setup' AND status = 'pending'`)
+                .doNothing())
+                .returning("id")
+                .executeTakeFirst();
+            if (inserted !== undefined) {
+                await audit(t, {
+                    actorAccountId: a.actor,
+                    ...(a.actorTokenId !== undefined && { actorTokenId: a.actorTokenId }),
+                    orgId: a.orgId,
+                    action: "catalog.requested",
+                    target: id,
+                    detail: { kind: "connector_setup", agentId: a.agentId, keys },
+                });
+                return { id, created: true };
+            }
+            const existing = await t
+                .selectFrom("catalog_requests")
+                .select("id")
+                .where("agent_id", "=", a.agentId)
+                .where("kind", "=", "connector_setup")
+                .where("status", "=", "pending")
+                .executeTakeFirst();
+            if (existing)
+                return { id: existing.id, created: false };
+        }
+        throw new Error(`cannot open the connector setup request of agent ${a.agentId}`);
+    }
+    /**
+     * The agent's new owner receives its setup request's decision (fix round 1, item 4): the pending
+     * request and the decided ones not dismissed move to `owner`. In the caller's transaction.
+     */
+    async retargetIn(agentIds, owner) {
+        await retargetSetupRequests(this.kdb.db, agentIds, owner);
+    }
+    /**
+     * Settles the agent's pending request after a definition write, in the caller's transaction
+     * (it holds the agent row lock): `keys` are the agent's pending connector keys now. The request
+     * keeps the ones still pending; with none left it closes as `close`, decided by `actor` (a close
+     * the requester made themself needs no notice: it is dismissed at once). Audits
+     * `catalog.request_closed` on a close.
+     */
+    async settleIn(a) {
+        const t = this.kdb.db;
+        const row = await t
+            .selectFrom("catalog_requests")
+            .select(["id", "pending_keys", "requested_by"])
+            .where("agent_id", "=", a.agentId)
+            .where("kind", "=", "connector_setup")
+            .where("status", "=", "pending")
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row)
+            return;
+        const before = row.pending_keys ?? [];
+        const left = before.filter((k) => a.keys.includes(k));
+        if (left.length > 0) {
+            if (left.length !== before.length) {
+                await t
+                    .updateTable("catalog_requests")
+                    .set({ pending_keys: JSON.stringify(left) })
+                    .where("id", "=", row.id)
+                    .execute();
+            }
+            return;
+        }
+        await t
+            .updateTable("catalog_requests")
+            .set({
+            status: a.close,
+            pending_keys: JSON.stringify([]),
+            decided_by: a.actor,
+            decided_at: sql `now()`,
+            ...(a.close === "approved" &&
+                row.requested_by === a.actor && { dismissed_at: sql `now()` }),
+        })
+            .where("id", "=", row.id)
+            .execute();
+        await audit(t, {
+            actorAccountId: a.actor,
+            ...(a.actorTokenId !== undefined && { actorTokenId: a.actorTokenId }),
+            orgId: a.orgId,
+            action: "catalog.request_closed",
+            target: row.id,
+            detail: { kind: "connector_setup", agentId: a.agentId, status: a.close },
+        });
+    }
+};
+__decorate([
+    Transactional()
+], PendingConnectorRequests.prototype, "open", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PendingConnectorRequests.prototype, "retargetIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], PendingConnectorRequests.prototype, "settleIn", null);
+PendingConnectorRequests = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost))
+], PendingConnectorRequests);
+export { PendingConnectorRequests };

package/dist/agents/pending-connectors.controller.d.ts

@@ -0,0 +1,39 @@
+import type { FastifyReply } from "fastify";
+import { z } from "zod";
+import { CatalogRequestsService, type CatalogRequestView } from "../catalog/requests.service.js";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import type { AgentView } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.js";
+import { PendingConnectorsService } from "./pending-connectors.service.js";
+declare const BindBody: z.ZodObject<{
+    connectorId: z.ZodString;
+}, z.core.$strict>;
+/**
+ * An agent's pending connectors (`/api/v1/orgs/:orgId/agents/:agentId/pending-connectors`,
+ * rulings P4-6, P4-7; human users only):
+ * - `POST :key/bind { connectorId }` (`agents.create`; the service allows the owner or an org
+ *   admin+) -> 200 `{ agent, dropped }`: a new version with the connector's tools, the entry gone;
+ * - `POST request` (same) -> 201 `{ request }` a new `connector_setup` request, 200 `{ request }`
+ *   the pending one;
+ * - `GET request` (`agents.use`; the service allows only the agent's owner or an org admin+:
+ *   another member who sees the agent -> 403 `forbidden`, anyone else 404 `agent.not_found`) ->
+ *   200 `{ request }`: the latest `connector_setup` request of the agent, any status, or null.
+ */
+export declare class PendingConnectorsController {
+    private readonly pending;
+    private readonly agents;
+    private readonly requests;
+    constructor(pending: PendingConnectorsService, agents: AgentsService, requests: CatalogRequestsService);
+    bind(principal: Principal, org: OrgContext, agentId: string, key: string, body: z.infer<typeof BindBody>): Promise<{
+        agent: AgentView;
+        dropped: string[];
+    }>;
+    reopen(principal: Principal, org: OrgContext, agentId: string, reply: FastifyReply): Promise<{
+        request: CatalogRequestView;
+    }>;
+    latest(principal: Principal, org: OrgContext, agentId: string): Promise<{
+        request: CatalogRequestView | null;
+    }>;
+}
+export {};

package/dist/agents/pending-connectors.controller.js

@@ -0,0 +1,91 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, HttpCode, Inject, Param, Post, Res } from "@nestjs/common";
+import { z } from "zod";
+import { CatalogRequestsService } from "../catalog/requests.service.js";
+import { CurrentPrincipal, patTokenId, requireUser, } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AgentsService } from "./agents.service.js";
+import { PendingConnectorsService } from "./pending-connectors.service.js";
+const BindBody = z.object({ connectorId: z.string().min(1).max(100) }).strict();
+class PendingConnectorBindBody extends createZodDto(BindBody, "PendingConnectorBindBody") {
+}
+/**
+ * An agent's pending connectors (`/api/v1/orgs/:orgId/agents/:agentId/pending-connectors`,
+ * rulings P4-6, P4-7; human users only):
+ * - `POST :key/bind { connectorId }` (`agents.create`; the service allows the owner or an org
+ *   admin+) -> 200 `{ agent, dropped }`: a new version with the connector's tools, the entry gone;
+ * - `POST request` (same) -> 201 `{ request }` a new `connector_setup` request, 200 `{ request }`
+ *   the pending one;
+ * - `GET request` (`agents.use`; the service allows only the agent's owner or an org admin+:
+ *   another member who sees the agent -> 403 `forbidden`, anyone else 404 `agent.not_found`) ->
+ *   200 `{ request }`: the latest `connector_setup` request of the agent, any status, or null.
+ */
+let PendingConnectorsController = class PendingConnectorsController {
+    pending;
+    agents;
+    requests;
+    constructor(pending, agents, requests) {
+        this.pending = pending;
+        this.agents = agents;
+        this.requests = requests;
+    }
+    async bind(principal, org, agentId, key, body) {
+        const p = requireUser(principal);
+        const r = await this.pending.bind(org.orgId, agentId, key, body.connectorId, p.account.id, patTokenId(p));
+        const [agent] = await this.agents.withTemplateLinks(org.orgId, [r.agent]);
+        return { agent: agent, dropped: r.dropped };
+    }
+    async reopen(principal, org, agentId, reply) {
+        const p = requireUser(principal);
+        const r = await this.pending.reopen(org.orgId, agentId, p.account.id, patTokenId(p));
+        reply.status(r.created ? 201 : 200);
+        return { request: await this.requests.view(r.id) };
+    }
+    async latest(principal, org, agentId) {
+        const p = requireUser(principal);
+        const id = await this.pending.latestRequest(org.orgId, agentId, p.account.id);
+        return { request: id === null ? null : await this.requests.view(id) };
+    }
+};
+__decorate([
+    Post(":key/bind"),
+    HttpCode(200),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Param("key")),
+    __param(4, ZBody(PendingConnectorBindBody))
+], PendingConnectorsController.prototype, "bind", null);
+__decorate([
+    Post("request"),
+    OrgAction("agents.create"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId")),
+    __param(3, Res({ passthrough: true }))
+], PendingConnectorsController.prototype, "reopen", null);
+__decorate([
+    Get("request"),
+    OrgAction("agents.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, Param("agentId"))
+], PendingConnectorsController.prototype, "latest", null);
+PendingConnectorsController = __decorate([
+    Controller("api/v1/orgs/:orgId/agents/:agentId/pending-connectors"),
+    __param(0, Inject(PendingConnectorsService)),
+    __param(1, Inject(AgentsService)),
+    __param(2, Inject(CatalogRequestsService))
+], PendingConnectorsController);
+export { PendingConnectorsController };

package/dist/agents/pending-connectors.service.d.ts

@@ -0,0 +1,62 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { AgentLookup, type AgentView } from "./agent-lookup.js";
+import { AgentsService } from "./agents.service.js";
+import { PendingConnectorRequests } from "./pending-connector-requests.js";
+/** Why a connector does not fit a pending entry (ruling P4-T6-1). */
+export type PendingMismatch = "template" | "protocol" | "tools" | "not_synced";
+/** What binding a pending connector did. */
+export interface BindResult {
+    agent: AgentView;
+    /**
+     * What the entry named and the connector does not offer, left out: `tools.<name>`,
+     * `policies.<name>`.
+     */
+    dropped: string[];
+}
+/**
+ * Resolving an agent's pending connectors (rulings P4-6, P4-7): binding a connector of the org to a
+ * pending entry, and the agent's connector setup request (re-opening it, reading the latest).
+ * Writes run under the org row lock and the agent row lock ({@link AgentsService.lockForWrite}: the
+ * owner or an org admin+).
+ */
+export declare class PendingConnectorsService {
+    private readonly kdb;
+    private readonly agents;
+    private readonly lookup;
+    private readonly requests;
+    readonly txHost: TransactionHost;
+    constructor(kdb: KernelDb, agents: Pick<AgentsService, "lockForWrite">, lookup: Pick<AgentLookup, "view">, requests: Pick<PendingConnectorRequests, "open" | "settleIn">, txHost: TransactionHost);
+    /** The current version's definition of a locked agent. */
+    private currentDefinition;
+    /**
+     * Binds connector `connectorId` to the agent's pending entry `key` (ruling P4-6; P4-T6-1,
+     * P4-T6-2): a new agent version with a connector ref to it (merged into an existing ref of that
+     * connector) for the entry's tools the connector offers (all of them when the entry names none),
+     * the entry's policies on those tools (the tighter one wins), and without the entry; then the
+     * setup request narrows or closes (`approved`). Refused: no entry `key` -> 404
+     * `agent.pending_connector_not_found`; a connector that is missing, deleted or of another org ->
+     * 404 `connector.not_found`; another connector template (a `template` entry), another protocol
+     * (a `needs` entry), no tool snapshot yet (`not_synced`: an authorization-code connector nobody
+     * authorized) or none of the entry's tools -> 400 `agent.pending_connector_mismatch`.
+     * Audits `agent.pending_connector_bound`.
+     */
+    bind(orgId: string, agentId: string, key: string, connectorId: string, actor: string, actorTokenId?: string): Promise<BindResult>;
+    /**
+     * (Re-)opens the agent's connector setup request (ruling P4-T6-7; the owner or an org admin+):
+     * the pending one when it has one (`created` false), else a new one for the current pending
+     * keys, requested by the agent's owner (P4-T6-4). No pending connectors -> 409
+     * `agent.no_pending_connectors`.
+     */
+    reopen(orgId: string, agentId: string, actor: string, actorTokenId?: string): Promise<{
+        id: string;
+        created: boolean;
+    }>;
+    /**
+     * The id of the agent's latest connector setup request (any status), or null. Authorized as the
+     * writes are (fix round 1): the agent's owner or an org admin+, whether or not the agent is
+     * visible to them; a member who sees the agent otherwise -> 403 `forbidden`; anyone else, or a
+     * deleted agent -> 404 `agent.not_found`.
+     */
+    latestRequest(orgId: string, agentId: string, viewer: string): Promise<string | null>;
+}