@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.21

package/dist/platform/actor.d.ts

@@ -0,0 +1,48 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { type OrgSettings } from "../orgs/settings.service.js";
+/** What `availability()` (./availability.ts) decides on, read live for each call (spec §6.1). */
+export interface ActorFacts {
+    /**
+     * The actor's role in the org; null: not a member any more, or the account is disabled (the HTTP
+     * auth refuses a disabled account on every request).
+     */
+    role: OrgRole | null;
+    isSuperAdmin: boolean;
+    /** A person who can see and answer a confirmation is behind this run. */
+    personPresent: boolean;
+    /** The root conversation's agent is `private` and its owner is the actor. */
+    agentPrivateToActor: boolean;
+    /** The org setting `platformTool`. */
+    setting: OrgSettings["platformTool"];
+}
+/**
+ * Reads the facts about the actor of a `Platform` call: the run's trigger account (spec §6.1),
+ * re-read on every call, as the HTTP guards would.
+ *
+ * A person is present when all of these hold:
+ * - there is a run, it belongs to the conversation and its trigger account is the actor;
+ * - the root conversation of the tree (a sub-agent's is followed up through its parents) is a
+ *   `chat` (an `eval` conversation replays, nobody watches it);
+ * - the actor is an active member of the org, and not the org's anonymous guest account (a channel
+ *   message from an unlinked user under the `anonymous` policy runs as that account).
+ *
+ * The agent is private to the actor when the root conversation's agent is `private` and owned by
+ * the actor (a sub-agent's own agent does not count; Platform tool spec §6.1).
+ *
+ * Service tokens cannot start runs (posting a message requires a user principal), so no run is
+ * token-started; a wake run (`budget_run_id` set) runs as the person whose run it continues and
+ * counts as present. No new run column is needed to tell the origins apart.
+ */
+export declare class PlatformActor {
+    private readonly db;
+    constructor(db: KernelDb);
+    facts(ctx: {
+        orgId: string;
+        accountId: string;
+        /** The calling agent (from the runtime, never from the model's input). */
+        agentId: string;
+        conversationId: string;
+        runId?: string | null;
+    }): Promise<ActorFacts>;
+}

package/dist/platform/actor.js

@@ -0,0 +1,100 @@
+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 { Inject, Injectable } from "@nestjs/common";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { readOrgSettings } from "../orgs/settings.service.js";
+import { rootConversationOf } from "../runtime/subagents/child.js";
+/**
+ * Reads the facts about the actor of a `Platform` call: the run's trigger account (spec §6.1),
+ * re-read on every call, as the HTTP guards would.
+ *
+ * A person is present when all of these hold:
+ * - there is a run, it belongs to the conversation and its trigger account is the actor;
+ * - the root conversation of the tree (a sub-agent's is followed up through its parents) is a
+ *   `chat` (an `eval` conversation replays, nobody watches it);
+ * - the actor is an active member of the org, and not the org's anonymous guest account (a channel
+ *   message from an unlinked user under the `anonymous` policy runs as that account).
+ *
+ * The agent is private to the actor when the root conversation's agent is `private` and owned by
+ * the actor (a sub-agent's own agent does not count; Platform tool spec §6.1).
+ *
+ * Service tokens cannot start runs (posting a message requires a user principal), so no run is
+ * token-started; a wake run (`budget_run_id` set) runs as the person whose run it continues and
+ * counts as present. No new run column is needed to tell the origins apart.
+ */
+let PlatformActor = class PlatformActor {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async facts(ctx) {
+        const rootId = await rootConversationOf(this.db.db, ctx.conversationId);
+        const [account, settings, root, anonymous, run] = await Promise.all([
+            this.db
+                .selectFrom("accounts")
+                .leftJoin("memberships", (j) => j
+                .onRef("memberships.account_id", "=", "accounts.id")
+                .on("memberships.org_id", "=", ctx.orgId))
+                .select(["accounts.is_super_admin", "accounts.status", "memberships.role"])
+                .where("accounts.id", "=", ctx.accountId)
+                .executeTakeFirst(),
+            readOrgSettings(this.db.db, ctx.orgId),
+            this.db
+                .selectFrom("conversations")
+                .select(["kind", "agent_id"])
+                .where("id", "=", rootId)
+                .where("org_id", "=", ctx.orgId)
+                .executeTakeFirst(),
+            this.db
+                .selectFrom("org_anonymous_accounts")
+                .select("account_id")
+                .where("org_id", "=", ctx.orgId)
+                .where("account_id", "=", ctx.accountId)
+                .executeTakeFirst(),
+            ctx.runId == null
+                ? undefined
+                : this.db
+                    .selectFrom("runs")
+                    .select("trigger_account_id")
+                    .where("id", "=", ctx.runId)
+                    .where("conversation_id", "=", ctx.conversationId)
+                    .executeTakeFirst(),
+        ]);
+        // the super admin's "own private agent" is the tree's root agent: a sub-agent (a template or
+        // general-purpose child) of a shared agent's conversation never counts as private
+        const agentId = rootId === ctx.conversationId ? ctx.agentId : root?.agent_id;
+        const agent = agentId == null
+            ? undefined
+            : await this.db
+                .selectFrom("agents")
+                .select(["owner_account_id", "visibility"])
+                .where("id", "=", agentId)
+                .where("org_id", "=", ctx.orgId)
+                .where("deleted_at", "is", null)
+                .executeTakeFirst();
+        const activeMember = account?.role != null && account.status === "active";
+        return {
+            role: activeMember ? (account?.role ?? null) : null,
+            isSuperAdmin: account?.is_super_admin === true && account.status === "active",
+            // the run is the actor's, in this conversation, and its tree's root is a `chat`
+            personPresent: activeMember &&
+                anonymous === undefined &&
+                run?.trigger_account_id === ctx.accountId &&
+                root?.kind === "chat",
+            agentPrivateToActor: agent?.visibility === "private" && agent.owner_account_id === ctx.accountId,
+            setting: settings.platformTool,
+        };
+    }
+};
+PlatformActor = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb))
+], PlatformActor);
+export { PlatformActor };

