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

package/dist/platform/ops/approvals.ops.d.ts

@@ -0,0 +1,30 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { ApprovalsService, type ApprovalView } from "../../tools/approvals.service.js";
+import { PlatformOperations } from "../registry.js";
+/** Where a person decides an approval: never through an agent (spec §6.4, §14.1 item 2). */
+export declare const DECIDE_ON_WEB = "Decide it on the web, in the inbox or in its conversation; agents never decide approvals.";
+/**
+ * An approval as the waiting list shows it: a compact row with the summary the inbox shows (the
+ * kernel-rendered summary of a per-call policy, else null). Never the tool input: it may carry
+ * another person's data or credentials (Review Focus 5); the web shows it to the person deciding.
+ */
+export declare const approvalRow: (a: ApprovalView) => {
+    id: string;
+    name: string;
+    state: import("../../tools/approvals.service.js").ApprovalStatus;
+    summary: string | null;
+    agent: string;
+    expiresAt: string;
+    next?: string;
+};
+/**
+ * The approval reads of the `Platform` tool (spec §14.1 item 2): what waits for my decision, as
+ * the inbox shows it. Deciding stays with the person on the web; `POST /approvals/:id/decision`
+ * and the standing grants (`/me/tool-grants`) are excluded as human-only.
+ */
+export declare class ApprovalsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly approvals;
+    constructor(registry: PlatformOperations, approvals: ApprovalsService);
+    onModuleInit(): void;
+}

package/dist/platform/ops/approvals.ops.js

@@ -0,0 +1,116 @@
+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 { z } from "zod";
+import { ApprovalPathParams, ApprovalsListQuerySchema } from "../../tools/approvals.schemas.js";
+import { ApprovalsService } from "../../tools/approvals.service.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+/** Where a person decides an approval: never through an agent (spec §6.4, §14.1 item 2). */
+export const DECIDE_ON_WEB = "Decide it on the web, in the inbox or in its conversation; agents never decide approvals.";
+/**
+ * An approval as the waiting list shows it: a compact row with the summary the inbox shows (the
+ * kernel-rendered summary of a per-call policy, else null). Never the tool input: it may carry
+ * another person's data or credentials (Review Focus 5); the web shows it to the person deciding.
+ */
+export const approvalRow = (a) => ({
+    id: a.id,
+    name: a.toolKey,
+    state: a.status,
+    summary: a.summary?.en ?? null,
+    agent: a.agent.name,
+    expiresAt: a.expiresAt,
+    ...(a.status === "pending" && { next: DECIDE_ON_WEB }),
+});
+/**
+ * One approval as `approvals.get` shows it: what was called, by which agent and conversation, its
+ * state and the scopes a decider may choose. Left out: the tool input, the spec hash and the call
+ * and run ids (the decision route's material, not a summary).
+ */
+const detail = (a) => ({
+    id: a.id,
+    toolKey: a.toolKey,
+    toolName: a.toolName,
+    connector: a.connector === null ? null : { id: a.connector.id, name: a.connector.name },
+    extension: a.extension,
+    agent: a.agent,
+    conversationId: a.conversationId,
+    conversationPath: a.conversationPath,
+    ...(a.parentConversationId !== undefined && { parentConversationId: a.parentConversationId }),
+    initiatorAccountId: a.initiatorAccountId,
+    summary: a.summary,
+    status: a.status,
+    approverRole: a.approverRole,
+    scopes: a.scopes,
+    attempt: a.attempt,
+    denyReason: a.denyReason,
+    decidedAt: a.decidedAt,
+    expiresAt: a.expiresAt,
+    createdAt: a.createdAt,
+    ...(a.status === "pending" && { next: DECIDE_ON_WEB }),
+});
+/**
+ * The approval reads of the `Platform` tool (spec §14.1 item 2): what waits for my decision, as
+ * the inbox shows it. Deciding stays with the person on the web; `POST /approvals/:id/decision`
+ * and the standing grants (`/me/tool-grants`) are excluded as human-only.
+ */
+let ApprovalsOperations = class ApprovalsOperations {
+    registry;
+    approvals;
+    constructor(registry, approvals) {
+        this.registry = registry;
+        this.approvals = approvals;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "approvals.waiting",
+                description: "List the tool call approvals you can decide in this org, newest first: your own runs' calls and, for org admins, other people's calls that need an admin. One compact row each (tool, state, the summary the inbox shows, agent, expiry); pending by default, or pass one status (pending, approved, denied, expired, cancelled; there is no \"all\": call once per status to see more). Never the call's input. Deciding is done by you on the web, never by an agent. Pages by 50: pass the returned next as params.cursor.",
+                input: z
+                    .object({ status: ApprovalsListQuerySchema.shape.status, cursor: Cursor.optional() })
+                    .strict(),
+                example: {},
+                authz: { orgAction: "approvals.decide" },
+                mirrors: ["GET /api/v1/orgs/:orgId/approvals"],
+                extras: ["cursor"],
+                confirm: "read",
+                run: async (input, ctx) => {
+                    const all = await this.approvals.list(ctx.orgId, ctx.actorAccountId, input.status ?? "pending");
+                    return pageOf(all.map(approvalRow), startOf(input.cursor), 50);
+                },
+            }),
+            defineOperation({
+                id: "approvals.get",
+                description: "Read one approval you can decide (the id from approvals.waiting or inbox.list): the tool, its connector or extension, the agent and conversation, the summary, state, expiry and the scopes a decision may take. Never the call's input; the web shows it to you when you decide there.",
+                input: z.object({ id: ApprovalPathParams.shape.id.uuid() }).strict(),
+                example: { id: "3f1c2a9e-5b7d-4e21-9c0a-1d2e3f4a5b6c" },
+                authz: { orgAction: "approvals.decide" },
+                mirrors: ["GET /api/v1/orgs/:orgId/approvals/:id"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "approval.not_found",
+                        next: "No approval with this id waits for you (it may be another person's); list yours with approvals.waiting.",
+                    },
+                ],
+                run: async (input, ctx) => ({
+                    approval: detail(await this.approvals.get(ctx.orgId, input.id, ctx.actorAccountId)),
+                }),
+            }),
+        ]);
+    }
+};
+ApprovalsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(ApprovalsService))
+], ApprovalsOperations);
+export { ApprovalsOperations };

