dsh-a2a-server 0.2.0 → 0.4.0

package/cordis.patch.yml

@@ -7,12 +7,15 @@
 # REQUIRES ctx.webServer, which ships in `dsh-web-app`, NOT in `dsh-base`. On a
 # profile without it this row loads but stays PENDING (Cordis holds a plugin
 # whose injected services are absent), so nothing serves and nothing errors.
+#
+# NOTE: keep this file plain YAML — the installer's package validation parses
+# it with a strict loader that rejects `!!js` expressions, even though the
+# runtime overlay loader accepts them.
 - insert:
     - id: a2a-server
       name: dsh-a2a-server
       config:
         basePath: /a2a
-        protocolVersion: '0.3.0'
         card:
           name: dsh-harness
           description: A DeepSeek Harness agent reachable over A2A.
@@ -20,11 +23,12 @@
           skills: []
         peers: {}
         isolation:
-          # Default posture is isolation: each peer gets its own working
-          # directory, which also makes the cwd-equality authority in
-          # cross-session tooling separate peers for free. A deployment whose
-          # peers collaborate on one repository must say so explicitly.
+          # Each peer gets its own working directory. This is not a filesystem
+          # sandbox: read_file separately restricts reads to the selected root,
+          # or to a peerWorkspaces override. Other visitor tools are disabled.
+          # This placeholder is overridden by any real deployment layer (the
+          # console's overlay sets it per agent); supply an absolute path.
           workspaceMode: per-peer
-          workspaceRoot: !!js `${process.env.DSH_HOME ?? process.env.HOME}/a2a-workspaces`
+          workspaceRoot: /srv/dsh/a2a
         push:
           enabled: false

package/docker/Dockerfile