package/dist/platform/agent-docs.d.ts

@@ -0,0 +1,18 @@
+export interface AgentDocTopic {
+    id: string;
+    title: string;
+}
+/**
+ * The documentation topics the `Platform` tool's `read` action serves (Platform tool spec §8):
+ * the Markdown files of the SDK's `agent-docs` directory, versioned with the contracts they
+ * describe. The files are immutable within a version, so one read per process is a cache of
+ * package files, not shared state.
+ */
+export declare class AgentDocs {
+    private cache;
+    private load;
+    /** Topic ids (path without `.md`, e.g. `extension-points/channel`) with their titles. */
+    topics(): AgentDocTopic[];
+    /** The Markdown of a topic, or null when there is none. */
+    read(id: string): string | null;
+}

package/dist/platform/agent-docs.js

@@ -0,0 +1,59 @@
+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;
+};
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { Injectable } from "@nestjs/common";
+/** The SDK's `agent-docs` directory, found from the installed `@capybara-hq/plugin-sdk` package. */
+function agentDocsDir() {
+    const pkg = createRequire(import.meta.url).resolve("@capybara-hq/plugin-sdk/package.json");
+    return join(dirname(pkg), "agent-docs");
+}
+function listTopics(dir, prefix = "") {
+    const topics = new Map();
+    if (!existsSync(dir))
+        return topics;
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.isDirectory()) {
+            for (const [id, text] of listTopics(join(dir, e.name), `${prefix}${e.name}/`)) {
+                topics.set(id, text);
+            }
+        }
+        else if (e.name.endsWith(".md")) {
+            topics.set(`${prefix}${e.name.slice(0, -3)}`, readFileSync(join(dir, e.name), "utf8"));
+        }
+    }
+    return topics;
+}
+/**
+ * The documentation topics the `Platform` tool's `read` action serves (Platform tool spec §8):
+ * the Markdown files of the SDK's `agent-docs` directory, versioned with the contracts they
+ * describe. The files are immutable within a version, so one read per process is a cache of
+ * package files, not shared state.
+ */
+let AgentDocs = class AgentDocs {
+    cache;
+    load() {
+        this.cache ??= listTopics(agentDocsDir());
+        return this.cache;
+    }
+    /** Topic ids (path without `.md`, e.g. `extension-points/channel`) with their titles. */
+    topics() {
+        return [...this.load()].map(([id, text]) => ({
+            id,
+            title: /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? id,
+        }));
+    }
+    /** The Markdown of a topic, or null when there is none. */
+    read(id) {
+        return this.load().get(id) ?? null;
+    }
+};
+AgentDocs = __decorate([
+    Injectable()
+], AgentDocs);
+export { AgentDocs };