package/dist/platform/ops/background.ops.d.ts

@@ -0,0 +1,14 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { BackgroundTasks } from "../../background/tasks.service.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Background task operations of the `Platform` tool (the conversation domain): list the
+ * background commands of one of your conversations and stop one. The output is the web's
+ * (`transport`): bytes of a command's output are read there.
+ */
+export declare class BackgroundOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly tasks;
+    constructor(registry: PlatformOperations, tasks: BackgroundTasks);
+    onModuleInit(): void;
+}

package/dist/platform/ops/background.ops.js

@@ -0,0 +1,134 @@
+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 { z } from "zod";
+import { BackgroundConversationParams, BackgroundTaskParams, } from "../../background/background.schemas.js";
+import { BackgroundTasks } from "../../background/tasks.service.js";
+import { ApiError } from "../../errors.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { viaAgent } from "./errors.js";
+import { Cursor, pageOf, startOf } from "./paging.js";
+import { named } from "./summary.js";
+const PAGE = 50;
+const ConversationId = BackgroundConversationParams.shape.id;
+const TaskId = BackgroundTaskParams.shape.taskId;
+/** The longest command a row or a card quotes. */
+const COMMAND_MAX = 200;
+const row = (t) => ({
+    id: t.id,
+    name: t.description,
+    state: t.status,
+    ...(t.lostReason !== null && { reason: t.lostReason }),
+    command: t.command.length > COMMAND_MAX ? `${t.command.slice(0, COMMAND_MAX)}…` : t.command,
+    subagentId: t.subagentId,
+    stopping: t.stopping,
+});
+/**
+ * Background task operations of the `Platform` tool (the conversation domain): list the
+ * background commands of one of your conversations and stop one. The output is the web's
+ * (`transport`): bytes of a command's output are read there.
+ */
+let BackgroundOperations = class BackgroundOperations {
+    registry;
+    tasks;
+    constructor(registry, tasks) {
+        this.registry = registry;
+        this.tasks = tasks;
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "conversations.background-tasks",
+                description: "List the background commands of one of your conversations and of its sub-agents, newest first: description, state (running, finished, failed, stopped, lost), the command and whether a stop is under way. Pages by 50: pass the returned next as params.cursor.",
+                input: z.object({ conversationId: ConversationId, cursor: Cursor.optional() }).strict(),
+                example: { conversationId: "3f2b8a40-6c1d-4e0b-9a77-5d1e2c8b9f10" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/conversations/:id/background-tasks"],
+                renames: { conversationId: "id" },
+                extras: ["cursor"],
+                confirm: "read",
+                errors: [
+                    {
+                        code: "conversation.not_found",
+                        next: "Check the id with conversations.list: only conversations you can see are readable.",
+                    },
+                ],
+                run: async (input, ctx) => pageOf((await this.tasks.list(ctx.orgId, input.conversationId, ctx.actorAccountId)).map(row), startOf(input.cursor), PAGE),
+            }),
+            defineOperation({
+                id: "conversations.stop-background-task",
+                description: "Stop one background command of one of your conversations, as the stop button does: the command is killed. Takes the task id from conversations.background-tasks. A task already stopping or finished is returned as it is. The person confirms every stop; it is never remembered.",
+                input: z.object({ conversationId: ConversationId, taskId: TaskId }).strict(),
+                example: {
+                    conversationId: "3f2b8a40-6c1d-4e0b-9a77-5d1e2c8b9f10",
+                    taskId: "bg-1a2b3c4d",
+                },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["POST /api/v1/orgs/:orgId/conversations/:id/background-tasks/:taskId/stop"],
+                renames: { conversationId: "id" },
+                confirm: "personal",
+                // a stop kills the command: asked every time and never remembered, like conversations.abort
+                rememberable: false,
+                errors: [
+                    {
+                        code: "conversation.not_found",
+                        next: "Check the id with conversations.list: only conversations you can see are readable.",
+                    },
+                    {
+                        code: "background_task.not_found",
+                        next: "Check the task id with conversations.background-tasks; the task may be gone.",
+                    },
+                ],
+                precheck: async (i, ctx) => {
+                    try {
+                        const tasks = await this.tasks.list(ctx.orgId, i.conversationId, ctx.actorAccountId);
+                        return tasks.some((t) => t.id === i.taskId)
+                            ? { ok: true }
+                            : {
+                                ok: false,
+                                code: "background_task.not_found",
+                                message: "Background task not found",
+                            };
+                    }
+                    catch (e) {
+                        if (e instanceof ApiError)
+                            return { ok: false, code: e.code, message: e.message };
+                        throw e;
+                    }
+                },
+                summary: async (i, ctx) => {
+                    let label = i.taskId;
+                    try {
+                        const t = (await this.tasks.list(ctx.orgId, i.conversationId, ctx.actorAccountId)).find((x) => x.id === i.taskId);
+                        if (t !== undefined)
+                            label = `${t.description} (${named(t.command)})`;
+                    }
+                    catch {
+                        // the card names the id when the task cannot be read
+                    }
+                    return {
+                        zh: `停止后台任务「${named(label)}」`,
+                        en: `Stop background task "${named(label)}"`,
+                    };
+                },
+                run: async (input, ctx) => ({
+                    task: row(await this.tasks.stop(ctx.orgId, input.conversationId, ctx.actorAccountId, input.taskId, undefined, viaAgent("conversations.stop-background-task", ctx))),
+                }),
+            }),
+        ]);
+    }
+};
+BackgroundOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(BackgroundTasks))
+], BackgroundOperations);
+export { BackgroundOperations };