@@ -0,0 +1,5 @@
+FROM node:22-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends python3 \
+    && rm -rf /var/lib/apt/lists/*
+USER 1000:1000
+WORKDIR /work

package/docs/visitor-isolation.en.md

@@ -0,0 +1,51 @@
+# Per-visitor sandboxes (0.4.0)
+
+Portal defaults to local Microsandbox 0.7.11 microVMs. DSH remains the trusted orchestrator for authentication, model requests and conversation storage. Only read_file is exposed to visitors today; Python, shell and write tools are not automatically enabled. Real Python tests verify private read/write capability for future tool integrations.
+
+## Automatic preparation
+
+Click Start in Portal. It checks/upgrades the plugin, downloads a pinned SDK and a digest-pinned Python image, and reports progress. Components are cached in the user directory; no manual Microsandbox or Docker installation is needed. Plain chat creates no visitor VM. The first tool call creates one; later calls reuse it.
+
+Supported targets are Windows x64/ARM64 with WHP, Linux x64/ARM64 with KVM, and Apple Silicon macOS with ARM64 Node.js. Node.js 22+ is required. Only Windows x64 has been tested locally; macOS and Linux still need acceptance testing. Intel Macs are unsupported.
+
+Enabling Windows Hypervisor Platform may require a user action and restart. Linux requires access to /dev/kvm. Administrator privileges, firmware settings and OS restarts cannot be silently arranged. Preparation failures are visible and retryable; tools never fall back to host execution.
+
+Portal installs dsh-a2a-server@^0.4.0 from npm. For local development, build the dsh-a2a checkout with pnpm install and pnpm build, then set A2A_PLUGIN_SOURCE to its absolute path in the terminal launching Portal. The npm release does not need this override. Standalone configurations select isolation.execution: microsandbox. Existing configs without that field retain read-only mode, which has no VM boundary. The docker backend remains available for compatibility.
+
+## File boundaries and persistence
+
+| Data | Inside the VM | Local persistence |
+| --- | --- | --- |
+| Selected public data | /source, read-only copy | Original host directory is never mounted |
+| Current visitor files | /work, read/write | Exclusive persistent virtual disk |
+| Other visitors | Not mounted | Separate disks |
+| Sessions, protocol state, credentials | Not mounted | Trusted backend storage |
+
+Public data includes .hop/handoff.md. Before each tool call it is validated and copied; changes stop that visitor VM before replacing its public projection, then restart with the same private disk. Trees are capped at 512 MiB and 100000 entries, so large datasets increase tool latency. Microsandbox public projections exclude entries named node_modules at any depth, case-insensitively, including dependency links. Their contents are never traversed; the original project's dependencies are neither moved nor deleted. Other symlinks, junctions, hard links, special files and nested filesystems remain rejected. Private workspace imports and Docker raw mounts do not use this exclusion and still reject all links.
+
+Portal stores VM mappings at ~/.a2a/workspaces/<agent>/.microsandbox/<peer>/record.json and read-only public projections beside them. Existing <peer>/ files are imported on first boot and retained as migration sources. New /work files persist in the virtual disk; they are **not synchronized back to the old host folder**. A generated-file download/export interface has not been added.
+
+The SDK, native state and VM disks live under ~/.a2a/sandbox-runtime, overridable with A2A_SANDBOX_HOME before startup. Back up both the private mapping directory and runtime state. Do not delete either or run destroy/remove on user VMs; those actions delete disks. Removing a peer credential does not automatically delete its files.
+
+Identity is agent + authenticated peer, not conversation or message. Multiple contexts for one peer share a VM and private files. People sharing a token share this identity; issue independent credentials.
+
+## Lifecycle and quotas
+
+After the last tool finishes, 30 idle seconds pause the VM; 10 idle minutes stop it. Pausing retains memory. Stopping releases runtime resources and keeps disks. New tool calls resume a paused VM or restart a stopped VM with its original disk. Active or queued work prevents idle transitions, and calls for one visitor are serialized.
+
+Each backend allows four resident VMs including paused ones. At capacity, the oldest idle VM stops early; if every VM is busy, new tool work is rejected. Normal backend shutdown stops its VMs. A new controller reclaims recorded instances abandoned by a previous controller, without destroying disks. Abrupt power loss or forced termination can still lose unflushed writes.
+
+VMs have one CPU, 512 MiB RAM, a 256 MiB root disk and 512 MiB private disk. Networking is disabled. Tools run as UID 1000 with a 30-second execution timeout and 256 KB output cap. The public projection is read-only/noexec/nosuid/nodev; private disks are nosuid/nodev. The host user, hypervisor and pinned image remain trusted; this is not an absolute defense against virtualization vulnerabilities.
+
+read_file defaults to public data; root: workspace selects the current visitor's disk. Text reads remain bounded to UTF-8 files up to 2 MiB, 32000 returned characters and 500 lines/entries per call. Backend conversation records are not tool-readable.
+
+## Migration and verification
+
+Stop the old agent and start with the new Portal. It copies current visitors' legacy directories outside public data, verifies the copy and removes the old source. Conflicting destinations are never overwritten. First VM boot imports that visitor's private files and refuses conflicting content. Archive private leftovers for removed visitors outside public data manually.
+
+Automatic public briefings still update .hop/handoff.md and appear in Portal. Trusted owner maintenance runs on the host, outside the visitor sandbox.
+
+Run pnpm typecheck, pnpm test, pnpm test:package and pnpm test:microsandbox. The last command automatically prepares real microVMs and synthetic files to exercise public mutation denial, private CRUD, peer separation, link attacks, network/credential isolation, cancellation, lifecycle, persistence and abandoned-instance recovery.
+
+Set A2A_MSB_WALLCLOCK=1 for a full ten-minute wall-clock lifecycle test. Otherwise controlled time triggers actual native VM transitions. A2A_MSB_TEST_RUNTIME optionally reuses a test runtime cache. Legacy Docker validation remains pnpm test:docker and requires a local Linux Docker engine plus the image built from docker/Dockerfile.
+

package/docs/visitor-isolation.md

@@ -0,0 +1,75 @@
+# 访客独立沙箱（0.4.0）
+
+Portal 默认使用 Microsandbox 0.7.11，本机运行微型虚拟机。DSH 后端负责认证、模型调用和聊天记录；工具运行在访客沙箱中。当前模型仍只开放 `read_file`，没有自动开放 Python、Shell 或写入工具。私有目录读写能力已经由真实 Python 测试验证，可供以后受控开放的工具使用。
+
+## 启动体验
+
+点击 Portal「启动」即可自动检查/更新插件、下载固定版本的沙箱组件和固定摘要的 Python 镜像，页面显示进度。组件安装到用户目录并缓存，不需要手动安装 Microsandbox 或 Docker。纯聊天不创建访客 VM；首次工具调用才创建，后续调用复用。
+
+支持的宿主环境：Windows x64/ARM64 + WHP、Linux x64/ARM64 + KVM、Apple Silicon macOS + ARM64 Node.js；Node.js 22 以上。当前只在 Windows x64 实测，其他平台需要单独验收。Intel Mac 暂不支持。
+
+Windows 未启用“Windows 虚拟机监控程序平台”时，需要用户启用系统功能并重启。Linux 需要 /dev/kvm 访问权限。管理员权限、BIOS 设置和系统重启无法静默代办。准备失败会显示原因，重试复用已下载内容，绝不退回宿主机执行工具。
+
+Portal 使用 npm 插件 `dsh-a2a-server@^0.4.0`。仅在测试本地源码时：
+
+```powershell
+# D:\code\dsh-a2a
+pnpm install
+pnpm build
+# 在启动 Portal 的同一个终端里指定源码包位置
+$env:A2A_PLUGIN_SOURCE='D:\code\dsh-a2a'
+# 然后启动 Talk2MyAgent Portal
+```
+
+使用 npm 版本无需设置这个开发变量。独立 DSH 配置使用 `isolation.execution: microsandbox`；旧配置未填写时仍是 `read-only`，仅有受限读取器，没有 VM 边界。`docker` 作为兼容选项保留。
+
+## 目录与持久化
+
+| 内容 | 沙箱可见范围 | 本地保存 |
+| --- | --- | --- |
+| 用户指定公共资料 | /source，只读副本 | 原始目录不挂入 VM；包括公开简报 .hop/handoff.md |
+| 当前访客的文件 | /work，可增加、修改、重命名、删除 | 每个访客独享持久化虚拟磁盘 |
+| 其他访客的文件 | 不挂载 | 各自独立磁盘 |
+| 聊天记录、协议状态、凭据 | 不挂载 | 可信 DSH 后端独立保存 |
+
+Portal 的私有根在 `~/.a2a/workspaces/<agent>`。其 `.microsandbox/<peer>/record.json` 保存访客到 VM 的稳定映射，`public/` 保存公共资料副本；原有 `<peer>/` 文件作为首次导入源保留。以后 /work 中的新文件保存在虚拟磁盘中，**不会同步回旧的宿主机普通文件夹**。
+
+运行组件与所有 VM 磁盘默认保存在 `~/.a2a/sandbox-runtime`；可在启动前通过 `A2A_SANDBOX_HOME` 指定。备份需同时包含私有根的映射和 runtime 的 state 目录。不要清除这些目录，或对用户 VM 执行 destroy/remove；这些操作会删除磁盘。用户生成文件的独立下载/导出入口尚未增加。
+
+公共资料会在工具调用前验证并复制；内容更新时停止该访客旧 VM、更新只读副本，然后以原私有磁盘启动。复制最多 512 MiB、100000 项，大目录会增加调用耗时。Microsandbox 的公共资料副本自动排除各层级的 `node_modules`（不区分大小写），包括同名依赖链接；不会遍历其内容，也不会移动或删除原项目的依赖。其他硬链接、符号链接/junction、特殊文件和嵌套文件系统仍被拒绝，避免通过别名访问宿主机其他资料。私有工作区导入和 Docker 原目录挂载不使用此排除规则，仍拒绝所有链接。
+
+隔离单位是 **agent + 已认证 peer**，不是每轮消息或 contextId。不同聊天共享同一 peer 的文件；多人共用访客令牌也会共用沙箱。每人应分配独立凭据。删除凭据不会自动删除旧文件。
+
+## 生命周期
+
+- 第一次调用工具：创建该访客 VM；聊天本身不创建。
+- 工具完成后空闲 30 秒：暂停，保留进程和内存；暂停不释放主要内存。
+- 自最后一次工具完成空闲 10 分钟：停止 VM，释放运行资源；磁盘与文件保留。
+- 暂停期间来新工具请求：恢复原 VM；停止后再来：用原磁盘重新启动。
+- 有工具执行或排队时不暂停；同一访客工具串行，不同访客各用自己的 VM。
+- 每个后端最多 4 个驻留 VM（包括暂停的）；满额先停止最久未使用的空闲 VM。都忙时拒绝新增工具，已有文件不丢失。
+- 正常关闭后端会停止其 VM；控制进程意外退出后，下次启动回收其记录的遗留实例。不会销毁用户磁盘。机器断电/强杀与普通磁盘一样可能丢失未落盘写入。
+
+每个 VM 为 1 CPU、512 MiB 内存、256 MiB 根磁盘、512 MiB 私有工作盘，无网络，工具以 UID 1000 运行，单次执行限时 30 秒、输出 256 KB。公共副本只读且 noexec/nosuid/nodev；私有盘 nosuid/nodev。宿主用户、虚拟化实现与受信镜像仍属于可信边界，这不是对虚拟化漏洞的绝对保证。
+
+`read_file({"path":"info.txt"})` 读公共资料；`read_file({"root":"workspace","path":"."})` 读自己的工作区。文件限 UTF-8 文本、2 MiB、单次 32000 字符与 500 行/项。后端聊天记录不作为可读工具目录。
+
+## 旧数据迁移
+
+停止旧 agent，再用新版 Portal 启动。Portal 把公共目录中的当前访客旧目录复制到独立私有根，校验后移除旧目录；目标已存在则拒绝覆盖。首次 VM 启动再导入自己的私有文件，冲突拒绝覆盖。已删除访客留下的历史私有文件需要主人移出公共资料目录。
+
+公开简报继续默认定时更新到 .hop/handoff.md 并显示在 Portal。主人简报任务是可信后端任务，仍在宿主机执行，不属于访客沙箱。
+
+## 测试
+
+```sh
+pnpm typecheck
+pnpm test
+pnpm test:package
+pnpm test:microsandbox
+```
+
+最后一项会自动准备真实 Microsandbox，使用合成文件测试只读公共资料、私有 CRUD、跨访客隔离、链接攻击、网络/凭据隔离、取消、暂停/恢复/停止、重启和遗留实例回收。不会读取真实用户资料。
+
+设置 `A2A_MSB_WALLCLOCK=1` 再运行，可执行完整 10 分钟真实计时测试；否则通过可控时钟触发真实 VM 的生命周期转换。`A2A_MSB_TEST_RUNTIME` 可复用一个测试 runtime 缓存。Docker 兼容验证仍用 `pnpm test:docker`（需本地 Linux Docker 和 docker/Dockerfile 构建的镜像）。
+

package/lib/briefing.d.ts

@@ -0,0 +1,39 @@
+export declare const BRIEFING_INTERVAL_MS: number;
+interface LegacyBriefingScheduler {
+    catalog(): Promise<Array<{
+        id: string;
+        sessionId: string;
+        title: string;
+        prompt: string;
+    }>>;
+    delete(request: {
+        id: string;
+        sessionId: string;
+    }): Promise<unknown>;
+}
+/** Retire only the old Portal-generated job for this exact project. */
+export declare function retireLegacyBriefing(scheduler: LegacyBriefingScheduler | undefined, root: string): Promise<void>;
+export declare class AutomaticBriefing {
+    private readonly options;
+    private timer;
+    private closed;
+    private running;
+    private enabled;
+    private nextRunAt;
+    private readonly stateFile;
+    constructor(options: {
+        settingsFile: string;
+        stateDirectory: string;
+        run: () => Promise<void>;
+        warn: (message: string) => void;
+        now?: () => number;
+    });
+    private save;
+    private readEnabled;
+    /** Polling also observes an off/on switch without restarting the agent. */
+    tick(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export {};
+//# sourceMappingURL=briefing.d.ts.map

package/lib/briefing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefing.d.ts","sourceRoot":"","sources":["../src/briefing.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,oBAAoB,QAAiB,CAAA;AAGlD,UAAU,uBAAuB;IAC/B,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAC3F,MAAM,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACrE;AAED,uEAAuE;AACvE,wBAAsB,oBAAoB,CAAC,SAAS,EAAE,uBAAuB,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtH;AAED,qBAAa,iBAAiB;IAQhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,KAAK,CAA4C;IACzD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,SAAS,CAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;gBAEL,OAAO,EAAE;QACpC,YAAY,EAAE,MAAM,CAAA;QACpB,cAAc,EAAE,MAAM,CAAA;QACtB,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;QACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;QAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KACnB;IAWD,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,WAAW;IAWnB,2EAA2E;IACrE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,KAAK,IAAI,IAAI;IAOb,IAAI,IAAI,IAAI;CAIb"}

package/lib/briefing.js

@@ -0,0 +1,108 @@
+/** One automatic briefing loop owned by the online agent, independent of Portal. */
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const BRIEFING_INTERVAL_MS = 60 * 60 * 1000;
+const CHECK_INTERVAL_MS = 5000;
+/** Retire only the old Portal-generated job for this exact project. */
+export async function retireLegacyBriefing(scheduler, root) {
+    if (!scheduler?.catalog || !scheduler.delete)
+        return;
+    const prefix = `【简报维护任务】受信任的项目范围只有一个：\n  ${root}\n`;
+    for (const task of await scheduler.catalog()) {
+        if (task.title === '简报维护' && task.prompt.startsWith(prefix)
+            && (task.prompt.includes('4. 把简报写入当前工作目录的 handoff.draft.md')
+                || task.prompt.includes('4. 完整生成并检查上述内容后，直接覆盖写入当前工作目录的 handoff.md。'))) {
+            await scheduler.delete({ id: task.id, sessionId: task.sessionId });
+        }
+    }
+}
+export class AutomaticBriefing {
+    options;
+    timer;
+    closed = false;
+    running = false;
+    enabled = true;
+    nextRunAt = 0;
+    stateFile;
+    constructor(options) {
+        this.options = options;
+        mkdirSync(options.stateDirectory, { recursive: true, mode: 0o700 });
+        this.stateFile = join(options.stateDirectory, 'briefing-state.json');
+        try {
+            const state = JSON.parse(readFileSync(this.stateFile, 'utf8'));
+            if (typeof state.enabled !== 'boolean' || !Number.isSafeInteger(state.nextRunAt) || state.nextRunAt < 0)
+                throw new Error('invalid briefing state');
+            this.enabled = state.enabled;
+            this.nextRunAt = state.nextRunAt;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    save() {
+        const temporary = `${this.stateFile}.tmp`;
+        try {
+            writeFileSync(temporary, JSON.stringify({ enabled: this.enabled, nextRunAt: this.nextRunAt }), { mode: 0o600 });
+            renameSync(temporary, this.stateFile);
+        }
+        finally {
+            rmSync(temporary, { force: true });
+        }
+    }
+    readEnabled() {
+        try {
+            const value = JSON.parse(readFileSync(this.options.settingsFile, 'utf8'));
+            if (typeof value.enabled !== 'boolean')
+                throw new Error('invalid automatic briefing setting');
+            return value.enabled;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return true;
+            throw error;
+        }
+    }
+    /** Polling also observes an off/on switch without restarting the agent. */
+    async tick() {
+        if (this.closed)
+            return;
+        try {
+            const enabled = this.readEnabled();
+            const now = this.options.now?.() ?? Date.now();
+            if (enabled !== this.enabled) {
+                this.enabled = enabled;
+                if (enabled)
+                    this.nextRunAt = now;
+                this.save();
+            }
+            if (!enabled || this.running || now < this.nextRunAt)
+                return;
+            // Persist before paid work: restarting must not immediately repeat a run.
+            this.nextRunAt = now + BRIEFING_INTERVAL_MS;
+            this.save();
+            this.running = true;
+            try {
+                await this.options.run();
+            }
+            finally {
+                this.running = false;
+            }
+        }
+        catch (error) {
+            this.options.warn(`a2a: automatic briefing failed: ${String(error)}`);
+        }
+    }
+    start() {
+        if (this.closed || this.timer)
+            return;
+        this.timer = setInterval(() => { void this.tick(); }, CHECK_INTERVAL_MS);
+        this.timer.unref();
+        void this.tick();
+    }
+    stop() {
+        this.closed = true;
+        clearInterval(this.timer);
+    }
+}
+//# sourceMappingURL=briefing.js.map

package/lib/briefing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefing.js","sourceRoot":"","sources":["../src/briefing.ts"],"names":[],"mappings":"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"}

package/lib/config.d.ts

@@ -15,27 +15,21 @@ export interface PeerConfig {
     /** Credential reference name, NOT the token itself. */
     tokenEnv: string;
 }
-/**
- * How peers are kept from reaching each other.
- *
- * DEFERRED — a tool deny-list (`session_search`, `session_event_search`,
- * `session_trace`, `session_event_trace`, `session_event_read`, `list_agents`)
- * plus a named `unsafeAllowCrossSessionSearch` escape hatch for single-peer
- * deployments. Both were designed as defense in depth behind `workspaceMode`,
- * and neither is declared here until it is enforced: a security knob that
- * silently does nothing is worse than no knob at all.
- */
+/** Working directories and the data roots exposed through the scoped reader. */
 export interface IsolationConfig {
     /**
-     * `per-peer` gives each identity its own cwd, which also makes the existing
-     * cwd-equality authority in cross-session tooling isolate them for free.
-     * `shared` is the collaborative posture and must be chosen deliberately.
+     * Legacy field retained for checkpoint migration. Every visitor now has a
+     * private cwd outside public data, including old `shared` configurations.
      */
     workspaceMode: 'per-peer' | 'shared';
-    /** Parent directory in `per-peer` mode; the common cwd in `shared` mode. */
+    /** Shared public data. Never the parent of new visitor workspaces. */
     workspaceRoot: string;
-    /** Per-peer cwd overrides, e.g. pointing one trusted peer at a real repo. */
+    /** Legacy per-peer public-data overrides; no longer control runtime cwd. */
     peerWorkspaces: Record<string, string>;
+    /** Private runtime parent, disjoint from all public-data directories. */
+    privateRoot?: string;
+    /** Native mode only permits the bounded reader; isolated runtimes never fall back. */
+    execution?: 'read-only' | 'docker' | 'microsandbox';
 }
 /** One declared skill, as it appears on the Agent Card. */
 export interface SkillConfig {
@@ -82,6 +76,28 @@ export interface PushConfig {
      */
     enabled: boolean;
 }
+/**
+ * The host's background briefing, injected when a visitor's context opens.
+ *
+ * The files are read once per Activation (best effort: an absent file is the
+ * normal "nothing to hand over" case) and merged into the context's FIRST
+ * visitor message rather than sent as their own turn — one model call is
+ * spared, and the turn counters stay about the visitor's messages only.
+ */
+export interface PreambleConfig {
+    /** Publication-safe paths relative to the workspace root; absolute paths pass through. */
+    files: string[];
+}
+/** Local-only monitoring surface credentials. */
+export interface AdminConfig {
+    /**
+     * Credential REFERENCE name holding the admin token, NOT the token itself.
+     * Empty or absent means the monitoring surface stays unmounted.
+     */
+    tokenEnv: string;
+    /** Local named pipe / Unix socket. Never served on the public HTTP carrier. */
+    socketPath?: string;
+}
 /** The whole plugin configuration. */
 export interface A2AServerConfig {
     basePath: string;
@@ -103,7 +119,34 @@ export interface A2AServerConfig {
     blockTimeoutMs: number;
     contextIdleTtlMs: number;
     maxResidentContexts: number;
+    maxConcurrentTasks: number;
+    maxConcurrentTasksPerPeer: number;
+    maxTasksPerPeerPerDay: number;
+    taskTimeoutMs: number;
+    maxModelCallsPerTask: number;
+    maxOutputTokens: number;
+    maxInputChars: number;
+    maxOutputChars: number;
+    streamHeartbeatMs: number;
+    maxStreamsPerTask: number;
+    maxStreamBufferBytes: number;
+    storage: {
+        directory?: string;
+        retentionMs: number;
+        maxContexts: number;
+        maxContextBytes: number;
+    };
     isolation: IsolationConfig;
+    preamble: PreambleConfig;
+    /** Optional Portal-managed automatic updates; omission leaves the transport inert. */
+    briefing?: {
+        settingsFile: string;
+        prompt: string;
+    };
+    /**
+     * Enables owner RPC and monitoring on private local IPC, never public HTTP.
+     */
+    admin?: AdminConfig;
     push: PushConfig;
 }
 export declare const Config: Schema<A2AServerConfig>;

package/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAQ7C,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,aAAa,EAAE,UAAU,GAAG,QAAQ,CAAA;IACpC,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED,2DAA2D;AAC3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAED,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB;;;;;OAKG;IACH,cAAc,EAAE,WAAW,EAAE,CAAA;IAC7B,QAAQ,CAAC,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;CACjD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACjC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,OAAO,GAAG,WAAW,CAAA;IAC/B,cAAc,EAAE,MAAM,CAAA;IACtB,gBAAgB,EAAE,MAAM,CAAA;IACxB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,SAAS,EAAE,eAAe,CAAA;IAC1B,IAAI,EAAE,UAAU,CAAA;CACjB;AAcD,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,eAAe,CAoDzC,CAAA;AAEF,oEAAoE;AACpE,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CA4BlE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/lib/config.js

@@ -10,6 +10,7 @@
  * @module dsh-a2a/config
  */
 import Schema from '@deepseek-ai/schemastery';
+import { isAbsolute } from 'node:path';
 /** A credential reference name: the shape `ctx.credentials` addresses. */
 const CREDENTIAL_REF = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** A peer name: also the workspace directory component, so no separators. */
@@ -20,10 +21,7 @@ const PEER_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
  * - `streamGranularity: 'message' | 'chunk'` — streaming currently emits only
  *   committed assistant messages. The `chunk` mode needs an `assistant/chunk`
  *   subscription and a decision about retried text reaching a peer.
- * - `taskTimeoutMs` — the orphan-task watchdog that would fail a task stuck
- *   non-terminal. Nothing sweeps for those yet.
- *
- * Both were in the design; neither is wired. They return with their code.
+ * This option returns with its implementation.
  */
 export const Config = Schema.object({
     basePath: Schema.string().default('/a2a'),
@@ -57,18 +55,53 @@ export const Config = Schema.object({
     peers: Schema.dict(Schema.object({
         tokenEnv: Schema.string().required(),
     })).default({}),
-    trustedPeers: Schema.array(Schema.string()),
+    // An array schema implicitly defaults to []; the wrapper preserves omission.
+    trustedPeers: Schema.union([Schema.array(Schema.string())]),
     rateLimitPerMinute: Schema.natural().default(60),
     maxContextTurns: Schema.natural().default(5),
     sendMode: Schema.union(['block', 'immediate']).default('block'),
     blockTimeoutMs: Schema.natural().default(60_000),
     contextIdleTtlMs: Schema.natural().default(1_800_000),
     maxResidentContexts: Schema.natural().default(64),
+    maxConcurrentTasks: Schema.natural().default(8),
+    maxConcurrentTasksPerPeer: Schema.natural().default(2),
+    maxTasksPerPeerPerDay: Schema.natural().default(200),
+    taskTimeoutMs: Schema.natural().default(120_000),
+    maxModelCallsPerTask: Schema.natural().default(8),
+    maxOutputTokens: Schema.natural().default(4096),
+    maxInputChars: Schema.natural().default(32_000),
+    maxOutputChars: Schema.natural().default(64_000),
+    streamHeartbeatMs: Schema.natural().default(15_000),
+    maxStreamsPerTask: Schema.natural().default(4),
+    maxStreamBufferBytes: Schema.natural().default(262_144),
+    storage: Schema.object({
+        directory: Schema.string(),
+        retentionMs: Schema.natural().default(86_400_000),
+        maxContexts: Schema.natural().default(256),
+        maxContextBytes: Schema.natural().default(4_000_000),
+    }),
     isolation: Schema.object({
         workspaceMode: Schema.union(['per-peer', 'shared']).default('per-peer'),
         workspaceRoot: Schema.string().required(),
         peerWorkspaces: Schema.dict(Schema.string()).default({}),
+        privateRoot: Schema.string(),
+        execution: Schema.union(['read-only', 'docker', 'microsandbox']).default('read-only'),
     }).required(),
+    preamble: Schema.object({
+        files: Schema.array(Schema.string()).default(['.hop/handoff.md']),
+    }),
+    briefing: Schema.object({
+        settingsFile: Schema.string().default(''),
+        prompt: Schema.string().default(''),
+    }),
+    // Schemastery instantiates a nested object even when the deployment omits
+    // it, so `required()` here would make every admin-less config fail at load.
+    // An empty tokenEnv instead reads as "not configured", and the coherence
+    // check below is what keeps a non-empty one a valid REFERENCE name.
+    admin: Schema.object({
+        tokenEnv: Schema.string().default(''),
+        socketPath: Schema.string(),
+    }),
     push: Schema.object({
         enabled: Schema.boolean().default(false),
     }),
@@ -90,7 +123,35 @@ export class A2AConfigError extends Error {
  * @throws {A2AConfigError} when a peer name, credential reference, or path is unusable.
  */
 export function assertConfigCoherent(config) {
+    if (config.isolation.privateRoot !== undefined && !isAbsolute(config.isolation.privateRoot))
+        throw new A2AConfigError('isolation.privateRoot must be absolute');
+    if (config.briefing?.prompt || config.briefing?.settingsFile) {
+        if (!config.admin?.tokenEnv || !config.briefing.prompt.trim() || !isAbsolute(config.briefing.settingsFile)) {
+            throw new A2AConfigError('automatic briefing requires owner administration, a prompt, and an absolute settingsFile');
+        }
+    }
+    for (const key of ['maxResidentContexts', 'maxConcurrentTasks', 'maxConcurrentTasksPerPeer',
+        'maxTasksPerPeerPerDay', 'taskTimeoutMs', 'maxModelCallsPerTask', 'maxOutputTokens',
+        'maxInputChars', 'maxOutputChars', 'streamHeartbeatMs', 'maxStreamsPerTask',
+        'maxStreamBufferBytes']) {
+        if (!Number.isSafeInteger(config[key]) || config[key] <= 0)
+            throw new A2AConfigError(`${key} must be positive`);
+    }
+    for (const [key, value] of Object.entries(config.storage)) {
+        if (key !== 'directory' && (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0)) {
+            throw new A2AConfigError(`storage.${key} must be positive`);
+        }
+    }
+    if (config.publicUrl !== undefined) {
+        const url = new URL(config.publicUrl);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+            throw new A2AConfigError('publicUrl must be an HTTP(S) RPC URL without credentials, query, or fragment');
+        }
+    }
     for (const [peer, entry] of Object.entries(config.peers)) {
+        if (peer === 'owner') {
+            throw new A2AConfigError('peer name "owner" is reserved for the deployment owner (the local console)');
+        }
         if (!PEER_NAME.test(peer)) {
             throw new A2AConfigError(`peer name "${peer}" must match ${String(PEER_NAME)}: it becomes a workspace directory component`);
         }
@@ -108,6 +169,14 @@ export function assertConfigCoherent(config) {
             throw new A2AConfigError(`isolation.peerWorkspaces names "${peer}", which is not declared in peers`);
         }
     }
+    const adminTokenEnv = config.admin === undefined
+        || typeof config.admin.tokenEnv !== 'string'
+        || config.admin.tokenEnv.length === 0
+        ? undefined
+        : config.admin.tokenEnv;
+    if (adminTokenEnv !== undefined && !CREDENTIAL_REF.test(adminTokenEnv)) {
+        throw new A2AConfigError(`admin.tokenEnv must be a credential REFERENCE name (${String(CREDENTIAL_REF)}), not a token value`);
+    }
     if (!config.basePath.startsWith('/')) {
         throw new A2AConfigError(`basePath must start with "/": ${config.basePath}`);
     }

package/lib/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/lib/contexts.d.ts

@@ -23,8 +23,14 @@ export interface Activation {
     readonly peer: string;
     /** The resolved working directory this context's agent runs in. */
     readonly cwd: string;
-    /** In-flight tasks, keyed by task id. FIFO order comes from the agent inbox. */
+    /** In-flight tasks, keyed by task id. The transport admits one per context. */
     readonly slots: Map<A2ATaskId, TaskSlot>;
+    /**
+     * The host briefing read at activation, merged into this context's FIRST
+     * visitor message and then cleared — a one-shot, so `undefined` means both
+     * "nothing was configured" and "already delivered".
+     */
+    preambleText?: string | undefined;
     /** Last time a request touched this context, for idle eviction. */
     lastTouchedAt: number;
 }
@@ -74,9 +80,8 @@ export declare class ContextRegistry {
      * Select Activations that may be evicted right now.
      *
      * An Activation is evictable only when nothing is owed: no in-flight task and
-     * no recent touch. A context over the resident ceiling is evicted by least
-     * recent touch — but a busy context is NEVER evicted to make room, because
-     * dropping work a peer is waiting on is worse than exceeding a soft ceiling.
+     * no recent touch. Admission separately evicts the oldest quiet activation
+     * BEFORE creating a new agent. A busy context is never evicted for capacity.
      * @returns Activations the caller should dispose and remove.
      */
     evictable(): Activation[];