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

package/dist/local-devices/local-device-provider.js

@@ -0,0 +1,151 @@
+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 { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { deviceNotFound, SandboxService } from "../sandbox/sandbox.service.js";
+import { deviceOffline, LocalDeviceRelay } from "./relay.js";
+import { DeviceTargets, sameRoots } from "./targets.js";
+/** Extra time the machine gets beyond a command's own timeout (spawn, output, the trip back). */
+export const EXEC_DEADLINE_MARGIN_MS = 5000;
+/** How long the machine may take for one non-exec operation. */
+export const OP_DEADLINE_MS = 30_000;
+/**
+ * Room left in a frame for everything around a `readFile` result's base64 data (the `res`
+ * envelope): a read is clamped so the machine's answer fits `devices.local.maxFrameBytes`
+ * (ruling R26).
+ */
+export const FRAME_ENVELOPE_BYTES = 64 * 1024;
+/** The most raw bytes whose base64 plus {@link FRAME_ENVELOPE_BYTES} fit in `maxFrameBytes`. */
+export const maxReadBytes = (maxFrameBytes) => Math.max(0, Math.floor((maxFrameBytes - FRAME_ENVELOPE_BYTES) / 4) * 3);
+const NAME_PREFIX = "cap-device-";
+/** The device id of a `cap-device-<deviceId>` name; undefined for any other name. */
+export const deviceIdOfName = (name) => name.startsWith(NAME_PREFIX) && name.length > NAME_PREFIX.length
+    ? name.slice(NAME_PREFIX.length)
+    : undefined;
+const rootsOf = (h) => h.roots;
+const bytesOf = (b64) => new Uint8Array(Buffer.from(b64, "base64"));
+/**
+ * The kernel-internal provider `@local` (environments spec §13.5): every operation runs on the
+ * device's connected machine through the {@link LocalDeviceRelay}. The file system is the
+ * machine's device directory (the program creates it on first use), so `createFileSystem`
+ * touches nothing; `suspend` and `destroy` do nothing (the machine is not the platform's to stop);
+ * deleting the device leaves the files on the machine where they are. Nothing here throws `device.offline` on the cleanup paths (ruling R9).
+ *
+ * The files on a machine are its owner's: `destroyFileSystem` (a files reset, the deletion sweep)
+ * does nothing; the deletion's `stop` comes from `MachinesService.revokeActive` (ruling R24).
+ */
+let LocalDeviceProvider = class LocalDeviceProvider {
+    relay;
+    targets;
+    sandbox;
+    config;
+    concurrentExec = true;
+    sessionIsolation = false;
+    constructor(relay, targets, sandbox, config) {
+        this.relay = relay;
+        this.targets = targets;
+        this.sandbox = sandbox;
+        this.config = config;
+    }
+    async createFileSystem(args) {
+        args.signal.throwIfAborted();
+        const id = deviceIdOfName(args.name);
+        if (id === undefined)
+            throw new Error(`not a device name: ${args.name}`);
+        return { id };
+    }
+    /** The files are the machine owner's: nothing to do (ruling R24; never a `stop`). */
+    async destroyFileSystem(_fs, signal) {
+        signal.throwIfAborted();
+    }
+    async destroyFileSystemByName(_name, signal) {
+        signal.throwIfAborted();
+    }
+    async create(args) {
+        const id = args.fileSystem.id;
+        const r = await this.relay.call(id, "create", { limits: args.limits }, { deadlineMs: OP_DEADLINE_MS, signal: args.signal });
+        return { id, roots: r.roots, limits: args.limits };
+    }
+    /**
+     * Needs the machine online. `gone` (the kernel recreates the instance) when the active machine
+     * last reported other roots than the instance was created with (a new login into another
+     * directory or mode, ruling R23).
+     */
+    async resume(h, signal) {
+        signal.throwIfAborted();
+        if (!(await this.relay.holderLive(h.id)))
+            throw deviceOffline();
+        const had = rootsOf(h);
+        const now = await this.targets.machineRoots(h.id);
+        if (had === undefined || (now !== null && !sameRoots(had, now)))
+            return "gone";
+        return "resumed";
+    }
+    async suspend(_h, signal) {
+        signal.throwIfAborted();
+    }
+    async destroy(_h, signal) {
+        signal.throwIfAborted();
+    }
+    async destroyByName(_name, signal) {
+        signal.throwIfAborted();
+    }
+    async killAll(h, signal) {
+        await this.relay.call(h.id, "killAll", {}, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    async killTagged(h, tags, signal) {
+        await this.relay.call(h.id, "killTagged", { tags }, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    async exec(h, args) {
+        const { signal, ...rest } = args;
+        signal.throwIfAborted();
+        const limits = await this.currentLimits(h.id);
+        signal.throwIfAborted();
+        try {
+            return await this.relay.call(h.id, "exec", { ...rest, limits }, { deadlineMs: args.timeoutMs + EXEC_DEADLINE_MARGIN_MS, signal });
+        }
+        catch (e) {
+            // the contract: an exec aborted after it was sent resolves with exitCode null (the relay
+            // queued a cancel, which kills the command on the machine); the output stays there
+            if (signal.aborted && e === signal.reason) {
+                return { exitCode: null, stdout: "", stderr: "", truncated: false, timedOut: false };
+            }
+            throw e;
+        }
+    }
+    async readFile(h, path, opts) {
+        // the answer must fit one frame: a larger file comes back truncated (Deliver: too large)
+        const maxBytes = Math.min(opts.maxBytes, maxReadBytes(this.config.get().devices.local.maxFrameBytes));
+        const r = await this.relay.call(h.id, "readFile", { path, maxBytes }, { deadlineMs: OP_DEADLINE_MS, signal: opts.signal });
+        return r === null ? null : { data: bytesOf(r.dataB64), truncated: r.truncated };
+    }
+    async writeFile(h, path, data, signal) {
+        const dataB64 = Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("base64");
+        await this.relay.call(h.id, "writeFile", { path, dataB64 }, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    async stat(h, path, signal) {
+        return this.relay.call(h.id, "stat", { path }, { deadlineMs: OP_DEADLINE_MS, signal });
+    }
+    /** The org's effective limits now (ruling R27); a deleted device is not found. */
+    async currentLimits(deviceId) {
+        const orgId = await this.targets.orgOf(deviceId);
+        if (orgId === null)
+            throw deviceNotFound();
+        return this.sandbox.orgLimits(orgId);
+    }
+};
+LocalDeviceProvider = __decorate([
+    Injectable(),
+    __param(0, Inject(LocalDeviceRelay)),
+    __param(1, Inject(DeviceTargets)),
+    __param(2, Inject(SandboxService)),
+    __param(3, Inject(KernelConfigService))
+], LocalDeviceProvider);
+export { LocalDeviceProvider };

package/dist/local-devices/local-devices.module.d.ts

@@ -0,0 +1,16 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { SandboxProviders } from "../sandbox/providers.js";
+import { LocalDeviceProvider } from "./local-device-provider.js";
+/**
+ * Connected machines (environments spec §6, §13): the caller side of the device relay and the
+ * kernel-internal `@local` sandbox provider, registered with {@link SandboxProviders} on init, and
+ * the machines and their credentials ({@link MachinesService}).
+ * Imported on every role: any replica may run a sandbox operation on a local device
+ * (the socket itself is held by the gateway role).
+ */
+export declare class LocalDevicesModule implements OnModuleInit {
+    private readonly providers;
+    private readonly provider;
+    constructor(providers: SandboxProviders, provider: LocalDeviceProvider);
+    onModuleInit(): void;
+}

package/dist/local-devices/local-devices.module.js

@@ -0,0 +1,44 @@
+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, Module } from "@nestjs/common";
+import { LOCAL_PROVIDER, SandboxProviders } from "../sandbox/providers.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { LocalDeviceProvider } from "./local-device-provider.js";
+import { MachinesService } from "./machines.js";
+import { LocalDeviceRelay } from "./relay.js";
+import { DeviceTargets } from "./targets.js";
+/**
+ * Connected machines (environments spec §6, §13): the caller side of the device relay and the
+ * kernel-internal `@local` sandbox provider, registered with {@link SandboxProviders} on init, and
+ * the machines and their credentials ({@link MachinesService}).
+ * Imported on every role: any replica may run a sandbox operation on a local device
+ * (the socket itself is held by the gateway role).
+ */
+let LocalDevicesModule = class LocalDevicesModule {
+    providers;
+    provider;
+    constructor(providers, provider) {
+        this.providers = providers;
+        this.provider = provider;
+    }
+    onModuleInit() {
+        this.providers.register({ plugin: LOCAL_PROVIDER, impl: this.provider });
+    }
+};
+LocalDevicesModule = __decorate([
+    Module({
+        imports: [SandboxModule],
+        providers: [DeviceTargets, LocalDeviceRelay, LocalDeviceProvider, MachinesService],
+        exports: [LocalDeviceRelay, LocalDeviceProvider, MachinesService],
+    }),
+    __param(0, Inject(SandboxProviders)),
+    __param(1, Inject(LocalDeviceProvider))
+], LocalDevicesModule);
+export { LocalDevicesModule };

package/dist/local-devices/machines.d.ts

@@ -0,0 +1,118 @@
+import type { DeviceHello, DeviceStopArgs, ExtensionContext } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { KernelLogger } from "../log.js";
+import { LocalDeviceRelay } from "./relay.js";
+/** The machine credential's prefix (`cap_dev_` plus 32 random bytes, base64url). */
+export declare const MACHINE_CREDENTIAL_PREFIX = "cap_dev_";
+/** What a machine credential stands for. */
+export interface MachineIdentity {
+    machineId: string;
+    orgId: string;
+    deviceId: string;
+    accountId: string;
+}
+/** The machine connected to a device (its unrevoked row). */
+export interface ActiveMachine {
+    id: string;
+    orgId: string;
+    accountId: string;
+    name: string;
+    os: string;
+    arch: string;
+    programVersion: string | null;
+    lastSeenAt: Date | null;
+    createdAt: Date;
+}
+/**
+ * Connected machines and their credentials (environments spec §13.2). One active machine per
+ * local device: issuing a credential revokes the device's previous machine. A
+ * credential is `cap_dev_` plus 32 random bytes; only its sha256 is stored. It is accepted only
+ * by the device connection route ({@link authenticate}), never by `/api`: it is no `Principal`.
+ *
+ * A revoked machine is told so after the commit: `stop { reason }` relayed while a replica holds
+ * its connection (fire-and-forget, ruling R14) and `device.revoked.<deviceId>` published with
+ * `{ machineId }`, so the holder closes that machine's connection.
+ */
+export declare class MachinesService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly relay;
+    private readonly bus;
+    private readonly log;
+    constructor(db: KernelDb, txHost: TransactionHost, relay: Pick<LocalDeviceRelay, "holderLive" | "send">, bus: ExtensionContext["bus"], log: Pick<KernelLogger, "warn">);
+    /**
+     * A new machine for the device and its credential (returned once). Revokes the
+     * device's active machine first. Joins the caller's transaction (the device confirmation),
+     * which has already checked the device is the person's own live local device.
+     */
+    issue(input: {
+        orgId: string;
+        deviceId: string;
+        accountId: string;
+        name: string;
+        os: string;
+        arch: string;
+        programVersion: string;
+    }): Promise<{
+        machineId: string;
+        credential: string;
+    }>;
+    /**
+     * Ruling R23: the new machine may serve the device from another directory or mode (other
+     * roots), and a login recreates a directory that was lost (ruling R24). So the instance row
+     * forgets its instance (status `none`, no handle) and its files count as there again; the next
+     * use creates a fresh instance on the machine (with its roots: a new `device_paths` event
+     * follows). The fence moves on, so a lifecycle holder of the old instance fails its next write.
+     * The reset count (`fs_resets`) moves on when the files the next instance sees are not the old
+     * ones, so conversations that used the old files are told their files were reset, not that they
+     * were kept: lost files come back as an empty directory, and another machine (`moved`: name, OS
+     * or arch differ from the device's previous machine) has other files. Another directory on
+     * the same machine is known only from the new machine's first hello ({@link recordHello}).
+     */
+    private resetInstance;
+    /**
+     * Who a machine credential stands for, or null: the machine is not revoked, its device is
+     * live, the org is not deleted (ruling R12), and the person is an active account still a member
+     * of the org. Read live on every call (a connection re-checks it as it sees fit).
+     */
+    authenticate(credential: string): Promise<MachineIdentity | null>;
+    /**
+     * Stores what the program reported in its hello frame and marks the machine seen. On the
+     * machine's first hello, when it is the same machine as the device's previous one (else
+     * {@link issue} already counted the reset) but serves another directory or mode (other roots,
+     * ruling R23), the device's files are other files: `fs_resets` moves on (maintainer
+     * decision 2026-11-08), so conversations get the files-reset notice. A previous machine that
+     * never said hello has no known roots: nothing to compare.
+     */
+    recordHello(machineId: string, hello: DeviceHello): Promise<void>;
+    /** Marks the machine seen (a ping); writes at most once every 60 seconds. */
+    touch(machineId: string): Promise<void>;
+    /**
+     * Disconnects the machine of one of the person's own live local devices (`DELETE
+     * /orgs/:orgId/devices/:id/machine`): revokes it and audits
+     * `device.machine_revoked`. Anyone else's device, a cloud one or a missing one →
+     * `device.not_found`; no machine connected is a no-op.
+     */
+    revoke(orgId: string, accountId: string, deviceId: string, actorTokenId?: string): Promise<void>;
+    /**
+     * Revokes the device's active machine, if any, in the caller's transaction, and after the
+     * commit tells it to stop for `reason` (none: only its connection is closed) and closes its
+     * connection. Returns the revoked machine's id. Used by {@link issue} (replaced: no stop),
+     * {@link revoke} and the device's deletion (`deleted`).
+     */
+    revokeActive(deviceId: string, reason: DeviceStopArgs["reason"] | null): Promise<string | null>;
+    /**
+     * Revokes one machine by id (a sign-in whose credential never reached the program), with the
+     * same post-commit disconnect as a replacement (no stop frame). True when it was active.
+     */
+    revokeMachine(machineId: string): Promise<boolean>;
+    /** The device's active machine, or null. */
+    activeFor(deviceId: string): Promise<ActiveMachine | null>;
+    /**
+     * After a revocation commits: `stop` is queued only while a replica holds the connection (an
+     * offline machine must not find it on the list later), then the revocation is published.
+     * Failures are logged; the revocation itself stands.
+     */
+    private disconnect;
+}