@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.13

package/dist/db/kernel-schema.d.ts

@@ -257,8 +257,8 @@ export interface ConversationsTable {
     deleted_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
     /** 0074: levels below the root conversation (0 = a root; a sub-agent's is its parent's + 1). */
     subagent_depth: ColumnType<number, number | undefined, number>;
-    /** 0088: the environment the conversation runs in; null = not chosen yet. */
-    environment_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0088, renamed in 0105: the device the conversation runs in; null = not chosen yet. */
+    device_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0060: an org's order of file-preview@1 previewers (UI refresh B Task 11). */
 export interface FilePreviewersTable {
@@ -783,8 +783,8 @@ export interface BackgroundTasksTable {
     read_offset: ColumnType<string, number | string | undefined, number | string>;
     /** Set while a stop is under way (0072); the poller skips such a task. */
     stopping_at: ColumnType<Date | null, Date | string | null | undefined, Date | string | null>;
-    /** 0088: the environment the task runs in. */
-    environment_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /** 0088, renamed in 0105: the device the task runs in. */
+    device_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /** 0023_sandboxes.sql: the legacy per-conversation sandbox; kept only for the cleanup job (0088). */
 export interface LegacySandboxesTable {
@@ -818,26 +818,29 @@ type InstanceHandle = ColumnType<{
     id: string;
     [k: string]: unknown;
 } | null, string | null | undefined, string | null>;
-/** 0088_environments.sql: a long-lived environment (one instance plus a kept file system). */
-export interface EnvironmentsTable {
+/**
+ * 0088_environments.sql, renamed in 0105: a device. A cloud device is one instance plus a kept file
+ * system; a local device is a person's machine (device_machines).
+ */
+export interface DevicesTable {
     id: string;
     org_id: string;
     owner_kind: "personal";
     owner_account_id: string;
     name: ColumnType<string | null, string | null | undefined, string | null>;
     is_default: ColumnType<boolean, boolean | undefined, boolean>;
-    /** 0093: `device` is a connected machine (environment_machines). */
-    source: "cloud" | "device";
+    /** 0093, renamed in 0105: `local` is a person's machine (device_machines). */
+    source: "cloud" | "local";
     provider: ColumnType<string | null, string | null | undefined, string | null>;
-    /** 0096: the provider a demoted default was demoted from; null for every other environment. */
+    /** 0096: the provider a demoted default was demoted from; null for every other device. */
     demoted_from_provider: ColumnType<string | null, string | null | undefined, string | null>;
     created_at: Ts;
     updated_at: Ts;
     deleted_at: TsNullable;
 }
-/** 0088_environments.sql: the instance and file system of an environment (replaces sandboxes). */
-export interface EnvironmentInstancesTable {
-    environment_id: string;
+/** 0088_environments.sql, renamed in 0105: the instance and file system of a device. */
+export interface DeviceInstancesTable {
+    device_id: string;
     org_id: string;
     provider: ColumnType<string | null, string | null | undefined, string | null>;
     /** The provider's `FileSystemHandle`; null before the file system exists or after a reset. */
@@ -862,13 +865,13 @@ export interface EnvironmentInstancesTable {
     sweep_failed_at: TsNullable;
 }
 /**
- * 0093_connected_environments.sql: the machine connected to a `device` environment. At most one
- * unrevoked row per environment; revoking sets `revoked_at` and keeps the row.
+ * 0093_connected_environments.sql, renamed in 0105: the machine of a local device. At most one
+ * unrevoked row per device; revoking sets `revoked_at` and keeps the row.
  */
-export interface EnvironmentMachinesTable {
+export interface DeviceMachinesTable {
     id: Generated<string>;
     org_id: string;
-    environment_id: string;
+    device_id: string;
     account_id: string;
     /** A hash of the machine credential, never the credential itself. */
     credential_hash: string;
@@ -884,11 +887,11 @@ export interface EnvironmentMachinesTable {
     created_at: Ts;
     revoked_at: TsNullable;
 }
-/** 0088_environments.sql: the environment a member's new conversations use by default. */
-export interface EnvironmentDefaultsTable {
+/** 0088_environments.sql, renamed in 0105: the device a member's new conversations use by default. */
+export interface DeviceDefaultsTable {
     org_id: string;
     account_id: string;
-    environment_id: string;
+    device_id: string;
     updated_at: Ts;
 }
 /** pg numeric：驱动读出为字符串（精确小数），读取方自行 `Number()`。 */
@@ -1170,10 +1173,10 @@ export interface KernelDatabase {
     directory_exclusions: DirectoryExclusionsTable;
     attachments: AttachmentsTable;
     sandboxes: LegacySandboxesTable;
-    environments: EnvironmentsTable;
-    environment_instances: EnvironmentInstancesTable;
-    environment_defaults: EnvironmentDefaultsTable;
-    environment_machines: EnvironmentMachinesTable;
+    devices: DevicesTable;
+    device_instances: DeviceInstancesTable;
+    device_defaults: DeviceDefaultsTable;
+    device_machines: DeviceMachinesTable;
     background_tasks: BackgroundTasksTable;
     skills: SkillsTable;
     skill_versions: SkillVersionsTable;

package/dist/{environments → devices}/access.d.ts

@@ -1,11 +1,11 @@
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { SandboxProviders } from "../sandbox/providers.js";
-/** What decides an environment's provider: its own record and its instance row's (if any). */
+/** What decides a device's provider: its own record and its instance row's (if any). */
 export interface ProviderFacts {
-    /** `environments.provider`: the provider current when it was created. */
+    /** `devices.provider`: the provider current when it was created. */
     provider: string | null;
-    /** `environment_instances.provider`; null without an instance row. */
+    /** `device_instances.provider`; null without an instance row. */
     instanceProvider: string | null;
     /** The instance row's `fs_status`; null without an instance row. */
     fsStatus: "none" | "ready" | "lost" | null;
@@ -13,15 +13,15 @@ export interface ProviderFacts {
     hasInstance: boolean;
 }
 /**
- * The provider an environment works with: a kernel-internal one (`@device`) as recorded; for a
- * cloud environment the one keeping its files or instance once it has any (they are never
+ * The provider a device works with: a kernel-internal one (`@local`) as recorded; for a
+ * cloud device the one keeping its files or instance once it has any (they are never
  * migrated, spec §4.2 item 13); before that, the current cloud provider (its first use creates
  * them there), else the one recorded at creation. The same rule as `SandboxService`'s use.
  */
-export declare function environmentProvider(f: ProviderFacts, current: string | undefined): string | null;
+export declare function deviceProvider(f: ProviderFacts, current: string | undefined): string | null;
 /** It has files or an instance at some provider (a file system, even a lost one, or a handle). */
 export declare const holdsResources: (f: ProviderFacts) => boolean;
-/** `environment_instances.status`. */
+/** `device_instances.status`. */
 export type InstanceStatus = "none" | "creating" | "running" | "suspended" | "destroyed";
 /**
  * For replacing a default (which one is the person's default): it holds healthy files or an
@@ -36,30 +36,30 @@ export declare const inUseForDefault: (f: ProviderFacts & {
  * The provider a former default belongs to (its label and the provider whose switch back restores
  * it): the one holding its resources once it holds any, else the one it was demoted from (the
  * marker). A former default demoted while empty and used afterwards keeps a stale marker; its
- * resources decide. null for an environment that is not a former default.
+ * resources decide. null for a device that is not a former default.
  */
 export declare function demotedProvider(marker: string | null, f: ProviderFacts): string | null;
 /**
- * The environment's provider is not the current one, or there is no provider (503); for an
- * internal provider (`@device`), this kernel does not serve it.
+ * The device's provider is not the current one, or there is no provider (503); for an
+ * internal provider (`@local`), this kernel does not serve it.
  */
-export declare const environmentUnavailable: (provider: string | null) => ApiError;
+export declare const deviceUnavailable: (provider: string | null) => ApiError;
 /**
- * Who may use an environment (spec §4.2 item 12): in phase 1 only the owner of a personal
- * environment. Anyone else gets `environment.not_found`, never `forbidden`, so ids cannot be
+ * Who may use a device (spec §4.2 item 12): in phase 1 only the owner of a personal
+ * device. Anyone else gets `device.not_found`, never `forbidden`, so ids cannot be
  * probed. Read live on every call (PG, no cache); phase 3 adds project membership.
  */
-export declare class EnvironmentAccess {
+export declare class DeviceAccess {
     private readonly db;
     private readonly providers;
     constructor(db: KernelDb, providers: Pick<SandboxProviders, "cloud" | "forName">);
     /**
-     * The environment if `accountId` may use it in `orgId` now: `environment.not_found` when it is
-     * missing, deleted, in another org or someone else's; `environment.unavailable` when its
-     * provider is not the current one (or there is none). A `device` environment is usable while
-     * `@device` is registered: whether its machine is online is the relay's concern, not access.
+     * The device if `accountId` may use it in `orgId` now: `device.not_found` when it is
+     * missing, deleted, in another org or someone else's; `device.unavailable` when its
+     * provider is not the current one (or there is none). A local device is usable while
+     * `@local` is registered: whether its machine is online is the relay's concern, not access.
      */
-    usable(orgId: string, accountId: string, environmentId: string): Promise<{
+    usable(orgId: string, accountId: string, deviceId: string): Promise<{
         id: string;
         provider: string | null;
     }>;

package/dist/{environments → devices}/access.js

@@ -11,14 +11,14 @@ import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { isInternalProvider, SandboxProviders } from "../sandbox/providers.js";
-import { environmentNotFound } from "../sandbox/sandbox.service.js";
+import { deviceNotFound } from "../sandbox/sandbox.service.js";
 /**
- * The provider an environment works with: a kernel-internal one (`@device`) as recorded; for a
- * cloud environment the one keeping its files or instance once it has any (they are never
+ * The provider a device works with: a kernel-internal one (`@local`) as recorded; for a
+ * cloud device the one keeping its files or instance once it has any (they are never
  * migrated, spec §4.2 item 13); before that, the current cloud provider (its first use creates
  * them there), else the one recorded at creation. The same rule as `SandboxService`'s use.
  */
-export function environmentProvider(f, current) {
+export function deviceProvider(f, current) {
     if (f.provider !== null && isInternalProvider(f.provider))
         return f.provider;
     if (holdsResources(f))
@@ -40,7 +40,7 @@ export const inUseForDefault = (f) => f.fsStatus === "ready" ||
  * The provider a former default belongs to (its label and the provider whose switch back restores
  * it): the one holding its resources once it holds any, else the one it was demoted from (the
  * marker). A former default demoted while empty and used afterwards keeps a stale marker; its
- * resources decide. null for an environment that is not a former default.
+ * resources decide. null for a device that is not a former default.
  */
 export function demotedProvider(marker, f) {
     if (marker === null)
@@ -48,20 +48,20 @@ export function demotedProvider(marker, f) {
     return (holdsResources(f) ? f.instanceProvider : null) ?? marker;
 }
 /**
- * The environment's provider is not the current one, or there is no provider (503); for an
- * internal provider (`@device`), this kernel does not serve it.
+ * The device's provider is not the current one, or there is no provider (503); for an
+ * internal provider (`@local`), this kernel does not serve it.
  */
-export const environmentUnavailable = (provider) => new ApiError("environment.unavailable", provider === null
+export const deviceUnavailable = (provider) => new ApiError("device.unavailable", provider === null
     ? "No cloud sandbox is available in this deployment; ask the super admin to enable a sandbox plugin"
     : isInternalProvider(provider)
-        ? `This environment runs on a connected machine (${provider}), which this deployment does not serve`
-        : `This environment is kept by the sandbox provider ${provider}, which is not the current provider; it can be used again once ${provider} is the deployment's sandbox provider`);
+        ? `This device runs on a connected machine (${provider}), which this deployment does not serve`
+        : `This device is kept by the sandbox provider ${provider}, which is not the current provider; it can be used again once ${provider} is the deployment's sandbox provider`);
 /**
- * Who may use an environment (spec §4.2 item 12): in phase 1 only the owner of a personal
- * environment. Anyone else gets `environment.not_found`, never `forbidden`, so ids cannot be
+ * Who may use a device (spec §4.2 item 12): in phase 1 only the owner of a personal
+ * device. Anyone else gets `device.not_found`, never `forbidden`, so ids cannot be
  * probed. Read live on every call (PG, no cache); phase 3 adds project membership.
  */
-let EnvironmentAccess = class EnvironmentAccess {
+let DeviceAccess = class DeviceAccess {
     db;
     providers;
     constructor(db, providers) {
@@ -69,45 +69,45 @@ let EnvironmentAccess = class EnvironmentAccess {
         this.providers = providers;
     }
     /**
-     * The environment if `accountId` may use it in `orgId` now: `environment.not_found` when it is
-     * missing, deleted, in another org or someone else's; `environment.unavailable` when its
-     * provider is not the current one (or there is none). A `device` environment is usable while
-     * `@device` is registered: whether its machine is online is the relay's concern, not access.
+     * The device if `accountId` may use it in `orgId` now: `device.not_found` when it is
+     * missing, deleted, in another org or someone else's; `device.unavailable` when its
+     * provider is not the current one (or there is none). A local device is usable while
+     * `@local` is registered: whether its machine is online is the relay's concern, not access.
      */
-    async usable(orgId, accountId, environmentId) {
+    async usable(orgId, accountId, deviceId) {
         const row = await this.db
-            .selectFrom("environments as e")
-            .leftJoin("environment_instances as i", "i.environment_id", "e.id")
+            .selectFrom("devices as e")
+            .leftJoin("device_instances as i", "i.device_id", "e.id")
             .select(["e.id", "e.provider", "i.provider as instance_provider", "i.fs_status", "i.handle"])
-            .where("e.id", "=", environmentId)
+            .where("e.id", "=", deviceId)
             .where("e.org_id", "=", orgId)
             .where("e.owner_kind", "=", "personal")
             .where("e.owner_account_id", "=", accountId)
             .where("e.deleted_at", "is", null)
             .executeTakeFirst();
         if (!row)
-            throw environmentNotFound();
+            throw deviceNotFound();
         if (row.provider !== null && isInternalProvider(row.provider)) {
             if (this.providers.forName(row.provider) === undefined) {
-                throw environmentUnavailable(row.provider);
+                throw deviceUnavailable(row.provider);
             }
             return { id: row.id, provider: row.provider };
         }
         const current = this.providers.cloud()?.plugin;
-        const provider = environmentProvider({
+        const provider = deviceProvider({
             provider: row.provider,
             instanceProvider: row.instance_provider,
             fsStatus: row.fs_status,
             hasInstance: row.handle !== null,
         }, current);
         if (current === undefined || provider !== current)
-            throw environmentUnavailable(provider);
+            throw deviceUnavailable(provider);
         return { id: row.id, provider };
     }
 };
-EnvironmentAccess = __decorate([
+DeviceAccess = __decorate([
     Injectable(),
     __param(0, Inject(KernelDb)),
     __param(1, Inject(SandboxProviders))
-], EnvironmentAccess);
-export { EnvironmentAccess };
+], DeviceAccess);
+export { DeviceAccess };

package/dist/devices/conversation-devices.d.ts

@@ -0,0 +1,75 @@
+import { ApiError } from "../errors.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { DeviceAccess } from "./access.js";
+import { DevicesService } from "./devices.service.js";
+/** `details[0].reason` of the error an anonymous IM conversation's sandbox call gets. */
+export declare const ANONYMOUS_NO_DEVICE = "anonymous";
+/** Anonymous IM senders have no device (spec §4.2 item 8): their sandbox tools are off. */
+export declare const anonymousNoDevice: () => ApiError;
+/** How a new conversation picks its device. */
+export interface NewConversationDevice {
+    /** The device the person chose (the composer's picker); checked with `usable`. */
+    deviceId?: string;
+    /** An IM thread: the person's IM default (`device_defaults`) when still usable. */
+    im?: boolean;
+}
+/**
+ * Which device a conversation works in (spec 2026-11-07-environments-design §4.1 items 1, 3;
+ * §4.2 items 8, 9, 12). A conversation is bound once, to a device of its owner
+ * (`conversations.account_id`): the one chosen at its first send, else the owner's IM default
+ * (IM threads), else the owner's default device. Its sub-agents use the root's. Access is
+ * checked when it is bound and again on every sandbox tool call ({@link forTool}); only the owner
+ * may use a personal device, so a conversation never reaches another person's.
+ */
+export declare class ConversationDevices {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly providers;
+    private readonly access;
+    private readonly devices;
+    constructor(db: KernelDb, txHost: TransactionHost, providers: Pick<SandboxProviders, "cloud"> & Partial<Pick<SandboxProviders, "forName">>, access: Pick<DeviceAccess, "usable">, devices: Pick<DevicesService, "ensureDefault">);
+    /**
+     * The device a new conversation of `accountId` is bound to: the chosen one when it is
+     * usable by the person (else `device.not_found` / `device.unavailable`, and nothing
+     * is created); without a choice the IM default (IM only) or the person's default device.
+     * Null (unbound) for anonymous IM senders, and without a cloud sandbox provider when no usable
+     * IM default (a connected machine's device, say) applies.
+     */
+    forNew(orgId: string, accountId: string, pick?: NewConversationDevice): Promise<string | null>;
+    /**
+     * The device a sandbox tool call of the conversation tree rooted at `rootConversationId`
+     * enters, checked for its owner now. A conversation still unbound (created before
+     * devices, or while no provider existed) is bound first, to the owner's IM default when it
+     * is an IM thread, else to the owner's default device; a racing call binds it once.
+     * Throws `sandbox.unavailable` for a cloud device (or none to bind) without a cloud
+     * provider and for an anonymous IM conversation, and `device.not_found` /
+     * `device.unavailable` when the owner may not use it now. A conversation bound to a
+     * connected machine's device (`@local`) does not need a cloud provider.
+     */
+    forTool(orgId: string, rootConversationId: string): Promise<string>;
+    /**
+     * Whether a sandbox tool call of the tree rooted at `rootConversationId` has a provider to run
+     * on, for tool listings (ruling R8; no binding, no access check, never throws): a cloud
+     * provider is loaded, or the device the conversation is bound to (an unbound IM thread:
+     * its owner's IM default) runs on a registered kernel provider (`@local`). A forbidden or gone
+     * device still counts: the call then says why.
+     */
+    usableNow(orgId: string, rootConversationId: string): Promise<boolean>;
+    /**
+     * The person's IM default when `im` and it is still theirs, live, in this org and usable (the
+     * table has no such guard), else their default device (created when missing); null when
+     * that is needed and there is no cloud provider to make or use it. The owner having left the org
+     * reads as `device.not_found`.
+     */
+    private defaultFor;
+    /** Binds an unbound conversation to `deviceId`; returns what it is bound to now. */
+    private bind;
+    /** The device runs on a kernel-internal provider (`@local`). */
+    private isInternal;
+    /** The account is the org's anonymous IM guest (no person behind it). */
+    private isAnonymous;
+    /** The conversation is (or was) an IM thread's. */
+    private isImThread;
+}