@datalayer/agent-runtimes 1.5.70 → 1.5.73

package/lib/portable/localApprovals.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A local session's approvals (VSCODE VS-07, DESKTOP DK-13, the local
+ * place): a local runtime decides an *ask me first* request over its
+ * websocket (`/api/v1/tool-approvals/ws`) — it sends `agent.snapshot`
+ * messages listing the approvals as they stand, and takes
+ * `tool_approval_decision` messages — not over an HTTP route
+ * (`routes/tool_approvals.py` has no other). What is read from a snapshot,
+ * what a decision is sent as, and what a decision came to once the next
+ * snapshot no longer lists the approval. Pure: no host API, no socket.
+ *
+ * @module portable/localApprovals
+ */
+import { type ApprovalRaised } from './attention';
+/** The agent of a local runtime's sessions: the runtime names it `default`. */
+export declare const LOCAL_AGENT_ID = "default";
+/** What the local approval source says. */
+export declare const LOCAL_APPROVAL_WORDS: {
+    readonly notConfirmed: "The local runtime did not confirm the decision in time: decide it in the chat.";
+    readonly socketGone: (folderName: string) => string;
+};
+/**
+ * Where the local runtime's approvals are decided: its websocket, for one agent.
+ *
+ * @param runtimeUrl - The local runtime's address (`http://127.0.0.1:<port>`).
+ * @param agentId - The agent whose approvals are read.
+ *
+ * @returns The websocket URL.
+ */
+export declare function localApprovalsSocketUrl(runtimeUrl: string, agentId?: string): string;
+/**
+ * Whether a websocket message is a snapshot of the agent (`agent.snapshot`).
+ *
+ * @param message - The message, parsed.
+ *
+ * @returns Whether it is one.
+ */
+export declare function isSnapshot(message: unknown): boolean;
+/**
+ * The approvals still pending in a snapshot, for one agent: read strictly,
+ * a row without an id or a tool left out.
+ *
+ * @param message - The `agent.snapshot` message, parsed.
+ * @param agentId - The agent whose approvals are kept.
+ *
+ * @returns The pending approvals, in the snapshot's order.
+ */
+export declare function approvalsOfSnapshot(message: unknown, agentId?: string): ApprovalRaised[];
+/**
+ * The decision as the runtime's websocket takes it.
+ *
+ * @param approvalId - The approval decided.
+ * @param approved - Whether it is approved.
+ * @param note - A note, when the person left one.
+ *
+ * @returns The message to send, serialized.
+ */
+export declare function decisionMessage(approvalId: string, approved: boolean, note?: string): string;
+/**
+ * What a decision came to, read from the snapshots: nothing while the
+ * approval is still listed pending; the sentence (done, as the route's 200
+ * would say it) once it is no longer; *answered elsewhere* when it was not
+ * pending when the decision was asked.
+ *
+ * @param pendingWhenAsked - Whether the approval was pending when asked.
+ * @param pendingNow - The approvals pending in the latest snapshot.
+ * @param approvalId - The approval decided.
+ * @param approved - Whether approval was asked.
+ * @param action - The action in words, for the sentence.
+ *
+ * @returns The sentence, or null while nothing says yet.
+ */
+export declare function decisionSettled(pendingWhenAsked: boolean, pendingNow: readonly Pick<ApprovalRaised, 'id'>[], approvalId: string, approved: boolean, action: string): string | null;

package/lib/portable/localApprovals.js