package/dist/platform/availability.d.ts

@@ -0,0 +1,14 @@
+import type { ActorFacts } from "./actor.js";
+import type { PlatformOperation } from "./operation.js";
+export type Availability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Whether the actor may call `op` now (spec §6), decided on facts read at call time. The reason
+ * is model-visible English: it says who can do it or why not, so the agent can offer the next
+ * step (a request operation, the web page, an admin) instead of retrying.
+ */
+export declare function availability(op: PlatformOperation, f: ActorFacts): Availability;

package/dist/platform/availability.js

@@ -0,0 +1,43 @@
+import { ACTION_MIN_ROLE, can } from "../orgs/roles.js";
+/** Who holds a role, as a reason names them. */
+const HOLDER = {
+    guest: "any org member",
+    member: "an org member (not a guest)",
+    admin: "an org admin",
+    owner: "an org owner",
+};
+const refuse = (reason) => ({ ok: false, reason });
+/**
+ * Whether the actor may call `op` now (spec §6), decided on facts read at call time. The reason
+ * is model-visible English: it says who can do it or why not, so the agent can offer the next
+ * step (a request operation, the web page, an admin) instead of retrying.
+ */
+export function availability(op, f) {
+    if (f.role === null) {
+        return refuse("You are not a member of this org any more, or your account is disabled, so no Platform operation is available; ask an org admin to add you back or the super admin to enable your account.");
+    }
+    if (f.setting === "off") {
+        return refuse("The org turned the Platform tool off; an org admin can switch it on in the organization settings.");
+    }
+    if ("superAdmin" in op.authz) {
+        if (!f.isSuperAdmin) {
+            return refuse("Only the super admin can do this; ask them, or use a request operation where one exists.");
+        }
+        if (!f.agentPrivateToActor) {
+            return refuse("Platform-scope operations run only through your own private agent; open a conversation with a private agent you own and do it there.");
+        }
+    }
+    else if (!can(f.role, op.authz.orgAction)) {
+        const min = ACTION_MIN_ROLE[op.authz.orgAction];
+        return refuse(`This needs the ${min} role in the org (you are ${f.role}); ${HOLDER[min]} can do it, or use a request operation where one exists.`);
+    }
+    if (op.confirm !== "read") {
+        if (f.setting === "read-only") {
+            return refuse("The org set the Platform tool to read-only, so writes are unavailable; do it on the web, or ask an org admin to change the setting.");
+        }
+        if (!f.personPresent) {
+            return refuse("This write needs a person to confirm it, and no person is present in this run (a scheduled, evaluation or anonymous run); only read operations are available.");
+        }
+    }
+    return { ok: true };
+}

package/dist/platform/errors.d.ts

@@ -0,0 +1,28 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import type { ActorFacts } from "./actor.js";
+import type { OperationError, OperationErrorNext } from "./operation.js";
+/** What the model is told to do after an operation refused its input (Platform tool spec §5.2). */
+export declare const OPERATION_ERROR_NEXT = "Check the input with describe and call again, or ask the person.";
+/** The role an error's next step is written for (spec §14.5 item 7). */
+export type ErrorRole = "superAdmin" | "orgAdmin" | "member";
+/** The actor's role for next steps: the super admin first, then an org admin (admin or owner). */
+export declare function errorRoleOf(facts: Pick<ActorFacts, "role" | "isSuperAdmin">): ErrorRole;
+/** The next step an operation declares for `code`, for this role; undefined when it has none. */
+export declare function nextStepFor(errors: readonly OperationError[] | undefined, code: string, role: ErrorRole): string | undefined;
+/** One next step resolved for this role (the fallbacks of {@link nextStepFor}). */
+export declare function resolveNext(next: OperationErrorNext | undefined, role: ErrorRole): string | undefined;
+/** `errors[]` as `describe` shows them to this actor: each `next` resolved for the role. */
+export declare function errorsFor(errors: readonly OperationError[], role: ErrorRole): {
+    code: string;
+    next: string;
+}[];
+/**
+ * An error an operation threw, as the `Platform` tool's error for the model (spec §5.2: errors say
+ * what to do next). A `ToolError` passes as is; an `ApiError` (what the same HTTP route would
+ * answer) keeps its code, message and details, then gives the next step: `nextOf(code)` (the
+ * operation's entry for the actor's role), else the generic one. Anything else is a kernel fault,
+ * not the model's: it is rethrown, so the pipeline logs it and reports the generic failure.
+ */
+export declare function toToolError(e: unknown, nextOf?: (code: string) => string | undefined): ToolError;
+/** A text ending with a full stop (`.` added unless it ends with `.`, `!` or `?`). */
+export declare const sentence: (s: string) => string;

