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

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,11 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+/** 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.";
+/**
+ * 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 says what to do next. 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): ToolError;

package/dist/platform/errors.js

@@ -0,0 +1,26 @@
+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.";
+/**
+ * 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 says what to do next. 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) {
+    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))}`
+            : "";
+        const message = e.message.trim().replace(/[.!]?$/, ".");
+        return new ToolError(`${e.code}: ${message}${details} ${OPERATION_ERROR_NEXT}`);
+    }
+    throw e;
+}
+const clip = (s) => (s.length > DETAILS_MAX ? `${s.slice(0, DETAILS_MAX)}…` : s);

package/dist/platform/exclusions.d.ts

@@ -0,0 +1,12 @@
+export type ExclusionCategory = "human-only" | "secret" | "transport" | "internal" | "later";
+/**
+ * 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.
+ * `later` needs an `issue` URL.
+ */
+export declare const PLATFORM_EXCLUSIONS: readonly {
+    route: string;
+    category: ExclusionCategory;
+    reason: string;
+    issue?: string;
+}[];