@@ -0,0 +1,125 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A local session's approvals (VSCODE VS-07, DESKTOP DK-13, the local
+ * place): a local runtime decides an *ask me first* request over its
+ * websocket (`/api/v1/tool-approvals/ws`) — it sends `agent.snapshot`
+ * messages listing the approvals as they stand, and takes
+ * `tool_approval_decision` messages — not over an HTTP route
+ * (`routes/tool_approvals.py` has no other). What is read from a snapshot,
+ * what a decision is sent as, and what a decision came to once the next
+ * snapshot no longer lists the approval. Pure: no host API, no socket.
+ *
+ * @module portable/localApprovals
+ */
+import { ATTENTION_WORDS, decisionOutcome, } from './attention.js';
+/** The agent of a local runtime's sessions: the runtime names it `default`. */
+export const LOCAL_AGENT_ID = 'default';
+/** What the local approval source says. */
+export const LOCAL_APPROVAL_WORDS = {
+    notConfirmed: 'The local runtime did not confirm the decision in time: decide it in the chat.',
+    socketGone: (folderName) => `The local runtime of ${folderName} went away before answering.`,
+};
+/**
+ * Where the local runtime's approvals are decided: its websocket, for one agent.
+ *
+ * @param runtimeUrl - The local runtime's address (`http://127.0.0.1:<port>`).
+ * @param agentId - The agent whose approvals are read.
+ *
+ * @returns The websocket URL.
+ */
+export function localApprovalsSocketUrl(runtimeUrl, agentId = LOCAL_AGENT_ID) {
+    const base = runtimeUrl.replace(/\/+$/, '').replace(/^http/, 'ws');
+    return `${base}/api/v1/tool-approvals/ws?agent_id=${encodeURIComponent(agentId)}`;
+}
+const text = (value) => typeof value === 'string' ? value : '';
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+/**
+ * Whether a websocket message is a snapshot of the agent (`agent.snapshot`).
+ *
+ * @param message - The message, parsed.
+ *
+ * @returns Whether it is one.
+ */
+export function isSnapshot(message) {
+    return record(message).type === 'agent.snapshot';
+}
+/**
+ * The approvals still pending in a snapshot, for one agent: read strictly,
+ * a row without an id or a tool left out.
+ *
+ * @param message - The `agent.snapshot` message, parsed.
+ * @param agentId - The agent whose approvals are kept.
+ *
+ * @returns The pending approvals, in the snapshot's order.
+ */
+export function approvalsOfSnapshot(message, agentId = LOCAL_AGENT_ID) {
+    const envelope = record(message);
+    if (envelope.type !== 'agent.snapshot') {
+        return [];
+    }
+    const payload = record(envelope.payload);
+    const listed = Array.isArray(payload.approvals) ? payload.approvals : [];
+    const approvals = [];
+    for (const raw of listed.map(record)) {
+        const id = text(raw.id);
+        const toolName = text(raw.tool_name);
+        const status = text(raw.status) || 'pending';
+        const agent = text(raw.agent_id) || agentId;
+        if (!id || !toolName || status !== 'pending' || agent !== agentId) {
+            continue;
+        }
+        approvals.push({
+            id,
+            toolName,
+            args: record(raw.tool_args),
+            agentId: agent,
+            requestedAt: text(raw.created_at),
+        });
+    }
+    return approvals;
+}
+/**
+ * The decision as the runtime's websocket takes it.
+ *
+ * @param approvalId - The approval decided.
+ * @param approved - Whether it is approved.
+ * @param note - A note, when the person left one.
+ *
+ * @returns The message to send, serialized.
+ */
+export function decisionMessage(approvalId, approved, note) {
+    return JSON.stringify({
+        type: 'tool_approval_decision',
+        approvalId,
+        approved,
+        ...(note ? { note } : {}),
+    });
+}
+/**
+ * What a decision came to, read from the snapshots: nothing while the
+ * approval is still listed pending; the sentence (done, as the route's 200
+ * would say it) once it is no longer; *answered elsewhere* when it was not
+ * pending when the decision was asked.
+ *
+ * @param pendingWhenAsked - Whether the approval was pending when asked.
+ * @param pendingNow - The approvals pending in the latest snapshot.
+ * @param approvalId - The approval decided.
+ * @param approved - Whether approval was asked.
+ * @param action - The action in words, for the sentence.
+ *
+ * @returns The sentence, or null while nothing says yet.
+ */
+export function decisionSettled(pendingWhenAsked, pendingNow, approvalId, approved, action) {
+    if (!pendingWhenAsked) {
+        return ATTENTION_WORDS.answeredElsewhere;
+    }
+    if (pendingNow.some(approval => approval.id === approvalId)) {
+        return null;
+    }
+    return decisionOutcome(200, approved, action);
+}

