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

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

@@ -0,0 +1,26 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { EnvironmentsService } from "../../environments/environments.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Environment operations of the `Platform` tool (environments design, phase 1): a person's own
+ * cloud environments. Phase 1 has personal environments only, visible to their owner alone, so
+ * these are `personal` writes. A cloud environment carries no credentials or device connection;
+ * deleting one and wiping its files are `personal` writes that are never remembered.
+ */
+export declare class EnvironmentsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly environments;
+    private readonly kdb;
+    constructor(registry: PlatformOperations, environments: EnvironmentsService, kdb: KernelDb);
+    /**
+     * Whether `id` is the environment the run works in: the one its root conversation is bound to
+     * (sub-agents use the root's). Deleting or wiping it would pull the sandbox from under the run.
+     */
+    private isRunsEnvironment;
+    /** The precheck of a destructive write: never the run's own environment, then the service's. */
+    private precheckDestructive;
+    /** The environment's name for a card; its id when it cannot be read. */
+    private label;
+    onModuleInit(): void;
+}

package/dist/platform/ops/environments.ops.js

@@ -0,0 +1,289 @@
+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 { EnvironmentNameBody, EnvironmentParams } from "../../environments/dto.js";
+import { EnvironmentsService, } from "../../environments/environments.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { rootConversationOf } from "../../runtime/subagents/child.js";
+import { defineOperation } from "../operation.js";
+import { PlatformOperations } from "../registry.js";
+import { precheckBy, viaAgent } from "./errors.js";
+import { named, orElse } from "./summary.js";
+const EnvironmentId = z.object({ environmentId: EnvironmentParams.shape.id }).strict();
+const Name = z.object({ name: EnvironmentNameBody.shape.name }).strict();
+/** The default environment has no name; the web shows it as 「个人环境」 / "Personal". */
+const labelOf = (e) => e.name ?? "Personal";
+/** A row's state: why it cannot be used now, else whether its instance runs. */
+function stateOf(e) {
+    if (!e.available) {
+        return {
+            state: "unavailable",
+            reason: "Its sandbox provider is no longer the deployment's current one.",
+            next: "Ask an org admin; use another environment meanwhile.",
+        };
+    }
+    if (e.filesLost) {
+        return {
+            state: "files_lost",
+            reason: "Its file system is gone at the provider.",
+            next: "Wipe its files with environments.reset-files to use it again.",
+        };
+    }
+    return { state: e.instance?.status ?? "ready" };
+}
+const row = (e) => ({
+    id: e.id,
+    name: labelOf(e),
+    ...stateOf(e),
+    isDefault: e.isDefault,
+    provider: e.provider,
+    lastUsedAt: e.instance?.lastUsedAt ?? null,
+});
+/**
+ * Environment operations of the `Platform` tool (environments design, phase 1): a person's own
+ * cloud environments. Phase 1 has personal environments only, visible to their owner alone, so
+ * these are `personal` writes. A cloud environment carries no credentials or device connection;
+ * deleting one and wiping its files are `personal` writes that are never remembered.
+ */
+let EnvironmentsOperations = class EnvironmentsOperations {
+    registry;
+    environments;
+    kdb;
+    constructor(registry, environments, kdb) {
+        this.registry = registry;
+        this.environments = environments;
+        this.kdb = kdb;
+    }
+    /**
+     * Whether `id` is the environment the run works in: the one its root conversation is bound to
+     * (sub-agents use the root's). Deleting or wiping it would pull the sandbox from under the run.
+     */
+    async isRunsEnvironment(id, ctx) {
+        const root = await rootConversationOf(this.kdb.db, ctx.conversationId);
+        const row = await this.kdb.db
+            .selectFrom("conversations")
+            .select("environment_id")
+            .where("id", "=", root)
+            .where("org_id", "=", ctx.orgId)
+            .executeTakeFirst();
+        return row?.environment_id === id;
+    }
+    /** The precheck of a destructive write: never the run's own environment, then the service's. */
+    async precheckDestructive(id, ctx, verb, read) {
+        if (await this.isRunsEnvironment(id, ctx)) {
+            return {
+                ok: false,
+                code: "environment.current",
+                message: `The environment you are running in cannot be ${verb} from here.`,
+            };
+        }
+        return precheckBy(read);
+    }
+    /** The environment's name for a card; its id when it cannot be read. */
+    label(ctx, id) {
+        return orElse(async () => named(labelOf(await this.environments.get(ctx.orgId, ctx.actorAccountId, id))), id);
+    }
+    onModuleInit() {
+        this.registry.register([
+            defineOperation({
+                id: "environments.list",
+                description: "List your own cloud environments in this org: one compact row each (name, state, whether it is the default, provider, last use), plus the default and last used ids and whether new cloud environments can be made. The default environment is shown as Personal.",
+                input: z.object({}).strict(),
+                example: {},
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/environments"],
+                confirm: "read",
+                run: async (_input, ctx) => {
+                    const l = await this.environments.list(ctx.orgId, ctx.actorAccountId);
+                    return {
+                        items: l.items.map(row),
+                        defaultId: l.defaultId,
+                        lastUsedId: l.lastUsedId,
+                        cloudAvailable: l.cloudAvailable,
+                    };
+                },
+            }),
+            defineOperation({
+                id: "environments.get",
+                description: "Read one of your environments with its provider, state, instance, limits and creation time. Takes the id from environments.list.",
+                input: EnvironmentId,
+                example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["GET /api/v1/orgs/:orgId/environments/:id"],
+                renames: { environmentId: "id" },
+                confirm: "read",
+                errors: [
+                    {
+                        code: "environment.not_found",
+                        next: "Check the id with environments.list: you only see your own environments.",
+                    },
+                ],
+                run: async (input, ctx) => {
+                    const e = await this.environments.get(ctx.orgId, ctx.actorAccountId, input.environmentId);
+                    return { environment: { ...e, name: labelOf(e), ...stateOf(e) } };
+                },
+            }),
+            defineOperation({
+                id: "environments.create",
+                description: "Create a personal cloud environment with a name (1-64 characters, unique among yours, case-insensitive). It is ready at once; its instance and files are made on first use. It needs a sandbox provider and is limited per person.",
+                input: Name,
+                example: { name: "Data analysis" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["POST /api/v1/orgs/:orgId/environments"],
+                confirm: "personal",
+                errors: [
+                    {
+                        code: "environment.name_taken",
+                        next: "You have an environment with this name: pick another name, or read yours with environments.list.",
+                    },
+                    {
+                        code: "environment.limit_reached",
+                        next: "You are at the limit: delete an environment you no longer need with environments.delete, or use an existing one.",
+                    },
+                    {
+                        code: "environment.current",
+                        next: "This conversation works in it: ask the person to wipe it on the web, or wipe a different one.",
+                    },
+                    {
+                        code: "environment.unavailable",
+                        next: {
+                            superAdmin: "No sandbox provider is current: set one up in the admin console under extensions, then call again.",
+                            orgAdmin: "No sandbox provider is set up; ask the super admin.",
+                            member: "No sandbox provider is set up in this deployment; ask an org admin.",
+                        },
+                    },
+                ],
+                precheck: (i, ctx) => precheckBy(() => this.environments.checkCreate(ctx.orgId, ctx.actorAccountId, i.name)),
+                summary: (i) => ({
+                    zh: `新建个人云环境「${named(i.name)}」`,
+                    en: `Create personal cloud environment "${named(i.name)}"`,
+                }),
+                run: async (input, ctx) => {
+                    const e = await this.environments.create(ctx.orgId, ctx.actorAccountId, { name: input.name }, undefined, viaAgent("environments.create", ctx));
+                    return { environment: row(e) };
+                },
+            }),
+            defineOperation({
+                id: "environments.delete",
+                description: "Delete one of your environments, the default one included: its instance and ALL its files are destroyed after the response and cannot be recovered. Conversations bound to it keep pointing at it and their sandbox tools then fail. The person confirms every delete; it is never remembered. The environment this conversation works in cannot be deleted. Takes the id from environments.list.",
+                input: EnvironmentId,
+                example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["DELETE /api/v1/orgs/:orgId/environments/:id"],
+                renames: { environmentId: "id" },
+                confirm: "personal",
+                // destructive: asked every time and never remembered
+                rememberable: false,
+                errors: [
+                    {
+                        code: "environment.not_found",
+                        next: "Check the id with environments.list: you only see your own environments.",
+                    },
+                    {
+                        code: "environment.current",
+                        next: "This conversation works in it: ask the person to delete it on the web, or delete a different one.",
+                    },
+                ],
+                precheck: (i, ctx) => this.precheckDestructive(i.environmentId, ctx, "deleted", () => this.environments.get(ctx.orgId, ctx.actorAccountId, i.environmentId)),
+                summary: async (i, ctx) => {
+                    const n = await this.label(ctx, i.environmentId);
+                    const c = await orElse(() => this.environments.boundConversations(ctx.orgId, ctx.actorAccountId, i.environmentId), 0);
+                    return {
+                        zh: `删除环境「${n}」：其中所有文件将被销毁且无法恢复；使用它的 ${c} 个对话将失去沙箱（沙箱工具会失败）`,
+                        en: `Delete environment "${n}": all its files are destroyed and cannot be recovered; the ${c} conversations using it lose their sandbox (their sandbox tools fail)`,
+                    };
+                },
+                run: async (input, ctx) => {
+                    await this.environments.remove(ctx.orgId, ctx.actorAccountId, input.environmentId, undefined, viaAgent("environments.delete", ctx));
+                    return { id: input.environmentId, deleted: true };
+                },
+            }),
+            defineOperation({
+                id: "environments.reset-files",
+                description: "Wipe one of your environments' files so it starts empty: ALL its files are destroyed (after running commands finish) and cannot be recovered; the next use creates a fresh workspace. Use it when an environment reports its files are lost. The person confirms every reset; it is never remembered. The environment this conversation works in cannot be wiped. Takes the id from environments.list.",
+                input: EnvironmentId,
+                example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["POST /api/v1/orgs/:orgId/environments/:id/files/reset"],
+                renames: { environmentId: "id" },
+                confirm: "personal",
+                rememberable: false,
+                errors: [
+                    {
+                        code: "environment.not_found",
+                        next: "Check the id with environments.list: you only see your own environments.",
+                    },
+                    {
+                        code: "environment.current",
+                        next: "This conversation works in it: ask the person to wipe it on the web, or wipe a different one.",
+                    },
+                    {
+                        code: "environment.unavailable",
+                        next: {
+                            orgAdmin: "Its sandbox provider is no longer the current one: use another environment, or ask the super admin about the provider.",
+                            member: "Its sandbox provider is no longer the current one: use another environment, or ask an org admin.",
+                        },
+                    },
+                ],
+                precheck: (i, ctx) => this.precheckDestructive(i.environmentId, ctx, "wiped", () => this.environments.checkReset(ctx.orgId, ctx.actorAccountId, i.environmentId)),
+                summary: async (i, ctx) => {
+                    const n = await this.label(ctx, i.environmentId);
+                    return {
+                        zh: `清空环境「${n}」的文件：所有文件将被销毁且无法恢复`,
+                        en: `Wipe the files of environment "${n}": all files are destroyed and cannot be recovered`,
+                    };
+                },
+                run: async (input, ctx) => {
+                    await this.environments.resetFiles(ctx.orgId, ctx.actorAccountId, input.environmentId, undefined, viaAgent("environments.reset-files", ctx));
+                    return { id: input.environmentId, reset: true };
+                },
+            }),
+            defineOperation({
+                id: "environments.rename",
+                description: "Rename one of your environments, the default one included (it then has a name). The new name is 1-64 characters and unique among yours, case-insensitive. Takes the id from environments.list.",
+                input: EnvironmentId.extend({ name: EnvironmentNameBody.shape.name }).strict(),
+                example: { environmentId: "4e8a0c1d-6b2f-4a37-8d19-3c5e7f9a1b20", name: "Reports" },
+                authz: { orgAction: "agents.use" },
+                mirrors: ["PATCH /api/v1/orgs/:orgId/environments/:id"],
+                renames: { environmentId: "id" },
+                confirm: "personal",
+                errors: [
+                    {
+                        code: "environment.not_found",
+                        next: "Check the id with environments.list: you only see your own environments.",
+                    },
+                    {
+                        code: "environment.name_taken",
+                        next: "You have an environment with this name: pick another name.",
+                    },
+                ],
+                precheck: (i, ctx) => precheckBy(() => this.environments.checkRename(ctx.orgId, ctx.actorAccountId, i.environmentId, i.name)),
+                summary: async (i, ctx) => {
+                    const from = await orElse(async () => named(labelOf(await this.environments.get(ctx.orgId, ctx.actorAccountId, i.environmentId))), i.environmentId);
+                    return {
+                        zh: `将环境「${from}」重命名为「${named(i.name)}」`,
+                        en: `Rename environment "${from}" to "${named(i.name)}"`,
+                    };
+                },
+                run: async (input, ctx) => ({
+                    environment: row(await this.environments.rename(ctx.orgId, ctx.actorAccountId, input.environmentId, input.name, undefined, viaAgent("environments.rename", ctx))),
+                }),
+            }),
+        ]);
+    }
+};
+EnvironmentsOperations = __decorate([
+    Injectable(),
+    __param(0, Inject(PlatformOperations)),
+    __param(1, Inject(EnvironmentsService)),
+    __param(2, Inject(KernelDb))
+], EnvironmentsOperations);
+export { EnvironmentsOperations };

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

@@ -1,10 +1,15 @@
+import type { PrecheckResult } from "../operation.js";
 /**
- * Runs a service call for an operation: an {@link ApiError} (the service's refusal: forbidden,
- * not found, a stale preview) becomes a {@link ToolError} naming its code, so the model reads what
- * to do next instead of a generic failure. Anything else is a bug and propagates.
+ * An operation's precheck from a service read that throws the write's own refusal: the
+ * {@link ApiError} it throws becomes the failure (its code and message), a return passes. Anything
+ * else propagates, and the tool skips the precheck.
+ */
+export declare function precheckBy(read: () => Promise<unknown>): Promise<PrecheckResult>;
+/**
+ * The audit detail of a write made through the tool (spec §6): who, where and which operation. The
+ * keys are distinct from any business field (`agentConversationId`, not `conversationId`), so
+ * merging it into a write's own detail never overwrites the conversation or run the write is about.
  */
-export declare function asToolError<T>(call: () => Promise<T>): Promise<T>;
-/** The audit detail of a write made through the tool (spec §6): who, where and which operation. */
 export declare function viaAgent(operation: string, ctx: {
     conversationId: string;
     runId: string | null;

package/dist/platform/ops/errors.js

@@ -1,22 +1,30 @@
-import { ToolError } from "@capybara-hq/plugin-sdk";
 import { ApiError } from "../../errors.js";
 /**
- * Runs a service call for an operation: an {@link ApiError} (the service's refusal: forbidden,
- * not found, a stale preview) becomes a {@link ToolError} naming its code, so the model reads what
- * to do next instead of a generic failure. Anything else is a bug and propagates.
+ * An operation's precheck from a service read that throws the write's own refusal: the
+ * {@link ApiError} it throws becomes the failure (its code and message), a return passes. Anything
+ * else propagates, and the tool skips the precheck.
  */
-export async function asToolError(call) {
+export async function precheckBy(read) {
     try {
-        return await call();
+        await read();
+        return { ok: true };
     }
     catch (e) {
-        if (e instanceof ApiError) {
-            throw new ToolError(`${e.code}: ${e.message}`);
-        }
+        if (e instanceof ApiError)
+            return { ok: false, code: e.code, message: e.message };
         throw e;
     }
 }
-/** The audit detail of a write made through the tool (spec §6): who, where and which operation. */
+/**
+ * The audit detail of a write made through the tool (spec §6): who, where and which operation. The
+ * keys are distinct from any business field (`agentConversationId`, not `conversationId`), so
+ * merging it into a write's own detail never overwrites the conversation or run the write is about.
+ */
 export function viaAgent(operation, ctx) {
-    return { via: "agent", conversationId: ctx.conversationId, runId: ctx.runId, operation };
+    return {
+        via: "agent",
+        operation,
+        agentConversationId: ctx.conversationId,
+        agentRunId: ctx.runId,
+    };
 }

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

@@ -0,0 +1,28 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { EvalRunsService } from "../../evals/runs.service.js";
+import { EvalSetsService } from "../../evals/sets.service.js";
+import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
+import { KernelDb } from "../../infra/database/kernel-db.js";
+import { PlatformOperations } from "../registry.js";
+/**
+ * Eval operations of the `Platform` tool (spec §14): eval sets, their cases, runs and results,
+ * all for org admins (`evals.manage`), like the routes. Cases and full results are copies of
+ * conversation content: reading one is audited (`trajectory.viewed`, `eval.results_viewed`) with
+ * the operation that did it.
+ */
+export declare class EvalsOperations implements OnModuleInit {
+    private readonly registry;
+    private readonly sets;
+    private readonly runs;
+    private readonly kdb;
+    private readonly config;
+    constructor(registry: PlatformOperations, sets: EvalSetsService, runs: EvalRunsService, kdb: KernelDb, config: Pick<KernelConfigService, "get">);
+    /** The position of a case in its set, from 1 (0 when it is not there): the case's label. */
+    private caseNo;
+    /** The set's eval-set row of the org, or the refusal the routes give. */
+    private setCheck;
+    /** Whether the set may take one more case (the configured maximum). */
+    private roomCheck;
+    private setName;
+    onModuleInit(): void;
+}