package/dist/platform/ops/catalog-admin.ops.d.ts

@@ -0,0 +1,74 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { CatalogService } from "../../catalog/catalog.service.js";
+import { CatalogScopeService } from "../../catalog/catalog-scope.service.js";
+import { PluginImport, type PluginReview } from "../../catalog/plugin-import.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { PlatformOperations } from "../registry.js";
+/** `plugins.set-shown` on a plugin an org owns. */
+export declare const ORG_OWNED = "An org owns this plugin and manages who sees it; the super admin changes that in the admin console, not here.";
+/** Where the person confirms a staged import (the admin console's import review). */
+export declare const reviewUrl: (stagingId: string) => string;
+/** What only a person does with a staged import, after reading its review on the web. */
+export declare const CONFIRM_ON_WEB = "Nothing is imported yet. Give the person the reviewUrl: they read the review (the extension's permissions among it) and confirm the import on the web. Confirming approves extension permissions, which only a person does.";
+/** A staged import's review as the model needs it: what it brings, not the files themselves. */
+export declare const reviewBrief: (r: PluginReview) => {
+    name: string;
+    version: string;
+    displayName: import("@capybara-hq/plugin-sdk").LocalizedName | null;
+    publisher: string;
+    description: string;
+    format: import("../../catalog/plugin-import.js").PluginSourceFormat;
+    source: {
+        kind: "bootstrap" | "file" | "git" | "marketplace" | "npm";
+        ref: string;
+    };
+    extension: {
+        name: string;
+        version: string;
+        action: import("../../catalog/plugin-import.js").ExtensionReviewAction;
+        deployed: boolean;
+        currentVersion: string | null;
+        sensitive: boolean;
+        addedPermissions: string[];
+        warnings: number;
+    } | null;
+    skills: string[];
+    connectorTemplates: string[];
+    agentTemplates: string[];
+    dependencies: {
+        name: string;
+        range: string;
+        resolved: string | null;
+    }[];
+};
+/**
+ * The super admin's platform catalog operations of the `Platform` tool (spec §14.2, §14.5 item
+ * 1): prepare an import from npm or git and read its review (a person confirms it on the web: the
+ * confirm approves extension permissions), preview and change a plugin's scope, disable or enable
+ * it on the platform, show or hide it, and delete it. Platform plugins and the org's own come with
+ * the admin console's data in full (orgs named); another org's own plugin is refused (the phase-1
+ * rule), and the plugins in a name conflict are counted, never named.
+ */
+export declare class CatalogAdminOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly catalog;
+    private readonly scope;
+    private readonly pluginImport;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, catalog: CatalogService, scope: CatalogScopeService, pluginImport: PluginImport, kdb: KernelDb);
+    /** The precheck refusal of another org's private plugin (the phase-1 rule), else null. */
+    private otherOrgs;
+    /** Whether an org owns the item (its owner org manages it, not the super admin's agent). */
+    private orgOwned;
+    /**
+     * A name conflict the service found at write time (the precheck skipped, or a change landed in
+     * between) without the plugins it names, which may be another org's own: the same error code,
+     * the orgs and skill names from the current preview, the plugins counted, no details.
+     */
+    private withoutPluginNames;
+    /** The precheck refusal of an unknown or deleted item (`catalog.get` includes deleted ones). */
+    private live;
+    /** The item's names for a card, or the id when it cannot be read. */
+    private names;
+    onModuleInit(): void;
+}