package/dist/platform/errors.js

@@ -0,0 +1,65 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+/** Longest `details` JSON quoted in an operation's tool error. */
+const DETAILS_MAX = 1000;
+/** What the model is told to do after an operation refused its input (Platform tool spec §5.2). */
+export const OPERATION_ERROR_NEXT = "Check the input with describe and call again, or ask the person.";
+/** The actor's role for next steps: the super admin first, then an org admin (admin or owner). */
+export function errorRoleOf(facts) {
+    if (facts.isSuperAdmin)
+        return "superAdmin";
+    return facts.role === "admin" || facts.role === "owner" ? "orgAdmin" : "member";
+}
+/**
+ * Which keyed texts a role may get, in order. The super admin's text (the admin console path) goes
+ * to the super admin only; an org admin falls back to the member's step and a member to the org
+ * admin's (both name steps inside the org).
+ */
+const FALLBACK = {
+    superAdmin: ["superAdmin", "orgAdmin", "member"],
+    orgAdmin: ["orgAdmin", "member"],
+    member: ["member", "orgAdmin"],
+};
+/** The next step an operation declares for `code`, for this role; undefined when it has none. */
+export function nextStepFor(errors, code, role) {
+    return resolveNext(errors?.find((e) => e.code === code)?.next, role);
+}
+/** One next step resolved for this role (the fallbacks of {@link nextStepFor}). */
+export function resolveNext(next, role) {
+    if (next === undefined || typeof next === "string")
+        return next;
+    for (const r of FALLBACK[role]) {
+        const text = next[r];
+        if (text !== undefined)
+            return text;
+    }
+    return undefined;
+}
+/** `errors[]` as `describe` shows them to this actor: each `next` resolved for the role. */
+export function errorsFor(errors, role) {
+    return errors.flatMap((e) => {
+        const next = nextStepFor(errors, e.code, role);
+        return next === undefined ? [] : [{ code: e.code, next }];
+    });
+}
+/**
+ * An error an operation threw, as the `Platform` tool's error for the model (spec §5.2: errors say
+ * what to do next). A `ToolError` passes as is; an `ApiError` (what the same HTTP route would
+ * answer) keeps its code, message and details, then gives the next step: `nextOf(code)` (the
+ * operation's entry for the actor's role), else the generic one. Anything else is a kernel fault,
+ * not the model's: it is rethrown, so the pipeline logs it and reports the generic failure.
+ */
+export function toToolError(e, nextOf) {
+    if (e instanceof ToolError)
+        return e;
+    if (e instanceof ApiError) {
+        const details = e.details !== undefined && e.details.length > 0
+            ? ` Details: ${clip(JSON.stringify(e.details))}`
+            : "";
+        return new ToolError(`${e.code}: ${sentence(e.message)}${details} ${nextOf?.(e.code) ?? OPERATION_ERROR_NEXT}`);
+    }
+    throw e;
+}
+/** A text ending with a full stop (`.` added unless it ends with `.`, `!` or `?`). */
+export const sentence = (s) => s.trim().replace(/[.!?]?$/, (m) => m || ".");
+const clip = (s) => (s.length > DETAILS_MAX ? `${s.slice(0, DETAILS_MAX)}…` : s);

package/dist/platform/exclusions.d.ts

@@ -0,0 +1,11 @@
+export type ExclusionCategory = "human-only" | "secret" | "transport" | "internal";
+/**
+ * Kernel HTTP routes the `Platform` tool does not mirror, each with a reason (spec §9);
+ * `check:platform-ops` fails a route that is neither mirrored by an operation nor listed here.
+ * Every exclusion is for good: there is no "later" (rule `platform-op-later`).
+ */
+export declare const PLATFORM_EXCLUSIONS: readonly {
+    route: string;
+    category: ExclusionCategory;
+    reason: string;
+}[];