package/lib/portable/localRuntime.d.ts

@@ -0,0 +1,365 @@
+/**
+ * A local runtime on a person's machine, and the harness it runs (VSCODE
+ * VS-02, VS-03; DESKTOP DK-05, DK-06, DK-25): the pure part every host
+ * shares — the VS Code extension host and Datalayer Desktop's main process
+ * alike import it as `@datalayer/agent-runtimes/lib/portable/localRuntime`.
+ *
+ * - **Finding `loop`.** No host bundles Python or Agent Runtimes: `loop` is a
+ *   prerequisite, found where the person installed it (a path the host's
+ *   settings name, else `PATH`, then `uv tool`'s and `pipx`'s bins), checked
+ *   to be at least {@link LOOP_MIN_VERSION}, and refused in a sentence naming
+ *   the install line when it is absent, too old or does not answer.
+ * - **Starting it.** A local runtime is `loop serve --host 127.0.0.1 --port 0`
+ *   for one folder, its port read from the first line that names it. The
+ *   process is given a trimmed environment plus the credentials the
+ *   harnesses declare by name (the environment first, the host's secret
+ *   store second), the folder as the harness's workspace, the file session
+ *   store, and the person's token and IAM when signed in.
+ * - **The harness on the machine.** Before a coding agent starts in a folder,
+ *   what `agent-shield setup --harness <id>` checks is checked here: the
+ *   binaries the register names, the pinned adapter in the Shield's prefix,
+ *   the credential the harness declares — each missing part a sentence, and
+ *   `setup` offered for the part it fixes. A harness whose terms refuse the
+ *   person's credential is refused in the register's words.
+ *
+ * The sentences name the host through {@link LocalRuntimeHost}: what the
+ * host is called, how a path to `loop` is set by hand, where a credential is
+ * kept and how it is given. Pure: no host API, no child process, no file
+ * system — the host does the I/O.
+ *
+ * @module portable/localRuntime
+ */
+/** The oldest Agent Runtimes whose `loop` a host starts: the release that keeps the folder's instructions file, serves `GET /api/v1/harnesses` and binds the Shield's subject right. */
+export declare const LOOP_MIN_VERSION = "1.5.70";
+/** The one line that installs `loop` with the Shield. */
+export declare const INSTALL_LINE = "uv tool install 'agent-runtimes[shield]'";
+/** How a local runtime is started: loopback, a free port picked by the server. */
+export declare const LOOP_SERVE_ARGUMENTS: readonly string[];
+/** The variables of the person's shell a local runtime is given, and nothing else of it. */
+export declare const TRIMMED_VARIABLES: readonly string[];
+/**
+ * How a host is named in the sentences: the words differ between an editor
+ * extension and a desktop application, the rules do not.
+ */
+export interface LocalRuntimeHost {
+    /** *this extension*, *Datalayer Desktop*: the subject of *needs 1.5.70 or later*. */
+    name: string;
+    /** How a path to `loop` is set by hand: *set datalayer.local.loopPath to where it is*. */
+    loopPathHint: string;
+    /** Where a credential given to the host is kept: *VS Code's secret storage*, *the app's keychain*. */
+    secretStore: string;
+    /** How a credential is given once: *Datalayer: Set a harness credential*. */
+    credentialCommand: string;
+}
+/** The VS Code extension's words. */
+export declare const VSCODE_HOST: LocalRuntimeHost;
+/** Datalayer Desktop's words. */
+export declare const DESKTOP_HOST: LocalRuntimeHost;
+/** What the host says about itself, for the candidate paths. */
+export interface DetectHost {
+    /** `process.platform`. */
+    platform: string;
+    /** The person's home folder. */
+    home: string;
+    /** The `PATH` variable, or nothing. */
+    pathVariable: string | undefined;
+    /** The path the host's settings name, empty when unset. */
+    configured: string;
+}
+/**
+ * Where `loop` may be, in the order it is looked for: the configured path,
+ * each `PATH` entry, then `uv tool`'s and `pipx`'s bins under the home.
+ *
+ * @param host - The host's platform, home, `PATH` and configured path.
+ *
+ * @returns Candidate paths, the first that exists being `loop`.
+ */
+export declare function candidateLoopPaths(host: DetectHost): string[];
+/**
+ * The version `loop --version` printed (`Agent Runtimes Chat v1.5.70`,
+ * `agent_runtimes: 1.5.70`, colours stripped), or null when none is in it.
+ *
+ * @param output - What the command wrote, stdout and stderr together.
+ *
+ * @returns The first `major.minor.patch` found, or null.
+ */
+export declare function versionOf(output: string): string | null;
+/**
+ * Orders two `major.minor.patch` versions.
+ *
+ * @param a - One version.
+ * @param b - The other.
+ *
+ * @returns Negative when `a` is older, zero when equal, positive when newer.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** What was found on the machine, before it is judged. */
+export interface LoopFound {
+    /** The path that exists. */
+    path: string;
+    /** What `loop --version` wrote, or null when it could not be run. */
+    versionOutput: string | null;
+    /** Why it could not be run, when it could not. */
+    failure?: string;
+}
+/** Why `loop` is not started. */
+export type LoopRefusalReason = 'absent' | 'too-old' | 'unanswered' | 'disabled';
+/** `loop` found and good, or the sentence that refuses it. */
+export type LoopDetection = {
+    ok: true;
+    path: string;
+    version: string;
+} | {
+    ok: false;
+    reason: LoopRefusalReason;
+    sentence: string;
+};
+/**
+ * Judges what was found: present, answering and at least the minimum.
+ *
+ * @param found - The first candidate that exists, with its version output; null when none does.
+ * @param host - The host's words.
+ * @param minimum - The oldest version accepted.
+ *
+ * @returns The path and version, or the refusal naming the install line.
+ */
+export declare function loopDetection(found: LoopFound | null, host: LocalRuntimeHost, minimum?: string): LoopDetection;
+/**
+ * The port a `loop serve` line names: `Auto-selected free port 41231`,
+ * `Uvicorn running on http://127.0.0.1:41231`, `API docs available at http://127.0.0.1:41231/docs`.
+ *
+ * @param line - One line of the process's output.
+ *
+ * @returns The port, or null when the line names none.
+ */
+export declare function portOf(line: string): number | null;
+/**
+ * The origins a host's content-security policy admits for one local
+ * runtime, and nothing else on loopback (DESKTOP DK-05).
+ *
+ * @param port - The runtime's port.
+ *
+ * @returns `http://127.0.0.1:<port>` and `ws://127.0.0.1:<port>`.
+ */
+export declare function loopbackSourcesOf(port: number): string[];
+/** What the environment of a local runtime is built from. */
+export interface RuntimeEnvironmentInput {
+    /** The host's environment (`process.env`). */
+    host: Record<string, string | undefined>;
+    /** The folder: the harness's workspace. */
+    folder: string;
+    /** The credential names the harnesses declare (`requires.secrets`). */
+    declared: readonly string[];
+    /** What the host's secret store holds for those names. */
+    secrets: Record<string, string | undefined>;
+    /** The person's token and IAM, when signed in. */
+    signedIn?: {
+        token: string;
+        iamUrl: string;
+    };
+    /** `AGENT_RUNTIMES_SESSIONS_PATH`, when the person set one; else the runtime's default. */
+    sessionsPath?: string;
+}
+/** Where each declared credential came from, said to the person (VSCODE O-1, DESKTOP O-2). */
+export type CredentialSource = 'environment' | 'secrets';
+/** The environment a local runtime is started with, and where its credentials came from. */
+export interface RuntimeEnvironment {
+    environment: Record<string, string>;
+    credentials: Record<string, CredentialSource>;
+}
+/**
+ * The environment of a local runtime: the trimmed set of the person's
+ * shell, the declared credentials by name (the environment first, the
+ * secret store second — nothing undeclared), the folder as the workspace,
+ * the file session store (META_HARNESS decision K: without it a signed-in
+ * runtime would pick the record), and the person's token and IAM when
+ * signed in.
+ *
+ * @param input - The host's environment, the folder, the declared names, the secrets, the sign-in.
+ *
+ * @returns The environment and the source of each credential handed.
+ */
+export declare function runtimeEnvironment(input: RuntimeEnvironmentInput): RuntimeEnvironment;
+/** A local runtime as a chat lists it beside Datalayer's runtimes: a place of its own. */
+export interface LocalRuntimeHandle {
+    /** `local:<folder path>`: unique per folder. */
+    runtimeName: string;
+    /** `http://127.0.0.1:<port>`. */
+    ingress: string;
+    /** Nothing: no token is lent to loopback. */
+    token: string;
+    /** *This machine — <folder name>*. */
+    givenName: string;
+    /** `local`. */
+    environmentName: string;
+    /** The place, for the picker. */
+    place: 'local';
+}
+/**
+ * The handle a chat's picker shows for a running local runtime.
+ *
+ * @param folderName - The folder's name.
+ * @param folderPath - Its path.
+ * @param url - The runtime's address.
+ *
+ * @returns The handle, with no token.
+ */
+export declare function localRuntimeHandle(folderName: string, folderPath: string, url: string): LocalRuntimeHandle;
+/** One harness of the catalogue, as the check reads it. */
+export interface HarnessFacts {
+    /** `claude-code`, `codex`, … */
+    id: string;
+    /** *Claude Code*. */
+    name: string;
+    /** The adapter pinned (`@agentclientprotocol/claude-agent-acp`). */
+    adapter: string;
+    /** Its version (`0.91.0`). */
+    adapterVersion: string;
+    /** The credential it takes, the register's words. */
+    credential: string;
+    /** The credential names it declares (`ANTHROPIC_API_KEY`). */
+    secrets: string[];
+    /** The executables it needs on the path (`node`, `git`). */
+    binaries: string[];
+    /** The register's line on binaries (*Node 22 (engines.node >=22 on npm), git*). */
+    registeredBinaries: string;
+    /** `api_key_only`, `permitted`, `organizations_own`. */
+    servedToThirdParties: string;
+    /** The licence, the register's words. */
+    licence: string;
+    /** Tier restrictions, or empty. */
+    tierRestrictions: string;
+    /** The capabilities table (MH-20). */
+    capabilities: {
+        resume: string;
+        forkHistory: string;
+        interrupt: boolean;
+        steering: boolean;
+        images: boolean;
+        compaction: string;
+    };
+    /** How it is launched: the executable. */
+    command: string;
+    /** The executable's arguments. */
+    args: string[];
+    /** Whether its ACP adapter loads a session again. */
+    loadSession: boolean;
+    /** The modes it offers. */
+    modes: string[];
+}
+/**
+ * The catalogue as `GET /api/v1/harnesses` answers it (`{harnesses: [...]}`,
+ * each the harness spec whole).
+ *
+ * @param body - The route's answer.
+ *
+ * @returns The harnesses, in the route's order.
+ *
+ * @throws Error when the answer is not a list of harnesses.
+ */
+export declare function harnessesOf(body: unknown): HarnessFacts[];
+/**
+ * The credential names a register line names: *An Anthropic API key
+ * (ANTHROPIC_API_KEY), the person's own* → `["ANTHROPIC_API_KEY"]`.
+ *
+ * @param credential - The register's credential line.
+ *
+ * @returns The upper-case names in it, in order, once each.
+ */
+export declare function credentialNamesOf(credential: string): string[];
+/**
+ * The Node major the register asks for (*Node 22 (engines.node >=22 on npm), git*).
+ *
+ * @param registeredBinaries - The register's binaries line.
+ *
+ * @returns The major, or null when the line names no Node version.
+ */
+export declare function requiredNodeMajor(registeredBinaries: string): number | null;
+/**
+ * The major of a `node --version` answer (`v22.11.0` → 22).
+ *
+ * @param output - What `node --version` printed.
+ *
+ * @returns The major, or null when none is in it.
+ */
+export declare function nodeMajorOf(output: string): number | null;
+/**
+ * Where `agent-shield setup` pins an adapter: `~/.agent-shield/harnesses/<id>@<version>`.
+ *
+ * @param home - The person's home folder.
+ * @param facts - The harness.
+ *
+ * @returns The prefix path.
+ */
+export declare function shieldPrefixOf(home: string, facts: HarnessFacts): string;
+/**
+ * The command that installs what a harness needs, shown whole before it runs.
+ *
+ * @param id - The harness.
+ *
+ * @returns `agent-shield setup --harness <id>`.
+ */
+export declare function setupCommandOf(id: string): string;
+/** What the machine has, read by the host, judged here. */
+export interface HarnessMachine {
+    /** Each binary the harness needs: what `<binary> --version` printed, or null when it is absent. */
+    binaries: Record<string, string | null>;
+    /** The person's environment. */
+    environment: Record<string, string | undefined>;
+    /** What the host's secret store holds. */
+    secrets: Record<string, string | undefined>;
+    /** Whether the pinned adapter is in the Shield's prefix. */
+    adapterInstalled: boolean;
+    /** Whether a subscription login of the vendor's is what the machine has (no API key). */
+    subscriptionLogin: boolean;
+}
+/** One part of the check that is not met. */
+export interface HarnessCheckPart {
+    part: 'binary' | 'node' | 'adapter' | 'credential' | 'terms';
+    sentence: string;
+    /** Whether `agent-shield setup` fixes it. */
+    setup: boolean;
+    /** Whether it stops the start. */
+    blocking: boolean;
+}
+/** The check's verdict. */
+export interface HarnessCheck {
+    ok: boolean;
+    parts: HarnessCheckPart[];
+    /** Where the credential was found, when it was. */
+    credentialSource: CredentialSource | null;
+    setupCommand: string;
+}
+/**
+ * The register's sentence when the harness's terms refuse what the person has.
+ *
+ * @param facts - The harness.
+ * @param machine - What the machine has.
+ * @param host - The host's words.
+ *
+ * @returns The sentence, or null when the terms admit the person's credential.
+ */
+export declare function termsRefusal(facts: HarnessFacts, machine: Pick<HarnessMachine, 'subscriptionLogin'>, host: LocalRuntimeHost): string | null;
+/**
+ * Checks a harness against the machine: binaries and Node's version, the
+ * adapter in the Shield's prefix, the credential, the terms.
+ *
+ * @param facts - The harness.
+ * @param machine - What the machine has.
+ * @param host - The host's words.
+ *
+ * @returns The verdict, each unmet part a sentence.
+ */
+export declare function harnessCheck(facts: HarnessFacts, machine: HarnessMachine, host: LocalRuntimeHost): HarnessCheck;
+/**
+ * The sentence that says where a credential came from (VSCODE O-1, DESKTOP O-2).
+ *
+ * @param name - The credential's name.
+ * @param source - Where it was found.
+ * @param host - The host's words.
+ *
+ * @returns The sentence.
+ */
+export declare function credentialSourceSaid(name: string, source: CredentialSource, host: LocalRuntimeHost): string;
+/** The key under which a credential is kept in a host's secret store. */
+export declare function credentialSecretKey(name: string): string;