From e8e779eb3d5f2745206de851390ea3072060f02d Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Thu, 8 Oct 2026 00:39:52 +0000 Subject: [PATCH 01/36] fix(agentlet): compile harness definitions through platform shell Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 18 +- .../packages/local/src/agent-process.ts | 11 +- .../agentlet/packages/local/src/agentlet.ts | 39 ++-- .../packages/local/src/harnesses/catalogue.ts | 173 ----------------- .../packages/local/src/harnesses/claude.ts | 22 +++ .../packages/local/src/harnesses/codebuddy.ts | 9 + .../packages/local/src/harnesses/codex.ts | 22 +++ .../src/harnesses/common/command-discovery.ts | 85 +++++++++ .../src/harnesses/common/compile-command.ts | 10 + .../common/define-command-harness.ts | 34 ++++ .../packages/local/src/harnesses/copilot.ts | 10 + .../packages/local/src/harnesses/cursor.ts | 11 ++ .../packages/local/src/harnesses/custom.ts | 21 +++ .../packages/local/src/harnesses/detect.ts | 34 +++- .../packages/local/src/harnesses/gemini.ts | 10 + .../packages/local/src/harnesses/harness.ts | 132 ++++--------- .../packages/local/src/harnesses/hermes.ts | 10 + .../packages/local/src/harnesses/kimi.ts | 11 ++ .../packages/local/src/harnesses/opencode.ts | 9 + .../packages/local/src/harnesses/probe.ts | 76 -------- .../packages/local/src/harnesses/qwen.ts | 10 + .../packages/local/src/harnesses/registry.ts | 32 ++++ .../packages/local/src/harnesses/types.ts | 29 +++ .../packages/local/src/harnesses/workspace.ts | 6 +- .../local/tests/agent-process.test.ts | 15 +- .../packages/local/tests/catalogue.test.ts | 177 ++++-------------- .../local/tests/daemon-integration.test.ts | 5 +- .../local/tests/harness-launch.test.ts | 127 +++++-------- .../packages/local/tests/harnesses.test.ts | 86 ++++----- .../packages/protocol/src/constants.ts | 1 - .../agentlet/packages/protocol/src/harness.ts | 48 +---- .../agentlet/packages/protocol/src/index.ts | 5 +- .../packages/protocol/src/messages.ts | 19 +- external/agentlet/spec/protocol.md | 23 +-- 34 files changed, 570 insertions(+), 760 deletions(-) delete mode 100644 external/agentlet/packages/local/src/harnesses/catalogue.ts create mode 100644 external/agentlet/packages/local/src/harnesses/claude.ts create mode 100644 external/agentlet/packages/local/src/harnesses/codebuddy.ts create mode 100644 external/agentlet/packages/local/src/harnesses/codex.ts create mode 100644 external/agentlet/packages/local/src/harnesses/common/command-discovery.ts create mode 100644 external/agentlet/packages/local/src/harnesses/common/compile-command.ts create mode 100644 external/agentlet/packages/local/src/harnesses/common/define-command-harness.ts create mode 100644 external/agentlet/packages/local/src/harnesses/copilot.ts create mode 100644 external/agentlet/packages/local/src/harnesses/cursor.ts create mode 100644 external/agentlet/packages/local/src/harnesses/custom.ts create mode 100644 external/agentlet/packages/local/src/harnesses/gemini.ts create mode 100644 external/agentlet/packages/local/src/harnesses/hermes.ts create mode 100644 external/agentlet/packages/local/src/harnesses/kimi.ts create mode 100644 external/agentlet/packages/local/src/harnesses/opencode.ts delete mode 100644 external/agentlet/packages/local/src/harnesses/probe.ts create mode 100644 external/agentlet/packages/local/src/harnesses/qwen.ts create mode 100644 external/agentlet/packages/local/src/harnesses/registry.ts create mode 100644 external/agentlet/packages/local/src/harnesses/types.ts diff --git a/external/agentlet/README.md b/external/agentlet/README.md index 8d28f8fb5..6288c165a 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -73,29 +73,27 @@ The control and session connections use the same `agentletId`. Each spawned ACP ## Harness discovery -The daemon advertises `capabilities.harnessDiscovery: { version: 1 }`. Gateways may call `server/discoverHarnesses` with `{}` for read-only discovery or `{ "prepareWorkspaces": true }` for automatic provisioning. The response includes every static catalogue entry, installation state, resolved executable path, optional version, and diagnostics. No remote candidates, commands, IDs, or roots are accepted. +The daemon advertises `capabilities.harnessDiscovery: { version: 2 }`. Gateways may call `server/discoverHarnesses` with `{}` for read-only discovery or `{ "prepareWorkspaces": true }` for automatic provisioning. The response includes every registered Definition with static identity, boolean capabilities, `ready`, `adapter-missing`, or `not-found` status, optional version, workspace, and diagnostics. No remote candidates, commands, IDs, or roots are accepted. -Detected catalogue entries include `launchVersion: 1` as the explicit opt-in for hosts provisioning structured Profiles or presenting the structured editor only when the located executable supports shell-free launch. Windows opts in native `.exe`/`.com` executables, not npm `.cmd`/`.bat` shims or other script wrappers; shim entries remain installed and retain their legacy command recipe. Missing binaries and older daemon responses omit the field as well. This discovery hint does not replace the Gateway's independent handshake capability check at spawn. +Windows discovery scans all `where.exe` results and accepts absolute `.exe`, `.com`, `.cmd`, and `.bat` candidates, so an extensionless POSIX npm shim does not hide a later shell-resolvable wrapper. Unix discovery requires an absolute `which` result. Version probing uses the Windows command shell for wrappers and shell-free invocation on Unix. Discovery models the target platform shell but does not promise interactive aliases or startup-script behavior. Discovery uses bounded, shell-free PATH and optional version probes. It does not start ACP sessions, install packages, provision credentials, or copy prompts or skills. An optional version-probe failure does not change a successfully detected executable into a missing binary. -Only explicit workspace preparation creates `~/.agentlet/workspace/` on the daemon machine, and only for installed binaries. Existing contents are retained. Failed creation produces a diagnostic without a fallback directory. Agent Team runtime packages, setup commands, and Team RPCs are retired; manifests remain historical data only. +Only explicit workspace preparation creates `~/.agentlet/workspace/` on the daemon machine, and only for ready known harnesses. Existing contents are retained. Failed creation produces a diagnostic without a fallback directory. Agent Team runtime packages, setup commands, and Team RPCs are retired; manifests remain historical data only. ## Protocol lifecycle ### Typed harness launch -The daemon advertises `capabilities.harnessLaunch: { version: 1 }` independently of discovery. A host must gate structured spawning on that capability. `sessionSpec` accepts exactly one of the legacy trusted `command` string or `launch: { kind: 'acp-harness', harnessId, options?: { autoApprove?: boolean } }`. The structured path validates the daemon's own catalogue, rejects unknown options and unsupported approval presets, and spawns executable/argv without a shell. The legacy command path is unchanged. Editable display metadata never chooses an executable. +The daemon advertises `capabilities.harnessLaunch: { version: 2 }` independently of discovery. A host must gate structured spawning on that capability. `sessionSpec` accepts exactly one of the legacy trusted `command` string or `launch: { kind: 'acp-harness', harnessId, options?: { autoApprove?: boolean } }`. The structured path validates the daemon's own registry, rejects unknown options and unsupported approval presets, and compiles trusted fixed tokens plus bounded options into a terminal-style shell command. The legacy command path remains explicit user-authorized shell input. Editable display metadata never chooses a command. -Every Profile selects a wrapper from its launch identity alone: `acp-harness` selects `harnessId`, and legacy `acp-command` selects the special `custom` wrapper. Metadata and command text never infer a known wrapper, and old records are not converted. Each wrapper implements `detect()`, `describeCapabilities()`, and `buildLaunch()`. Discovery appends a manually selectable `custom` descriptor (`installed: false`) that never probes executables or prepares a workspace; hosts must exclude it from automatic provisioning. +Every Profile selects a Definition from its launch identity alone: `acp-harness` selects `harnessId`, and legacy `acp-command` selects the special `custom` Definition. Metadata and command text never infer a known harness, and old records are not converted. Each Definition implements `discover()` and `compile()`. Custom reports ready for manual selection, never probes executables or prepares a workspace, and hosts exclude it from automatic provisioning. -`@agentlet/protocol` exports `CUSTOM_COMMAND_WRAPPER_ID = 'custom'` and the frozen `CUSTOM_COMMAND_CAPABILITIES` object as canonical constants. Hosts may reuse these when projecting a manual Custom descriptor for older daemons without duplicating capability policy or implying preview RPC support. +`@agentlet/protocol` exports `CUSTOM_COMMAND_WRAPPER_ID = 'custom'` and the frozen `CUSTOM_COMMAND_CAPABILITIES` object as canonical constants. Hosts may reuse these when projecting the manual Custom descriptor without duplicating capability policy. -`Harness.get(id).describeCapabilities()` reports `supported`, `unsupported`, or `unknown` for `autoApprove`, `modelOverride`, `sessionPersistence`, and `customLaunchCommand`, scoped specifically to the ACP entry. The new `customLaunchCommand` field is optional on the wire for older daemons. Custom supports only `customLaunchCommand`; its other capabilities are unsupported. Known wrappers reject custom command overrides. `buildLaunch()` returns `{ kind: 'exec', executable, argv, env }` for known wrappers and `{ kind: 'shell', command }` for explicit custom commands. A known wrapper's optional model intent remains `initialPreferences.model` for existing ACP controls, never a launch option or guessed CLI argument. Known model override and session-persistence control remain unknown until verified; native print transports and adapter no-save flags are not inferred. +Definition capabilities are the booleans `autoApprove` and `customLaunchCommand`. Custom supports only `customLaunchCommand`; known Definitions reject custom command overrides. `compile()` returns `{ kind: 'shell', command }`. A known harness's optional model intent remains `initialPreferences.model` for existing ACP controls, never a launch option or guessed CLI argument. -The read-only `server/buildHarnessLaunch` RPC accepts exactly `{ launch: AgentProfileLaunch }` and uses the same wrapper compiler as runtime launch. It returns the exec/shell discriminated result, performs no executable probes, process spawning, or workspace preparation, and does not assert installation or authentication. The daemon advertises `capabilities.harnessLaunchPreview: { version: 1 }` and discovery entries include `launchPreviewVersion: 1`. Hosts must gate this RPC independently from spawning and display the daemon result rather than compile argv locally. Malformed input and unsupported options fail with `-32602`. - -A successful structured spawn returns `launchPlan: { version: 1, executable, argv, env }`. A host can persist and send that plan with subsequent spawns; the daemon compares it against its locally resolved plan and refuses catalogue drift instead of executing caller-supplied arguments. This pins the catalogue command recipe, not the installed binary version, PATH resolution, inherited environment, credentials, or runtime reachback environment. Structured launch requires an executable that the OS can spawn without a shell; shell-only wrappers such as Windows `.cmd` shims are not converted into shell commands. +Compilation occurs inside `server/spawn`; there is no preview RPC. Known commands are generated only from trusted Definition tokens and bounded options, while Custom commands remain user-authorized shell code. Historical `launchPlan` input is schema-validated then ignored, and spawn does not return a new plan. Runtime and recovery therefore compile the frozen launch intent with the target Agentlet's current Definition. ```text agentlet daemon diff --git a/external/agentlet/packages/local/src/agent-process.ts b/external/agentlet/packages/local/src/agent-process.ts index 8362539f0..c8712148c 100644 --- a/external/agentlet/packages/local/src/agent-process.ts +++ b/external/agentlet/packages/local/src/agent-process.ts @@ -1,11 +1,9 @@ import { createInterface } from 'node:readline' import { spawn, type ChildProcess } from 'node:child_process' import { EventEmitter } from 'node:events' -import type { HarnessLaunchPlan } from '@agentlet/protocol' export interface AgentProcessOptions { command: string - launchPlan?: HarnessLaunchPlan cwd?: string env?: Record } @@ -40,14 +38,9 @@ export class AgentProcess extends EventEmitter { throw new Error('Agent process already running') } - this.process = this.options.launchPlan ? spawn(this.options.launchPlan.executable, this.options.launchPlan.argv, { - shell: false, - cwd: this.options.cwd, - env: { ...process.env, ...this.options.env, ...this.options.launchPlan.env }, - stdio: ['pipe', 'pipe', 'pipe'], - // Legacy Custom commands intentionally execute shell code authorized by the host, not prompt data. + // Commands are either generated from daemon-owned harness definitions or explicitly authorized by the user. // codeql[js/command-line-injection] - }) : spawn(this.options.command, { + this.process = spawn(this.options.command, { shell: true, cwd: this.options.cwd, env: { ...process.env, ...this.options.env }, diff --git a/external/agentlet/packages/local/src/agentlet.ts b/external/agentlet/packages/local/src/agentlet.ts index 813db98a3..f9c137c4e 100644 --- a/external/agentlet/packages/local/src/agentlet.ts +++ b/external/agentlet/packages/local/src/agentlet.ts @@ -17,10 +17,9 @@ import { type SendResourceParams, type JsonRpcMessage, type JsonRpcError, - type HarnessLaunchPlan, } from '@agentlet/protocol' import { discoverHarnesses, parseHarnessDiscoveryParams } from './harnesses/detect.js' -import { buildHarnessLaunch, resolveHarnessLaunch } from './harnesses/harness.js' +import { compileHarnessLaunch } from './harnesses/harness.js' import { AgentProcess } from './agent-process.js' import { WsClient } from './ws-client.js' import { Relay } from './relay.js' @@ -212,9 +211,8 @@ export class Agentlet { autoRestart: true, bufferLimit: this.options.bufferLimit, maxAgents: this.options.maxAgents, - harnessDiscovery: { version: 1 }, - harnessLaunch: { version: 1 }, - harnessLaunchPreview: { version: 1 }, + harnessDiscovery: { version: 2 }, + harnessLaunch: { version: 2 }, }, } const params: AgentletHelloParams = { @@ -278,15 +276,6 @@ export class Agentlet { case ServerMethods.DISCOVER_HARNESSES: void this.handleDiscoverHarnesses(msg.id, msg.params) break - case ServerMethods.BUILD_HARNESS_LAUNCH: - try { - this.sendDaemonResponse(msg.id, buildHarnessLaunch(msg.params)) - } catch (error) { - this.sendDaemonResponse(msg.id, undefined, { - code: -32602, message: error instanceof Error ? error.message : String(error), - }) - } - break default: this.sendDaemonResponse(msg.id, undefined, { code: -32601, message: `Unknown method: ${msg.method}` }) } @@ -340,7 +329,7 @@ export class Agentlet { return } - let launchPlan: HarnessLaunchPlan | undefined + let command: string if (sessionSpec && 'launch' in sessionSpec) { try { if ('command' in sessionSpec) throw new Error('Provide exactly one of sessionSpec.command or sessionSpec.launch') @@ -357,7 +346,7 @@ export class Agentlet { ))) { throw new Error('Invalid structured sessionSpec process options') } - launchPlan = resolveHarnessLaunch(sessionSpec.launch, sessionSpec.launchPlan) + command = compileHarnessLaunch(sessionSpec.launch, sessionSpec.launchPlan).command } catch (error) { this.sendDaemonResponse(requestId, undefined, { code: -32602, message: error instanceof Error ? error.message : String(error) }) return @@ -368,14 +357,13 @@ export class Agentlet { } else if (typeof sessionSpec?.command !== 'string' || !sessionSpec.command.trim()) { this.sendDaemonResponse(requestId, undefined, { code: -32602, message: 'Missing required param: sessionSpec.command' }) return - } - let command: string - try { - const custom = launchPlan ? undefined : buildHarnessLaunch({ launch: { kind: 'acp-command', command: sessionSpec.command } }) - command = custom?.kind === 'shell' ? custom.command : `acp-harness:${sessionSpec.launch!.harnessId}` - } catch (error) { - this.sendDaemonResponse(requestId, undefined, { code: -32602, message: error instanceof Error ? error.message : String(error) }) - return + } else { + try { + command = compileHarnessLaunch({ kind: 'acp-command', command: sessionSpec.command }).command + } catch (error) { + this.sendDaemonResponse(requestId, undefined, { code: -32602, message: error instanceof Error ? error.message : String(error) }) + return + } } // Validate cwd: must be non-empty if provided, must exist on this machine @@ -435,7 +423,6 @@ export class Agentlet { // Host env overrides defaults, except for the daemon-owned token. const agent = new AgentProcess({ command, - ...(launchPlan ? { launchPlan } : {}), cwd, env: buildAgentProcessEnv( this.options.server, @@ -651,7 +638,7 @@ export class Agentlet { agentWs.connect() // Return spawn result immediately (agent PID is already known) - this.sendDaemonResponse(requestId, { sessionId, pid: managed.pid, ...(launchPlan ? { launchPlan } : {}) }) + this.sendDaemonResponse(requestId, { sessionId, pid: managed.pid }) } catch (err) { this.sendDaemonResponse(requestId, undefined, { code: -32000, diff --git a/external/agentlet/packages/local/src/harnesses/catalogue.ts b/external/agentlet/packages/local/src/harnesses/catalogue.ts deleted file mode 100644 index 1f56d2397..000000000 --- a/external/agentlet/packages/local/src/harnesses/catalogue.ts +++ /dev/null @@ -1,173 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -/** - * Trusted catalogue of ACP-capable agents the daemon knows how to - * launch. Kept separate from the probing logic in - * {@link ./detect} so adding / editing an agent is a pure data - * change with no need to touch the detection machinery. - * - * Each entry is a launch *recipe*: what binary to look for on PATH and - * what to spawn. There is no way to infer this from the binary alone — - * some agents speak ACP natively (` --acp`), others are driven - * through an adapter whose bin *is* the ACP agent (empty `acpArgs`). - * - * This is intentionally a daemon-local module, with no remote catalogue - * or caller-supplied commands. IDs also select daemon-owned workspaces. - */ - -import type { HarnessCatalogueEntry } from '@agentlet/protocol'; - -/** One known external agent's detection + launch recipe. */ -export interface KnownCli extends HarnessCatalogueEntry { - /** - * When true, skip the ` --version` probe during detection. - * Used for agents whose bin starts an interactive / stdio server on - * any invocation (e.g. ACP adapters that speak the protocol over - * stdin/stdout) and would otherwise block until the probe timeout - * instead of printing a version. - */ - skipVersionProbe?: boolean; -} - -/** - * Canonical catalogue of ACP-capable CLIs. Stable order is retained in - * discovery responses for hosts presenting the catalogue. - */ -export const KNOWN_CLIS: readonly KnownCli[] = [ - { - id: 'copilot', - displayName: 'GitHub Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - autoApprove: { - args: ['--allow-all'], - position: 'after-acp', - }, - installHint: 'npm install -g @github/copilot', - }, - { - id: 'claude', - displayName: 'Claude Agent', - // Claude Agent has no native ACP mode; it's driven through the - // official ACP adapter (backed by the Claude Agent SDK). Users - // install the adapter globally and we detect + launch its - // `claude-agent-acp` bin directly — the bin *is* the ACP agent, so - // there is no `--acp` argument. Auth is via ANTHROPIC_API_KEY or an - // existing `claude login` session; the adapter does NOT depend on - // the `claude` binary being on PATH. - binary: 'claude-agent-acp', - acpArgs: [], - autoApprove: null, - // The adapter bin starts the stdio ACP server on any invocation and - // would block on stdin rather than print a version, so skip the - // probe to avoid burning the full timeout on the happy path. - skipVersionProbe: true, - installHint: 'npm install -g @agentclientprotocol/claude-agent-acp', - }, - { - id: 'gemini', - displayName: 'Gemini', - binary: 'gemini', - acpArgs: ['--acp'], - autoApprove: { - args: ['--approval-mode=yolo'], - position: 'after-acp', - }, - installHint: 'npm install -g @google/gemini-cli', - }, - { - id: 'codex', - displayName: 'Codex', - // Codex has no native ACP mode; it's driven through the Codex ACP - // adapter (a Rust binary named `codex-acp`). Users install it via - // the adapter's npm package or a GitHub release, and we detect + - // launch the `codex-acp` bin directly — the bin *is* the ACP agent, - // so there is no `--acp` argument. Auth is via OPENAI_API_KEY / - // CODEX_API_KEY or a ChatGPT-subscription login; the adapter does - // NOT require the `codex` binary on PATH. - binary: 'codex-acp', - acpArgs: [], - autoApprove: null, - // Skip the version probe: like other ACP adapters the bin may start - // the stdio ACP server and block on stdin rather than print a - // version, which would burn the full probe timeout. - skipVersionProbe: true, - installHint: 'npm install -g @agentclientprotocol/codex-acp', - }, - { - id: 'qwen', - displayName: 'Qwen Code', - binary: 'qwen', - acpArgs: ['--acp'], - autoApprove: { - args: ['--approval-mode=yolo'], - position: 'after-acp', - }, - installHint: 'npm install -g @qwen-code/qwen-code', - }, - { - id: 'kimi', - displayName: 'Kimi Code', - binary: 'kimi', - acpArgs: ['acp'], - autoApprove: { - args: ['--yolo'], - position: 'before-acp', - }, - installHint: 'Install from https://code.kimi.com/', - }, - { - id: 'opencode', - displayName: 'OpenCode', - binary: 'opencode', - acpArgs: ['acp'], - autoApprove: null, - installHint: 'npm install -g opencode-ai@latest', - }, - { - id: 'cursor', - displayName: 'Cursor', - binary: 'agent', - acpArgs: ['acp'], - autoApprove: { - args: ['--yolo'], - position: 'before-acp', - }, - installHint: 'Install from https://cursor.com/docs/cli/installation', - }, - { - id: 'codebuddy', - displayName: 'CodeBuddy', - // Tencent Cloud's CodeBuddy Code CLI is built on the same - // architecture as Claude Code (same slash-command surface: /agents, - // /bashes, /compact, …) and speaks ACP natively via `--acp`, so no - // separate adapter binary is needed. - binary: 'codebuddy', - acpArgs: ['--acp'], - // Like Claude Code (which it is architecturally derived from), - // CodeBuddy delegates tool permission decisions to ACP requests - // rather than exposing a documented blanket auto-approve flag for - // `--acp` mode, so there is no official argument-based recipe. - autoApprove: null, - installHint: 'npm install -g @tencent-ai/codebuddy-code', - }, - { - id: 'hermes', - displayName: 'Hermes Agent', - // Hermes ships a native stdio ACP server reached via the `acp` - // subcommand. It has no argument-based blanket auto-approval mode — - // permissions and session modes are handled inside Hermes itself — - // so `autoApprove` is null and no launch-command toggle is exposed. - binary: 'hermes', - acpArgs: ['acp'], - autoApprove: null, - // The `hermes` bin ignores `--version`/`--help` and launches its - // interactive agent on any invocation, blocking on stdin instead of - // printing a version. Skip the probe so detection doesn't burn the - // full timeout (and spawn a full agent) on every request. - skipVersionProbe: true, - installHint: - 'Install from https://hermes-agent.nousresearch.com/docs/user-guide/features/acp', - }, -]; diff --git a/external/agentlet/packages/local/src/harnesses/claude.ts b/external/agentlet/packages/local/src/harnesses/claude.ts new file mode 100644 index 000000000..0841f9985 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/claude.ts @@ -0,0 +1,22 @@ +import { commandExists, discoverCommand } from './common/command-discovery.js' +import { compileTrustedCommand } from './common/compile-command.js' +import type { HarnessDefinition } from './types.js' + +export const claudeHarness: HarnessDefinition = { + id: 'claude', + displayName: 'Claude Agent', + installHint: 'npm install -g @agentclientprotocol/claude-agent-acp', + capabilities: { customLaunchCommand: false, autoApprove: false }, + async discover() { + const adapter = await discoverCommand('claude-agent-acp', { probeVersion: false }) + if (adapter.status === 'ready') return adapter + if (await commandExists('claude')) { + return { + status: 'adapter-missing', + diagnostics: [{ code: 'adapter_missing', message: 'Claude is installed but claude-agent-acp is required' }], + } + } + return adapter + }, + compile: () => compileTrustedCommand(['claude-agent-acp']), +} diff --git a/external/agentlet/packages/local/src/harnesses/codebuddy.ts b/external/agentlet/packages/local/src/harnesses/codebuddy.ts new file mode 100644 index 000000000..677867b72 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/codebuddy.ts @@ -0,0 +1,9 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const codebuddyHarness = defineCommandHarness({ + id: 'codebuddy', + displayName: 'CodeBuddy', + command: 'codebuddy', + acpArgs: ['--acp'], + installHint: 'npm install -g @tencent-ai/codebuddy-code', +}) diff --git a/external/agentlet/packages/local/src/harnesses/codex.ts b/external/agentlet/packages/local/src/harnesses/codex.ts new file mode 100644 index 000000000..387cffcd2 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/codex.ts @@ -0,0 +1,22 @@ +import { commandExists, discoverCommand } from './common/command-discovery.js' +import { compileTrustedCommand } from './common/compile-command.js' +import type { HarnessDefinition } from './types.js' + +export const codexHarness: HarnessDefinition = { + id: 'codex', + displayName: 'Codex', + installHint: 'npm install -g @agentclientprotocol/codex-acp', + capabilities: { customLaunchCommand: false, autoApprove: false }, + async discover() { + const adapter = await discoverCommand('codex-acp', { probeVersion: false }) + if (adapter.status === 'ready') return adapter + if (await commandExists('codex')) { + return { + status: 'adapter-missing', + diagnostics: [{ code: 'adapter_missing', message: 'Codex is installed but codex-acp is required' }], + } + } + return adapter + }, + compile: () => compileTrustedCommand(['codex-acp']), +} diff --git a/external/agentlet/packages/local/src/harnesses/common/command-discovery.ts b/external/agentlet/packages/local/src/harnesses/common/command-discovery.ts new file mode 100644 index 000000000..ec948a269 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/common/command-discovery.ts @@ -0,0 +1,85 @@ +import { execFile } from 'node:child_process' +import { platform } from 'node:os' +import { isAbsolute, win32 } from 'node:path' +import { promisify } from 'node:util' +import type { HarnessDiagnostic, HarnessDiscovery } from '../types.js' + +const execFileP = promisify(execFile) +const PROBE_OPTIONS = { + timeout: 2_500, + killSignal: 'SIGKILL' as const, + maxBuffer: 64 * 1024, + windowsHide: true, + shell: false, +} +const WINDOWS_SHELL_EXTENSIONS = /\.(?:exe|com|cmd|bat)$/i + +function message(error: unknown): string { + return error instanceof Error ? error.message : String(error) +} + +function missingLookup(error: unknown): boolean { + return typeof error === 'object' && error !== null && + 'code' in error && error.code === 1 && !('killed' in error && error.killed) +} + +async function locateCommand(command: string): Promise { + const windows = platform() === 'win32' + const { stdout } = await execFileP(windows ? 'where.exe' : 'which', [command], PROBE_OPTIONS) + return stdout.split(/\r?\n/).some((candidate) => { + const path = candidate.trim() + if (!path) return false + if (windows) return win32.isAbsolute(path) && WINDOWS_SHELL_EXTENSIONS.test(path) + return isAbsolute(path) + }) +} + +async function probeVersion(command: string): Promise { + if (platform() === 'win32') { + const shell = process.env.ComSpec || 'cmd.exe' + const { stdout } = await execFileP(shell, ['/d', '/s', '/c', `${command} --version`], PROBE_OPTIONS) + return stdout.split(/\r?\n/)[0]?.trim() || undefined + } + const { stdout } = await execFileP(command, ['--version'], PROBE_OPTIONS) + return stdout.split(/\r?\n/)[0]?.trim() || undefined +} + +export async function commandExists(command: string): Promise { + try { + return await locateCommand(command) + } catch { + return false + } +} + +export async function discoverCommand( + command: string, + options: { probeVersion?: boolean } = {}, +): Promise { + const diagnostics: HarnessDiagnostic[] = [] + try { + if (!await locateCommand(command)) { + return { + status: 'not-found', + diagnostics: [{ code: 'lookup_failed', message: 'PATH lookup returned no platform-shell command' }], + } + } + } catch (error) { + return { + status: 'not-found', + diagnostics: [{ + code: missingLookup(error) ? 'binary_missing' : 'lookup_failed', + message: missingLookup(error) ? `${command} is not on PATH` : message(error), + }], + } + } + if (options.probeVersion === false) return { status: 'ready' } + try { + const version = await probeVersion(command) + if (version) return { status: 'ready', version } + diagnostics.push({ code: 'version_unknown', message: 'Version probe returned no version' }) + } catch (error) { + diagnostics.push({ code: 'version_probe_failed', message: message(error) }) + } + return { status: 'ready', diagnostics } +} diff --git a/external/agentlet/packages/local/src/harnesses/common/compile-command.ts b/external/agentlet/packages/local/src/harnesses/common/compile-command.ts new file mode 100644 index 000000000..6b989a01d --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/common/compile-command.ts @@ -0,0 +1,10 @@ +import type { CompiledHarnessLaunch } from '../types.js' + +const TRUSTED_COMMAND_TOKEN = /^[A-Za-z0-9@%_./:=+-]+$/ + +export function compileTrustedCommand(tokens: readonly string[]): CompiledHarnessLaunch { + if (!tokens.length || tokens.some((token) => !TRUSTED_COMMAND_TOKEN.test(token))) { + throw new Error('Harness command contains an unsafe token') + } + return { kind: 'shell', command: tokens.join(' ') } +} diff --git a/external/agentlet/packages/local/src/harnesses/common/define-command-harness.ts b/external/agentlet/packages/local/src/harnesses/common/define-command-harness.ts new file mode 100644 index 000000000..d994e6c22 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/common/define-command-harness.ts @@ -0,0 +1,34 @@ +import type { HarnessLaunchOptions } from '@agentlet/protocol' +import { compileTrustedCommand } from './compile-command.js' +import { discoverCommand } from './command-discovery.js' +import type { HarnessDefinition } from '../types.js' + +export function defineCommandHarness(config: { + id: string + displayName: string + command: string + acpArgs: readonly string[] + autoApproveArgs?: readonly string[] + autoApprovePosition?: 'before-acp' | 'after-acp' + installHint: string + probeVersion?: boolean +}): HarnessDefinition { + const supportsAutoApprove = config.autoApproveArgs !== undefined + return { + id: config.id, + displayName: config.displayName, + installHint: config.installHint, + capabilities: { customLaunchCommand: false, autoApprove: supportsAutoApprove }, + discover: () => discoverCommand(config.command, { probeVersion: config.probeVersion }), + compile(options: HarnessLaunchOptions = {}) { + if (options.autoApprove && !supportsAutoApprove) { + throw new Error(`Harness '${config.id}' does not support launch-time autoApprove`) + } + const approval = options.autoApprove ? config.autoApproveArgs ?? [] : [] + const args = config.autoApprovePosition === 'before-acp' + ? [...approval, ...config.acpArgs] + : [...config.acpArgs, ...approval] + return compileTrustedCommand([config.command, ...args]) + }, + } +} diff --git a/external/agentlet/packages/local/src/harnesses/copilot.ts b/external/agentlet/packages/local/src/harnesses/copilot.ts new file mode 100644 index 000000000..e0ef5adc2 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/copilot.ts @@ -0,0 +1,10 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const copilotHarness = defineCommandHarness({ + id: 'copilot', + displayName: 'GitHub Copilot', + command: 'copilot', + acpArgs: ['--acp'], + autoApproveArgs: ['--allow-all'], + installHint: 'npm install -g @github/copilot', +}) diff --git a/external/agentlet/packages/local/src/harnesses/cursor.ts b/external/agentlet/packages/local/src/harnesses/cursor.ts new file mode 100644 index 000000000..36e74897c --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/cursor.ts @@ -0,0 +1,11 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const cursorHarness = defineCommandHarness({ + id: 'cursor', + displayName: 'Cursor', + command: 'agent', + acpArgs: ['acp'], + autoApproveArgs: ['--yolo'], + autoApprovePosition: 'before-acp', + installHint: 'Install from https://cursor.com/docs/cli/installation', +}) diff --git a/external/agentlet/packages/local/src/harnesses/custom.ts b/external/agentlet/packages/local/src/harnesses/custom.ts new file mode 100644 index 000000000..9f8bc9cc0 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/custom.ts @@ -0,0 +1,21 @@ +import { parseAgentProfileLaunch, CUSTOM_COMMAND_CAPABILITIES } from '@agentlet/protocol' +import type { HarnessDefinition } from './types.js' + +export const customHarness: HarnessDefinition = { + id: 'custom', + displayName: 'Custom command', + installHint: '', + capabilities: CUSTOM_COMMAND_CAPABILITIES, + async discover() { + return { status: 'ready' } + }, + compile() { + throw new Error('Custom command compilation requires an explicit command') + }, +} + +export function compileCustomCommand(command: unknown) { + const launch = parseAgentProfileLaunch({ kind: 'acp-command', command }) + if (launch.kind !== 'acp-command') throw new Error('Custom command is required') + return { kind: 'shell' as const, command: launch.command } +} diff --git a/external/agentlet/packages/local/src/harnesses/detect.ts b/external/agentlet/packages/local/src/harnesses/detect.ts index 18f97143d..484027e00 100644 --- a/external/agentlet/packages/local/src/harnesses/detect.ts +++ b/external/agentlet/packages/local/src/harnesses/detect.ts @@ -2,9 +2,8 @@ // Licensed under the MIT license. import type { HarnessDiscoveryParams, HarnessDiscoveryResult } from '@agentlet/protocol' -import { CUSTOM_COMMAND_WRAPPER_ID } from '@agentlet/protocol' -import { KNOWN_CLIS } from './catalogue.js' -import { Harness } from './harness.js' +import { HARNESS_DEFINITIONS } from './registry.js' +import { prepareHarnessWorkspace } from './workspace.js' export function parseHarnessDiscoveryParams(params: unknown): HarnessDiscoveryParams { if (params === undefined) return {} @@ -23,6 +22,31 @@ export function parseHarnessDiscoveryParams(params: unknown): HarnessDiscoveryPa /** Probe only the daemon's trusted catalogue; no install, bootstrap, or credential changes. */ export async function discoverHarnesses(params: HarnessDiscoveryParams = {}): Promise { const options = parseHarnessDiscoveryParams(params) - const ids = [...KNOWN_CLIS.map(({ id }) => id), CUSTOM_COMMAND_WRAPPER_ID] - return { harnesses: await Promise.all(ids.map((id) => Harness.get(id).detect(options))) } + return { + harnesses: await Promise.all(HARNESS_DEFINITIONS.map(async (definition) => { + const observation = await definition.discover() + const diagnostics = [...(observation.diagnostics ?? [])] + let workingDirPath: string | undefined + if (options.prepareWorkspaces && observation.status === 'ready' && definition.id !== 'custom') { + try { + workingDirPath = await prepareHarnessWorkspace(definition.id) + } catch (error) { + diagnostics.push({ + code: 'workspace_failed', + message: error instanceof Error ? error.message : String(error), + }) + } + } + return { + id: definition.id, + displayName: definition.displayName, + installHint: definition.installHint, + capabilities: { ...definition.capabilities }, + status: observation.status, + ...(observation.version ? { version: observation.version } : {}), + ...(workingDirPath ? { workingDirPath } : {}), + ...(diagnostics.length ? { diagnostics } : {}), + } + })), + } } diff --git a/external/agentlet/packages/local/src/harnesses/gemini.ts b/external/agentlet/packages/local/src/harnesses/gemini.ts new file mode 100644 index 000000000..d46b096e0 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/gemini.ts @@ -0,0 +1,10 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const geminiHarness = defineCommandHarness({ + id: 'gemini', + displayName: 'Gemini', + command: 'gemini', + acpArgs: ['--acp'], + autoApproveArgs: ['--approval-mode=yolo'], + installHint: 'npm install -g @google/gemini-cli', +}) diff --git a/external/agentlet/packages/local/src/harnesses/harness.ts b/external/agentlet/packages/local/src/harnesses/harness.ts index 96e0ff114..9ac4d8079 100644 --- a/external/agentlet/packages/local/src/harnesses/harness.ts +++ b/external/agentlet/packages/local/src/harnesses/harness.ts @@ -1,107 +1,39 @@ -import { isDeepStrictEqual } from 'node:util' -import { parseAcpHarnessLaunch, parseAgentProfileLaunch, parseBuildHarnessLaunchParams, parseHarnessLaunchPreview, CUSTOM_COMMAND_WRAPPER_ID, CUSTOM_COMMAND_CAPABILITIES } from '@agentlet/protocol' -import type { HarnessCapabilities, HarnessLaunchOptions, HarnessLaunchPlan, HarnessLaunchPreview, HarnessDiscoveryParams, HarnessDiscoveryEntry } from '@agentlet/protocol' -import { KNOWN_CLIS, type KnownCli } from './catalogue.js' -import { detectKnownHarness } from './probe.js' - -export interface HarnessLaunchIntent { - autoApprove?: boolean - customLaunchCommand?: string - /** ACP preference only; never translated into guessed command-line arguments. */ - model?: string +import { + parseAgentProfileLaunch, + type AgentProfileLaunch, + type HarnessLaunchPlan, +} from '@agentlet/protocol' +import { compileCustomCommand } from './custom.js' +import { getHarnessDefinition } from './registry.js' +import type { CompiledHarnessLaunch } from './types.js' + +function object(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) } -export type HarnessBuiltLaunch = HarnessLaunchPreview & { initialPreferences?: { model: string } } - -/** A wrapper selected by launch identity, never editable metadata or command inference. */ -export class Harness { - private constructor(private readonly entry?: KnownCli) {} - - static get(harnessId: string): Harness { - if (harnessId === CUSTOM_COMMAND_WRAPPER_ID) return new Harness() - const entry = KNOWN_CLIS.find((candidate) => candidate.id === harnessId) - if (!entry) throw new Error(`Unknown harness: ${harnessId}`) - return new Harness(entry) - } - - static forLaunch(launch: unknown): Harness { - const parsed = parseAgentProfileLaunch(launch) - if (parsed.kind === 'acp-harness' && parsed.harnessId === CUSTOM_COMMAND_WRAPPER_ID) - throw new Error('Custom wrapper requires an explicit ACP command launch') - return Harness.get(parsed.kind === 'acp-command' ? CUSTOM_COMMAND_WRAPPER_ID : parsed.harnessId) - } - - async detect(options: HarnessDiscoveryParams = {}): Promise { - if (this.entry) return { - ...await detectKnownHarness(this.entry, options), - capabilities: this.describeCapabilities(), - } - return { - id: CUSTOM_COMMAND_WRAPPER_ID, displayName: 'Custom', binary: CUSTOM_COMMAND_WRAPPER_ID, acpArgs: [], - autoApprove: null, installHint: 'Provide a trusted ACP command', - installed: false, launchPreviewVersion: 1, capabilities: this.describeCapabilities(), - } - } - - describeCapabilities(): HarnessCapabilities { - if (!this.entry) return { ...CUSTOM_COMMAND_CAPABILITIES } - return { - customLaunchCommand: 'unsupported', - autoApprove: this.entry.autoApprove ? 'supported' : 'unsupported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', - } - } - - buildLaunch(intent: HarnessLaunchIntent = {}): HarnessBuiltLaunch { - if (!this.entry) { - if (intent === null || typeof intent !== 'object' || Array.isArray(intent) || - Object.keys(intent).some((key) => key !== 'customLaunchCommand')) - throw new Error('Custom wrapper accepts only customLaunchCommand') - const parsed = parseAgentProfileLaunch({ kind: 'acp-command', command: intent.customLaunchCommand }) - if (parsed.kind !== 'acp-command') throw new Error('Custom wrapper requires a command') - return { kind: 'shell', command: parsed.command } - } - if (intent === null || typeof intent !== 'object' || Array.isArray(intent) || - Object.keys(intent).some((key) => !['autoApprove', 'model'].includes(key)) || - (intent.model !== undefined && (typeof intent.model !== 'string' || - !intent.model.trim() || intent.model.length > 1024 || intent.model.includes('\0')))) { - throw new Error('Harness launch accepts only autoApprove and a bounded ACP model preference') - } - const options: HarnessLaunchOptions = intent.autoApprove === undefined ? {} : { autoApprove: intent.autoApprove } - parseAcpHarnessLaunch({ kind: 'acp-harness', harnessId: this.entry.id, options }) - const approval = intent.autoApprove ? this.entry.autoApprove : null - if (intent.autoApprove && !approval) { - throw new Error(`Harness '${this.entry.id}' does not support launch-time autoApprove`) - } - return { - kind: 'exec', - executable: this.entry.binary, - argv: approval?.position === 'before-acp' - ? [...approval.args, ...this.entry.acpArgs] - : [...this.entry.acpArgs, ...(approval?.args ?? [])], - env: {}, - ...(intent.model === undefined ? {} : { initialPreferences: { model: intent.model } }), - } +function validateLegacyLaunchPlan(value: unknown): void { + if (value === undefined) return + if (!object(value) || value.version !== 1 || + typeof value.executable !== 'string' || !value.executable || + !Array.isArray(value.argv) || value.argv.some((arg) => typeof arg !== 'string') || + !object(value.env) || Object.values(value.env).some((entry) => typeof entry !== 'string')) { + throw new Error('Invalid legacy harness launch plan') } } -/** Resolve locally; a caller-supplied plan is only an equality assertion, never executable input. */ -export function resolveHarnessLaunch(launch: unknown, expectedPlan?: unknown): HarnessLaunchPlan { - const parsed = parseAcpHarnessLaunch(launch) - const built = buildHarnessLaunch({ launch: parsed }) - if (built.kind !== 'exec') throw new Error('Typed harness launch must be shell-free') - const plan: HarnessLaunchPlan = { version: 1, executable: built.executable, argv: built.argv, env: built.env } - if (expectedPlan !== undefined && !isDeepStrictEqual(expectedPlan, plan)) { - throw new Error('Harness launch plan changed; explicit reauthorization is required') +export function compileHarnessLaunch( + launch: unknown, + legacyPlan?: HarnessLaunchPlan, +): CompiledHarnessLaunch { + validateLegacyLaunchPlan(legacyPlan) + const parsed: AgentProfileLaunch = parseAgentProfileLaunch(launch) + if (parsed.kind === 'acp-command') return compileCustomCommand(parsed.command) + if (parsed.harnessId === 'custom') { + throw new Error('Custom wrapper requires an explicit ACP command launch') } - return plan -} - -/** Pure compilation: never detects executables, prepares directories, or starts a process. */ -export function buildHarnessLaunch(params: unknown): HarnessLaunchPreview { - const { launch } = parseBuildHarnessLaunchParams(params) - const wrapper = Harness.forLaunch(launch) - return parseHarnessLaunchPreview(wrapper.buildLaunch(launch.kind === 'acp-command' - ? { customLaunchCommand: launch.command } : launch.options)) + const definition = getHarnessDefinition(parsed.harnessId) + if (parsed.options?.autoApprove && !definition.capabilities.autoApprove) { + throw new Error(`Harness ${parsed.harnessId} does not support auto-approval`) + } + return definition.compile(parsed.options) } diff --git a/external/agentlet/packages/local/src/harnesses/hermes.ts b/external/agentlet/packages/local/src/harnesses/hermes.ts new file mode 100644 index 000000000..3ba265475 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/hermes.ts @@ -0,0 +1,10 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const hermesHarness = defineCommandHarness({ + id: 'hermes', + displayName: 'Hermes Agent', + command: 'hermes', + acpArgs: ['acp'], + installHint: 'Install from https://hermes-agent.nousresearch.com/docs/user-guide/features/acp', + probeVersion: false, +}) diff --git a/external/agentlet/packages/local/src/harnesses/kimi.ts b/external/agentlet/packages/local/src/harnesses/kimi.ts new file mode 100644 index 000000000..ddb9c852b --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/kimi.ts @@ -0,0 +1,11 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const kimiHarness = defineCommandHarness({ + id: 'kimi', + displayName: 'Kimi Code', + command: 'kimi', + acpArgs: ['acp'], + autoApproveArgs: ['--yolo'], + autoApprovePosition: 'before-acp', + installHint: 'Install from https://code.kimi.com/', +}) diff --git a/external/agentlet/packages/local/src/harnesses/opencode.ts b/external/agentlet/packages/local/src/harnesses/opencode.ts new file mode 100644 index 000000000..011658782 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/opencode.ts @@ -0,0 +1,9 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const opencodeHarness = defineCommandHarness({ + id: 'opencode', + displayName: 'OpenCode', + command: 'opencode', + acpArgs: ['acp'], + installHint: 'npm install -g opencode-ai@latest', +}) diff --git a/external/agentlet/packages/local/src/harnesses/probe.ts b/external/agentlet/packages/local/src/harnesses/probe.ts deleted file mode 100644 index 1f5f2aa7b..000000000 --- a/external/agentlet/packages/local/src/harnesses/probe.ts +++ /dev/null @@ -1,76 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -import { execFile } from 'node:child_process' -import { platform } from 'node:os' -import { isAbsolute, win32 } from 'node:path' -import { promisify } from 'node:util' -import type { HarnessDiscoveryEntry, HarnessDiscoveryParams } from '@agentlet/protocol' -import type { KnownCli } from './catalogue.js' -import { prepareHarnessWorkspace } from './workspace.js' - -const execFileP = promisify(execFile) -const PROBE_OPTIONS = { - timeout: 2_500, - killSignal: 'SIGKILL' as const, - maxBuffer: 64 * 1024, - windowsHide: true, - shell: false, -} - -function message(error: unknown): string { - return error instanceof Error ? error.message : String(error) -} - -export async function detectKnownHarness( - { skipVersionProbe, ...cli }: KnownCli, - options: HarnessDiscoveryParams, -): Promise { - const windows = platform() === 'win32' - const entry: HarnessDiscoveryEntry = { - ...cli, - acpArgs: [...cli.acpArgs], - autoApprove: cli.autoApprove ? { ...cli.autoApprove, args: [...cli.autoApprove.args] } : null, - installed: false, - launchPreviewVersion: 1, - } - const diagnose = (code: string, detail: string) => { - ;(entry.diagnostics ??= []).push({ code, message: detail }) - } - try { - const { stdout } = await execFileP(windows ? 'where.exe' : 'which', [cli.binary], PROBE_OPTIONS) - const executablePath = stdout.split(/\r?\n/)[0]?.trim() - if (!executablePath || !(windows ? win32.isAbsolute(executablePath) : isAbsolute(executablePath))) { - diagnose('lookup_failed', 'PATH lookup did not return an absolute executable path') - return entry - } - entry.executablePath = executablePath - entry.installed = true - // Windows npm shims require a shell; only native executables opt into typed launch. - if (!windows || /\.(exe|com)$/i.test(executablePath)) entry.launchVersion = 1 - } catch (error) { - const missing = typeof error === 'object' && error !== null && - 'code' in error && error.code === 1 && !('killed' in error && error.killed) - diagnose(missing ? 'binary_missing' : 'lookup_failed', missing ? `${cli.binary} is not on PATH` : message(error)) - return entry - } - - if (!skipVersionProbe) { - try { - const { stdout } = await execFileP(entry.executablePath!, ['--version'], PROBE_OPTIONS) - const version = stdout.split(/\r?\n/)[0]?.trim() - if (version) entry.version = version - else diagnose('version_unknown', 'Version probe returned no version') - } catch (error) { - diagnose('version_probe_failed', message(error)) - } - } - if (options.prepareWorkspaces) { - try { - entry.workingDirPath = await prepareHarnessWorkspace(cli.id) - } catch (error) { - diagnose('workspace_failed', message(error)) - } - } - return entry -} diff --git a/external/agentlet/packages/local/src/harnesses/qwen.ts b/external/agentlet/packages/local/src/harnesses/qwen.ts new file mode 100644 index 000000000..5e9c1e42c --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/qwen.ts @@ -0,0 +1,10 @@ +import { defineCommandHarness } from './common/define-command-harness.js' + +export const qwenHarness = defineCommandHarness({ + id: 'qwen', + displayName: 'Qwen Code', + command: 'qwen', + acpArgs: ['--acp'], + autoApproveArgs: ['--approval-mode=yolo'], + installHint: 'npm install -g @qwen-code/qwen-code', +}) diff --git a/external/agentlet/packages/local/src/harnesses/registry.ts b/external/agentlet/packages/local/src/harnesses/registry.ts new file mode 100644 index 000000000..fc5747604 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/registry.ts @@ -0,0 +1,32 @@ +import { claudeHarness } from './claude.js' +import { codebuddyHarness } from './codebuddy.js' +import { codexHarness } from './codex.js' +import { copilotHarness } from './copilot.js' +import { cursorHarness } from './cursor.js' +import { customHarness } from './custom.js' +import { geminiHarness } from './gemini.js' +import { hermesHarness } from './hermes.js' +import { kimiHarness } from './kimi.js' +import { opencodeHarness } from './opencode.js' +import { qwenHarness } from './qwen.js' +import type { HarnessDefinition } from './types.js' + +export const HARNESS_DEFINITIONS: readonly HarnessDefinition[] = [ + copilotHarness, + claudeHarness, + geminiHarness, + codexHarness, + qwenHarness, + kimiHarness, + opencodeHarness, + cursorHarness, + codebuddyHarness, + hermesHarness, + customHarness, +] + +export function getHarnessDefinition(id: string): HarnessDefinition { + const definition = HARNESS_DEFINITIONS.find((candidate) => candidate.id === id) + if (!definition) throw new Error(`Unknown harness: ${id}`) + return definition +} diff --git a/external/agentlet/packages/local/src/harnesses/types.ts b/external/agentlet/packages/local/src/harnesses/types.ts new file mode 100644 index 000000000..fa69424f6 --- /dev/null +++ b/external/agentlet/packages/local/src/harnesses/types.ts @@ -0,0 +1,29 @@ +import type { + HarnessCapabilities, + HarnessDiscoveryEntry, + HarnessLaunchOptions, +} from '@agentlet/protocol' + +export interface HarnessDiagnostic { + code: string + message: string +} + +export type HarnessDiscovery = Pick< + HarnessDiscoveryEntry, + 'status' | 'version' | 'diagnostics' +> + +export interface CompiledHarnessLaunch { + kind: 'shell' + command: string +} + +export interface HarnessDefinition { + id: string + displayName: string + installHint: string + capabilities: HarnessCapabilities + discover(): Promise + compile(options?: HarnessLaunchOptions): CompiledHarnessLaunch +} diff --git a/external/agentlet/packages/local/src/harnesses/workspace.ts b/external/agentlet/packages/local/src/harnesses/workspace.ts index c5b4444b0..4dc314f3d 100644 --- a/external/agentlet/packages/local/src/harnesses/workspace.ts +++ b/external/agentlet/packages/local/src/harnesses/workspace.ts @@ -1,12 +1,12 @@ import { mkdir } from 'node:fs/promises' import { homedir } from 'node:os' import { join } from 'node:path' -import { KNOWN_CLIS } from './catalogue.js' +import { getHarnessDefinition } from './registry.js' /** Only static catalogue IDs may select daemon-owned workspaces. Existing contents are retained. */ export async function prepareHarnessWorkspace(id: string): Promise { - const harness = KNOWN_CLIS.find((entry) => entry.id === id) - if (!harness) throw new Error(`Unknown harness ID: ${id}`) + const harness = getHarnessDefinition(id) + if (harness.id === 'custom') throw new Error('Custom harness has no daemon-owned workspace') const workingDirPath = join(homedir(), '.agentlet', 'workspace', harness.id) await mkdir(workingDirPath, { recursive: true }) return workingDirPath diff --git a/external/agentlet/packages/local/tests/agent-process.test.ts b/external/agentlet/packages/local/tests/agent-process.test.ts index ff47df3a8..f877b1f4c 100644 --- a/external/agentlet/packages/local/tests/agent-process.test.ts +++ b/external/agentlet/packages/local/tests/agent-process.test.ts @@ -24,16 +24,11 @@ describe('process transport selection', () => { })) }) - it('never interpolates structured executable paths or argument values', () => { - const executable = '/path with spaces/adapter' - const argv = ['literal argument', '$(not-run); | &', '"quoted"'] - new AgentProcess({ - command: 'display-only', - launchPlan: { version: 1, executable, argv, env: {} }, - cwd: '/work', - }).start() - expect(spawn).toHaveBeenCalledWith(executable, argv, expect.objectContaining({ - shell: false, cwd: '/work', stdio: ['pipe', 'pipe', 'pipe'], + it('executes a compiled known-harness command through the platform shell', () => { + const command = 'copilot --acp --allow-all' + new AgentProcess({ command, cwd: '/work' }).start() + expect(spawn).toHaveBeenCalledWith(command, expect.objectContaining({ + shell: true, cwd: '/work', stdio: ['pipe', 'pipe', 'pipe'], })) }) }) diff --git a/external/agentlet/packages/local/tests/catalogue.test.ts b/external/agentlet/packages/local/tests/catalogue.test.ts index 78db4afd0..3933c8f4c 100644 --- a/external/agentlet/packages/local/tests/catalogue.test.ts +++ b/external/agentlet/packages/local/tests/catalogue.test.ts @@ -1,143 +1,38 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. +import { describe, expect, it } from 'vitest' +import { HARNESS_DEFINITIONS } from '../src/harnesses/registry.js' +import { compileHarnessLaunch } from '../src/harnesses/harness.js' -import { describe, expect, it } from 'vitest'; +describe('harness definitions', () => { + it('exposes the supported agents in stable UI order', () => { + expect(HARNESS_DEFINITIONS.map(({ id, displayName }) => ({ id, displayName }))).toEqual([ + { id: 'copilot', displayName: 'GitHub Copilot' }, + { id: 'claude', displayName: 'Claude Agent' }, + { id: 'gemini', displayName: 'Gemini' }, + { id: 'codex', displayName: 'Codex' }, + { id: 'qwen', displayName: 'Qwen Code' }, + { id: 'kimi', displayName: 'Kimi Code' }, + { id: 'opencode', displayName: 'OpenCode' }, + { id: 'cursor', displayName: 'Cursor' }, + { id: 'codebuddy', displayName: 'CodeBuddy' }, + { id: 'hermes', displayName: 'Hermes Agent' }, + { id: 'custom', displayName: 'Custom command' }, + ]) + }) -import { KNOWN_CLIS } from '../src/harnesses/catalogue.js'; - -describe('KNOWN_CLIS', () => { - it('exposes the supported agents in UI order with their ACP commands', () => { - expect( - KNOWN_CLIS.map(({ id, displayName, binary, acpArgs }) => ({ - id, - displayName, - binary, - acpArgs, - })), - ).toEqual([ - { - id: 'copilot', - displayName: 'GitHub Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - }, - { - id: 'claude', - displayName: 'Claude Agent', - binary: 'claude-agent-acp', - acpArgs: [], - }, - { - id: 'gemini', - displayName: 'Gemini', - binary: 'gemini', - acpArgs: ['--acp'], - }, - { - id: 'codex', - displayName: 'Codex', - binary: 'codex-acp', - acpArgs: [], - }, - { - id: 'qwen', - displayName: 'Qwen Code', - binary: 'qwen', - acpArgs: ['--acp'], - }, - { - id: 'kimi', - displayName: 'Kimi Code', - binary: 'kimi', - acpArgs: ['acp'], - }, - { - id: 'opencode', - displayName: 'OpenCode', - binary: 'opencode', - acpArgs: ['acp'], - }, - { - id: 'cursor', - displayName: 'Cursor', - binary: 'agent', - acpArgs: ['acp'], - }, - { - id: 'codebuddy', - displayName: 'CodeBuddy', - binary: 'codebuddy', - acpArgs: ['--acp'], - }, - { - id: 'hermes', - displayName: 'Hermes Agent', - binary: 'hermes', - acpArgs: ['acp'], - }, - ]); - }); - - it('uses unique ids and binary names', () => { - expect(new Set(KNOWN_CLIS.map((cli) => cli.id)).size).toBe( - KNOWN_CLIS.length, - ); - expect(new Set(KNOWN_CLIS.map((cli) => cli.binary)).size).toBe( - KNOWN_CLIS.length, - ); - }); - - it('defines official argument-based auto-approval recipes', () => { - expect( - Object.fromEntries( - KNOWN_CLIS.map(({ id, autoApprove }) => [id, autoApprove]), - ), - ).toEqual({ - copilot: { - args: ['--allow-all'], - position: 'after-acp', - }, - claude: null, - gemini: { - args: ['--approval-mode=yolo'], - position: 'after-acp', - }, - codex: null, - qwen: { - args: ['--approval-mode=yolo'], - position: 'after-acp', - }, - kimi: { - args: ['--yolo'], - position: 'before-acp', - }, - opencode: null, - cursor: { - args: ['--yolo'], - position: 'before-acp', - }, - codebuddy: null, - hermes: null, - }); - - expect( - Object.fromEntries( - KNOWN_CLIS.filter((cli) => cli.autoApprove).map((cli) => { - const approval = cli.autoApprove; - if (!approval) throw new Error(`Missing recipe for ${cli.id}`); - const args = - approval.position === 'before-acp' - ? [...approval.args, ...cli.acpArgs] - : [...cli.acpArgs, ...approval.args]; - return [cli.id, [cli.binary, ...args].join(' ')]; - }), - ), - ).toEqual({ - copilot: 'copilot --acp --allow-all', - gemini: 'gemini --acp --approval-mode=yolo', - qwen: 'qwen --acp --approval-mode=yolo', - kimi: 'kimi --yolo acp', - cursor: 'agent --yolo acp', - }); - }); -}); + it('compiles trusted terminal-style commands', () => { + expect(compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'copilot', + options: { autoApprove: true }, + })).toEqual({ kind: 'shell', command: 'copilot --acp --allow-all' }) + expect(compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'kimi', + options: { autoApprove: true }, + })).toEqual({ kind: 'shell', command: 'kimi --yolo acp' }) + expect(compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'claude', + })).toEqual({ kind: 'shell', command: 'claude-agent-acp' }) + }) +}) diff --git a/external/agentlet/packages/local/tests/daemon-integration.test.ts b/external/agentlet/packages/local/tests/daemon-integration.test.ts index 8a80c99bc..958f92fe9 100644 --- a/external/agentlet/packages/local/tests/daemon-integration.test.ts +++ b/external/agentlet/packages/local/tests/daemon-integration.test.ts @@ -139,7 +139,10 @@ describe('agentlet daemon integration', () => { agentletId: 'machine-a', agentletProfile: { machine: { hostname: hostname(), platform: platform(), arch: arch() }, - capabilities: { harnessDiscovery: { version: 1 } }, + capabilities: { + harnessDiscovery: { version: 2 }, + harnessLaunch: { version: 2 }, + }, }, }) diff --git a/external/agentlet/packages/local/tests/harness-launch.test.ts b/external/agentlet/packages/local/tests/harness-launch.test.ts index 222c82dc1..9e01e555f 100644 --- a/external/agentlet/packages/local/tests/harness-launch.test.ts +++ b/external/agentlet/packages/local/tests/harness-launch.test.ts @@ -1,53 +1,43 @@ import { describe, expect, it } from 'vitest' -import { parseAcpHarnessLaunch, CUSTOM_COMMAND_WRAPPER_ID, CUSTOM_COMMAND_CAPABILITIES } from '@agentlet/protocol' -import { KNOWN_CLIS } from '../src/harnesses/catalogue.js' -import { Harness, buildHarnessLaunch, resolveHarnessLaunch } from '../src/harnesses/harness.js' +import { parseAcpHarnessLaunch } from '@agentlet/protocol' +import { compileHarnessLaunch } from '../src/harnesses/harness.js' describe('typed ACP harness launch', () => { - it.each(KNOWN_CLIS)('retains the existing $id ACP preset exactly', (entry) => { - const harness = Harness.get(entry.id) - expect(harness.buildLaunch()).toEqual({ - kind: 'exec', executable: entry.binary, argv: entry.acpArgs, env: {}, + it('compiles known and Custom launch intent through the shell boundary', () => { + expect(compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'copilot', + options: { autoApprove: true }, + })).toEqual({ kind: 'shell', command: 'copilot --acp --allow-all' }) + expect(compileHarnessLaunch({ + kind: 'acp-command', + command: 'copilot --acp && echo explicitly-authorized', + })).toEqual({ + kind: 'shell', + command: 'copilot --acp && echo explicitly-authorized', }) - expect(harness.describeCapabilities()).toEqual({ - autoApprove: entry.autoApprove ? 'supported' : 'unsupported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', - customLaunchCommand: 'unsupported', - }) - expect(harness.buildLaunch({ autoApprove: false })).toEqual(harness.buildLaunch()) - if (entry.autoApprove) { - const built = harness.buildLaunch({ autoApprove: true }) - expect(built.kind === 'exec' && built.argv).toEqual( - entry.autoApprove.position === 'before-acp' - ? [...entry.autoApprove.args, ...entry.acpArgs] - : [...entry.acpArgs, ...entry.autoApprove.args], - ) - } else { - expect(() => harness.buildLaunch({ autoApprove: true })).toThrow('does not support') - } }) - it('defers model intent to ACP without native flags or shell interpretation', () => { - const model = 'custom model; $(not-a-command) "quoted"' - for (const id of ['claude', 'codex', 'copilot']) { - const harness = Harness.get(id) - expect(harness.buildLaunch({ model })).toEqual({ - ...harness.buildLaunch(), - initialPreferences: { model }, - }) + it('validates but ignores legacy persisted plans', () => { + const launch = { + kind: 'acp-harness', + harnessId: 'copilot', + options: { autoApprove: true }, + } + const plan = { + version: 1 as const, + executable: 'old-copilot', + argv: ['--old'], + env: { OLD: 'value' }, } - expect(Harness.get('claude').buildLaunch()).toMatchObject({ - executable: 'claude-agent-acp', argv: [], + expect(compileHarnessLaunch(launch, plan)).toEqual({ + kind: 'shell', + command: 'copilot --acp --allow-all', }) - }) - - it('does not expose mutable catalogue arrays', () => { - const built = Harness.get('copilot').buildLaunch({ autoApprove: true }) - if (built.kind === 'exec') built.argv.push('--untrusted') - const next = Harness.get('copilot').buildLaunch({ autoApprove: true }) - expect(next.kind === 'exec' && next.argv) - .toEqual(['--acp', '--allow-all']) + expect(() => compileHarnessLaunch(launch, { + ...plan, + version: 2 as never, + })).toThrow('Invalid legacy') }) it.each([ @@ -55,49 +45,24 @@ describe('typed ACP harness launch', () => { { kind: 'native-print', harnessId: 'copilot' }, { kind: 'acp-harness', harnessId: 'copilot', executable: 'other' }, { kind: 'acp-harness', harnessId: 'copilot', options: { argv: ['--other'] } }, - { kind: 'acp-harness', harnessId: 'copilot', options: { model: 'not-a-launch-flag' } }, - { kind: 'acp-harness', harnessId: 'claude', options: { noSave: true } }, { kind: 'acp-harness', harnessId: 'copilot', options: { autoApprove: 'true' } }, ])('rejects unsupported or malformed structured input %j', (launch) => { expect(() => parseAcpHarnessLaunch(launch)).toThrow() }) - it('validates identity locally and rejects altered persisted plans instead of executing them', () => { - expect(() => Harness.get('not-known')).toThrow('Unknown harness') - const launch = { kind: 'acp-harness', harnessId: 'copilot', options: { autoApprove: true } } - const plan = resolveHarnessLaunch(launch) - expect(resolveHarnessLaunch(launch, plan)).toEqual(plan) - for (const changed of [ - { ...plan, executable: 'untrusted' }, - { ...plan, argv: [...plan.argv, 'a; echo injected'] }, - { ...plan, env: { UNTRUSTED: 'value' } }, - ]) { - expect(() => resolveHarnessLaunch(launch, changed)).toThrow('reauthorization') - } - expect(() => resolveHarnessLaunch({ ...launch, options: {} }, plan)).toThrow('reauthorization') - }) - - it('maps legacy commands only to custom without inferring a known wrapper', async () => { - const custom = Harness.get(CUSTOM_COMMAND_WRAPPER_ID) - expect(custom.describeCapabilities()).toEqual(CUSTOM_COMMAND_CAPABILITIES) - expect(Object.isFrozen(CUSTOM_COMMAND_CAPABILITIES)).toBe(true) - expect(custom.describeCapabilities()).toEqual({ - customLaunchCommand: 'supported', autoApprove: 'unsupported', - modelOverride: 'unsupported', sessionPersistence: 'unsupported', - }) - expect(await custom.detect({ prepareWorkspaces: true })).toMatchObject({ - id: 'custom', installed: false, launchPreviewVersion: 1, - }) - expect(buildHarnessLaunch({ launch: { kind: 'acp-command', command: 'copilot --acp && echo trusted' } })) - .toEqual({ kind: 'shell', command: 'copilot --acp && echo trusted' }) - for (const intent of [{ autoApprove: false }, { model: 'model' }, { sessionPersistence: false }]) { - expect(() => custom.buildLaunch({ customLaunchCommand: 'agent', ...intent })).toThrow() - } - expect(() => Harness.get('copilot').buildLaunch({ customLaunchCommand: 'agent' })).toThrow() - expect(() => buildHarnessLaunch({ launch: { kind: 'acp-harness', harnessId: 'custom' } })).toThrow() - expect(() => buildHarnessLaunch({ launch: { kind: 'acp-command', command: ' ' } })).toThrow() - expect(() => buildHarnessLaunch({ launch: { kind: 'acp-command', command: 'agent', options: { autoApprove: true } } })).toThrow() - expect(buildHarnessLaunch({ launch: { kind: 'acp-harness', harnessId: 'copilot', options: { autoApprove: true } } })) - .toEqual({ kind: 'exec', executable: 'copilot', argv: ['--acp', '--allow-all'], env: {} }) + it('rejects unsupported approval and invalid identities', () => { + expect(() => compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'claude', + options: { autoApprove: true }, + })).toThrow('does not support') + expect(() => compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'custom', + })).toThrow('explicit ACP command') + expect(() => compileHarnessLaunch({ + kind: 'acp-harness', + harnessId: 'unknown', + })).toThrow('Unknown harness') }) }) diff --git a/external/agentlet/packages/local/tests/harnesses.test.ts b/external/agentlet/packages/local/tests/harnesses.test.ts index 4240e8476..3b8326e3b 100644 --- a/external/agentlet/packages/local/tests/harnesses.test.ts +++ b/external/agentlet/packages/local/tests/harnesses.test.ts @@ -21,7 +21,7 @@ vi.mock('node:os', async (importOriginal) => ({ ...await importOriginal(), platform: mocks.platform, homedir: mocks.home, })) -import { KNOWN_CLIS } from '../src/harnesses/catalogue.js' +import { HARNESS_DEFINITIONS } from '../src/harnesses/registry.js' import { discoverHarnesses, parseHarnessDiscoveryParams } from '../src/harnesses/detect.js' import { prepareHarnessWorkspace } from '../src/harnesses/workspace.js' import { Agentlet } from '../src/agentlet.js' @@ -41,15 +41,17 @@ beforeEach(() => { describe('trusted harness discovery', () => { it('returns the complete stable catalogue without creating workspaces by default', async () => { const { harnesses } = await discoverHarnesses() - expect(harnesses.map((entry) => entry.id)).toEqual([...KNOWN_CLIS.map((entry) => entry.id), 'custom']) + expect(harnesses.map((entry) => entry.id)).toEqual(HARNESS_DEFINITIONS.map((entry) => entry.id)) expect(harnesses).toHaveLength(11) - expect(harnesses.filter((entry) => entry.id !== 'custom').every((entry) => entry.installed)).toBe(true) - expect(harnesses.filter((entry) => entry.id !== 'custom').every((entry) => entry.launchVersion === 1)).toBe(true) - expect(harnesses.at(-1)).toMatchObject({ id: 'custom', installed: false }) + expect(harnesses.every((entry) => entry.status === 'ready')).toBe(true) + expect(harnesses.at(-1)).toMatchObject({ + id: 'custom', + capabilities: { customLaunchCommand: true, autoApprove: false }, + }) expect(mocks.probe.mock.calls.some(([, args]) => args.includes('custom'))).toBe(false) expect(harnesses.every((entry) => !('skipVersionProbe' in entry))).toBe(true) expect(harnesses.every((entry) => !entry.workingDirPath)).toBe(true) - expect(harnesses[0]).toMatchObject({ executablePath: '/usr/local/bin/copilot', version: '1.2.3' }) + expect(harnesses[0]).toMatchObject({ status: 'ready', version: '1.2.3' }) expect(mocks.mkdir).not.toHaveBeenCalled() for (const [file, , options] of mocks.probe.mock.calls) { expect(file).not.toBe('sh') @@ -59,12 +61,12 @@ describe('trusted harness discovery', () => { it('never invokes adapters that skip the optional version probe', async () => { const { harnesses } = await discoverHarnesses() - expect(KNOWN_CLIS.filter((entry) => entry.skipVersionProbe).map((entry) => entry.id)) - .toEqual(['claude', 'codex', 'hermes']) - for (const cli of KNOWN_CLIS.filter((entry) => entry.skipVersionProbe)) { - expect(mocks.probe).not.toHaveBeenCalledWith(`/usr/local/bin/${cli.binary}`, ['--version'], expect.anything()) - expect(harnesses.find((entry) => entry.id === cli.id)?.version).toBeUndefined() + for (const command of ['claude-agent-acp', 'codex-acp', 'hermes']) { + expect(mocks.probe).not.toHaveBeenCalledWith(`/usr/local/bin/${command}`, ['--version'], expect.anything()) } + expect(harnesses.find((entry) => entry.id === 'claude')?.version).toBeUndefined() + expect(harnesses.find((entry) => entry.id === 'codex')?.version).toBeUndefined() + expect(harnesses.find((entry) => entry.id === 'hermes')?.version).toBeUndefined() }) it('distinguishes a missing binary from a failed or timed-out PATH lookup', async () => { @@ -74,8 +76,7 @@ describe('trusted harness discovery', () => { throw Object.assign(new Error('lookup executable missing'), { code: 'ENOENT' }) }) const { harnesses } = await discoverHarnesses({ prepareWorkspaces: true }) - expect(harnesses.every((entry) => !entry.installed)).toBe(true) - expect(harnesses.every((entry) => entry.launchVersion === undefined)).toBe(true) + expect(harnesses.filter((entry) => entry.id !== 'custom').every((entry) => entry.status === 'not-found')).toBe(true) expect(harnesses[0]?.diagnostics?.[0]?.code).toBe('binary_missing') expect(harnesses.find((entry) => entry.id === 'gemini')?.diagnostics?.[0]?.code).toBe('lookup_failed') expect(harnesses.find((entry) => entry.id === 'qwen')?.diagnostics?.[0]?.code).toBe('lookup_failed') @@ -90,26 +91,26 @@ describe('trusted harness discovery', () => { }) const { harnesses } = await discoverHarnesses({ prepareWorkspaces: true }) expect(harnesses[0]).toMatchObject({ - installed: true, + status: 'ready', workingDirPath: join('/home/agentlet-test', '.agentlet', 'workspace', 'copilot'), diagnostics: [{ code: outcome ? 'version_probe_failed' : 'version_unknown', message: expect.any(String) }], }) expect(harnesses[0]?.version).toBeUndefined() }) - it('supports Windows lookup without a shell and probes the first absolute result', async () => { + it('supports Windows native executables and probes through the platform shell', async () => { mocks.platform.mockReturnValue('win32') mocks.probe.mockImplementation(async (file: string, args: string[]) => ({ stdout: file === 'where.exe' ? `C:\\Tools\\${args[0]}.exe\r\nD:\\Other\\${args[0]}.exe\r\n` : '2.0\r\n', })) expect((await discoverHarnesses()).harnesses[0]).toMatchObject({ - executablePath: 'C:\\Tools\\copilot.exe', installed: true, version: '2.0', launchVersion: 1, + status: 'ready', version: '2.0', }) - expect(mocks.probe).toHaveBeenCalledWith('C:\\Tools\\copilot.exe', ['--version'], expect.objectContaining({ shell: false })) + expect(mocks.probe).toHaveBeenCalledWith('cmd.exe', ['/d', '/s', '/c', 'copilot --version'], expect.objectContaining({ shell: false })) }) - it.each(['cmd', 'CMD', 'bat', 'BAT', 'ps1', ''])( - 'preserves Windows shim discovery without opting %s into shell-free launch', async (extension) => { + it.each(['cmd', 'CMD', 'bat', 'BAT'])( + 'treats Windows platform-shell .%s wrappers as ready', async (extension) => { mocks.platform.mockReturnValue('win32') mocks.probe.mockImplementation(async (file: string, args: string[]) => ({ stdout: file === 'where.exe' @@ -117,19 +118,28 @@ describe('trusted harness discovery', () => { : '1.0\r\n', })) const { harnesses } = await discoverHarnesses() - expect(harnesses.filter((entry) => entry.id !== 'custom').every((entry) => entry.installed)).toBe(true) - expect(harnesses.every((entry) => entry.launchVersion === undefined)).toBe(true) + expect(harnesses.filter((entry) => entry.id !== 'custom').every((entry) => entry.status === 'ready')).toBe(true) expect(harnesses[0]).toMatchObject({ - binary: 'copilot', acpArgs: ['--acp'], - autoApprove: { args: ['--allow-all'], position: 'after-acp' }, + status: 'ready', + capabilities: { autoApprove: true, customLaunchCommand: false }, }) }, ) + it('ignores a leading extensionless npm shim when a later .cmd target is shell-ready', async () => { + mocks.platform.mockReturnValue('win32') + mocks.probe.mockImplementation(async (file: string, args: string[]) => ({ + stdout: file === 'where.exe' + ? `C:\\Tools\\${args[0]}\r\nC:\\Tools\\${args[0]}.cmd\r\n` + : '1.0\r\n', + })) + expect((await discoverHarnesses()).harnesses[0]).toMatchObject({ status: 'ready' }) + }) + it('does not trust malformed lookup output', async () => { mocks.probe.mockResolvedValue({ stdout: 'relative-path' }) expect((await discoverHarnesses()).harnesses[0]).toMatchObject({ - installed: false, diagnostics: [{ code: 'lookup_failed', message: expect.any(String) }], + status: 'not-found', diagnostics: [{ code: 'lookup_failed', message: expect.any(String) }], }) }) @@ -148,7 +158,7 @@ describe('trusted harness discovery', () => { mocks.mkdir.mockRejectedValue(Object.assign(new Error('access denied'), { code: 'EACCES' })) const { harnesses } = await discoverHarnesses({ prepareWorkspaces: true }) expect(harnesses[0]).toMatchObject({ - installed: true, diagnostics: [{ code: 'workspace_failed', message: 'access denied' }], + status: 'ready', diagnostics: [{ code: 'workspace_failed', message: 'access denied' }], }) expect(harnesses[0]?.workingDirPath).toBeUndefined() }) @@ -163,7 +173,7 @@ describe('trusted harness discovery', () => { describe('daemon discovery RPC', () => { function createDaemon() { const daemon = new Agentlet({ - server: 'wss://example.test', token: 'test', reconnectMax: 1, + server: 'wss://example.test', token: 'test', agentletId: 'test-agentlet', reconnectMax: 1, bufferLimit: 10, heartbeat: 0, allowInsecure: false, logLevel: 'error', maxAgents: 10, }, new Logger('error')) const responses: JsonRpcMessage[] = [] @@ -203,30 +213,6 @@ describe('daemon discovery RPC', () => { expect(mocks.probe).not.toHaveBeenCalled() }) - it.each([ - [{ kind: 'acp-command', command: 'copilot --acp' }, { kind: 'shell', command: 'copilot --acp' }], - [{ kind: 'acp-harness', harnessId: 'copilot', options: { autoApprove: true } }, - { kind: 'exec', executable: 'copilot', argv: ['--acp', '--allow-all'], env: {} }], - ])('previews %j without probing, workspace preparation or spawning', async (launch, result) => { - const start = vi.spyOn(AgentProcess.prototype, 'start') - try { - expect(await createDaemon().request(ServerMethods.BUILD_HARNESS_LAUNCH, { launch })).toMatchObject({ result }) - expect(start).not.toHaveBeenCalled() - expect(mocks.probe).not.toHaveBeenCalled() - expect(mocks.mkdir).not.toHaveBeenCalled() - } finally { start.mockRestore() } - }) - - it.each([undefined, {}, { launch: { kind: 'acp-harness', harnessId: 'unknown' } }, - { launch: { kind: 'acp-harness', harnessId: 'claude', options: { autoApprove: true } } }, - { launch: { kind: 'acp-command', command: 'agent', options: {} } }, - { launch: { kind: 'acp-command', command: 'agent' }, cwd: '/work' }, - ])('rejects invalid preview %j without side effects', async (params) => { - expect(await createDaemon().request(ServerMethods.BUILD_HARNESS_LAUNCH, params)).toMatchObject({ error: { code: -32602 } }) - expect(mocks.probe).not.toHaveBeenCalled() - expect(mocks.mkdir).not.toHaveBeenCalled() - }) - it.each([ null, 'not-an-object', diff --git a/external/agentlet/packages/protocol/src/constants.ts b/external/agentlet/packages/protocol/src/constants.ts index a9010fb84..a93242885 100644 --- a/external/agentlet/packages/protocol/src/constants.ts +++ b/external/agentlet/packages/protocol/src/constants.ts @@ -27,7 +27,6 @@ export const ServerMethods = { LIST: 'server/list', SEND_RESOURCE: 'server/sendResource', DISCOVER_HARNESSES: 'server/discoverHarnesses', - BUILD_HARNESS_LAUNCH: 'server/buildHarnessLaunch', } as const /** Error codes used in agent/hello rejection */ diff --git a/external/agentlet/packages/protocol/src/harness.ts b/external/agentlet/packages/protocol/src/harness.ts index 0d9c91781..7c0355e6a 100644 --- a/external/agentlet/packages/protocol/src/harness.ts +++ b/external/agentlet/packages/protocol/src/harness.ts @@ -1,21 +1,13 @@ -/** Capabilities describe this catalogue entry's ACP transport, not its native CLI. */ -export type HarnessCapabilityStatus = 'supported' | 'unsupported' | 'unknown' - export interface HarnessCapabilities { - /** Absent on older daemons; absence is not evidence of support. */ - customLaunchCommand?: HarnessCapabilityStatus - autoApprove: HarnessCapabilityStatus - modelOverride: HarnessCapabilityStatus - sessionPersistence: HarnessCapabilityStatus + customLaunchCommand: boolean + autoApprove: boolean } export const CUSTOM_COMMAND_WRAPPER_ID = 'custom' as const export const CUSTOM_COMMAND_CAPABILITIES = Object.freeze({ - customLaunchCommand: 'supported', - autoApprove: 'unsupported', - modelOverride: 'unsupported', - sessionPersistence: 'unsupported', + customLaunchCommand: true, + autoApprove: false, } as const satisfies HarnessCapabilities) export interface HarnessLaunchOptions { @@ -30,15 +22,7 @@ export interface AcpHarnessLaunch { export type AgentProfileLaunch = AcpHarnessLaunch | { kind: 'acp-command'; command: string } -export interface BuildHarnessLaunchParams { - launch: AgentProfileLaunch -} - -export type HarnessLaunchPreview = - | { kind: 'exec'; executable: string; argv: string[]; env: Record } - | { kind: 'shell'; command: string } - -/** Catalogue-resolved process arguments. Never interpreted by a shell. */ +/** Legacy persisted launch evidence. New executions compile from launch intent. */ export interface HarnessLaunchPlan { version: 1 executable: string @@ -59,28 +43,6 @@ export function parseAgentProfileLaunch(value: unknown): AgentProfileLaunch { return parseAcpHarnessLaunch(value) } -export function parseBuildHarnessLaunchParams(value: unknown): BuildHarnessLaunchParams { - if (!object(value) || Object.keys(value).some((key) => key !== 'launch')) { - throw new Error('Expected only a Profile launch') - } - return { launch: parseAgentProfileLaunch(value.launch) } -} - -export function parseHarnessLaunchPreview(value: unknown): HarnessLaunchPreview { - const text = (v: unknown): v is string => typeof v === 'string' && !v.includes('\0') - if (object(value)) { - if (value.kind === 'shell' && Object.keys(value).every((key) => ['kind', 'command'].includes(key)) && - text(value.command) && value.command.trim()) return { kind: 'shell', command: value.command } - if (value.kind === 'exec' && Object.keys(value).every((key) => ['kind', 'executable', 'argv', 'env'].includes(key)) && - text(value.executable) && value.executable.trim() && value.executable.length <= 4096 && - Array.isArray(value.argv) && value.argv.length <= 128 && value.argv.every((arg) => text(arg) && arg.length <= 4096) && - object(value.env) && Object.entries(value.env).every(([key, val]) => text(key) && key.length <= 256 && text(val) && val.length <= 4096)) { - return { kind: 'exec', executable: value.executable, argv: [...value.argv], env: { ...value.env } as Record } - } - } - throw new Error('Invalid harness launch preview') -} - /** Strict portable validation; the daemon separately checks its own catalogue. */ export function parseAcpHarnessLaunch(value: unknown): AcpHarnessLaunch { if (!object(value) || value.kind !== 'acp-harness' || diff --git a/external/agentlet/packages/protocol/src/index.ts b/external/agentlet/packages/protocol/src/index.ts index 413a75504..8438fc09e 100644 --- a/external/agentlet/packages/protocol/src/index.ts +++ b/external/agentlet/packages/protocol/src/index.ts @@ -11,15 +11,12 @@ export { ErrorCodes, } from './constants.js' -export { parseAcpHarnessLaunch, parseAgentProfileLaunch, parseBuildHarnessLaunchParams, parseHarnessLaunchPreview } from './harness.js' +export { parseAcpHarnessLaunch, parseAgentProfileLaunch } from './harness.js' export { CUSTOM_COMMAND_WRAPPER_ID, CUSTOM_COMMAND_CAPABILITIES } from './harness.js' export type { AgentProfileLaunch, - BuildHarnessLaunchParams, - HarnessLaunchPreview, AcpHarnessLaunch, HarnessCapabilities, - HarnessCapabilityStatus, HarnessLaunchOptions, HarnessLaunchPlan, } from './harness.js' diff --git a/external/agentlet/packages/protocol/src/messages.ts b/external/agentlet/packages/protocol/src/messages.ts index 4029320e1..61ad54845 100644 --- a/external/agentlet/packages/protocol/src/messages.ts +++ b/external/agentlet/packages/protocol/src/messages.ts @@ -23,9 +23,8 @@ export interface AgentletProfile { autoRestart: boolean bufferLimit: number maxAgents?: number - harnessDiscovery?: { version: 1 } - harnessLaunch?: { version: 1 } - harnessLaunchPreview?: { version: 1 } + harnessDiscovery?: { version: 1 | 2 } + harnessLaunch?: { version: 1 | 2 } } } @@ -90,7 +89,7 @@ export interface SessionSpec { command?: string /** Structured alternative to command; requires harnessLaunch v1. */ launch?: AcpHarnessLaunch - /** Previously authorized plan. A mismatch with the local catalogue fails closed. */ + /** Legacy persisted evidence. Version 2 daemons validate then ignore it. */ launchPlan?: HarnessLaunchPlan /** Working directory for the agent subprocess */ cwd?: string @@ -278,20 +277,12 @@ export interface SendResourceParams { export interface HarnessCatalogueEntry { id: string displayName: string - binary: string - acpArgs: string[] - autoApprove: { args: string[]; position: 'before-acp' | 'after-acp' } | null installHint: string + capabilities: HarnessCapabilities } export interface HarnessDiscoveryEntry extends HarnessCatalogueEntry { - /** Structured ACP launch support; absent on older daemons. */ - launchVersion?: 1 - launchPreviewVersion?: 1 - /** Absent on older daemons; absence is not evidence of support. */ - capabilities?: HarnessCapabilities - installed: boolean - executablePath?: string + status: 'ready' | 'adapter-missing' | 'not-found' version?: string workingDirPath?: string diagnostics?: Array<{ code: string; message: string }> diff --git a/external/agentlet/spec/protocol.md b/external/agentlet/spec/protocol.md index 77960208e..bacb7ca94 100644 --- a/external/agentlet/spec/protocol.md +++ b/external/agentlet/spec/protocol.md @@ -83,23 +83,20 @@ Both hello methods are requests and require a matching JSON-RPC response before | `server/stop` | Request | Stop one managed agent session. | | `server/list` | Request | List the daemon's active agents. | | `server/discoverHarnesses` | Request | Discover the daemon's static ACP harness catalogue, optionally preparing local workspaces. | -| `server/buildHarnessLaunch` | Request | Compile a Profile launch without probing, spawning, or preparing workspaces. | | `server/sendResource` | Notification | Write a host-provided resource through the daemon environment registry. | | `server/replay` | Notification | Replay Gateway-to-daemon messages buffered during disconnection. | | `server/ping` | Notification | Application-level heartbeat request. | | `server/shutdown` | Notification | Ask the daemon to stop gracefully. | -`server/discoverHarnesses` accepts omitted params, `{}`, or `{ "prepareWorkspaces": boolean }`; every other option and invalid request shape is rejected with `-32602`. The advertised `AgentletProfile.capabilities.harnessDiscovery` is `{ version: 1 }`. Unsupported daemons must not be inferred to support discovery. +`server/discoverHarnesses` accepts omitted params, `{}`, or `{ "prepareWorkspaces": boolean }`; every other option and invalid request shape is rejected with `-32602`. The advertised `AgentletProfile.capabilities.harnessDiscovery` is `{ version: 2 }`. Unsupported daemons must not be inferred to support discovery. -Discovery includes a final `custom` descriptor for manual selection, with `installed: false` and no executable probe or workspace preparation. Hosts must not auto-provision it. Entries may include `launchPreviewVersion: 1` and `capabilities.customLaunchCommand` (`supported`, `unsupported`, or `unknown`); older responses may omit these fields. Custom supports only custom commands, while known wrappers do not support command overrides. +Discovery includes a final `custom` descriptor for manual selection, with `status: "ready"` and no executable probe or workspace preparation. Hosts must not auto-provision it. Capabilities are required booleans: Custom supports only `customLaunchCommand`, while known Definitions may support `autoApprove` and do not support command overrides. -`server/buildHarnessLaunch` requires `AgentletProfile.capabilities.harnessLaunchPreview: { version: 1 }`. Its only parameter is `{ launch }`, where launch is the unchanged Profile union `{ kind: 'acp-command', command }` or `{ kind: 'acp-harness', harnessId, options?: { autoApprove?: boolean } }`. A legacy command maps to Custom without inspecting its text or metadata. A structured launch maps to its known catalogue wrapper; `harnessId: 'custom'` is invalid. The response is `{ kind: 'exec', executable, argv, env }` or `{ kind: 'shell', command }`. Compilation is pure and shares runtime wrapper logic; it does not resolve PATH, create directories, test credentials, or start ACP. Unknown fields, malformed input, unknown wrappers, and unsupported options fail with `-32602`. No model launch option is introduced. Gateways validate request and response and reject old daemons explicitly rather than computing a local fallback. +The result is `{ harnesses: HarnessDiscoveryEntry[] }`, including the complete Definition registry in stable order. Each entry contains `id`, `displayName`, `installHint`, `capabilities: { autoApprove, customLaunchCommand }`, and `status: "ready" | "adapter-missing" | "not-found"`, with optional `version`, `workingDirPath`, and `diagnostics: Array<{ code, message }>`. -The result is `{ harnesses: HarnessDiscoveryEntry[] }`, including the complete catalogue in stable order. Each entry contains `id`, `displayName`, `binary`, `acpArgs`, `autoApprove`, `installHint`, and `installed`, with optional `executablePath`, `version`, `workingDirPath`, and `diagnostics: Array<{ code, message }>`. `autoApprove` is either `null` or `{ args: string[], position: "before-acp" | "after-acp" }`. Skip-version rules are internal catalogue data and are not returned. +Discovery is read-only unless `prepareWorkspaces` is explicitly true. PATH lookup uses bounded `execFile` calls. Windows scans every `where.exe` result and accepts absolute `.exe`, `.com`, `.cmd`, and `.bat` candidates; Unix requires an absolute `which` result. Optional version probing uses `cmd.exe` for Windows wrappers and shell-free execution on Unix. Version failures produce `version_unknown` or `version_probe_failed` while retaining `status: "ready"`. Discovery never installs tools, copies skills or prompts, provisions credentials, or starts an ACP session. -Discovery is read-only unless `prepareWorkspaces` is explicitly true. Probes use shell-free `execFile` calls with a 2.5-second timeout and bounded output. PATH lookup distinguishes `binary_missing` from `lookup_failed`; optional version failures produce `version_unknown` or `version_probe_failed` while retaining `installed: true`. Known interactive adapters are never invoked for version detection. Discovery never installs tools, copies skills or prompts, provisions credentials, or starts an ACP session. - -With preparation enabled, only installed entries receive reusable directories under the daemon's own `homedir()/.agentlet/workspace/`. Neither roots nor IDs are supplied remotely. Directory creation never clears existing data; failure returns `workspace_failed` without `workingDirPath` and without a fallback path. Installation state remains independent of workspace readiness. +With preparation enabled, only ready non-Custom entries receive reusable directories under the daemon's own `homedir()/.agentlet/workspace/`. Neither roots nor IDs are supplied remotely. Directory creation never clears existing data; failure returns `workspace_failed` without `workingDirPath` and without a fallback path. The retired `agent-team/*` RPCs return unknown-method errors; there is no setup worker or progress notification. @@ -107,9 +104,9 @@ All JSON-RPC envelopes and method payloads are defined in [`messages.ts`](../pac ## 4. Spawn and bootstrap -`server/spawn` includes a host correlation `appId`, an optional `workloadType` (`Job` or `Deployment`) used only for aggregate diagnostics, an optional native ACP `sessionId`, and a `sessionSpec`. +`server/spawn` includes a host correlation `appId`, an optional `workloadType` (`Job` or `Deployment`) used only for aggregate diagnostics, an optional native ACP `sessionId`, and a `sessionSpec`. The daemon advertises `capabilities.harnessLaunch: { version: 2 }`. -The daemon uses the required `sessionSpec.command` and optional `sessionSpec.cwd` directly, then launches the process with `shell: true`. The host must therefore send only trusted commands. Any `sessionSpec.agentTeam` field is explicitly rejected with `-32602`, including when a command is also supplied; there is no manifest resolution or silent fallback. +The daemon accepts either trusted `sessionSpec.command` or structured `sessionSpec.launch`. Structured launch selects a registered Definition by `harnessId`, validates bounded options, and compiles a trusted shell command immediately before execution; command launch remains explicit host-authorized shell code. Both use the target platform shell. Historical optional `sessionSpec.launchPlan` data is validated then ignored and is never executable input. Any `sessionSpec.agentTeam` field is explicitly rejected with `-32602`; there is no manifest resolution or silent fallback. For a fresh session the daemon performs: @@ -164,10 +161,10 @@ The native ACP `sessionId` is established by session bootstrap and is the routin - Production connections require `wss://`; `--allow-insecure` permits `ws://` only when explicitly requested. - The Gateway authenticates both control and session connections before accepting hello. - Agent commands run with the daemon process's operating-system permissions. -- `sessionSpec.command` uses a shell and is trusted control-plane input. +- Both compiled known-harness commands and explicit Custom commands use the target platform shell. Known commands are built only from trusted static Definition tokens and bounded options; Custom commands are trusted control-plane input. - Resource destinations are resolved through the daemon environment registry. -The legacy Custom shell spawn carries a narrowly scoped `codeql[js/command-line-injection]` annotation because executing host-authorized shell code is its intended capability, including pipelines and custom launch scripts. This is not a sanitizer, an executable allow-list, a sandbox, or proof of interactive confirmation: the host must authorize commands for the target machine and must not interpolate prompts or other untrusted content into them. Structured harness launches remain shell-free. The annotation requires compatible alert-suppression analysis and alert handling; adding it alone does not guarantee dismissal in GitHub code scanning. +The Custom shell spawn carries a narrowly scoped `codeql[js/command-line-injection]` annotation because executing host-authorized shell code is its intended capability, including pipelines and custom launch scripts. This is not a sanitizer, an executable allow-list, a sandbox, or proof of interactive confirmation: the host must authorize commands for the target machine and must not interpolate prompts or other untrusted content into them. Known Definitions share shell execution but compile only trusted fixed tokens and bounded options. The annotation requires compatible alert-suppression analysis and alert handling; adding it alone does not guarantee dismissal in GitHub code scanning. ## 9. Resource distribution @@ -188,6 +185,6 @@ The host-agnostic Reachback contract is documented in [`agent-reachback.md`](age | Hello, lifecycle, spawn, replay, and resource payloads | [`packages/protocol/src/messages.ts`](../packages/protocol/src/messages.ts) | | Shared Gateway-facing connection types | [`packages/protocol/src/gateway-types.ts`](../packages/protocol/src/gateway-types.ts) | | Daemon implementation | [`packages/local/src/agentlet.ts`](../packages/local/src/agentlet.ts) | -| Trusted harness catalogue and probes | [`packages/local/src/harnesses/catalogue.ts`](../packages/local/src/harnesses/catalogue.ts), [`detect.ts`](../packages/local/src/harnesses/detect.ts) | +| Harness Definitions, registry, and probes | [`packages/local/src/harnesses/registry.ts`](../packages/local/src/harnesses/registry.ts), [`detect.ts`](../packages/local/src/harnesses/detect.ts), [`common/command-discovery.ts`](../packages/local/src/harnesses/common/command-discovery.ts) | | Daemon-owned reusable workspaces | [`packages/local/src/harnesses/workspace.ts`](../packages/local/src/harnesses/workspace.ts) | | WebSocket client and reconnect behavior | [`packages/local/src/ws-client.ts`](../packages/local/src/ws-client.ts) | From 7f436d722e7346471f29a4d7b29e99fa7ee4727d Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Thu, 8 Oct 2026 00:39:52 +0000 Subject: [PATCH 02/36] fix(agenetes): recover from frozen harness intent Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agenetes/README.md | 8 +- .../packages/acp-driver/src/handle.ts | 26 ++--- .../packages/acp-driver/src/placement.test.ts | 9 +- .../src/session-self-repair.test.ts | 6 +- .../acp-driver/src/session-state.test.ts | 4 +- .../packages/acp-driver/src/session.ts | 19 +-- .../acp-driver/src/spawn-orchestrator.ts | 14 --- .../agentlet-gateway/src/gateway.test.ts | 109 +----------------- .../packages/agentlet-gateway/src/gateway.ts | 45 +------- .../src/harness-discovery.test.ts | 90 +++------------ .../agentlet-gateway/src/harness-discovery.ts | 89 ++------------ .../packages/agentlet-gateway/src/index.ts | 2 - 12 files changed, 56 insertions(+), 365 deletions(-) diff --git a/external/agenetes/README.md b/external/agenetes/README.md index 34a826355..ed610de98 100644 --- a/external/agenetes/README.md +++ b/external/agenetes/README.md @@ -79,13 +79,13 @@ New Profiles start with `revision: 0` and `executionRevision: 0`. Both fields re The ACP driver accepts optional `profileExecutionRevision` on its spec, separately from the process recipe. Profile lowering propagates snapshot execution revisions, and session opening and recovery forward that frozen value to `AcpProfileCachePort.readCommands(profileId, profileExecutionRevision?)`. Hosts compare this identity with their current Profile revision before returning warm-start commands; absent legacy values mean zero. The optional argument preserves compatibility with existing single-argument cache adapters. -Profile lowering carries the structured launch through the ACP recipe to the selected agentlet without manufacturing a command string. The Gateway rejects structured spawning when the daemon does not advertise `harnessLaunch` v1. Profile `initialPreferences` are forwarded to existing ACP model/config preference controls rather than command-line flags; no permission, history, or Job policy is introduced. +Profile lowering carries the structured launch through the ACP recipe to the selected agentlet without manufacturing a command string. The Gateway rejects structured spawning when the daemon does not advertise `harnessLaunch` v2. Profile `initialPreferences` are forwarded to existing ACP model/config preference controls rather than command-line flags; no permission, history, or Job policy is introduced. -Discovery entries optionally carry `launchVersion: 1`, which hosts can use to opt new Profiles and editors into structured launch without looking up a separate connection object. Its absence retains legacy command provisioning. The Gateway validates the discovery field and independently enforces the machine's handshake capability when spawning. +Discovery v2 entries carry `ready`, `adapter-missing`, or `not-found` status plus boolean `autoApprove` and `customLaunchCommand` capabilities. Hosts create typed automatic Profiles only for ready known harnesses; Custom remains manually selectable and is never automatically provisioned. The Gateway validates discovery replies and independently enforces the machine's v2 handshake capability when spawning. -`AgentletGateway.buildHarnessLaunch(agentletId, { launch: AgentProfileLaunch })` targets the explicit machine and requires `capabilities.harnessLaunchPreview.version === 1`, independently from discovery and spawn support. It validates the request and daemon response and returns `{ kind: 'exec', executable, argv, env }` or `{ kind: 'shell', command }`. This read-only daemon compilation never spawns or prepares workspaces; hosts must not manufacture argv. Old daemons fail with `harness_launch_preview_unsupported`, malformed replies with `invalid_harness_launch_preview_response`, and disconnected targets with `agentlet_disconnected`. Discovery's optional `launchPreviewVersion: 1` and `capabilities.customLaunchCommand` are validated without requiring them from old daemons. The `custom` discovery descriptor is manually selectable, never automatically provisioned; only its custom-command capability is supported. +Launch compilation is part of the existing spawn operation; Agenetes has no preview RPC and does not compile commands. Runtime, idle respawn, and native-session repair send the frozen Profile launch intent to the selected Agentlet, where the current matching Definition compiles it for the target platform shell. -After successful structured bootstrap, the ACP driver stores the daemon-resolved `harnessLaunchPlan` in its ordinary durable state, including for empty sessions whose native session ID is not yet recoverable. Recovery, idle respawn, and native-session repair send the plan back for equality validation against the daemon's catalogue; changed arguments fail explicitly. Persistence uses the existing state-report channel, so a crash before the first successful state report can precede plan persistence. The plan pins executable name, argv, and catalogue environment, not binary versions, PATH resolution, inherited environment, or runtime host environment. +Historical optional `harnessLaunchPlan` fields remain accepted by durable-state and binding-recipe parsers but are ignored as executable input. New state snapshots do not write the field. No Profile, workload, or durable-state records are migrated or rewritten. ## The Name: Agenetes / 名称：Agenetes diff --git a/external/agenetes/packages/acp-driver/src/handle.ts b/external/agenetes/packages/acp-driver/src/handle.ts index 78a21e7f9..f14089ec7 100644 --- a/external/agenetes/packages/acp-driver/src/handle.ts +++ b/external/agenetes/packages/acp-driver/src/handle.ts @@ -407,22 +407,16 @@ export class AcpAgentHandle< } await this.authorizeHistoryLoad('recover', turns); - const harnessLaunchPlan = - sourceState?.driverState.harnessLaunchPlan ?? - acpSessionRegistry.get(this.agentletId, this.sessionThreadId) - ?.bindingRecipe?.launchPlan; - const fallbackState = - sourceState?.metadata || harnessLaunchPlan - ? { - driverState: { - initialPreambleDelivered: false, - ...(harnessLaunchPlan ? { harnessLaunchPlan } : {}), - }, - ...(sourceState?.metadata - ? { metadata: sourceState.metadata } - : {}), - } - : undefined; + const fallbackState = sourceState?.metadata + ? { + driverState: { + initialPreambleDelivered: false, + }, + ...(sourceState?.metadata + ? { metadata: sourceState.metadata } + : {}), + } + : undefined; return this.openSession(fallbackState, logger, false); } } diff --git a/external/agenetes/packages/acp-driver/src/placement.test.ts b/external/agenetes/packages/acp-driver/src/placement.test.ts index 974d6df16..9efae9535 100644 --- a/external/agenetes/packages/acp-driver/src/placement.test.ts +++ b/external/agenetes/packages/acp-driver/src/placement.test.ts @@ -93,7 +93,7 @@ describe('explicit ACP placement', () => { ); }); - it('forwards a persisted structured plan and retains it when reusing the live process', async () => { + it('ignores a persisted structured plan and reuses the live process by frozen launch intent', async () => { const launch = { kind: 'acp-harness' as const, harnessId: 'copilot', @@ -127,21 +127,20 @@ describe('explicit ACP placement', () => { workloadType: 'Deployment', sessionSpec: { launch, - launchPlan, cwd: undefined, autoRestart: true, idleTimeoutSecs: 600, env: undefined, }, }); - expect(first.launchPlan).toEqual(launchPlan); + expect(first).not.toHaveProperty('launchPlan'); expect( await ensureAgentForThread('machine-a', 'typed', structured), ).toEqual(first); expect(spawnOnAgentlet).toHaveBeenCalledTimes(1); }); - it('does not silently accept a structured spawn response without a resolved plan', async () => { + it('accepts structured spawn responses without a compiled plan', async () => { host.gateway = { getAgentlet: () => ({ agentletId: 'machine-a', status: 'connected' }), getSession: () => ({ status: 'connected' }), @@ -156,7 +155,7 @@ describe('explicit ACP placement', () => { autoRestart: true, launch: { kind: 'acp-harness', harnessId: 'copilot' }, }), - ).rejects.toMatchObject({ code: 'spawn_failed' }); + ).resolves.toMatchObject({ sessionId: 'wrong-daemon', pid: 404 }); }); it('classifies redacted capacity diagnostics separately from spawn failures', async () => { diff --git a/external/agenetes/packages/acp-driver/src/session-self-repair.test.ts b/external/agenetes/packages/acp-driver/src/session-self-repair.test.ts index eadb42ec0..d61cede8b 100644 --- a/external/agenetes/packages/acp-driver/src/session-self-repair.test.ts +++ b/external/agenetes/packages/acp-driver/src/session-self-repair.test.ts @@ -126,7 +126,7 @@ afterEach(() => { }); describe('ACP Handle session self-repair', () => { - it('recovers the frozen recipe and resolved plan after the Profile template changes', async () => { + it('recovers the frozen recipe while ignoring the legacy resolved plan', async () => { const profile = { executionRevision: 1, workingDirPath: '/original', @@ -186,7 +186,7 @@ describe('ACP Handle session self-repair', () => { expect(orchestrator.ensureAgentForThread).toHaveBeenCalledWith( agentletId, threadId, - { ...frozenRecipe, launchPlan }, + frozenRecipe, 'original-session', undefined, undefined, @@ -194,7 +194,7 @@ describe('ACP Handle session self-repair', () => { ); expect(entry).toMatchObject({ cwd: '/original', - bindingRecipe: { launch: { options: { autoApprove: true } }, launchPlan }, + bindingRecipe: { launch: { options: { autoApprove: true } } }, availableCommands: [], }); expect(readCommands).toHaveBeenCalledWith(binding.profileId, 1); diff --git a/external/agenetes/packages/acp-driver/src/session-state.test.ts b/external/agenetes/packages/acp-driver/src/session-state.test.ts index 040200b23..2b648e293 100644 --- a/external/agenetes/packages/acp-driver/src/session-state.test.ts +++ b/external/agenetes/packages/acp-driver/src/session-state.test.ts @@ -31,7 +31,7 @@ function entry(overrides: Partial = {}): AcpSessionEntry { } describe('ACP durable state snapshot', () => { - it('persists authorized harness arguments even before an empty native session is recoverable', () => { + it('does not persist compiled harness arguments for new executions', () => { const launchPlan = { version: 1 as const, executable: 'copilot', @@ -49,7 +49,7 @@ describe('ACP durable state snapshot', () => { }, }), ); - expect(state.driverState.harnessLaunchPlan).toEqual(launchPlan); + expect(state.driverState.harnessLaunchPlan).toBeUndefined(); expect(state.driverState.sessionId).toBeUndefined(); }); diff --git a/external/agenetes/packages/acp-driver/src/session.ts b/external/agenetes/packages/acp-driver/src/session.ts index a9b682be9..8a3108980 100644 --- a/external/agenetes/packages/acp-driver/src/session.ts +++ b/external/agenetes/packages/acp-driver/src/session.ts @@ -305,9 +305,6 @@ export function snapshotEntryState( ? { sessionId: entry.sessionId as SessionId } : {}), initialPreambleDelivered: entry.initialPreambleDelivered, - ...(entry.bindingRecipe?.launchPlan - ? { harnessLaunchPlan: entry.bindingRecipe.launchPlan } - : {}), }, metadata: snapshotEntryMeta(entry), }; @@ -854,7 +851,7 @@ async function ensureAcpSessionInner( // returning thread's recipe stable; the driver no longer reads a // persisted `bindingRecipe`. When absent, the binding is unbound — fail // with a clear, user-actionable error. - let recipe: AcpBindingRecipe | null = opts.recipe ?? null; + const recipe: AcpBindingRecipe | null = opts.recipe ?? null; if (!recipe) { throw new AcpServiceError( 'profile_missing', @@ -921,16 +918,6 @@ async function ensureAcpSessionInner( ); } const priorSessionId = priorState?.driverState.sessionId; - const savedPlan = priorState?.driverState.harnessLaunchPlan; - if (savedPlan) { - if (!recipe.launch) { - throw new AcpServiceError( - 'spawn_failed', - 'Persisted harness launch cannot be replaced by a shell command', - ); - } - recipe = { ...recipe, launchPlan: savedPlan }; - } // Resolve the thread to a live agentlet agent. Each thread owns its // own CLI process — the orchestrator either returns the cached spawn @@ -939,7 +926,7 @@ async function ensureAcpSessionInner( // the daemon can resume a suspended session instead of creating new. // Failures here surface as a 503 from the caller with a user-actionable // hint pointing at Settings → External Agents. - const { sessionId: agentSessionId, launchPlan } = await ensureAgentForThread( + const { sessionId: agentSessionId } = await ensureAgentForThread( agentletId, threadId, recipe, @@ -1006,7 +993,7 @@ async function ensureAcpSessionInner( namespace, cwd, createdAt: Date.now(), - bindingRecipe: launchPlan ? { ...recipe, launchPlan } : recipe, + bindingRecipe: recipe, // Resume path (`priorSessionId` was down-fed + agent accepted it) // already has a recoverable session, so the entry starts persisted and // the handle's first up-report refreshes the durable record. Fresh diff --git a/external/agenetes/packages/acp-driver/src/spawn-orchestrator.ts b/external/agenetes/packages/acp-driver/src/spawn-orchestrator.ts index b29a32123..9c3a7c9cf 100644 --- a/external/agenetes/packages/acp-driver/src/spawn-orchestrator.ts +++ b/external/agenetes/packages/acp-driver/src/spawn-orchestrator.ts @@ -42,10 +42,6 @@ import { getAgentletGateway, resolveConnectedAgentletId, } from '@agenetes/agentlet-host'; -import { - harnessLaunchPlanSchema, - type HarnessLaunchPlan, -} from '@agenetes/protocol'; import { acpBindingRecipeSchema } from './binding-recipe.js'; import { AcpServiceError } from './errors.js'; @@ -80,7 +76,6 @@ interface CachedAgent { pid: number; /** Which agentlet instance owns this agent. */ agentletId: string; - launchPlan?: HarnessLaunchPlan; } const threadToAgent = new Map(); @@ -190,7 +185,6 @@ export async function ensureAgentForThread( agentletId: string; sessionId: string; pid: number; - launchPlan?: HarnessLaunchPlan; }> { acpBindingRecipeSchema.parse(recipe); const agentlet = await waitForTargetAgentlet( @@ -214,7 +208,6 @@ export async function ensureAgentForThread( agentletId: cached.agentletId, sessionId: cached.sessionId, pid: cached.pid, - ...(cached.launchPlan ? { launchPlan: cached.launchPlan } : {}), }; } threadToAgent.delete(cacheKey); @@ -236,7 +229,6 @@ export async function ensureAgentForThread( let sessionId: string; let pid: number; - let launchPlan: HarnessLaunchPlan | undefined; try { const result = await gateway.spawnOnAgentlet(agentlet.agentletId, { appId: threadId, @@ -246,7 +238,6 @@ export async function ensureAgentForThread( ...(recipe.launch ? { launch: recipe.launch, - ...(recipe.launchPlan ? { launchPlan: recipe.launchPlan } : {}), } : { command: recipe.command }), cwd: recipe.cwd, @@ -257,9 +248,6 @@ export async function ensureAgentForThread( }); sessionId = result.sessionId; pid = result.pid; - if (recipe.launch) { - launchPlan = harnessLaunchPlanSchema.parse(result.launchPlan); - } } catch (err) { const message = err instanceof Error ? err.message : String(err); if (existingSessionId && isSessionResumeUnavailableError(err)) { @@ -344,13 +332,11 @@ export async function ensureAgentForThread( sessionId, pid, agentletId: agentlet.agentletId, - ...(launchPlan ? { launchPlan } : {}), }); return { agentletId: agentlet.agentletId, sessionId, pid, - ...(launchPlan ? { launchPlan } : {}), }; } diff --git a/external/agenetes/packages/agentlet-gateway/src/gateway.test.ts b/external/agenetes/packages/agentlet-gateway/src/gateway.test.ts index bd4bb90bd..3b3fe7da9 100644 --- a/external/agenetes/packages/agentlet-gateway/src/gateway.test.ts +++ b/external/agenetes/packages/agentlet-gateway/src/gateway.test.ts @@ -105,7 +105,7 @@ function agentletHello(agentletId: string): JsonRpcMessage { autoRestart: true, bufferLimit: 1000, maxAgents: 10, - harnessDiscovery: { version: 1 }, + harnessDiscovery: { version: 2 }, }, }, }; @@ -188,7 +188,7 @@ describe('AgentletGateway', () => { if ('params' in hello) { ( hello.params as unknown as AgentletHelloParams - ).agentletProfile.capabilities.harnessLaunch = { version: 1 }; + ).agentletProfile.capabilities.harnessLaunch = { version: 2 }; } const client = await connect(url, { role: 'agentlet', @@ -799,111 +799,6 @@ describe('AgentletGateway', () => { ).rejects.toMatchObject({ code: 'harness_discovery_unsupported' }); }); - it('fails launch preview on old and disconnected daemons without sending requests', async () => { - const { gateway, url } = await startHarness(); - const params = { - launch: { kind: 'acp-command' as const, command: 'agent --acp' }, - }; - await expect( - gateway.buildHarnessLaunch('machine-a', params), - ).rejects.toMatchObject({ code: 'agentlet_disconnected' }); - const client = await connect(url, { - role: 'agentlet', - queryId: 'machine-a', - token: 'token-a', - hello: agentletHello('machine-a'), - }); - await expect( - gateway.buildHarnessLaunch('machine-a', params), - ).rejects.toMatchObject({ code: 'harness_launch_preview_unsupported' }); - expect( - client.messages.some( - (message) => - 'method' in message && - message.method === ServerMethods.BUILD_HARNESS_LAUNCH, - ), - ).toBe(false); - }); - - it('routes preview to the explicit daemon and validates both request and reply', async () => { - const { gateway, url } = await startHarness(); - const hello = agentletHello('machine-a'); - ( - hello as { params: AgentletHelloParams } - ).params.agentletProfile.capabilities.harnessLaunchPreview = { version: 1 }; - const client = await connect(url, { - role: 'agentlet', - queryId: 'machine-a', - token: 'token-a', - hello, - }); - const other = await connect(url, { - role: 'agentlet', - queryId: 'machine-b', - token: 'token-b', - hello: agentletHello('machine-b'), - }); - let result: unknown = { - kind: 'exec', - executable: 'copilot', - argv: ['--acp', '--allow-all'], - env: {}, - }; - const requests: unknown[] = []; - client.socket.on('message', (data) => { - const message = JSON.parse(data.toString()); - if (message.method === ServerMethods.BUILD_HARNESS_LAUNCH) { - requests.push(message.params); - client.socket.send( - JSON.stringify({ jsonrpc: '2.0', id: message.id, result }), - ); - } - }); - const params = { - launch: { - kind: 'acp-harness' as const, - harnessId: 'copilot', - options: { autoApprove: true }, - }, - }; - await expect( - gateway.buildHarnessLaunch('machine-a', params), - ).resolves.toEqual(result); - expect(requests).toEqual([params]); - expect( - other.messages.some( - (message) => - 'method' in message && - message.method === ServerMethods.BUILD_HARNESS_LAUNCH, - ), - ).toBe(false); - await expect( - gateway.buildHarnessLaunch('machine-a', { - launch: { ...params.launch, options: { argv: [] } }, - } as never), - ).rejects.toThrow(); - expect(requests).toHaveLength(1); - for (result of [ - { kind: 'exec', executable: '', argv: [], env: {} }, - { kind: 'exec', executable: 'copilot', argv: [1], env: {} }, - { kind: 'exec', executable: 'copilot', argv: [], env: { VAR: 1 } }, - { kind: 'exec', executable: 'copilot', argv: [], env: {}, shell: true }, - { kind: 'shell', command: 'copilot --acp' }, - null, - ]) { - await expect( - gateway.buildHarnessLaunch('machine-a', params), - ).rejects.toMatchObject({ - code: 'invalid_harness_launch_preview_response', - }); - } - result = { kind: 'shell', command: 'custom && echo trusted' }; - await expect( - gateway.buildHarnessLaunch('machine-a', { - launch: { kind: 'acp-command', command: 'custom && echo trusted' }, - }), - ).resolves.toEqual(result); - }); it('rejects stale pending RPCs on disconnect and routes replies after reconnect', async () => { const { gateway, url } = await startHarness(); const first = await connect(url, { diff --git a/external/agenetes/packages/agentlet-gateway/src/gateway.ts b/external/agenetes/packages/agentlet-gateway/src/gateway.ts index 7df5ef10a..20cb95d0a 100644 --- a/external/agenetes/packages/agentlet-gateway/src/gateway.ts +++ b/external/agenetes/packages/agentlet-gateway/src/gateway.ts @@ -3,10 +3,6 @@ import { AgentMethods, ErrorCodes, ServerMethods, - parseBuildHarnessLaunchParams, - parseHarnessLaunchPreview, - type BuildHarnessLaunchParams, - type HarnessLaunchPreview, type AgentHelloParams, type AgentHelloResult, type AgentletHelloParams, @@ -191,7 +187,7 @@ export class AgentletGateway { if (params.sessionSpec.launch !== undefined) { const connection = this.requireConnectedAgentlet(agentletId); if ( - connection.agentletProfile?.capabilities?.harnessLaunch?.version !== 1 + connection.agentletProfile?.capabilities?.harnessLaunch?.version !== 2 ) { throw new AgentletGatewayError( 'harness_launch_unsupported', @@ -224,52 +220,17 @@ export class AgentletGateway { return this.sendControlRequest(agentletId, ServerMethods.LIST, {}); } - async buildHarnessLaunch( - agentletId: string, - params: BuildHarnessLaunchParams, - ): Promise { - const request = parseBuildHarnessLaunchParams(params); - const connection = this.requireConnectedAgentlet(agentletId); - if ( - connection.agentletProfile?.capabilities?.harnessLaunchPreview - ?.version !== 1 - ) - throw new AgentletGatewayError( - 'harness_launch_preview_unsupported', - `Agentlet does not support harness launch preview v1: ${agentletId}`, - ); - const response = await this.sendControlRequest( - agentletId, - ServerMethods.BUILD_HARNESS_LAUNCH, - request, - ); - try { - const preview = parseHarnessLaunchPreview(response); - if ( - (request.launch.kind === 'acp-command') !== - (preview.kind === 'shell') - ) - throw new Error('Launch kind mismatch'); - return preview; - } catch { - throw new AgentletGatewayError( - 'invalid_harness_launch_preview_response', - 'Agentlet returned malformed harness launch preview', - ); - } - } - async discoverHarnesses( agentletId: string, params: HarnessDiscoveryParams, ): Promise { const connection = this.requireConnectedAgentlet(agentletId); if ( - connection.agentletProfile?.capabilities?.harnessDiscovery?.version !== 1 + connection.agentletProfile?.capabilities?.harnessDiscovery?.version !== 2 ) { throw new AgentletGatewayError( 'harness_discovery_unsupported', - `Agentlet does not support harness discovery v1: ${agentletId}`, + `Agentlet does not support harness discovery v2: ${agentletId}`, ); } return parseHarnessDiscoveryResult( diff --git a/external/agenetes/packages/agentlet-gateway/src/harness-discovery.test.ts b/external/agenetes/packages/agentlet-gateway/src/harness-discovery.test.ts index d8362d5dc..d28d52ff2 100644 --- a/external/agenetes/packages/agentlet-gateway/src/harness-discovery.test.ts +++ b/external/agenetes/packages/agentlet-gateway/src/harness-discovery.test.ts @@ -5,105 +5,41 @@ import { parseHarnessDiscoveryResult } from './harness-discovery.js'; const entry = { id: 'copilot', displayName: 'Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - autoApprove: { args: ['--allow-all'], position: 'before-acp' }, installHint: 'Install from upstream', - installed: true, - executablePath: '/bin/copilot', + capabilities: { + autoApprove: true, + customLaunchCommand: false, + }, + status: 'ready', workingDirPath: '/work/copilot', version: '1', diagnostics: [{ code: 'probe', message: 'Observation' }], }; + describe('discovery response validation', () => { - it('preserves optional structured launch opt-in without assuming it for older daemons', () => { - expect( - parseHarnessDiscoveryResult({ - harnesses: [{ ...entry, launchVersion: 1 }], - }).harnesses[0], - ).toHaveProperty('launchVersion', 1); - expect( - parseHarnessDiscoveryResult({ harnesses: [entry] }).harnesses[0], - ).not.toHaveProperty('launchVersion'); - for (const launchVersion of [0, 2, '1', null]) { - expect(() => - parseHarnessDiscoveryResult({ - harnesses: [{ ...entry, launchVersion }], - }), - ).toThrow(); - } - }); it('preserves every supported response field', () => { expect(parseHarnessDiscoveryResult({ harnesses: [entry] })).toEqual({ harnesses: [entry], }); }); - it('retains ACP capability evidence when present without requiring it from older daemons', () => { - const capabilities = { - autoApprove: 'supported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', - }; - expect( - parseHarnessDiscoveryResult({ harnesses: [{ ...entry, capabilities }] }) - .harnesses[0], - ).toMatchObject({ capabilities }); - expect( - parseHarnessDiscoveryResult({ harnesses: [entry] }).harnesses[0], - ).not.toHaveProperty('capabilities'); - expect( - parseHarnessDiscoveryResult({ - harnesses: [ - { - ...entry, - launchPreviewVersion: 1, - capabilities: { - ...capabilities, - customLaunchCommand: 'unsupported', - }, - }, - ], - }).harnesses[0], - ).toMatchObject({ - launchPreviewVersion: 1, - capabilities: { customLaunchCommand: 'unsupported' }, - }); - expect( - parseHarnessDiscoveryResult({ harnesses: [{ ...entry, capabilities }] }) - .harnesses[0]?.capabilities, - ).not.toHaveProperty('customLaunchCommand'); - }); + it.each([ - { ...entry, installed: 'true' }, - { ...entry, acpArgs: [1] }, + { ...entry, status: 'unknown' }, + { ...entry, status: undefined }, { ...entry, workingDirPath: false }, { ...entry, diagnostics: [null] }, - { ...entry, autoApprove: { args: [], position: 'unknown' } }, - { ...entry, autoApprove: undefined }, + { ...entry, capabilities: undefined }, { ...entry, - capabilities: { - autoApprove: true, - modelOverride: 'unknown', - sessionPersistence: 'unknown', - }, - }, - { ...entry, capabilities: { autoApprove: 'supported' } }, - { ...entry, launchPreviewVersion: 2 }, - { - ...entry, - capabilities: { - autoApprove: 'supported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', - customLaunchCommand: true, - }, + capabilities: { autoApprove: 'yes', customLaunchCommand: false }, }, + { ...entry, capabilities: { autoApprove: true } }, ])('rejects invalid fields', (invalid) => { expect(() => parseHarnessDiscoveryResult({ harnesses: [invalid] })).toThrow( expect.objectContaining({ code: 'invalid_harness_discovery_response' }), ); }); + it('rejects duplicate IDs', () => { expect(() => parseHarnessDiscoveryResult({ harnesses: [entry, entry] }), diff --git a/external/agenetes/packages/agentlet-gateway/src/harness-discovery.ts b/external/agenetes/packages/agentlet-gateway/src/harness-discovery.ts index 25e5ed09c..ded55cf7e 100644 --- a/external/agenetes/packages/agentlet-gateway/src/harness-discovery.ts +++ b/external/agenetes/packages/agentlet-gateway/src/harness-discovery.ts @@ -9,8 +9,6 @@ export class AgentletGatewayError extends Error { | 'agentlet_disconnected' | 'harness_discovery_unsupported' | 'harness_launch_unsupported' - | 'harness_launch_preview_unsupported' - | 'invalid_harness_launch_preview_response' | 'invalid_harness_discovery_response', message: string, ) { @@ -22,11 +20,6 @@ export class AgentletGatewayError extends Error { function object(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value); } -function strings(value: unknown): value is string[] { - return ( - Array.isArray(value) && value.every((entry) => typeof entry === 'string') - ); -} function invalid(): never { throw new AgentletGatewayError( 'invalid_harness_discovery_response', @@ -47,86 +40,28 @@ export function parseHarnessDiscoveryResult( typeof entry.id !== 'string' || !entry.id.trim() || typeof entry.displayName !== 'string' || - typeof entry.binary !== 'string' || - !entry.binary.trim() || typeof entry.installHint !== 'string' || - !strings(entry.acpArgs) || - typeof entry.installed !== 'boolean' + !object(entry.capabilities) || + typeof entry.capabilities.autoApprove !== 'boolean' || + typeof entry.capabilities.customLaunchCommand !== 'boolean' || + !['ready', 'adapter-missing', 'not-found'].includes( + String(entry.status), + ) ) return invalid(); if (ids.has(entry.id)) return invalid(); ids.add(entry.id); - let autoApprove: HarnessDiscoveryEntry['autoApprove'] = null; - if (entry.autoApprove !== null) { - if ( - !object(entry.autoApprove) || - !strings(entry.autoApprove.args) || - (entry.autoApprove.position !== 'before-acp' && - entry.autoApprove.position !== 'after-acp') - ) - return invalid(); - autoApprove = { - args: entry.autoApprove.args, - position: entry.autoApprove.position, - }; - } const result: HarnessDiscoveryEntry = { id: entry.id, displayName: entry.displayName, - binary: entry.binary, - acpArgs: entry.acpArgs, - autoApprove, installHint: entry.installHint, - installed: entry.installed, + capabilities: { + autoApprove: entry.capabilities.autoApprove, + customLaunchCommand: entry.capabilities.customLaunchCommand, + }, + status: entry.status as HarnessDiscoveryEntry['status'], }; - if (entry.capabilities !== undefined) { - if (!object(entry.capabilities)) return invalid(); - const capabilities = entry.capabilities; - const statuses = ['supported', 'unsupported', 'unknown']; - if ( - ['autoApprove', 'modelOverride', 'sessionPersistence'].some( - (key) => - typeof capabilities[key] !== 'string' || - !statuses.includes(capabilities[key]), - ) - ) - return invalid(); - result.capabilities = { - autoApprove: capabilities.autoApprove as NonNullable< - HarnessDiscoveryEntry['capabilities'] - >['autoApprove'], - modelOverride: capabilities.modelOverride as NonNullable< - HarnessDiscoveryEntry['capabilities'] - >['modelOverride'], - sessionPersistence: capabilities.sessionPersistence as NonNullable< - HarnessDiscoveryEntry['capabilities'] - >['sessionPersistence'], - }; - if (capabilities.customLaunchCommand !== undefined) { - if ( - typeof capabilities.customLaunchCommand !== 'string' || - !statuses.includes(capabilities.customLaunchCommand) - ) - return invalid(); - result.capabilities.customLaunchCommand = - capabilities.customLaunchCommand as NonNullable< - HarnessDiscoveryEntry['capabilities'] - >['customLaunchCommand']; - } - } - if (entry.launchVersion !== undefined) { - if (entry.launchVersion !== 1) return invalid(); - result.launchVersion = 1; - } - if (entry.launchPreviewVersion !== undefined) { - if (entry.launchPreviewVersion !== 1) return invalid(); - result.launchPreviewVersion = 1; - } - for (const key of [ - 'executablePath', - 'version', - 'workingDirPath', - ] as const) { + for (const key of ['version', 'workingDirPath'] as const) { if (entry[key] !== undefined) { if (typeof entry[key] !== 'string') return invalid(); result[key] = entry[key]; diff --git a/external/agenetes/packages/agentlet-gateway/src/index.ts b/external/agenetes/packages/agentlet-gateway/src/index.ts index 6f8a6bb96..a465bc904 100644 --- a/external/agenetes/packages/agentlet-gateway/src/index.ts +++ b/external/agenetes/packages/agentlet-gateway/src/index.ts @@ -20,7 +20,5 @@ export type { HarnessDiscoveryResult, HarnessDiscoveryEntry, HarnessCatalogueEntry, - BuildHarnessLaunchParams, - HarnessLaunchPreview, HarnessCapabilities, } from '@agentlet/protocol'; From c8c3210733aa983a5777a40dcb2ca5b4f5b2d0b1 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Thu, 8 Oct 2026 00:39:52 +0000 Subject: [PATCH 03/36] fix(profiles): adopt harness discovery v2 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../modules/agent/acp/agent-cli.route.test.ts | 20 +- .../src/modules/agent/acp/agent-cli.route.ts | 5 +- .../acp/harness-profile-discovery.test.ts | 85 +++---- .../agent/acp/harness-profile-discovery.ts | 39 ++-- .../modules/agent/acp/profiles.route.test.ts | 87 ++----- .../src/modules/agent/acp/profiles.route.ts | 59 +---- apps/web/src/api/_routes.ts | 1 - apps/web/src/api/acp.test.ts | 32 +-- apps/web/src/api/acp.ts | 19 -- .../AgentProfileEditor.test.tsx | 213 +++--------------- .../agent-profiles/CommandProfileForm.tsx | 78 +------ .../agent-profiles/useDetectedClis.test.tsx | 6 +- .../agent-profiles/useProfileLaunchPreview.ts | 62 ----- docs/architecture/agent-profiles.md | 16 +- docs/architecture/api-design.md | 2 +- packages/shared/src/types/api/acp.ts | 28 +-- .../src/types/api/agent-profile.test.ts | 9 +- .../shared/src/types/api/agent-profile.ts | 36 --- 18 files changed, 131 insertions(+), 666 deletions(-) delete mode 100644 apps/web/src/components/Settings/agent-profiles/useProfileLaunchPreview.ts diff --git a/apps/server/src/modules/agent/acp/agent-cli.route.test.ts b/apps/server/src/modules/agent/acp/agent-cli.route.test.ts index 194dd8d08..0a6331705 100644 --- a/apps/server/src/modules/agent/acp/agent-cli.route.test.ts +++ b/apps/server/src/modules/agent/acp/agent-cli.route.test.ts @@ -33,20 +33,16 @@ describe('ACP agent CLI route', () => { { id: 'copilot', displayName: 'GitHub Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - autoApprove: null, - installed: true, + status: 'ready' as const, installHint: 'Install Copilot', + capabilities: { autoApprove: true, customLaunchCommand: false }, }, { id: 'claude', displayName: 'Claude Agent', - binary: 'claude-agent-acp', - acpArgs: [], - autoApprove: null, - installed: false, + status: 'adapter-missing' as const, installHint: 'Install Claude Agent ACP', + capabilities: { autoApprove: false, customLaunchCommand: false }, }, ]); app = Fastify({ logger: false }); @@ -63,7 +59,7 @@ describe('ACP agent CLI route', () => { expect(response.json().agents).toEqual(await detect.mock.results[0]?.value); expect(response.json().agents[1]).toMatchObject({ id: 'claude', - installed: false, + status: 'adapter-missing', }); }); @@ -136,10 +132,8 @@ describe('ACP agent CLI route', () => { expect.objectContaining({ id: 'custom', capabilities: { - customLaunchCommand: 'supported', - autoApprove: 'unsupported', - modelOverride: 'unsupported', - sessionPersistence: 'unsupported', + customLaunchCommand: true, + autoApprove: false, }, }), ]); diff --git a/apps/server/src/modules/agent/acp/agent-cli.route.ts b/apps/server/src/modules/agent/acp/agent-cli.route.ts index a173f3737..023d20bbd 100644 --- a/apps/server/src/modules/agent/acp/agent-cli.route.ts +++ b/apps/server/src/modules/agent/acp/agent-cli.route.ts @@ -66,10 +66,7 @@ async function detectAgentClis(target: { { id: CUSTOM_COMMAND_WRAPPER_ID, displayName: 'Custom command', - binary: CUSTOM_COMMAND_WRAPPER_ID, - acpArgs: [], - autoApprove: null, - installed: false, + status: 'ready', installHint: '', capabilities: CUSTOM_COMMAND_CAPABILITIES, }, diff --git a/apps/server/src/modules/agent/acp/harness-profile-discovery.test.ts b/apps/server/src/modules/agent/acp/harness-profile-discovery.test.ts index 3f3f935ef..73dede14a 100644 --- a/apps/server/src/modules/agent/acp/harness-profile-discovery.test.ts +++ b/apps/server/src/modules/agent/acp/harness-profile-discovery.test.ts @@ -22,11 +22,12 @@ const observation: HarnessDiscoveryResult = { { id: 'copilot', displayName: 'GitHub Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - autoApprove: { args: ['--allow-all'], position: 'after-acp' }, installHint: 'Install Copilot', - installed: true, + status: 'ready', + capabilities: { + autoApprove: false, + customLaunchCommand: false, + }, workingDirPath: '/home/user/.agentlet/workspace/copilot', }, ], @@ -115,7 +116,7 @@ describe('automatic ordinary Profile provisioning', () => { dispose(); }); - it('creates a persisted command Profile with the daemon workspace and no auto-approval flags', async () => { + it('creates a persisted typed Profile with the daemon workspace and no auto-approval option', async () => { const context = setup(); const dispose = context.start(); await flush(); @@ -129,7 +130,11 @@ describe('automatic ordinary Profile provisioning', () => { alias: 'GitHub Copilot (machine-a: linux x64)', agentletId: 'machine-a', workingDirPath: '/home/user/.agentlet/workspace/copilot', - launch: { kind: 'acp-command', command: 'copilot --acp' }, + launch: { + kind: 'acp-harness', + harnessId: 'copilot', + options: undefined, + }, customData: { discoveredAgent: { version: 1, @@ -159,12 +164,11 @@ describe('automatic ordinary Profile provisioning', () => { dispose(); }); - it('uses structured harness configuration only when the daemon advertises it', async () => { + it('uses structured harness configuration for ready definitions', async () => { const context = setup(); context.gateway.discoverHarnesses.mockResolvedValue({ harnesses: observation.harnesses.map((harness) => ({ ...harness, - launchVersion: 1, })), }); const dispose = context.start(); @@ -180,23 +184,17 @@ describe('automatic ordinary Profile provisioning', () => { dispose(); }); - it.each(['supported', 'unsupported', 'unknown', undefined] as const)( - 'defaults structured auto-approval only for explicitly supported capabilities (%s)', + it.each([true, false] as const)( + 'defaults structured auto-approval only when the definition supports it (%s)', async (autoApprove) => { const context = setup(); context.gateway.discoverHarnesses.mockResolvedValue({ harnesses: observation.harnesses.map((harness) => ({ ...harness, - launchVersion: 1, - ...(autoApprove === undefined - ? {} - : { - capabilities: { - autoApprove, - modelOverride: 'unknown', - sessionPersistence: 'unknown', - }, - }), + capabilities: { + autoApprove, + customLaunchCommand: false, + }, })), }); const dispose = context.start(); @@ -204,34 +202,12 @@ describe('automatic ordinary Profile provisioning', () => { expect(context.profiles[0]?.launch).toEqual({ kind: 'acp-harness', harnessId: 'copilot', - options: - autoApprove === 'supported' ? { autoApprove: true } : undefined, + options: autoApprove ? { autoApprove: true } : undefined, }); dispose(); }, ); - it('does not inject approval options into compatibility command Profiles', async () => { - const context = setup(); - context.gateway.discoverHarnesses.mockResolvedValue({ - harnesses: observation.harnesses.map((harness) => ({ - ...harness, - capabilities: { - autoApprove: 'supported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', - }, - })), - }); - const dispose = context.start(); - await flush(); - expect(context.profiles[0]?.launch).toEqual({ - kind: 'acp-command', - command: 'copilot --acp', - }); - dispose(); - }); - it.each([ { kind: 'acp-harness', harnessId: 'copilot' }, { @@ -262,11 +238,9 @@ describe('automatic ordinary Profile provisioning', () => { context.gateway.discoverHarnesses.mockResolvedValue({ harnesses: observation.harnesses.map((harness) => ({ ...harness, - launchVersion: 1, capabilities: { - autoApprove: 'supported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', + autoApprove: true, + customLaunchCommand: false, }, })), }); @@ -315,11 +289,9 @@ describe('automatic ordinary Profile provisioning', () => { context.gateway.discoverHarnesses.mockResolvedValue({ harnesses: observation.harnesses.map((harness) => ({ ...harness, - launchVersion: 1, capabilities: { - autoApprove: 'supported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', + autoApprove: true, + customLaunchCommand: false, }, })), }); @@ -376,12 +348,11 @@ describe('automatic ordinary Profile provisioning', () => { } }); - it('does not create a compatibility duplicate when a daemon stops advertising typed launch', async () => { + it('does not create a duplicate on repeated ready discovery', async () => { const context = setup(); context.gateway.discoverHarnesses.mockResolvedValueOnce({ harnesses: observation.harnesses.map((harness) => ({ ...harness, - launchVersion: 1, })), }); const dispose = context.start(); @@ -453,11 +424,9 @@ describe('automatic ordinary Profile provisioning', () => { context.gateway.discoverHarnesses.mockResolvedValue({ harnesses: observation.harnesses.map((harness) => ({ ...harness, - launchVersion: 1, capabilities: { - autoApprove: 'supported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', + autoApprove: true, + customLaunchCommand: false, }, })), }); @@ -599,7 +568,7 @@ describe('automatic ordinary Profile provisioning', () => { const context = setup(); context.gateway.discoverHarnesses.mockResolvedValueOnce({ harnesses: [ - { ...observation.harnesses[0]!, installed: false }, + { ...observation.harnesses[0]!, status: 'not-found' }, { ...observation.harnesses[0]!, workingDirPath: undefined, diff --git a/apps/server/src/modules/agent/acp/harness-profile-discovery.ts b/apps/server/src/modules/agent/acp/harness-profile-discovery.ts index 12c2133d8..6cf88f9fd 100644 --- a/apps/server/src/modules/agent/acp/harness-profile-discovery.ts +++ b/apps/server/src/modules/agent/acp/harness-profile-discovery.ts @@ -137,7 +137,7 @@ export function registerHarnessProfileDiscovery({ '[acp] harness discovery diagnostic', ); } - if (!harness.installed) continue; + if (harness.status !== 'ready') continue; if (!harness.workingDirPath) { log.warn( { agentletId, harnessId: harness.id }, @@ -147,16 +147,14 @@ export function registerHarnessProfileDiscovery({ } // No await between the lookup and the synchronous registry commit. const profiles = registry.listProfiles(); - const typed = harness.launchVersion === 1; const existing = profiles.find((profile) => { const source = parseSource(profile.customData?.[SOURCE_KEY]); return ( profile.agentletId === agentletId && source?.agentletId === agentletId && source.harnessId === harness.id && - (!typed || - (profile.launch.kind === 'acp-harness' && - profile.launch.harnessId === harness.id)) + profile.launch.kind === 'acp-harness' && + profile.launch.harnessId === harness.id ); }); if (existing) continue; @@ -168,32 +166,23 @@ export function registerHarnessProfileDiscovery({ )})`; const common = { agentletId, - alias: - typed && profiles.some((profile) => profile.alias === defaultAlias) - ? `${defaultAlias} [${harness.id}]` - : defaultAlias, + alias: profiles.some((profile) => profile.alias === defaultAlias) + ? `${defaultAlias} [${harness.id}]` + : defaultAlias, workingDirPath: harness.workingDirPath, metadata: { cliId: harness.id }, customData: { [SOURCE_KEY]: { version: 1, agentletId, harnessId: harness.id }, }, }; - const profile = registry.createProfile( - typed - ? { - ...common, - launchKind: 'acp-harness', - harnessId: harness.id, - ...(harness.capabilities?.autoApprove === 'supported' - ? { options: { autoApprove: true } } - : {}), - } - : { - ...common, - launchKind: 'acp-command', - command: [harness.binary, ...harness.acpArgs].join(' '), - }, - ); + const profile = registry.createProfile({ + ...common, + launchKind: 'acp-harness', + harnessId: harness.id, + ...(harness.capabilities.autoApprove + ? { options: { autoApprove: true } } + : {}), + }); log.info( { agentletId, harnessId: harness.id, profileId: profile.id }, '[acp] automatically created Profile', diff --git a/apps/server/src/modules/agent/acp/profiles.route.test.ts b/apps/server/src/modules/agent/acp/profiles.route.test.ts index ed5032b9a..141ec6da3 100644 --- a/apps/server/src/modules/agent/acp/profiles.route.test.ts +++ b/apps/server/src/modules/agent/acp/profiles.route.test.ts @@ -19,7 +19,6 @@ const mocks = vi.hoisted(() => ({ invalidate: vi.fn(), initializeDefaults: vi.fn(), discoverHarnesses: vi.fn(), - buildHarnessLaunch: vi.fn(), connectedIds: new Set(['machine-a', 'remote-machine']), })); @@ -35,7 +34,6 @@ vi.mock('@agenetes/agentlet-host', () => ({ }), getAgentletGateway: () => ({ discoverHarnesses: mocks.discoverHarnesses, - buildHarnessLaunch: mocks.buildHarnessLaunch, getAgentlets: () => [...mocks.connectedIds].map((agentletId) => ({ agentletId, @@ -97,14 +95,11 @@ describe('ordinary Profile catalog routes', () => { harnesses: [ { id: 'copilot', - installed: true, - launchVersion: 1, - launchPreviewVersion: 1, + status: 'ready', capabilities: { - autoApprove: 'supported', - customLaunchCommand: 'unsupported', + autoApprove: true, + customLaunchCommand: false, }, - autoApprove: { args: ['--allow-all'], position: 'after-acp' }, }, ], }); @@ -356,10 +351,11 @@ describe('ordinary Profile catalog routes', () => { harnesses: [ { id: 'copilot', - installed: true, - launchVersion: 1, - launchPreviewVersion: 1, - capabilities: { autoApprove: 'supported' }, + status: 'ready', + capabilities: { + autoApprove: true, + customLaunchCommand: false, + }, }, ], }); @@ -375,9 +371,6 @@ describe('ordinary Profile catalog routes', () => { payload: { expectedRevision: 2, launch }, }); expect(response.statusCode).toBe(200); - expect(mocks.buildHarnessLaunch).toHaveBeenCalledWith('remote-machine', { - launch, - }); expect(mocks.registry.patchProfile).toHaveBeenCalledWith('command-1', { expectedRevision: 2, launch, @@ -411,26 +404,19 @@ describe('ordinary Profile catalog routes', () => { harnesses: [ { id: 'copilot', - installed: true, - launchVersion: 1, - launchPreviewVersion: 1, - capabilities: { autoApprove: 'supported' }, + status: 'ready', + capabilities: { + autoApprove: true, + customLaunchCommand: false, + }, }, ], }); - mocks.buildHarnessLaunch.mockImplementation(async () => { - mocks.registry.patchProfile.mockImplementation(() => { - throw new AgentProfileError( - 'profile_conflict', - 'Profile changed during validation', - ); - }); - return { - kind: 'exec', - executable: '/bin/copilot', - argv: ['--acp'], - env: {}, - }; + mocks.registry.patchProfile.mockImplementation(() => { + throw new AgentProfileError( + 'profile_conflict', + 'Profile changed during validation', + ); }); const server = await setup(); const response = await server.inject({ @@ -458,41 +444,4 @@ describe('ordinary Profile catalog routes', () => { expect(response.json().code).toBe('profile_wrapper_immutable'); expect(mocks.registry.patchProfile).not.toHaveBeenCalled(); }); - - it('previews on the Profile machine without creating or mutating a Profile', async () => { - mocks.registry.getProfile.mockReturnValue({ - ...commandProfile, - agentletId: 'remote-machine', - }); - const plan = { kind: 'shell', command: commandProfile.launch.command }; - mocks.buildHarnessLaunch.mockResolvedValue(plan); - const server = await setup(); - const response = await server.inject({ - method: 'POST', - url: '/api/acp/profile-launch-preview', - payload: { profileId: commandProfile.id, launch: commandProfile.launch }, - }); - expect(response.statusCode).toBe(200); - expect(response.json()).toEqual(plan); - expect(mocks.buildHarnessLaunch).toHaveBeenCalledWith('remote-machine', { - launch: commandProfile.launch, - }); - expect(mocks.registry.createProfile).not.toHaveBeenCalled(); - expect(mocks.registry.patchProfile).not.toHaveBeenCalled(); - }); - - it('reports unavailable preview instead of a fabricated command', async () => { - mocks.buildHarnessLaunch.mockRejectedValue(new Error('unsupported')); - const server = await setup(); - const response = await server.inject({ - method: 'POST', - url: '/api/acp/profile-launch-preview', - payload: { - agentletId: 'machine-a', - launch: commandProfile.launch, - }, - }); - expect(response.statusCode).toBe(503); - expect(response.json().code).toBe('harness_preview_unavailable'); - }); }); diff --git a/apps/server/src/modules/agent/acp/profiles.route.ts b/apps/server/src/modules/agent/acp/profiles.route.ts index 0386a0a76..2cf0daa4b 100644 --- a/apps/server/src/modules/agent/acp/profiles.route.ts +++ b/apps/server/src/modules/agent/acp/profiles.route.ts @@ -36,7 +36,6 @@ import { agentProfileParamsSchema, createAcpProfileBodySchema, patchAgentProfileBodySchema, - acpProfileLaunchPreviewBodySchema, } from '@huabu/shared'; import { @@ -55,7 +54,6 @@ import type { AgentletConnection } from '@agenetes/agentlet-host'; import type { AcpProfileMutationResponse, AcpProfilesListResponse, - AcpProfileLaunchPreviewResponse, AgentProfileView, ApiResult, } from '@huabu/shared'; @@ -99,11 +97,7 @@ async function validateHarnessLaunch( const harness = result.harnesses.find( (entry) => entry.id === launch.harnessId, ); - if ( - !harness?.installed || - harness.launchVersion !== 1 || - harness.launchPreviewVersion !== 1 - ) { + if (harness?.status !== 'ready') { reply.status(409).send({ code: 'harness_launch_unavailable', message: @@ -111,10 +105,7 @@ async function validateHarnessLaunch( }); return false; } - if ( - launch.options?.autoApprove && - harness.capabilities?.autoApprove !== 'supported' - ) { + if (launch.options?.autoApprove && !harness.capabilities.autoApprove) { reply.status(400).send({ code: 'harness_option_unsupported', message: @@ -122,7 +113,6 @@ async function validateHarnessLaunch( }); return false; } - await gateway.buildHarnessLaunch(resolvedAgentletId, { launch }); return true; } catch (error) { request.log.warn( @@ -138,51 +128,6 @@ async function validateHarnessLaunch( } const acpProfilesRoutes: FastifyPluginAsync = async (app) => { - app.post<{ Reply: ApiResult }>( - '/profile-launch-preview', - async (request, reply) => { - if (denyRemote(request, reply)) return; - const parsed = acpProfileLaunchPreviewBodySchema.safeParse(request.body); - if (!parsed.success) { - return reply.status(400).send({ - code: 'validation_failed', - message: 'Invalid launch preview request', - }); - } - const profile = parsed.data.profileId - ? getAgentProfileRegistry()?.getProfile(parsed.data.profileId) - : undefined; - if (parsed.data.profileId && !profile) { - return reply.status(404).send({ - code: 'profile_not_found', - message: 'Agent Profile is unavailable', - }); - } - try { - const gateway = getAgentletGateway(); - if (!gateway) throw new Error('Agentlet Gateway is not ready'); - const agentletId = profile - ? resolveConnectedAgentletId(profile.agentletId) - : parsed.data.agentletId; - if (!agentletId || !isAgentletConnected(agentletId)) { - return reply.status(409).send({ - code: 'agentlet_unavailable', - message: 'The selected Agentlet is not connected.', - }); - } - return await gateway.buildHarnessLaunch(agentletId, { - launch: parsed.data.launch, - }); - } catch (error) { - request.log.warn({ err: error }, 'Profile launch preview failed'); - return reply.status(503).send({ - code: 'harness_preview_unavailable', - message: - 'Agentlet could not preview this launch configuration. Check its availability and supported options.', - }); - } - }, - ); // ── List ───────────────────────────────────────────────────────────── app.get<{ Reply: ApiResult }>( '/profiles', diff --git a/apps/web/src/api/_routes.ts b/apps/web/src/api/_routes.ts index 52d205e4b..c5eb42722 100644 --- a/apps/web/src/api/_routes.ts +++ b/apps/web/src/api/_routes.ts @@ -158,7 +158,6 @@ export const routes = { }, // Profiles (loopback-only) — user-managed spawn recipes. acpProfiles: '/acp/profiles', - acpProfileLaunchPreview: '/acp/profile-launch-preview', acpProfileItem: (id: string) => `/acp/profiles/${enc(id)}`, // Embedded agentlet daemon — health + manual restart. acpAgentlet: '/acp/agentlet', diff --git a/apps/web/src/api/acp.test.ts b/apps/web/src/api/acp.test.ts index a4841ea6d..6d6563d81 100644 --- a/apps/web/src/api/acp.test.ts +++ b/apps/web/src/api/acp.test.ts @@ -4,13 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { ApiError } from './_client'; -import { - listAcpAgentClis, - previewAcpProfileLaunch, - updateAcpProfile, -} from './acp'; - -import type { AcpProfileLaunchPreviewBody } from '@huabu/shared'; +import { listAcpAgentClis, updateAcpProfile } from './acp'; afterEach(() => vi.unstubAllGlobals()); @@ -35,30 +29,6 @@ describe('ACP Profile editing API', () => { ); }); - it('posts a typed preview to the daemon route, including the saved target Profile', async () => { - const plan = { - kind: 'exec', - executable: '/bin/agent', - argv: ['--acp'], - env: {}, - }; - const fetch = vi.fn().mockResolvedValue(new Response(JSON.stringify(plan))); - vi.stubGlobal('fetch', fetch); - const body: AcpProfileLaunchPreviewBody = { - profileId: 'saved', - launch: { - kind: 'acp-harness', - harnessId: 'copilot', - options: { autoApprove: false }, - }, - }; - expect(await previewAcpProfileLaunch(body)).toEqual(plan); - expect(fetch).toHaveBeenCalledWith( - expect.stringMatching(/\/api\/acp\/profile-launch-preview$/), - expect.objectContaining({ method: 'POST', body: JSON.stringify(body) }), - ); - }); - it('sends expectedRevision and only explicit patch fields', async () => { const fetch = vi.fn().mockResolvedValue(new Response('{}')); vi.stubGlobal('fetch', fetch); diff --git a/apps/web/src/api/acp.ts b/apps/web/src/api/acp.ts index f8965f44f..01b3b2563 100644 --- a/apps/web/src/api/acp.ts +++ b/apps/web/src/api/acp.ts @@ -16,7 +16,6 @@ * and populate the profile editor's picker with installation state. * - `GET/POST/PATCH/DELETE /api/acp/profiles` — CRUD for spawn * recipes with revision-checked launch and working-directory edits. - * - `POST /api/acp/profile-launch-preview` — daemon-built launch preview. * - `GET/POST /api/acp/daemon` — daemon liveness + manual restart. * - `GET/PUT /api/acp/connection-token` — masked credential configuration. * - `POST /api/acp/connection-command` — explicit owner-only command reveal. @@ -35,8 +34,6 @@ import type { AcpPermissionDecisionRequest, AcpPermissionDecisionResponse, AcpProfileMutationResponse, - AcpProfileLaunchPreviewBody, - AcpProfileLaunchPreviewResponse, AcpProfilesListResponse, CreateAcpProfileBody, PatchAgentProfileBody, @@ -64,8 +61,6 @@ export type { AcpAgentletStatusResponse, AcpModelInfo, AcpProfileMutationResponse, - AcpProfileLaunchPreviewBody, - AcpProfileLaunchPreviewResponse, AcpProfilesListResponse, CreateAcpCommandProfileBody, CreateAcpProfileBody, @@ -126,20 +121,6 @@ export async function createAcpProfile( }); } -/** Resolve a launch on the target daemon without starting an execution. */ -export async function previewAcpProfileLaunch( - body: AcpProfileLaunchPreviewBody, -): Promise { - return apiFetch( - routes.acpProfileLaunchPreview, - { - method: 'POST', - json: body, - fallbackMessage: 'Failed to preview agent launch', - }, - ); -} - /** * Patch a Profile at its expected revision; omitted fields remain intact. */ diff --git a/apps/web/src/components/Settings/agent-profiles/AgentProfileEditor.test.tsx b/apps/web/src/components/Settings/agent-profiles/AgentProfileEditor.test.tsx index 9df45744c..1027061c3 100644 --- a/apps/web/src/components/Settings/agent-profiles/AgentProfileEditor.test.tsx +++ b/apps/web/src/components/Settings/agent-profiles/AgentProfileEditor.test.tsx @@ -11,7 +11,6 @@ import { AgentProfileEditor } from './AgentProfileEditor'; import type { AcpAgentCliInfo, - AcpProfileLaunchPreviewResponse, AgentProfileView, ConnectedAgentletDevice, } from '@huabu/shared'; @@ -24,7 +23,6 @@ globalThis.IS_REACT_ACT_ENVIRONMENT = true; const api = vi.hoisted(() => ({ create: vi.fn(), update: vi.fn(), - preview: vi.fn(), toast: vi.fn(), })); vi.mock('react-i18next', () => { @@ -34,7 +32,6 @@ vi.mock('react-i18next', () => { vi.mock('@/api/acp', () => ({ createAcpProfile: api.create, updateAcpProfile: api.update, - previewAcpProfileLaunch: api.preview, })); vi.mock('@/components/Common/Toast', () => ({ toast: api.toast })); vi.mock('@/components/Common/PathInput', () => ({ @@ -99,28 +96,19 @@ const agents: AcpAgentCliInfo[] = [ { id: 'copilot', displayName: 'GitHub Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - autoApprove: { args: ['--allow-all'], position: 'after-acp' }, - installed: true, - launchVersion: 1, - launchPreviewVersion: 1, + status: 'ready', capabilities: { - autoApprove: 'supported', - customLaunchCommand: 'unsupported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', + autoApprove: true, + customLaunchCommand: false, }, installHint: 'Install Copilot', }, { id: 'claude', displayName: 'Claude Agent', - binary: 'claude-agent-acp', - acpArgs: [], - autoApprove: null, - installed: false, + status: 'adapter-missing', installHint: 'Install Claude', + capabilities: { autoApprove: false, customLaunchCommand: false }, }, ]; @@ -139,13 +127,6 @@ const structured: AgentProfileView = { executionRevision: 4, launch: { kind: 'acp-harness', harnessId: 'copilot' }, }; -const plan: AcpProfileLaunchPreviewResponse = { - kind: 'exec', - executable: '/daemon/copilot', - argv: ['--acp', 'daemon-owned-argument'], - env: { SECRET: 'must-not-render' }, -}; - let root: Root | undefined; let container: HTMLDivElement | undefined; const onSaved = vi.fn<() => Promise>(); @@ -210,11 +191,6 @@ function saveButton() { function approval() { return container?.querySelector('input[type="checkbox"]'); } -async function settlePreview() { - await act(async () => { - await vi.advanceTimersByTimeAsync(300); - }); -} function chooseCustom() { const select = container?.querySelector( 'select[aria-label="settings.agent"]', @@ -230,7 +206,6 @@ beforeEach(() => { onSaved.mockResolvedValue(undefined); api.create.mockResolvedValue(legacy); api.update.mockResolvedValue(legacy); - api.preview.mockResolvedValue(plan); }); afterEach(() => { act(() => root?.unmount()); @@ -265,8 +240,6 @@ describe('AgentProfileEditor', () => { alias: 'Renamed', customData: legacy.customData, }); - - expect(api.preview).not.toHaveBeenCalled(); }); it('renders human-readable device labels while retaining UUID identity details', () => { @@ -346,26 +319,14 @@ describe('AgentProfileEditor', () => { expect(saveButton()?.disabled).toBe(true); }); - it('requires a daemon preview and explicit checkbox for elevated permissions', async () => { + it('requires an explicit checkbox for elevated permissions', async () => { renderEditor(); input('path', 'C:\\work\\project'); act(() => approval()?.click()); expect(container?.textContent).toContain( 'settings.profilePermissionIncrease', ); - expect(saveButton()?.disabled).toBe(true); - await settlePreview(); - expect(api.preview).toHaveBeenCalledWith({ - agentletId: 'device-1', - launch: { - kind: 'acp-harness', - harnessId: 'copilot', - options: { autoApprove: true }, - }, - }); - expect(container?.textContent).toContain('daemon-owned-argument'); - expect(container?.textContent).not.toContain('must-not-render'); - expect(container?.textContent).not.toContain('SECRET'); + expect(saveButton()?.disabled).toBe(false); expect( container?.querySelector('[aria-label="settings.launchCommand"]'), ).toBeNull(); @@ -388,20 +349,11 @@ describe('AgentProfileEditor', () => { expect(onClose).toHaveBeenCalledOnce(); }); - it('targets edit preview by saved Profile and patches only changed execution fields', async () => { + it('patches only changed execution fields', async () => { renderEditor(structured); act(() => approval()?.click()); input('path', '/different/work'); - expect(saveButton()?.disabled).toBe(true); - await settlePreview(); - expect(api.preview).toHaveBeenCalledWith({ - profileId: 'profile-1', - launch: { - kind: 'acp-harness', - harnessId: 'copilot', - options: { autoApprove: true }, - }, - }); + expect(saveButton()?.disabled).toBe(false); await act(async () => saveButton()?.click()); expect(api.update).toHaveBeenCalledWith('profile-1', { expectedRevision: 7, @@ -419,7 +371,6 @@ describe('AgentProfileEditor', () => { it('saves cwd alone without rewriting launch options', async () => { renderEditor(structured); input('path', '/different/work'); - await settlePreview(); await act(async () => saveButton()?.click()); expect(api.update.mock.calls[0]?.[1]).toMatchObject({ workingDirPath: '/different/work', @@ -439,22 +390,18 @@ describe('AgentProfileEditor', () => { metadata: { cliId: 'custom' }, }), ); - expect(api.preview).not.toHaveBeenCalled(); }); - it('falls back to manual creation for older daemons', () => { + it('falls back to manual creation when known harnesses are unavailable', () => { renderEditor( undefined, - agents.map((agent) => ({ ...agent, launchPreviewVersion: undefined })), + agents.map((agent) => ({ ...agent, status: 'not-found' })), ); expect( container?.querySelector( 'select[aria-label="settings.agent"]', )?.value, ).toBe('custom'); - expect(container?.textContent).toContain( - 'settings.structuredLaunchUnavailable', - ); expect(approval()).toBeNull(); }); @@ -464,10 +411,8 @@ describe('AgentProfileEditor', () => { ...agents[0], id: 'custom', capabilities: { - autoApprove: 'supported', - modelOverride: 'supported', - sessionPersistence: 'supported', - customLaunchCommand: 'unknown', + autoApprove: false, + customLaunchCommand: false, }, }, ]); @@ -488,14 +433,12 @@ describe('AgentProfileEditor', () => { { ...agents[0], capabilities: { - autoApprove: 'unsupported', - modelOverride: 'unknown', - sessionPersistence: 'unknown', + autoApprove: false, + customLaunchCommand: false, }, }, ]); input('path', '/work/project'); - await settlePreview(); await act(async () => saveButton()?.click()); expect(api.create.mock.calls[0]?.[0].launch).toEqual({ kind: 'acp-harness', @@ -503,55 +446,28 @@ describe('AgentProfileEditor', () => { }); }); - it('debounces rapid option changes into one preview request', async () => { - renderEditor(); - act(() => approval()?.click()); - await act(async () => { - await vi.advanceTimersByTimeAsync(100); - }); - act(() => approval()?.click()); - await act(async () => { - await vi.advanceTimersByTimeAsync(100); - }); - act(() => approval()?.click()); - expect(api.preview).not.toHaveBeenCalled(); - await settlePreview(); - expect(api.preview).toHaveBeenCalledOnce(); - expect(api.preview.mock.calls[0]?.[0].launch.options.autoApprove).toBe( - true, - ); - }); - - it.each(['unknown', 'unsupported', undefined] as const)( - 'does not infer approval capability %s from catalogue arguments', - async (status) => { - renderEditor(structured, [ - { - ...agents[0], - capabilities: status - ? { - autoApprove: status, - modelOverride: 'unknown', - sessionPersistence: 'unknown', - } - : undefined, + it('does not enable approval when the definition does not support it', async () => { + renderEditor(structured, [ + { + ...agents[0], + capabilities: { + autoApprove: false, + customLaunchCommand: false, }, - ]); - expect(approval()?.disabled).toBe(true); - input('settings.displayName', 'Alias only'); - await act(async () => saveButton()?.click()); - expect(api.update.mock.calls[0]?.[1]).not.toHaveProperty('launch'); - }, - ); + }, + ]); + expect(approval()?.disabled).toBe(true); + input('settings.displayName', 'Alias only'); + await act(async () => saveButton()?.click()); + expect(api.update.mock.calls[0]?.[1]).not.toHaveProperty('launch'); + }); - it('supports approval from capabilities even without legacy argument catalogue data', async () => { - renderEditor(structured, [{ ...agents[0], autoApprove: null }]); + it('supports approval from definition capabilities', async () => { + renderEditor(structured); expect(approval()?.disabled).toBe(false); act(() => approval()?.click()); - await settlePreview(); - expect(api.preview.mock.calls[0]?.[0].launch.options.autoApprove).toBe( - true, - ); + await act(async () => saveButton()?.click()); + expect(api.update.mock.calls[0]?.[1].launch.options.autoApprove).toBe(true); }); it('keeps alias editing available offline and preserves saved approval defaults', async () => { @@ -580,69 +496,6 @@ describe('AgentProfileEditor', () => { expect(api.update.mock.calls[0]?.[1]).not.toHaveProperty('launch'); }); - it('shows preview errors, prevents execution saves, and supports retry', async () => { - api.preview.mockRejectedValueOnce(new Error('Target daemon offline')); - renderEditor(); - input('path', '/work/project'); - await settlePreview(); - expect(container?.textContent).toContain('Target daemon offline'); - expect(saveButton()?.disabled).toBe(true); - const retry = [...(container?.querySelectorAll('button') ?? [])].find( - (button) => button.textContent === 'settings.profilePreviewRetry', - ); - act(() => retry?.click()); - await settlePreview(); - expect(saveButton()?.disabled).toBe(false); - }); - - it('allows alias saves despite failed previews when execution fields are untouched', async () => { - api.preview.mockRejectedValueOnce(new Error('Target daemon offline')); - renderEditor(structured); - await settlePreview(); - input('settings.displayName', 'Offline rename'); - expect(saveButton()?.disabled).toBe(false); - await act(async () => saveButton()?.click()); - expect(api.update.mock.calls[0]?.[1]).not.toHaveProperty('launch'); - }); - - it('debounces edits and ignores late preview results from an older draft', async () => { - let oldResolve!: (value: AcpProfileLaunchPreviewResponse) => void; - api.preview.mockImplementationOnce( - () => - new Promise((resolve) => { - oldResolve = resolve; - }), - ); - renderEditor(); - input('path', '/work/project'); - await settlePreview(); - act(() => approval()?.click()); - expect(saveButton()?.disabled).toBe(true); - await settlePreview(); - expect(api.preview).toHaveBeenCalledTimes(2); - await act(async () => - oldResolve({ kind: 'shell', command: 'stale-preview' }), - ); - expect(container?.textContent).not.toContain('stale-preview'); - expect(container?.textContent).toContain('daemon-owned-argument'); - }); - - it('ignores stale preview failures after changing to custom', async () => { - let reject!: (error: Error) => void; - api.preview.mockImplementationOnce( - () => - new Promise((_resolve, failure) => { - reject = failure; - }), - ); - renderEditor(); - await settlePreview(); - chooseCustom(); - await act(async () => reject(new Error('Stale failure'))); - expect(container?.textContent).not.toContain('Stale failure'); - expect(approval()).toBeNull(); - }); - it('does not reset unsaved edits when discovery changes', () => { renderEditor(legacy); input('settings.displayName', 'Draft'); diff --git a/apps/web/src/components/Settings/agent-profiles/CommandProfileForm.tsx b/apps/web/src/components/Settings/agent-profiles/CommandProfileForm.tsx index 107be07be..b64cbf270 100644 --- a/apps/web/src/components/Settings/agent-profiles/CommandProfileForm.tsx +++ b/apps/web/src/components/Settings/agent-profiles/CommandProfileForm.tsx @@ -6,7 +6,6 @@ import { useTranslation } from 'react-i18next'; import { ApiError } from '@/api/_client'; import { createAcpProfile, updateAcpProfile } from '@/api/acp'; -import { Button } from '@/components/Common/Button'; import { PathInput } from '@/components/Common/PathInput'; import { Select } from '@/components/Common/Select'; import { TextInput } from '@/components/Common/TextInput'; @@ -23,7 +22,6 @@ import { import { AgentIconField } from './AgentIconField'; import { ProfileEditActions } from './ProfileEditActions'; import { ReadOnlyField } from './ReadOnlyField'; -import { useProfileLaunchPreview } from './useProfileLaunchPreview'; import type { AcpAgentCliInfo, @@ -43,19 +41,12 @@ interface CommandProfileFormProps { } const CUSTOM_CAPABILITIES = { - customLaunchCommand: 'supported', - autoApprove: 'unsupported', - modelOverride: 'unsupported', - sessionPersistence: 'unsupported', + customLaunchCommand: true, + autoApprove: false, } as const; function supportsStructuredEditing(cli: AcpAgentCliInfo | undefined) { - return ( - cli?.installed === true && - cli.launchVersion === 1 && - cli.launchPreviewVersion === 1 && - cli.capabilities !== undefined - ); + return cli?.status === 'ready'; } function defaultWrapper(clis: AcpAgentCliInfo[]) { @@ -139,10 +130,9 @@ export function CommandProfileForm({ descriptor?.capabilities ?? (custom && !descriptor ? CUSTOM_CAPABILITIES : undefined); const structuredSupported = supportsStructuredEditing(descriptor); - const commandSupported = - custom && capabilities?.customLaunchCommand === 'supported'; + const commandSupported = custom && capabilities?.customLaunchCommand === true; const approvalSupported = - !custom && structuredSupported && capabilities?.autoApprove === 'supported'; + !custom && structuredSupported && capabilities?.autoApprove === true; const agentName = custom ? t('settings.customCommand') : (descriptor?.displayName ?? cliId); @@ -176,14 +166,6 @@ export function CommandProfileForm({ } : {}), }; - const preview = useProfileLaunchPreview( - !custom && structuredSupported - ? { - launch, - ...(editing ? { profileId: editing.id } : { agentletId }), - } - : null, - ); const executionChanged = launchChanged || cwdChanged; const invalidExecution = executionChanged && @@ -191,8 +173,6 @@ export function CommandProfileForm({ (custom ? launchChanged && (!commandSupported || !command.trim()) : !structuredSupported || - !preview.plan || - !!preview.error || (launchChanged && !approvalSupported && !!editing))); const saveDisabled = saving || @@ -200,8 +180,7 @@ export function CommandProfileForm({ !agentletId || (!editing && !connectedDevices.length) || invalidExecution; - const knownControlsDisabled = - saving || !structuredSupported || !!preview.error; + const knownControlsDisabled = saving || !structuredSupported; const options = [ ...detectedClis .filter((cli) => cli.id !== 'custom') @@ -325,49 +304,6 @@ export function CommandProfileForm({ ) : cliId ? ( <> - - - {preview.plan ? ( - - ) : ( - - {t( - preview.pending - ? 'settings.profilePreviewLoading' - : 'settings.profilePreviewUnavailable', - )} - - )} - {preview.error ? ( - <> -

- {preview.error} -

- - - ) : null} - - cli.id !== 'custom' && - cli.installed && + cli.status !== 'not-found' && !supportsStructuredEditing(cli), ) ? (

diff --git a/apps/web/src/components/Settings/agent-profiles/useDetectedClis.test.tsx b/apps/web/src/components/Settings/agent-profiles/useDetectedClis.test.tsx index b58d816b8..91ead3aca 100644 --- a/apps/web/src/components/Settings/agent-profiles/useDetectedClis.test.tsx +++ b/apps/web/src/components/Settings/agent-profiles/useDetectedClis.test.tsx @@ -57,11 +57,9 @@ let container: HTMLDivElement | undefined; const detectedAgent: AcpAgentCliInfo = { id: 'copilot', displayName: 'Copilot', - binary: 'copilot', - acpArgs: ['--acp'], - autoApprove: null, - installed: true, + status: 'ready', installHint: 'Install Copilot', + capabilities: { autoApprove: true, customLaunchCommand: false }, }; afterEach(() => { diff --git a/apps/web/src/components/Settings/agent-profiles/useProfileLaunchPreview.ts b/apps/web/src/components/Settings/agent-profiles/useProfileLaunchPreview.ts deleted file mode 100644 index 22d806ad5..000000000 --- a/apps/web/src/components/Settings/agent-profiles/useProfileLaunchPreview.ts +++ /dev/null @@ -1,62 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -import { useEffect, useState } from 'react'; - -import { previewAcpProfileLaunch } from '@/api/acp'; - -import type { - AcpProfileLaunchPreviewBody, - AcpProfileLaunchPreviewResponse, -} from '@huabu/shared'; - -interface PreviewResult { - key: string; - plan?: AcpProfileLaunchPreviewResponse; - error?: string; -} - -/** Debounce daemon compilation and fence results from older form drafts. */ -export function useProfileLaunchPreview( - body: AcpProfileLaunchPreviewBody | null, -) { - const key = body ? JSON.stringify(body) : null; - const [result, setResult] = useState(null); - const [attempt, setAttempt] = useState(0); - - useEffect(() => { - if (!key) return; - let active = true; - const timer = window.setTimeout(() => { - const request = JSON.parse(key) as AcpProfileLaunchPreviewBody; - void previewAcpProfileLaunch(request).then( - (plan) => { - if (active) setResult({ key, plan }); - }, - (error: unknown) => { - if (active) { - setResult({ - key, - error: error instanceof Error ? error.message : String(error), - }); - } - }, - ); - }, 300); - return () => { - active = false; - window.clearTimeout(timer); - }; - }, [key, attempt]); - - const current = result?.key === key ? result : null; - return { - plan: current?.plan, - error: current?.error, - pending: key !== null && current === null, - retry: () => { - setResult(null); - setAttempt((previous) => previous + 1); - }, - }; -} diff --git a/docs/architecture/agent-profiles.md b/docs/architecture/agent-profiles.md index 6fa5c14cd..e9e376e49 100644 --- a/docs/architecture/agent-profiles.md +++ b/docs/architecture/agent-profiles.md @@ -15,7 +15,7 @@ agentlet control connection / reconnection -> Settings and Agent Node selectors ``` -The catalogue resides in `external/agentlet/packages/local/src/harnesses/catalogue.ts`. Harness IDs are fixed catalogue IDs, such as `copilot`, `claude`, and `codex`, not generated instance IDs. Claude and Codex detection targets their ACP adapters rather than the similarly named native CLIs. Detection uses shell-free, bounded executable probes on the agentlet machine. An optional version probe failing does not make a located binary disappear; diagnostics distinguish unknown versions and actual lookup/workspace failures. +Definitions reside in per-harness modules under `external/agentlet/packages/local/src/harnesses/` and are registered in `registry.ts`. Harness IDs are fixed Definition IDs, such as `copilot`, `claude`, and `codex`, not generated instance IDs. Each Definition owns static identity, boolean capabilities, target-local discovery, and trusted command compilation. Claude and Codex discovery targets their ACP adapters and reports `adapter-missing` when only the corresponding native CLI is present. An optional version probe failing does not make a ready command disappear. The daemon advertises versioned harness discovery support. The Gateway routes requests to an explicit `agentletId` and validates the reply. Unsupported or unavailable daemons fail explicitly; Huabu never substitutes Server-local PATH observations. @@ -37,17 +37,17 @@ Gateway sends a WebSocket heartbeat every 15 seconds and terminates connections A Profile has `id`, `alias`, `agentletId`, `workingDirPath`, a launch configuration, optional `metadata.cliId`, opaque `customData`, and configuration/execution revisions. Launch is either `{ kind: 'acp-command', command }` or a structured `{ kind: 'acp-harness', harnessId, options?: { autoApprove? } }`. Every Profile has exactly one wrapper, derived from this launch union: a command Profile uses the Custom command wrapper; a structured Profile uses its `harnessId`. Neither editable metadata nor command-text inspection determines capabilities. Profile ID, target machine, launch kind, and harness identity are immutable; alias, icon, cwd, and supported launch options are editable. Changing machine or wrapper requires a new Profile. -Structured launches require the target daemon's versioned harness-launch capability. New automatic Profiles use this form when discovery advertises `launchVersion: 1`; older daemons keep the existing command provisioning path. Manual creation and runtime-relevant editing additionally require `launchPreviewVersion: 1` and validate options with the target daemon's canonical builder. The editor submits structured options and displays a read-only daemon-built launch preview rather than assembling shell commands in the browser. Legacy command Profiles, including formerly discovered commands, map to Custom without modifying their stored records. Existing Profiles are not rewritten on discovery, and existing permission defaults are not changed automatically. +Structured launches require the target daemon's version 2 discovery and harness-launch capabilities. New automatic Profiles use this form only for discovery entries whose status is `ready`; unavailable known harnesses do not produce compatibility command Profiles. Manual creation and runtime-relevant editing validate the unchanged structured option schema and current discovery capabilities without compiling a preview. Legacy command Profiles, including formerly discovered commands, map to Custom without modifying their stored records. Existing Profiles are not rewritten on discovery, and existing permission defaults are not changed automatically. -New automatic structured Profiles set `options.autoApprove: true` only when discovery explicitly reports `capabilities.autoApprove: 'supported'`. The wrapper compiles the corresponding approval flags; Huabu does not compose them. Unsupported, unknown, or missing capabilities leave the option unset. Users can disable it through Edit, and later discovery/reconnection preserves that choice, including after a host restart. Compatibility command Profiles, including Windows shell-only wrappers, remain Custom and receive no injected approval flags. This creation default does not change manual creation, existing Profiles, or realized execution snapshots. +New automatic structured Profiles set `options.autoApprove: true` only when discovery reports `capabilities.autoApprove: true`. The Definition compiles the corresponding approval flags; Huabu does not compose them. Users can disable the option through Edit, and later discovery/reconnection preserves that choice, including after a host restart. This creation default does not change manual creation, existing Profiles, or realized execution snapshots. -Discovery advertises structured launch only for a detected executable compatible with shell-free spawning. Windows shell-only wrappers, including npm `.cmd` shims, retain legacy command provisioning rather than creating an unusable structured Profile. Typed launch never silently enables shell execution. +Discovery is platform-aware and reports `ready`, `adapter-missing`, or `not-found`. On Windows it scans all `where.exe` results and accepts shell-resolvable `.exe`, `.com`, `.cmd`, and `.bat` candidates, so an extensionless npm POSIX shim cannot hide a later `.cmd` wrapper. On Unix it requires an absolute `which` result. Version probing uses `cmd.exe` on Windows and shell-free execution on Unix. This models the target platform shell, not interactive aliases or startup scripts. -Agentlet wrappers expose detection, capability description, and launch building. Capabilities describe `customLaunchCommand`, `autoApprove`, `modelOverride`, and `sessionPersistence` using `supported`, `unsupported`, or `unknown`. Custom supports only `customLaunchCommand`: the user supplies the raw command, and no generic approval, model, or session-persistence settings are injected. Known harness wrappers do not support raw-command editing and compile supported options into an executable, argv, and environment without a shell. The unified launch result preserves this boundary with separate `exec` and `shell` variants. Custom is manually configurable, not a binary discovered on PATH, and is never automatically provisioned. +Agentlet Definitions expose discovery, boolean `customLaunchCommand` and `autoApprove` capabilities, and launch compilation. Custom supports only `customLaunchCommand`: the user supplies the raw command, and no generic approval or model setting is injected. Known Definitions do not support raw-command editing and compile only trusted static tokens plus bounded options into a terminal-style shell command. Both known and Custom launches execute through the target Agentlet's platform shell; the trust boundary is command provenance, not a shell-free process API. Custom is manually configurable and is never automatically provisioned. The same capability-driven form handles creation and editing, including automatically created Profiles. Common alias/icon/cwd fields are not wrapper capabilities. Missing or unknown capability support never enables a control. ACP model configuration remains a protocol operation, not a guessed command-line flag; a Custom Agent may still report live ACP model controls without gaining generic Profile-level model injection. A detected binary does not prove authentication, model availability, or an ACP adapter's support for native CLI no-history options. This foundation does not add native print-mode execution or a new background permission policy. -After a successful structured ACP bootstrap, the driver persists the resolved `harnessLaunchPlan` in driver state and reuses it during recovery. The Profile recipe remains immutable and independent of later edits or deletion. The plan freezes launch arguments and launch-specific environment, not installed binary versions, inherited runtime environment, or a pre-bootstrap failure. +The frozen execution recipe stores the Profile launch intent and resolved cwd. Runtime and recovery send that frozen intent to the selected Agentlet, whose matching Definition compiles it immediately before spawn. Later Profile edits or deletion do not affect the execution. Historical optional `harnessLaunchPlan` data remains parseable for persisted-data compatibility but is ignored as executable input, and new executions do not write it. This change performs no migration or rewrite of existing Profiles, workloads, or durable state. The editable Profile is a template, not an execution. A conversation freezes its recipe, cwd, instructions, preferences, and `profileExecutionRevision` at first realization (first prompt or first mode/model/config control), not when its tab or Agent Node is created. Unrealized conversations use the latest template; realized executions and resumed/restarted processes keep their persisted snapshot. An editable external Agent Node may persist a Node-specific cwd override in `agentLaunchOverrides.workingDirPath`; an absent override inherits the selected Profile without copying its value, while an explicit override survives pre-realization Profile changes and takes precedence only for that Node. A successful non-no-op Profile patch advances `revision`; launch/cwd changes also advance `executionRevision`. Missing legacy revisions mean zero without rewriting the record. HTTP edits require `expectedRevision`; stale saves fail with `409 profile_conflict`, including changes that race asynchronous daemon validation. @@ -63,7 +63,7 @@ Huabu stores the reserved automatic-source marker in `customData.discoveredAgent } ``` -The tuple deduplicates only automatic defaults. For discovery advertising `launchVersion: 1`, an existing automatic Profile suppresses creation only when its actual launch is `acp-harness` for the same harness. A legacy automatic `acp-command` Profile therefore remains untouched while discovery creates a new typed Profile with a distinct ID. Reconnection and restart reuse that typed identity, preserving its edits; discovery without typed support continues to deduplicate against either launch kind rather than creating downgrade duplicates. Manual Profiles without automatic provenance do not suppress automatic creation. +The tuple deduplicates only automatic defaults. For a ready v2 Definition, an existing automatic Profile suppresses creation only when its actual launch is `acp-harness` for the same harness. A legacy automatic `acp-command` Profile therefore remains untouched while discovery creates a new typed Profile with a distinct ID. Reconnection and restart reuse that typed identity, preserving its edits. Manual Profiles without automatic provenance do not suppress automatic creation. Profile aliases are display labels, not unique keys: Utility Agent settings, conversational recency, edits, execution snapshots and thread bindings use Profile IDs. When a new automatic typed Profile's standard alias is already occupied, its initial alias adds the harness ID in brackets, such as `GitHub Copilot (huabu) [copilot]`; this is a display hint, not an alias-uniqueness constraint. Existing aliases, commands, launch options, directories, saved settings and conversation bindings are not rewritten or migrated. The create API rejects caller-supplied automatic provenance; patches preserve the original marker even when replacing or clearing other custom data, and reject attempts to change it. The generic Agenetes registry does not interpret this Huabu-owned field. @@ -103,7 +103,7 @@ Ink submission without an existing Question target refreshes the Profile catalog `GET /api/acp/agent-cli` requires exactly one explicit target: `agentletId` for creation or `profileId` for editing. It includes launch support and capability observations without preparing workspaces or creating Profiles. Older successful catalogues receive the canonical Custom descriptor; failed detection remains an explicit error, not a misleading successful catalogue. Custom command configuration and display-only edits remain available without successful detection. Manual creation requires an active device and an explicit `workingDirPath`; only automatic defaults get a daemon-prepared directory. -Owner-only `POST /api/acp/profile-launch-preview` requires `{ launch, agentletId }` for creation or `{ launch, profileId }` for editing and returns the explicitly targeted Agentlet's validated `exec`/`shell` plan. It never spawns an Agent or prepares a workspace. Unsupported or disconnected target previews fail explicitly. `POST /api/acp/profiles` requires an active `agentletId` and persists that immutable placement; Settings initializes the form with the first deterministically sorted active device only as an unsaved UI convenience. Profile creation and runtime-relevant patches independently validate structured launch support and options, so client-side controls are not the validation boundary. `PATCH /api/acp/profiles/:id` requires `expectedRevision` and permits mutable template fields only; display-only edits do not require a connected Agentlet. +`POST /api/acp/profiles` requires an active `agentletId` and persists that immutable placement; Settings initializes the form with the first deterministically sorted active device only as an unsaved UI convenience. Profile creation and runtime-relevant patches independently validate current discovery readiness, capabilities, and structured options, so client-side controls are not the validation boundary. There is no launch-preview endpoint: compilation remains Agentlet-owned and occurs inside runtime spawn. `PATCH /api/acp/profiles/:id` requires `expectedRevision` and permits mutable template fields only; display-only edits do not require a connected Agentlet. The Agent Settings surface presents active Connected Devices first, followed by ordinary Profiles, their existing edit/delete actions, and the supervised-child health banner alongside Utility Agent and backend-specific configuration. The create editor requires a device selection before harness selection; editing displays the immutable device identity read-only. Opening a Profile editor temporarily focuses that nested view without duplicating or rewriting Profile state. Template/member Config/setup controls are removed. Catalogue, Profile, Utility Agent, and conversational preference endpoints remain owner-only. Shared HTTP contracts remain under `packages/shared/src/types/api/`, with type-only imports in the Web app. diff --git a/docs/architecture/api-design.md b/docs/architecture/api-design.md index b24f12ceb..0c81b68ee 100644 --- a/docs/architecture/api-design.md +++ b/docs/architecture/api-design.md @@ -148,7 +148,7 @@ Malformed request fields and malformed cursors return HTTP 400 with `code: "malf `GET/PUT /api/acp/runtime-config` uses `externalAgentRuntimeConfigSchema` from [`acp.ts`](../../packages/shared/src/types/api/acp.ts). The owner-only full replacement body contains `idleTimeoutSecs` and `maxAgents`; `maxAgents` is a positive JavaScript safe integer with default `10` and no product-defined upper bound. The value is persisted globally and supplied to the supervised Agentlet daemon as `--max-agents` on its next start; the API does not restart the daemon or configure manually launched remote daemons. -`GET /api/acp/profiles` returns persisted Profiles, active connected devices, connectivity-filtered `selectableProfileIds`, supervised-child health, and optional Agent defaults. `POST /api/acp/profiles` requires an explicit active `agentletId`. `GET /api/acp/agent-cli` and `POST /api/acp/profile-launch-preview` require exactly one explicit target: `agentletId` while creating or `profileId` while editing. The server validates every target against the live Gateway and never substitutes the supervised child or first connected device. +`GET /api/acp/profiles` returns persisted Profiles, active connected devices, connectivity-filtered `selectableProfileIds`, supervised-child health, and optional Agent defaults. `POST /api/acp/profiles` requires an explicit active `agentletId`. `GET /api/acp/agent-cli` requires exactly one explicit target: `agentletId` while creating or `profileId` while editing. The server validates every target against the live Gateway and never substitutes the supervised child or first connected device. Harness commands are compiled by the target Agentlet during spawn; there is no HTTP launch-preview contract. ## Utility Agent selection diff --git a/packages/shared/src/types/api/acp.ts b/packages/shared/src/types/api/acp.ts index 10befbe49..aaea4a44b 100644 --- a/packages/shared/src/types/api/acp.ts +++ b/packages/shared/src/types/api/acp.ts @@ -130,32 +130,14 @@ export type AcpDaemonRestartResponse = AcpAgentletRestartResponse; export const acpAgentCliInfoSchema = z.object({ id: z.string().min(1), displayName: z.string().min(1), - binary: z.string().min(1), - acpArgs: z.array(z.string()), - /** `position` preserves CLIs whose global options precede ACP arguments. */ - autoApprove: z - .object({ - args: z.array(z.string()), - position: z.enum(['before-acp', 'after-acp']), - }) - .nullable(), + status: z.enum(['ready', 'adapter-missing', 'not-found']), version: z.string().optional(), - installed: z.boolean(), installHint: z.string(), - executablePath: z.string().optional(), workingDirPath: z.string().optional(), - launchVersion: z.literal(1).optional(), - launchPreviewVersion: z.literal(1).optional(), - capabilities: z - .object({ - autoApprove: z.enum(['supported', 'unsupported', 'unknown']), - modelOverride: z.enum(['supported', 'unsupported', 'unknown']), - sessionPersistence: z.enum(['supported', 'unsupported', 'unknown']), - customLaunchCommand: z - .enum(['supported', 'unsupported', 'unknown']) - .optional(), - }) - .optional(), + capabilities: z.object({ + autoApprove: z.boolean(), + customLaunchCommand: z.boolean(), + }), diagnostics: z .array(z.object({ code: z.string(), message: z.string() })) .optional(), diff --git a/packages/shared/src/types/api/agent-profile.test.ts b/packages/shared/src/types/api/agent-profile.test.ts index cbdb8675d..356f60078 100644 --- a/packages/shared/src/types/api/agent-profile.test.ts +++ b/packages/shared/src/types/api/agent-profile.test.ts @@ -170,11 +170,12 @@ describe('ordinary command Profile contracts', () => { { id: 'future-cli', displayName: 'Future CLI', - binary: 'future-cli', - acpArgs: ['acp'], - autoApprove: null, - installed: false, installHint: 'Install the CLI', + status: 'not-found', + capabilities: { + autoApprove: false, + customLaunchCommand: false, + }, diagnostics: [{ code: 'missing', message: 'Not on PATH' }], }, ], diff --git a/packages/shared/src/types/api/agent-profile.ts b/packages/shared/src/types/api/agent-profile.ts index 717227f23..9c04d420f 100644 --- a/packages/shared/src/types/api/agent-profile.ts +++ b/packages/shared/src/types/api/agent-profile.ts @@ -156,42 +156,6 @@ export const patchAgentProfileBodySchema = z ); export type PatchAgentProfileBody = z.infer; -export const acpProfileLaunchPreviewBodySchema = z - .object({ - profileId: trimmedString(255).optional(), - agentletId: trimmedString(255).optional(), - launch: agentProfileSchema.shape.launch, - }) - .strict() - .refine( - (value) => - Number(value.profileId !== undefined) + - Number(value.agentletId !== undefined) === - 1, - { message: 'Exactly one Profile or Agentlet target is required' }, - ); -export type AcpProfileLaunchPreviewBody = z.infer< - typeof acpProfileLaunchPreviewBodySchema ->; - -export const acpProfileLaunchPreviewResponseSchema = z.discriminatedUnion( - 'kind', - [ - z - .object({ - kind: z.literal('exec'), - executable: z.string().min(1), - argv: z.array(z.string()), - env: z.record(z.string(), z.string()), - }) - .strict(), - z.object({ kind: z.literal('shell'), command: z.string().min(1) }).strict(), - ], -); -export type AcpProfileLaunchPreviewResponse = z.infer< - typeof acpProfileLaunchPreviewResponseSchema ->; - export const agentProfileParamsSchema = z.object({ id: z.string().min(1) }); export type AgentProfileParams = z.infer; From ceb08daffad91d9b13c409c521d7c4518e2d3206 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Thu, 8 Oct 2026 02:13:00 +0000 Subject: [PATCH 04/36] fix(server): use canonical public origin for reachback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .env.example | 10 +++-- README.md | 3 +- apps/server/src/app.ts | 6 +-- apps/server/src/connection-token.test.ts | 16 +++++++ apps/server/src/connection-token.ts | 19 ++++---- apps/server/src/host-port.ts | 10 ++--- .../modules/agent/acp/reachback-env.test.ts | 40 +++++++++++++++++ .../src/modules/agent/acp/reachback-env.ts | 16 +++++-- .../security/deployment-config.test.ts | 38 ++++++++++++++++ .../src/modules/security/deployment-config.ts | 42 +++++++++++++++-- .../server/src/modules/security/host-guard.ts | 6 ++- .../modules/security/public-origin.test.ts | 37 +++++++++++++++ .../src/modules/security/public-origin.ts | 45 +++++++++++++++++++ bin/start-agentlet-daemon | 21 ++++++--- docs/architecture/agent-profiles.md | 2 +- docs/architecture/agent-reachback.md | 7 +-- docs/architecture/deployment-security.md | 5 ++- 17 files changed, 278 insertions(+), 45 deletions(-) create mode 100644 apps/server/src/modules/agent/acp/reachback-env.test.ts create mode 100644 apps/server/src/modules/security/public-origin.test.ts create mode 100644 apps/server/src/modules/security/public-origin.ts diff --git a/.env.example b/.env.example index 562580ab6..133e0b59b 100644 --- a/.env.example +++ b/.env.example @@ -51,10 +51,6 @@ # ── External ACP agents (Copilot, Claude Code, …) ── # Pairing itself is done in the Settings popover → "External Agents"; # codes are ephemeral and never written to disk (no env override). -# `ACP_URL` is only honoured by the `start-agentlet-daemon` wrapper when -# pointing the local CLI at a remote / TLS-fronted Huabu instance. -# ACP_URL=wss://my.host/api/acp/agent - # ── Network exposure ── # By default the server binds to 127.0.0.1 only, so a fresh install is # never silently exposed to the LAN. Set HUABU_BIND_HOST=0.0.0.0 (or a @@ -67,6 +63,12 @@ # anything beyond a trusted private network. # HUABU_BIND_HOST=0.0.0.0 # HUABU_ALLOWED_HOSTS=192.168.1.50,huabu.team-a.example +# Canonical root origin reachable by remote Agentlets. Required for a +# non-loopback bind. Use HTTP only on a trusted private network; otherwise +# terminate HTTPS in front of Huabu. Its hostname must also appear in +# HUABU_ALLOWED_HOSTS. Paths, credentials, queries, and fragments are rejected. +# RFS and Agentlet endpoints are derived from this one value. +# HUABU_PUBLIC_ORIGIN=https://huabu.team-a.example # ── Single-owner remote login ── # Both values are required together. The authenticated owner can use every diff --git a/README.md b/README.md index 18d54db9d..40c48973d 100644 --- a/README.md +++ b/README.md @@ -86,11 +86,12 @@ The remote address must be an origin without credentials, a query, fragment, or ```dotenv HUABU_BIND_HOST=0.0.0.0 HUABU_ALLOWED_HOSTS=huabu.example.com +HUABU_PUBLIC_ORIGIN=https://huabu.example.com HUABU_BASIC_AUTH_USER=owner HUABU_BASIC_AUTH_PASS= ``` -Then run `pnpm start:web`. Huabu rejects a non-loopback bind when allowed hosts or either Basic Auth value is missing. The authenticated owner can use all features, including Settings, OAuth, and External Agents. `pnpm dev` applies the same requirement to non-loopback browser clients while preserving zero-configuration local development. +Then run `pnpm start:web`. `HUABU_PUBLIC_ORIGIN` is the root HTTP(S) origin that remote Agentlets use to reach this deployment; Huabu derives both the Canvas RFS URL and Agentlet WebSocket endpoint from it. Its hostname must appear in `HUABU_ALLOWED_HOSTS`. Huabu rejects paths, credentials, queries, fragments, unsupported schemes, a Host-allowlist mismatch, and a missing or loopback public origin for non-loopback binds. It also rejects a non-loopback bind when allowed hosts or either Basic Auth value is missing. The authenticated owner can use all features, including Settings, OAuth, and External Agents. `pnpm dev` applies the same requirement to non-loopback browser clients while preserving zero-configuration local development. Huabu currently serves HTTP. Use a trusted private network or terminate HTTPS with deployment infrastructure such as Caddy, Nginx, Tailscale Serve, or a cloud load balancer. Do not put a Basic Auth deployment on an untrusted network without transport encryption. diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index 231aaeffe..d77c99ae7 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -341,10 +341,8 @@ app.addHook('onClose', async () => resetExternalNoteSessions()); // a connection-holding backend will need — a pool nobody closes leaks on // every restart, and the lifecycle is where that is visible. app.addHook('onClose', async () => closeStorage()); -// Capture the bound TCP port for L1-owned reachback (RFS): the -// canvas-scoped `HUABU_RFS_URL` base is built from this. RFS is -// canvas-coupled and therefore a pure L1 concern, so the port lives in -// L1 rather than being read back out of the L2 transport host. +// Capture the bound TCP port for the local RFS reachback fallback. Public +// deployments use their configured canonical origin instead. app.addHook('onListen', async () => { const addr = app.server.address(); if (addr && typeof addr !== 'string') setHostServerPort(addr.port); diff --git a/apps/server/src/connection-token.test.ts b/apps/server/src/connection-token.test.ts index 3967f9294..708e54674 100644 --- a/apps/server/src/connection-token.test.ts +++ b/apps/server/src/connection-token.test.ts @@ -49,10 +49,12 @@ beforeEach(() => { mocks.setSecret.mockResolvedValue(undefined); vi.clearAllMocks(); delete process.env.HUABU_CONNECTION_TOKEN; + delete process.env.HUABU_PUBLIC_ORIGIN; }); afterEach(() => { delete process.env.HUABU_CONNECTION_TOKEN; + delete process.env.HUABU_PUBLIC_ORIGIN; }); describe('connection token resolution', () => { @@ -144,4 +146,18 @@ describe('Agentlet connection command', () => { 'Origin must be an HTTP(S) origin without a path', ); }); + + it('uses the configured public origin instead of the browser origin', () => { + process.env.HUABU_CONNECTION_TOKEN = 'token'; + process.env.HUABU_PUBLIC_ORIGIN = 'https://public.huabu.example:8443/'; + initializeConnectionToken(); + + expect( + buildAgentletConnectionCommand('http://localhost:5173'), + ).toMatchObject({ + command: + "agentlet daemon --server 'wss://public.huabu.example:8443/api/acp/agent' --max-agents 7 --token 'token'", + warnings: [], + }); + }); }); diff --git a/apps/server/src/connection-token.ts b/apps/server/src/connection-token.ts index bef40ae48..ebe8758a4 100644 --- a/apps/server/src/connection-token.ts +++ b/apps/server/src/connection-token.ts @@ -10,6 +10,10 @@ import { } from '@agenetes/agentlet-host'; import { getExternalAgentRuntimeConfig } from './modules/agent/acp/runtime-config.js'; +import { + normalizePublicOrigin, + resolveConfiguredPublicOrigin, +} from './modules/security/public-origin.js'; import { SECRET_IDS } from './security/secret-ids.js'; import { getPersistedSecret, @@ -145,19 +149,16 @@ export class InvalidAgentletConnectionOriginError extends Error {} export function buildAgentletConnectionCommand( originValue: string, ): AgentletConnectionCommandResponse { - const origin = new URL(originValue); - if ( - !['http:', 'https:'].includes(origin.protocol) || - origin.username || - origin.password || - origin.pathname !== '/' || - origin.search || - origin.hash - ) { + let normalizedOrigin: string; + try { + normalizedOrigin = + resolveConfiguredPublicOrigin() ?? normalizePublicOrigin(originValue); + } catch { throw new InvalidAgentletConnectionOriginError( 'Origin must be an HTTP(S) origin without a path', ); } + const origin = new URL(normalizedOrigin); const insecure = origin.protocol === 'http:'; const endpoint = `${insecure ? 'ws:' : 'wss:'}//${origin.host}/api/acp/agent`; const maxAgents = getExternalAgentRuntimeConfig().maxAgents; diff --git a/apps/server/src/host-port.ts b/apps/server/src/host-port.ts index 2e7f554a4..5f3d74c33 100644 --- a/apps/server/src/host-port.ts +++ b/apps/server/src/host-port.ts @@ -6,9 +6,9 @@ * `onListen` hook in {@link ./app.ts}. * * This is L1-owned: the canvas-scoped Remote File System reachback - * (`HUABU_RFS_URL = http://127.0.0.1:/api/rfs/`) is a - * pure L1 concern (RFS is canvas-coupled), so the port lives here - * rather than being read back out of the L2 transport host. + * (`HUABU_RFS_URL = http://127.0.0.1:/api/rfs/`) uses + * this port only for the local fallback when no public origin is configured. + * The port lives here rather than being read back out of the L2 transport host. */ let serverPort = 0; @@ -19,8 +19,8 @@ export function setHostServerPort(port: number): void { /** * The bound TCP port, or `0` before the `onListen` hook has fired. - * Used by the spawn orchestrator to build the `HUABU_RFS_URL` reachback - * base injected into agent sessions. + * Used to build the local `HUABU_RFS_URL` fallback injected into agent + * sessions. */ export function getHostServerPort(): number { return serverPort; diff --git a/apps/server/src/modules/agent/acp/reachback-env.test.ts b/apps/server/src/modules/agent/acp/reachback-env.test.ts new file mode 100644 index 000000000..3c3f00806 --- /dev/null +++ b/apps/server/src/modules/agent/acp/reachback-env.test.ts @@ -0,0 +1,40 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, describe, expect, it, vi } from 'vitest'; + +vi.mock('../../../host-port.js', () => ({ + getHostServerPort: () => 3001, +})); + +import { buildReachbackEnv } from './reachback-env.js'; + +afterEach(() => { + delete process.env.HUABU_PUBLIC_ORIGIN; +}); + +describe('buildReachbackEnv', () => { + it('uses the configured canonical public origin', () => { + process.env.HUABU_PUBLIC_ORIGIN = 'https://huabu.example.com:8443/'; + + expect(buildReachbackEnv('thread-1', 'canvas-1')).toEqual({ + HUABU_RFS_URL: 'https://huabu.example.com:8443/api/rfs/canvas-1', + HUABU_THREAD_ID: 'thread-1', + }); + }); + + it('keeps the loopback fallback for local development', () => { + expect(buildReachbackEnv('thread-1', 'canvas-1')).toEqual({ + HUABU_RFS_URL: 'http://127.0.0.1:3001/api/rfs/canvas-1', + HUABU_THREAD_ID: 'thread-1', + }); + }); + + it('encodes the canvas id as one path segment', () => { + process.env.HUABU_PUBLIC_ORIGIN = 'https://192.0.2.10'; + + expect(buildReachbackEnv('thread-1', 'canvas/with space')).toMatchObject({ + HUABU_RFS_URL: 'https://192.0.2.10/api/rfs/canvas%2Fwith%20space', + }); + }); +}); diff --git a/apps/server/src/modules/agent/acp/reachback-env.ts b/apps/server/src/modules/agent/acp/reachback-env.ts index 484421ea1..a33a7c1a6 100644 --- a/apps/server/src/modules/agent/acp/reachback-env.ts +++ b/apps/server/src/modules/agent/acp/reachback-env.ts @@ -9,7 +9,7 @@ * host over the canvas-scoped Remote File System (RFS) and attribute its * change-review activity to the right conversation: * - * - `HUABU_RFS_URL` — `http://127.0.0.1:/api/rfs/`, + * - `HUABU_RFS_URL` — `/api/rfs/`, * the canvas-scoped RFS base (capabilities / query / * download / upload / execute / agent / skill). Bakes the canvasId into the path * so the agent needs no separate canvas variable. @@ -26,6 +26,7 @@ */ import { getHostServerPort } from '../../../host-port.js'; +import { resolveConfiguredPublicOrigin } from '../../security/public-origin.js'; /** * Build the reachback env for an agent serving `threadId` in `canvasId`. @@ -38,9 +39,16 @@ export function buildReachbackEnv( ): Record { const env: Record = {}; if (canvasId) { - const port = getHostServerPort(); - if (port > 0) { - env.HUABU_RFS_URL = `http://127.0.0.1:${port}/api/rfs/${canvasId}`; + let origin = resolveConfiguredPublicOrigin(); + if (!origin) { + const port = getHostServerPort(); + if (port > 0) origin = `http://127.0.0.1:${port}`; + } + if (origin) { + env.HUABU_RFS_URL = new URL( + `/api/rfs/${encodeURIComponent(canvasId)}`, + origin, + ).toString(); } } env.HUABU_THREAD_ID = threadId; diff --git a/apps/server/src/modules/security/deployment-config.test.ts b/apps/server/src/modules/security/deployment-config.test.ts index e861762b3..9c601e2aa 100644 --- a/apps/server/src/modules/security/deployment-config.test.ts +++ b/apps/server/src/modules/security/deployment-config.test.ts @@ -34,6 +34,14 @@ describe('resolveDeploymentConfig', () => { HUABU_ALLOWED_HOSTS: 'huabu.example', }), ).toThrow(/HUABU_BASIC_AUTH/); + expect(() => + resolveDeploymentConfig({ + HUABU_BIND_HOST: '0.0.0.0', + HUABU_ALLOWED_HOSTS: 'huabu.example', + HUABU_BASIC_AUTH_USER: 'owner', + HUABU_BASIC_AUTH_PASS: 'secret', + }), + ).toThrow(/HUABU_PUBLIC_ORIGIN/); }); it('accepts a fully protected network bind', () => { @@ -43,11 +51,41 @@ describe('resolveDeploymentConfig', () => { HUABU_ALLOWED_HOSTS: 'huabu.example', HUABU_BASIC_AUTH_USER: 'owner', HUABU_BASIC_AUTH_PASS: 'secret', + HUABU_PUBLIC_ORIGIN: 'https://huabu.example:8443/', }), ).toMatchObject({ allowedHostsConfigured: true, basicAuthConfigured: true, bindScope: 'network', + publicOrigin: 'https://huabu.example:8443', }); }); + + it.each([ + 'http://127.0.0.1:3001', + 'http://[::1]:3001', + 'http://localhost.:3001', + ])('rejects loopback public origin %s for a network bind', (publicOrigin) => { + expect(() => + resolveDeploymentConfig({ + HUABU_BIND_HOST: '0.0.0.0', + HUABU_ALLOWED_HOSTS: new URL(publicOrigin).hostname, + HUABU_BASIC_AUTH_USER: 'owner', + HUABU_BASIC_AUTH_PASS: 'secret', + HUABU_PUBLIC_ORIGIN: publicOrigin, + }), + ).toThrow(/beyond loopback/); + }); + + it('requires the public hostname in the Host allowlist', () => { + expect(() => + resolveDeploymentConfig({ + HUABU_BIND_HOST: '0.0.0.0', + HUABU_ALLOWED_HOSTS: 'internal.huabu.example', + HUABU_BASIC_AUTH_USER: 'owner', + HUABU_BASIC_AUTH_PASS: 'secret', + HUABU_PUBLIC_ORIGIN: 'https://public.huabu.example', + }), + ).toThrow(/included in HUABU_ALLOWED_HOSTS/); + }); }); diff --git a/apps/server/src/modules/security/deployment-config.ts b/apps/server/src/modules/security/deployment-config.ts index 3040e6c46..93ed2583c 100644 --- a/apps/server/src/modules/security/deployment-config.ts +++ b/apps/server/src/modules/security/deployment-config.ts @@ -3,18 +3,28 @@ import { isIP } from 'node:net'; +import { resolveAllowedHostnames } from './host-guard.js'; +import { resolveConfiguredPublicOrigin } from './public-origin.js'; + export interface DeploymentConfig { allowedHostsConfigured: boolean; basicAuthConfigured: boolean; bindHost: string; bindScope: 'loopback' | 'network'; + publicOrigin?: string; } function isLoopbackHost(host: string): boolean { - if (host === 'localhost') return true; - if (host === '::1') return true; - if (isIP(host) === 4) { - return host.split('.')[0] === '127'; + const lower = host.toLowerCase(); + const withoutTrailingDot = lower.endsWith('.') ? lower.slice(0, -1) : lower; + const normalized = + withoutTrailingDot.startsWith('[') && withoutTrailingDot.endsWith(']') + ? withoutTrailingDot.slice(1, -1) + : withoutTrailingDot; + if (normalized === 'localhost') return true; + if (normalized === '::1') return true; + if (isIP(normalized) === 4) { + return normalized.split('.')[0] === '127'; } return false; } @@ -33,6 +43,7 @@ export function resolveDeploymentConfig( const allowedHostsConfigured = Boolean(env.HUABU_ALLOWED_HOSTS?.trim()); const bindScope = isLoopbackHost(bindHost) ? 'loopback' : 'network'; + const publicOrigin = resolveConfiguredPublicOrigin(env); if (bindScope === 'network' && !allowedHostsConfigured) { throw new Error( 'HUABU_ALLOWED_HOSTS is required when HUABU_BIND_HOST is not loopback', @@ -43,11 +54,34 @@ export function resolveDeploymentConfig( 'HUABU_BASIC_AUTH_USER and HUABU_BASIC_AUTH_PASS are required when HUABU_BIND_HOST is not loopback', ); } + if (bindScope === 'network' && !publicOrigin) { + throw new Error( + 'HUABU_PUBLIC_ORIGIN is required when HUABU_BIND_HOST is not loopback', + ); + } + if ( + bindScope === 'network' && + publicOrigin && + isLoopbackHost(new URL(publicOrigin).hostname) + ) { + throw new Error( + 'HUABU_PUBLIC_ORIGIN must be reachable beyond loopback when HUABU_BIND_HOST is not loopback', + ); + } + if (bindScope === 'network' && publicOrigin) { + const publicHostname = new URL(publicOrigin).hostname.toLowerCase(); + if (!resolveAllowedHostnames(env).has(publicHostname)) { + throw new Error( + 'HUABU_PUBLIC_ORIGIN hostname must be included in HUABU_ALLOWED_HOSTS', + ); + } + } return { allowedHostsConfigured, basicAuthConfigured: userConfigured, bindHost, bindScope, + ...(publicOrigin ? { publicOrigin } : {}), }; } diff --git a/apps/server/src/modules/security/host-guard.ts b/apps/server/src/modules/security/host-guard.ts index 3fb1da344..801c91eae 100644 --- a/apps/server/src/modules/security/host-guard.ts +++ b/apps/server/src/modules/security/host-guard.ts @@ -43,8 +43,10 @@ function extractHostname(host: string | undefined): string | null { * * Exported so the CORS layer can reuse the same set of hostnames. */ -export function resolveAllowedHostnames(): Set { - const extra = (process.env.HUABU_ALLOWED_HOSTS ?? '') +export function resolveAllowedHostnames( + env: NodeJS.ProcessEnv = process.env, +): Set { + const extra = (env.HUABU_ALLOWED_HOSTS ?? '') .split(',') .map((s) => s.trim().toLowerCase()) .filter(Boolean); diff --git a/apps/server/src/modules/security/public-origin.test.ts b/apps/server/src/modules/security/public-origin.test.ts new file mode 100644 index 000000000..a31524dc2 --- /dev/null +++ b/apps/server/src/modules/security/public-origin.test.ts @@ -0,0 +1,37 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { describe, expect, it } from 'vitest'; + +import { + normalizePublicOrigin, + resolveConfiguredPublicOrigin, +} from './public-origin.js'; + +describe('public origin', () => { + it.each([ + ['https://huabu.example.com', 'https://huabu.example.com'], + ['https://huabu.example.com:8443/', 'https://huabu.example.com:8443'], + ['http://192.168.1.50:3001', 'http://192.168.1.50:3001'], + ['https://[2001:db8::1]:8443', 'https://[2001:db8::1]:8443'], + ])('normalizes %s', (input, expected) => { + expect(normalizePublicOrigin(input)).toBe(expected); + }); + + it.each([ + 'ftp://huabu.example.com', + 'https://owner:secret@huabu.example.com', + 'https://huabu.example.com/base', + 'https://huabu.example.com?mode=remote', + 'https://huabu.example.com#remote', + 'not-a-url', + ])('rejects unsafe or non-origin value %s', (input) => { + expect(() => normalizePublicOrigin(input)).toThrow(/HUABU_PUBLIC_ORIGIN/); + }); + + it('treats an empty setting as unconfigured', () => { + expect(resolveConfiguredPublicOrigin({ HUABU_PUBLIC_ORIGIN: ' ' })).toBe( + undefined, + ); + }); +}); diff --git a/apps/server/src/modules/security/public-origin.ts b/apps/server/src/modules/security/public-origin.ts new file mode 100644 index 000000000..3b299490c --- /dev/null +++ b/apps/server/src/modules/security/public-origin.ts @@ -0,0 +1,45 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +export class InvalidPublicOriginError extends Error {} + +export function normalizePublicOrigin(rawValue: string): string { + let url: URL; + try { + url = new URL(rawValue.trim()); + } catch { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must be an absolute HTTP(S) origin', + ); + } + + if (url.protocol !== 'http:' && url.protocol !== 'https:') { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must use HTTP or HTTPS', + ); + } + if (url.username || url.password) { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must not include credentials', + ); + } + if (url.search || url.hash) { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must not include a query or fragment', + ); + } + if (url.pathname !== '/') { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must be an origin without a path prefix', + ); + } + + return url.origin; +} + +export function resolveConfiguredPublicOrigin( + env: NodeJS.ProcessEnv = process.env, +): string | undefined { + const rawValue = env.HUABU_PUBLIC_ORIGIN?.trim(); + return rawValue ? normalizePublicOrigin(rawValue) : undefined; +} diff --git a/bin/start-agentlet-daemon b/bin/start-agentlet-daemon index 2c1cc5d3e..e63647322 100755 --- a/bin/start-agentlet-daemon +++ b/bin/start-agentlet-daemon @@ -41,8 +41,8 @@ if [ ! -f "$cli" ]; then fi fi -# Auto-load /.env so SERVER_PORT and ACP_URL (still legitimate -# `.env` settings, read by the Fastify server too) are visible here. +# Auto-load /.env so SERVER_PORT and HUABU_PUBLIC_ORIGIN (the same +# canonical public origin read by the Fastify server) are visible here. # We strip CR before sourcing because the file may have CRLF line # endings (some editors do that), which POSIX `.` interprets as part # of the value and trips with `: not found` errors. `set -a` makes @@ -85,10 +85,19 @@ fi # embedded mount that `pnpm dev` exposes on the same port as the rest of # Huabu's API. SERVER_PORT already lives in .env (see .env.example) # and the server reads it from there too — single source of truth. -# - For non-local setups (different host, wss://, custom path) set -# ACP_URL to the full URL — it wins outright. -if [ -n "$ACP_URL" ]; then - url="$ACP_URL" +# - For non-local setups, HUABU_PUBLIC_ORIGIN is the root HTTP(S) origin +# shared with RFS. The server validates it during startup; this wrapper +# maps its scheme and appends the fixed Agentlet endpoint. +if [ -n "$HUABU_PUBLIC_ORIGIN" ]; then + public_origin=${HUABU_PUBLIC_ORIGIN%/} + case "$public_origin" in + https://*) url="wss://${public_origin#https://}/api/acp/agent" ;; + http://*) url="ws://${public_origin#http://}/api/acp/agent" ;; + *) + echo "start-agentlet-daemon: HUABU_PUBLIC_ORIGIN must use HTTP or HTTPS." >&2 + exit 1 + ;; + esac else url="ws://localhost:${SERVER_PORT:-3001}/api/acp/agent" fi diff --git a/docs/architecture/agent-profiles.md b/docs/architecture/agent-profiles.md index 6fa5c14cd..6cd2c6dc2 100644 --- a/docs/architecture/agent-profiles.md +++ b/docs/architecture/agent-profiles.md @@ -111,7 +111,7 @@ Workload placement is always explicit. New workloads snapshot the Profile's `age Owner-only `GET/PUT /api/acp/runtime-config` persists the external-agent idle timeout and supervised-daemon process limit in `/external-agent-runtime-config.json`; both controls appear under Settings > Agent > External Agent runtime. `maxAgents` defaults to `10` and accepts any positive JavaScript safe integer without a product-defined maximum. Huabu passes it as `--max-agents` whenever the supervised daemon starts; saving does not hot-update or automatically restart the daemon, and manually launched remote daemons continue to use their own CLI argument without a configuration handshake. -The same runtime section owns the masked Agentlet connection-token setting and one-click remote connection command. `GET/PUT /api/acp/connection-token` reports the active source and saves or clears the encrypted override without returning plaintext. `POST /api/acp/connection-command` returns the current origin-derived daemon command only to an authorized owner; the Web app copies it directly and shows transport or loopback warnings without rendering the command. +The same runtime section owns the masked Agentlet connection-token setting and one-click remote connection command. `GET/PUT /api/acp/connection-token` reports the active source and saves or clears the encrypted override without returning plaintext. `POST /api/acp/connection-command` returns a daemon command only to an authorized owner; it derives the endpoint from the deployment's canonical `HUABU_PUBLIC_ORIGIN`, falling back to the validated browser origin only for an unconfigured loopback deployment. The Web app copies the command directly and shows transport or loopback warnings without rendering it. ## Code entry points diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 46999e49c..7888e12d3 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -97,7 +97,7 @@ Parent lineage is best effort. The route resolves `parentThreadId` or `X-Huabu-H ## External-agent bootstrap -Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. Every external-agent Deployment persists the bootstrap as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. The preamble owns the authentication contract and curl header setup because every external Agent needs them before loading any Skill. The public basic guide is loaded without credentials from `GET /skill`; repeating that request with authentication adds the current root override and live Space Skill Frames. Advanced layout, Task, recursive-Agent, and Interactive View procedures are loaded on demand from authenticated `GET /skill/layout`, `/skill/tasks`, `/skill/agents`, and `/skill/interactive-views`. +Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/`; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists the bootstrap as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. The preamble owns the authentication contract and curl header setup because every external Agent needs them before loading any Skill. The public basic guide is loaded without credentials from `GET /skill`; repeating that request with authentication adds the current root override and live Space Skill Frames. Advanced layout, Task, recursive-Agent, and Interactive View procedures are loaded on demand from authenticated `GET /skill/layout`, `/skill/tasks`, `/skill/agents`, and `/skill/interactive-views`. Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. @@ -105,7 +105,7 @@ The guide is direct-first: an external agent can discover, query, download, snap RFS errors use the normal API error body and include a runnable `/skill` recovery command so a caller can reload the current usage contract after a malformed request. -Settings > Agent > External Agent runtime can copy a complete `agentlet daemon` command for another machine. The owner-only command endpoint derives `ws:` or `wss:` from the current browser origin, includes the configured process limit and active token, and returns `Cache-Control: no-store`; the renderer writes the command directly to the clipboard without displaying it. HTTP origins add `--allow-insecure`, and loopback origins produce a contextual warning rather than being rejected because Windows/WSL, containers, virtual machines, and explicit forwarding can make them reachable. +Settings > Agent > External Agent runtime can copy a complete `agentlet daemon` command for another machine. The owner-only command endpoint derives `ws:` or `wss:` and `/api/acp/agent` from `HUABU_PUBLIC_ORIGIN` when configured; only an unconfigured loopback deployment uses the validated current browser origin as its local-development fallback. The command includes the configured process limit and active token and returns `Cache-Control: no-store`; the renderer writes it directly to the clipboard without displaying it. HTTP origins add `--allow-insecure`, and loopback origins produce a contextual warning rather than being rejected because Windows/WSL, containers, virtual machines, and explicit forwarding can make them reachable. The source wrapper `bin/start-agentlet-daemon` uses the same public origin and has no separate ACP endpoint override. ## Interactive View resources @@ -142,7 +142,8 @@ An external agent runs as an untrusted third-party CLI. It must receive its Huab | [`apps/server/src/prompt/external-agent/interactive-views.md`](../../apps/server/src/prompt/external-agent/interactive-views.md) | Interactive View creation and bridge workflow served by `GET /skill/interactive-views`. | | [`apps/server/src/modules/interactive-view/`](../../apps/server/src/modules/interactive-view/) | View resource validation, persistence, binding snapshots, and Agent action dispatch. | | [`apps/server/src/prompt/external-agent/system-preamble.ts`](../../apps/server/src/prompt/external-agent/system-preamble.ts) | Render the canonical external-agent bootstrap preamble. | -| [`apps/server/src/modules/agent/acp/reachback-env.ts`](../../apps/server/src/modules/agent/acp/reachback-env.ts) | Inject the canvas-scoped RFS environment into external sessions. | +| [`apps/server/src/modules/security/public-origin.ts`](../../apps/server/src/modules/security/public-origin.ts) | Validate and normalize the canonical public root origin. | +| [`apps/server/src/modules/agent/acp/reachback-env.ts`](../../apps/server/src/modules/agent/acp/reachback-env.ts) | Derive and inject the canvas-scoped RFS environment into external sessions. | | [`apps/server/src/modules/storage/migrate-agenetes-threads.ts`](../../apps/server/src/modules/storage/migrate-agenetes-threads.ts) | Repair persisted undelivered external Deployments that omitted the bootstrap preamble. | | [`external/agenetes/packages/agentlet-host/src/daemon-supervisor.ts`](../../external/agenetes/packages/agentlet-host/src/daemon-supervisor.ts) | Fork/supervise the daemon; `filterHostNamespacedEnv` strips the host namespace at the transport boundary. | | [`packages/shared/src/types/api/rfs.ts`](../../packages/shared/src/types/api/rfs.ts) | Shared file-plane RFS wire schemas, headers, and constants. | diff --git a/docs/architecture/deployment-security.md b/docs/architecture/deployment-security.md index 47d955b04..ab355849b 100644 --- a/docs/architecture/deployment-security.md +++ b/docs/architecture/deployment-security.md @@ -13,7 +13,7 @@ The owner may perform Settings, OAuth, credential, External Agent Profile and ha The connection token is a separate high-privilege machine credential shared by the complete read/write RFS surface and the embedded or remote Agentlet control and relay transports. Its generation and injection are independent of browser owner authentication; possession grants both Agentlet attachment and Space data access. -Owner-only `GET/PUT /api/acp/connection-token` exposes masked source metadata and changes the encrypted override. Owner-only `POST /api/acp/connection-command` is the deliberate reveal boundary: it derives the Agentlet endpoint from the browser origin and returns a complete command with no-store headers for direct clipboard use. Copying makes the token available to the clipboard and later shell/process history. An HTTP-derived command requires `--allow-insecure` and is appropriate only on a trusted network; loopback commands remain available for same-host, Windows/WSL, container, virtual-machine, or forwarded setups and carry a warning. +Owner-only `GET/PUT /api/acp/connection-token` exposes masked source metadata and changes the encrypted override. Owner-only `POST /api/acp/connection-command` is the deliberate reveal boundary: it derives the Agentlet endpoint from the canonical `HUABU_PUBLIC_ORIGIN`, using the validated browser origin only as an unconfigured loopback-development fallback, and returns a complete command with no-store headers for direct clipboard use. Copying makes the token available to the clipboard and later shell/process history. An HTTP-derived command requires `--allow-insecure` and is appropriate only on a trusted network; loopback commands remain available for same-host, Windows/WSL, container, virtual-machine, or forwarded setups and carry a warning. The global Agent Change Review configuration follows the same owner boundary. `GET` and `PUT /api/agent-change-review/config` are available only to loopback or Basic-authenticated owner requests; possession of the RFS connection token does not authorize reading or changing the automatic-acceptance policy. @@ -29,7 +29,7 @@ OCR settings validate HTTPS resource-root endpoints against the Azure public-clo ## Bind and authentication policy -`HUABU_BIND_HOST` defaults to `127.0.0.1`. A non-loopback bind requires all of `HUABU_ALLOWED_HOSTS`, `HUABU_BASIC_AUTH_USER`, and `HUABU_BASIC_AUTH_PASS`; the server fails before listening when any requirement is missing. A partial Basic Auth pair also fails on loopback because silently disabling authentication is more dangerous than rejecting an invalid deployment. +`HUABU_BIND_HOST` defaults to `127.0.0.1`. A non-loopback bind requires all of `HUABU_ALLOWED_HOSTS`, `HUABU_PUBLIC_ORIGIN`, `HUABU_BASIC_AUTH_USER`, and `HUABU_BASIC_AUTH_PASS`; the server fails before listening when any requirement is missing. `HUABU_PUBLIC_ORIGIN` is the single root HTTP(S) origin used to derive remote Canvas RFS and Agentlet WebSocket endpoints. It accepts public DNS names, IP literals, and non-default ports, normalizes a trailing slash, and rejects credentials, query strings, fragments, path prefixes, unsupported schemes, loopback origins for network binds, and hostnames absent from `HUABU_ALLOWED_HOSTS`. A partial Basic Auth pair also fails on loopback because silently disabling authentication is more dangerous than rejecting an invalid deployment. `HUABU_ALLOWED_HOSTS` contains only hostnames or IP addresses, without scheme, port, or path. Loopback aliases remain built in. The same resolved set drives the Host guard, CORS, and the Origin fallback. @@ -70,6 +70,7 @@ The Desktop remote-client path uses the operating system's normal certificate va | File | Responsibility | | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | [`apps/server/src/modules/security/deployment-config.ts`](../../apps/server/src/modules/security/deployment-config.ts) | Resolve and fail closed on invalid bind, allowed-host, and Basic Auth combinations. | +| [`apps/server/src/modules/security/public-origin.ts`](../../apps/server/src/modules/security/public-origin.ts) | Validate the canonical public origin used for Agentlet and RFS reachback. | | [`apps/server/src/modules/security/owner.ts`](../../apps/server/src/modules/security/owner.ts) | Recognize the loopback or Basic-authenticated single owner. | | [`apps/server/src/modules/security/deployment.route.ts`](../../apps/server/src/modules/security/deployment.route.ts) | Serve the redacted readiness model. | | [`apps/server/src/modules/security/rate-limit.ts`](../../apps/server/src/modules/security/rate-limit.ts) | Define global request admission, identity, exemptions, and 429 diagnostics. | From 6ad163f9623728414689775b67f7a6d2fa2a99c2 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Thu, 8 Oct 2026 05:33:03 +0000 Subject: [PATCH 05/36] fix(server): stabilize public deployment endpoint Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .env.example | 22 +++++----- README.md | 5 ++- apps/server/src/bind-host.ts | 2 +- .../security/deployment-config.test.ts | 16 ++----- .../src/modules/security/deployment-config.ts | 21 ++------- .../src/modules/security/host-guard.test.ts | 44 +++++++++++++++++++ .../server/src/modules/security/host-guard.ts | 35 ++++++++++++--- .../src/modules/security/origin-guard.ts | 10 ++--- apps/server/src/server-port.test.ts | 29 ++++++++++++ apps/server/src/server-port.ts | 20 +++++++++ apps/server/src/server.ts | 14 ++---- apps/web/vite.config.ts | 2 +- docs/architecture/canary-deployment.md | 6 +-- docs/architecture/deployment-security.md | 6 ++- docs/architecture/web-architecture.md | 2 +- scripts/dev-desktop.mjs | 2 +- scripts/dev.mjs | 2 +- scripts/start-huabu.sh | 44 ++++++++++++++++--- scripts/start-web.mjs | 21 --------- 19 files changed, 203 insertions(+), 100 deletions(-) create mode 100644 apps/server/src/modules/security/host-guard.test.ts create mode 100644 apps/server/src/server-port.test.ts create mode 100644 apps/server/src/server-port.ts diff --git a/.env.example b/.env.example index 133e0b59b..e8e21fcb9 100644 --- a/.env.example +++ b/.env.example @@ -26,6 +26,8 @@ # ══════════════════════════════════════════════════════════════════ # ── Ports ── +# Fixed Server port for `start:web`; startup fails if it is unavailable. +# Development launchers may advance from this preferred port for parallel use. # SERVER_PORT=3001 # WEB_PORT=5173 # Preferred standalone handbook port; dev:desktop advances if it is occupied. @@ -54,21 +56,19 @@ # ── Network exposure ── # By default the server binds to 127.0.0.1 only, so a fresh install is # never silently exposed to the LAN. Set HUABU_BIND_HOST=0.0.0.0 (or a -# specific NIC IP) to listen on every interface. When you do, you MUST -# also list every hostname/IP clients will use to reach the server in -# HUABU_ALLOWED_HOSTS — requests with any other Host header are -# rejected (defence against DNS rebinding). A non-loopback bind also -# REQUIRES both HUABU_BASIC_AUTH_* values; startup fails closed when -# either remote-access prerequisite is missing. Put HTTPS in front for -# anything beyond a trusted private network. +# specific NIC IP) to listen on every interface. A non-loopback bind requires +# HUABU_PUBLIC_ORIGIN and both HUABU_BASIC_AUTH_* values; startup fails closed +# when any prerequisite is missing. The public origin hostname is automatically +# trusted by the Host/CORS/Origin guards. Put HTTPS in front for anything beyond +# a trusted private network. # HUABU_BIND_HOST=0.0.0.0 -# HUABU_ALLOWED_HOSTS=192.168.1.50,huabu.team-a.example # Canonical root origin reachable by remote Agentlets. Required for a # non-loopback bind. Use HTTP only on a trusted private network; otherwise -# terminate HTTPS in front of Huabu. Its hostname must also appear in -# HUABU_ALLOWED_HOSTS. Paths, credentials, queries, and fragments are rejected. -# RFS and Agentlet endpoints are derived from this one value. +# terminate HTTPS in front of Huabu. Paths, credentials, queries, and fragments +# are rejected. RFS and Agentlet endpoints are derived from this one value. # HUABU_PUBLIC_ORIGIN=https://huabu.team-a.example +# Optional additional browser aliases beyond HUABU_PUBLIC_ORIGIN. +# HUABU_ALLOWED_HOSTS=192.168.1.50,huabu-alt.team-a.example # ── Single-owner remote login ── # Both values are required together. The authenticated owner can use every diff --git a/README.md b/README.md index 40c48973d..8e2653567 100644 --- a/README.md +++ b/README.md @@ -85,13 +85,14 @@ The remote address must be an origin without credentials, a query, fragment, or ```dotenv HUABU_BIND_HOST=0.0.0.0 -HUABU_ALLOWED_HOSTS=huabu.example.com HUABU_PUBLIC_ORIGIN=https://huabu.example.com HUABU_BASIC_AUTH_USER=owner HUABU_BASIC_AUTH_PASS= ``` -Then run `pnpm start:web`. `HUABU_PUBLIC_ORIGIN` is the root HTTP(S) origin that remote Agentlets use to reach this deployment; Huabu derives both the Canvas RFS URL and Agentlet WebSocket endpoint from it. Its hostname must appear in `HUABU_ALLOWED_HOSTS`. Huabu rejects paths, credentials, queries, fragments, unsupported schemes, a Host-allowlist mismatch, and a missing or loopback public origin for non-loopback binds. It also rejects a non-loopback bind when allowed hosts or either Basic Auth value is missing. The authenticated owner can use all features, including Settings, OAuth, and External Agents. `pnpm dev` applies the same requirement to non-loopback browser clients while preserving zero-configuration local development. +Then run `pnpm start:web`. `HUABU_PUBLIC_ORIGIN` is the root HTTP(S) origin that remote Agentlets use to reach this deployment; Huabu derives both the Canvas RFS URL and Agentlet WebSocket endpoint from it and automatically trusts its hostname in the Host, CORS, and Origin guards. Set optional `HUABU_ALLOWED_HOSTS` only for additional browser aliases. Huabu rejects paths, credentials, queries, fragments, unsupported schemes, and a missing or loopback public origin for non-loopback binds. It also rejects a non-loopback bind when either Basic Auth value is missing. The authenticated owner can use all features, including Settings, OAuth, and External Agents. `pnpm dev` applies the same requirement to non-loopback browser clients while preserving zero-configuration local development. + +`pnpm start:web` binds the fixed `SERVER_PORT` (default `3001`) and fails if that port is invalid or unavailable; it never advances to another port. Development launchers may advance from their preferred ports so intentional parallel instances remain possible. Huabu currently serves HTTP. Use a trusted private network or terminate HTTPS with deployment infrastructure such as Caddy, Nginx, Tailscale Serve, or a cloud load balancer. Do not put a Basic Auth deployment on an untrusted network without transport encryption. diff --git a/apps/server/src/bind-host.ts b/apps/server/src/bind-host.ts index 5c6cc0dc3..8f0c65b9b 100644 --- a/apps/server/src/bind-host.ts +++ b/apps/server/src/bind-host.ts @@ -7,7 +7,7 @@ * * Operators who explicitly want LAN / remote access set * `HUABU_BIND_HOST=0.0.0.0` (or a specific interface IP) and pair that - * with `HUABU_ALLOWED_HOSTS` and `HUABU_BASIC_AUTH_*` — see README. + * with `HUABU_PUBLIC_ORIGIN` and `HUABU_BASIC_AUTH_*` — see README. * * Lives in its own module (not inlined into `server.ts`) so the default * can be regression-tested without booting Fastify. The Electron diff --git a/apps/server/src/modules/security/deployment-config.test.ts b/apps/server/src/modules/security/deployment-config.test.ts index 9c601e2aa..01fee1dab 100644 --- a/apps/server/src/modules/security/deployment-config.test.ts +++ b/apps/server/src/modules/security/deployment-config.test.ts @@ -24,20 +24,13 @@ describe('resolveDeploymentConfig', () => { ).toThrow(/configured together/); }); - it('requires allowed hosts and Basic Auth for a network bind', () => { + it('requires Basic Auth and a public origin for a network bind', () => { expect(() => resolveDeploymentConfig({ HUABU_BIND_HOST: '0.0.0.0' }), - ).toThrow(/HUABU_ALLOWED_HOSTS/); - expect(() => - resolveDeploymentConfig({ - HUABU_BIND_HOST: '0.0.0.0', - HUABU_ALLOWED_HOSTS: 'huabu.example', - }), ).toThrow(/HUABU_BASIC_AUTH/); expect(() => resolveDeploymentConfig({ HUABU_BIND_HOST: '0.0.0.0', - HUABU_ALLOWED_HOSTS: 'huabu.example', HUABU_BASIC_AUTH_USER: 'owner', HUABU_BASIC_AUTH_PASS: 'secret', }), @@ -48,7 +41,6 @@ describe('resolveDeploymentConfig', () => { expect( resolveDeploymentConfig({ HUABU_BIND_HOST: '0.0.0.0', - HUABU_ALLOWED_HOSTS: 'huabu.example', HUABU_BASIC_AUTH_USER: 'owner', HUABU_BASIC_AUTH_PASS: 'secret', HUABU_PUBLIC_ORIGIN: 'https://huabu.example:8443/', @@ -77,8 +69,8 @@ describe('resolveDeploymentConfig', () => { ).toThrow(/beyond loopback/); }); - it('requires the public hostname in the Host allowlist', () => { - expect(() => + it('accepts optional additional Host aliases', () => { + expect( resolveDeploymentConfig({ HUABU_BIND_HOST: '0.0.0.0', HUABU_ALLOWED_HOSTS: 'internal.huabu.example', @@ -86,6 +78,6 @@ describe('resolveDeploymentConfig', () => { HUABU_BASIC_AUTH_PASS: 'secret', HUABU_PUBLIC_ORIGIN: 'https://public.huabu.example', }), - ).toThrow(/included in HUABU_ALLOWED_HOSTS/); + ).toMatchObject({ allowedHostsConfigured: true }); }); }); diff --git a/apps/server/src/modules/security/deployment-config.ts b/apps/server/src/modules/security/deployment-config.ts index 93ed2583c..924abc2eb 100644 --- a/apps/server/src/modules/security/deployment-config.ts +++ b/apps/server/src/modules/security/deployment-config.ts @@ -3,7 +3,6 @@ import { isIP } from 'node:net'; -import { resolveAllowedHostnames } from './host-guard.js'; import { resolveConfiguredPublicOrigin } from './public-origin.js'; export interface DeploymentConfig { @@ -41,14 +40,11 @@ export function resolveDeploymentConfig( ); } - const allowedHostsConfigured = Boolean(env.HUABU_ALLOWED_HOSTS?.trim()); - const bindScope = isLoopbackHost(bindHost) ? 'loopback' : 'network'; const publicOrigin = resolveConfiguredPublicOrigin(env); - if (bindScope === 'network' && !allowedHostsConfigured) { - throw new Error( - 'HUABU_ALLOWED_HOSTS is required when HUABU_BIND_HOST is not loopback', - ); - } + const allowedHostsConfigured = Boolean( + publicOrigin || env.HUABU_ALLOWED_HOSTS?.trim(), + ); + const bindScope = isLoopbackHost(bindHost) ? 'loopback' : 'network'; if (bindScope === 'network' && !userConfigured) { throw new Error( 'HUABU_BASIC_AUTH_USER and HUABU_BASIC_AUTH_PASS are required when HUABU_BIND_HOST is not loopback', @@ -68,15 +64,6 @@ export function resolveDeploymentConfig( 'HUABU_PUBLIC_ORIGIN must be reachable beyond loopback when HUABU_BIND_HOST is not loopback', ); } - if (bindScope === 'network' && publicOrigin) { - const publicHostname = new URL(publicOrigin).hostname.toLowerCase(); - if (!resolveAllowedHostnames(env).has(publicHostname)) { - throw new Error( - 'HUABU_PUBLIC_ORIGIN hostname must be included in HUABU_ALLOWED_HOSTS', - ); - } - } - return { allowedHostsConfigured, basicAuthConfigured: userConfigured, diff --git a/apps/server/src/modules/security/host-guard.test.ts b/apps/server/src/modules/security/host-guard.test.ts new file mode 100644 index 000000000..10ff36b15 --- /dev/null +++ b/apps/server/src/modules/security/host-guard.test.ts @@ -0,0 +1,44 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { describe, expect, it } from 'vitest'; + +import { resolveAllowedHostnames } from './host-guard.js'; + +describe('resolveAllowedHostnames', () => { + it('includes the canonical public hostname without duplicate configuration', () => { + expect( + resolveAllowedHostnames({ + HUABU_PUBLIC_ORIGIN: 'https://huabu.example.com:8443', + }), + ).toEqual( + new Set(['localhost', '127.0.0.1', '[::1]', 'huabu.example.com']), + ); + }); + + it('keeps HUABU_ALLOWED_HOSTS as optional extra aliases', () => { + expect( + resolveAllowedHostnames({ + HUABU_PUBLIC_ORIGIN: 'https://huabu.example.com', + HUABU_ALLOWED_HOSTS: '192.168.1.50, admin.example.com', + }), + ).toEqual( + new Set([ + 'localhost', + '127.0.0.1', + '[::1]', + 'huabu.example.com', + '192.168.1.50', + 'admin.example.com', + ]), + ); + }); + + it('defers invalid public-origin reporting to deployment validation', () => { + expect( + resolveAllowedHostnames({ + HUABU_PUBLIC_ORIGIN: 'file:///tmp/huabu', + }), + ).toEqual(new Set(['localhost', '127.0.0.1', '[::1]'])); + }); +}); diff --git a/apps/server/src/modules/security/host-guard.ts b/apps/server/src/modules/security/host-guard.ts index 801c91eae..d30e1d4c3 100644 --- a/apps/server/src/modules/security/host-guard.ts +++ b/apps/server/src/modules/security/host-guard.ts @@ -10,11 +10,17 @@ * rebinding: even if an attacker resolves `evil.com` to 127.0.0.1, the * browser still writes `Host: evil.com`, which we can reject. * - * Built-in entries cover the loopback aliases the bundled web client - * uses out of the box. Operators add LAN IPs or reverse-proxy hostnames - * via `HUABU_ALLOWED_HOSTS`. + * Built-in entries cover the loopback aliases the bundled web client uses out + * of the box. The canonical public origin contributes its hostname + * automatically; operators add only additional aliases through + * `HUABU_ALLOWED_HOSTS`. */ +import { + InvalidPublicOriginError, + resolveConfiguredPublicOrigin, +} from './public-origin.js'; + import type { FastifyPluginAsync } from 'fastify'; /** Hostnames always accepted, even when `HUABU_ALLOWED_HOSTS` is empty. */ @@ -39,7 +45,7 @@ function extractHostname(host: string | undefined): string | null { } /** - * Read the merged allowlist (builtins + env extras). + * Read the merged allowlist (builtins + canonical public host + env extras). * * Exported so the CORS layer can reuse the same set of hostnames. */ @@ -50,7 +56,24 @@ export function resolveAllowedHostnames( .split(',') .map((s) => s.trim().toLowerCase()) .filter(Boolean); - return new Set([...BUILTIN_HOSTNAMES, ...extra]); + let publicOrigin: string | undefined; + try { + publicOrigin = resolveConfiguredPublicOrigin(env); + } catch (error) { + // app.ts resolves the CORS allowlist during module initialization, before + // server.ts can report deployment validation failures. Defer this one + // known configuration error to resolveDeploymentConfig(); the Server never + // listens with an invalid origin. + if (!(error instanceof InvalidPublicOriginError)) throw error; + } + const publicHostname = publicOrigin + ? new URL(publicOrigin).hostname.toLowerCase() + : undefined; + return new Set([ + ...BUILTIN_HOSTNAMES, + ...(publicHostname ? [publicHostname] : []), + ...extra, + ]); } export const hostGuardPlugin: FastifyPluginAsync = async (app) => { @@ -65,7 +88,7 @@ export const hostGuardPlugin: FastifyPluginAsync = async (app) => { code: 'INVALID_HOST', details: { received: hostname ?? null, - hint: 'Add the hostname to HUABU_ALLOWED_HOSTS if this is an intentional deployment.', + hint: 'Use HUABU_PUBLIC_ORIGIN or add the hostname to HUABU_ALLOWED_HOSTS if this is an intentional alias.', }, }); } diff --git a/apps/server/src/modules/security/origin-guard.ts b/apps/server/src/modules/security/origin-guard.ts index 6f208e540..cb3c5db25 100644 --- a/apps/server/src/modules/security/origin-guard.ts +++ b/apps/server/src/modules/security/origin-guard.ts @@ -19,9 +19,9 @@ * 2. **`Origin` allowlist** — fallback for older browsers / WebViews * that don't emit `Sec-Fetch-*`. `Origin` is also browser-set and * not forgeable by JS, but lacks the explicit cross-site signal. - * We reuse {@link resolveAllowedHostnames} so a single env var - * (`HUABU_ALLOWED_HOSTS`) drives Host guard, CORS, and this - * check. + * We reuse {@link resolveAllowedHostnames} so the canonical public + * origin and optional additional aliases drive Host guard, CORS, and + * this check. * 3. **Loopback peer fallback** — non-browser callers (curl, native * apps, CI scripts) routinely emit neither header. For a local * developer tool we allow them *only* when the TCP peer is a @@ -82,7 +82,7 @@ export const originGuardPlugin: FastifyPluginAsync = async (app) => { code: 'CROSS_SITE_BLOCKED', details: { secFetchSite: site, - hint: 'Open the app from one of the allowed origins (HUABU_ALLOWED_HOSTS) or use a trusted client.', + hint: 'Open the app from HUABU_PUBLIC_ORIGIN or an additional HUABU_ALLOWED_HOSTS alias, or use a trusted client.', }, }); } @@ -97,7 +97,7 @@ export const originGuardPlugin: FastifyPluginAsync = async (app) => { code: 'BAD_ORIGIN', details: { receivedOrigin: origin, - hint: 'Add the hostname to HUABU_ALLOWED_HOSTS if this is an intentional deployment.', + hint: 'Use HUABU_PUBLIC_ORIGIN or add the hostname to HUABU_ALLOWED_HOSTS if this is an intentional alias.', }, }); } diff --git a/apps/server/src/server-port.test.ts b/apps/server/src/server-port.test.ts new file mode 100644 index 000000000..c0129037e --- /dev/null +++ b/apps/server/src/server-port.test.ts @@ -0,0 +1,29 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { describe, expect, it } from 'vitest'; + +import { DEFAULT_SERVER_PORT, resolveServerPort } from './server-port.js'; + +describe('resolveServerPort', () => { + it('uses the documented fixed default when unset', () => { + expect(resolveServerPort({})).toBe(DEFAULT_SERVER_PORT); + }); + + it('accepts a configured fixed port', () => { + expect(resolveServerPort({ SERVER_PORT: '4100' })).toBe(4100); + }); + + it.each(['0', '65536', '3001extra', '3.1', '-1'])( + 'rejects invalid configured port %s', + (value) => { + expect(() => resolveServerPort({ SERVER_PORT: value })).toThrow( + /SERVER_PORT/, + ); + }, + ); + + it('does not recognize the undocumented PORT alias', () => { + expect(resolveServerPort({ PORT: '4100' })).toBe(DEFAULT_SERVER_PORT); + }); +}); diff --git a/apps/server/src/server-port.ts b/apps/server/src/server-port.ts new file mode 100644 index 000000000..7d6481df0 --- /dev/null +++ b/apps/server/src/server-port.ts @@ -0,0 +1,20 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +export const DEFAULT_SERVER_PORT = 3001; + +export function resolveServerPort( + env: NodeJS.ProcessEnv = process.env, +): number { + const rawValue = env.SERVER_PORT?.trim(); + if (rawValue === undefined || rawValue === '') return DEFAULT_SERVER_PORT; + if (!/^\d+$/.test(rawValue)) { + throw new Error('SERVER_PORT must be an integer between 1 and 65535'); + } + + const port = Number(rawValue); + if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) { + throw new Error('SERVER_PORT must be an integer between 1 and 65535'); + } + return port; +} diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts index 02609afd6..d0cf21a29 100644 --- a/apps/server/src/server.ts +++ b/apps/server/src/server.ts @@ -13,22 +13,16 @@ import { initStorage, } from './modules/storage/index.js'; import { initializeSecretStore } from './security/secret-store.js'; +import { resolveServerPort } from './server-port.js'; import { getLogger } from './utils/logger.js'; const log = getLogger('server'); -const DEFAULT_PORT = 3001; -const parsedPort = Number.parseInt( - process.env.SERVER_PORT ?? process.env.PORT ?? '', - 10, -); -const PORT = - Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : DEFAULT_PORT; - const HOST = resolveBindHost(); async function start(): Promise { try { + const port = resolveServerPort(); const deployment = resolveDeploymentConfig(); if (deployment.bindScope === 'network') { log.warn( @@ -55,7 +49,7 @@ async function start(): Promise { await initializeSecretStore(); initializeConnectionToken(); - await app.listen({ port: PORT, host: HOST }); + await app.listen({ port, host: HOST }); // When bound to a wildcard address, "localhost" is still the URL a // browser on this machine would use — but log both so operators on a // remote machine know how to reach the server. @@ -63,7 +57,7 @@ async function start(): Promise { HOST === '0.0.0.0' || HOST === '::' ? `localhost (bound on ${HOST})` : HOST; - log.info(`Server running at http://${displayHost}:${PORT}`); + log.info(`Server running at http://${displayHost}:${port}`); // Warm up OAuth tokens off the request path so the first chat/Settings // action doesn't pay pi-ai's one-time lazy OAuth load + token refresh. diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts index e5d1b91f7..888722b51 100644 --- a/apps/web/vite.config.ts +++ b/apps/web/vite.config.ts @@ -68,7 +68,7 @@ export default defineConfig(({ mode }) => { ...process.env, }; - const apiPort = env.SERVER_PORT || env.PORT || '3001'; + const apiPort = env.SERVER_PORT || '3001'; const apiTarget = env.VITE_API_PROXY_TARGET || `http://localhost:${apiPort}`; const parsedDevPort = Number.parseInt( env.WEB_PORT || env.VITE_PORT || '', diff --git a/docs/architecture/canary-deployment.md b/docs/architecture/canary-deployment.md index bb1654fcd..5e0ae44c8 100644 --- a/docs/architecture/canary-deployment.md +++ b/docs/architecture/canary-deployment.md @@ -10,7 +10,7 @@ Canary use is additional end-to-end evidence only. It does not replace pull-requ ## Supported workflow -The supported helper runs from a source checkout through `pnpm start:web`. `scripts/start-web.mjs` captures the startup commit in `HUABU_DEPLOYED_SHA` and exports the resolved checkout root as `HUABU_REPO_ROOT` before loading the bundled Server. +The supported helper runs from a source checkout through `pnpm start:web`. `scripts/start-web.mjs` captures the startup commit in `HUABU_DEPLOYED_SHA` and exports the resolved checkout root as `HUABU_REPO_ROOT` before loading the bundled Server. Production-style startup binds the fixed `SERVER_PORT` (default `3001`) and fails rather than selecting another port when it is unavailable. Setting `HUABU_CANARY_REDEPLOY_ENABLED=1` enables an owner-only Settings surface. The selected branch is persisted as an application-global versioned record under `HUABU_DATA_DIR`; a missing record or explicit cleared value resolves to `alpha`. Malformed stored configuration fails explicitly rather than silently using the default. @@ -30,9 +30,9 @@ Only one check, configuration write, or redeployment admission may run at a time `scripts/start-huabu.sh` derives the repository root from its own tracked path, so the checkout may live anywhere. Direct operator and Settings use both accept exactly one validated branch argument. -The script requires a clean checkout, stops listeners on ports 3001–3005, removes the previous `app` tmux session, fetches the exact `refs/heads/` from fixed remote `origin` into its matching remote-tracking ref, checks out or creates the matching local branch, and fast-forwards it without rewriting divergent work. It then installs locked dependencies and starts `pnpm start:web` in a new `app` session. Interactive use immediately tails `/tmp/huabu-app.log` while startup continues. `--non-interactive` instead waits for readiness and exits when it succeeds or when the configurable `HUABU_CANARY_READINESS_TIMEOUT_SECONDS` window expires; the default is 300 seconds. +The script requires a clean checkout, resolves the fixed Server port from an exported `SERVER_PORT`, then the checkout's `.env`, then the default `3001`, and stops the listener on that port. It removes the previous `app` tmux session, fetches the exact `refs/heads/` from fixed remote `origin` into its matching remote-tracking ref, checks out or creates the matching local branch, and fast-forwards it without rewriting divergent work. It then installs locked dependencies and starts `pnpm start:web` in a new `app` session. Interactive use immediately tails `/tmp/huabu-app.log` while startup continues. `--non-interactive` instead waits for readiness on that same fixed port and exits when it succeeds or when the configurable `HUABU_CANARY_READINESS_TIMEOUT_SECONDS` window expires; the default is 300 seconds. -The script intentionally preserves the existing personal-development tradeoff: it updates one checkout in place and stops the old service before pull, install, and build complete. A failed redeployment can leave the Canary offline, and the port-range stop can affect another process using those ports. There is no rollback, immutable release directory, service preservation, self-restart supervisor, systemd unit, container deployment, or automatic installation. Inspect the persisted runner status and log, then repair manually through SSH when needed. +The script intentionally preserves the existing personal-development tradeoff: it updates one checkout in place and stops the old service before pull, install, and build complete. A failed redeployment can leave the Canary offline, and stopping the configured port can affect an unrelated process that owns it. There is no rollback, immutable release directory, service preservation, self-restart supervisor, systemd unit, container deployment, or automatic installation. Inspect the persisted runner status and log, then repair manually through SSH when needed. ## Security boundary diff --git a/docs/architecture/deployment-security.md b/docs/architecture/deployment-security.md index ab355849b..1813914c5 100644 --- a/docs/architecture/deployment-security.md +++ b/docs/architecture/deployment-security.md @@ -29,9 +29,11 @@ OCR settings validate HTTPS resource-root endpoints against the Azure public-clo ## Bind and authentication policy -`HUABU_BIND_HOST` defaults to `127.0.0.1`. A non-loopback bind requires all of `HUABU_ALLOWED_HOSTS`, `HUABU_PUBLIC_ORIGIN`, `HUABU_BASIC_AUTH_USER`, and `HUABU_BASIC_AUTH_PASS`; the server fails before listening when any requirement is missing. `HUABU_PUBLIC_ORIGIN` is the single root HTTP(S) origin used to derive remote Canvas RFS and Agentlet WebSocket endpoints. It accepts public DNS names, IP literals, and non-default ports, normalizes a trailing slash, and rejects credentials, query strings, fragments, path prefixes, unsupported schemes, loopback origins for network binds, and hostnames absent from `HUABU_ALLOWED_HOSTS`. A partial Basic Auth pair also fails on loopback because silently disabling authentication is more dangerous than rejecting an invalid deployment. +`HUABU_BIND_HOST` defaults to `127.0.0.1`. A non-loopback bind requires `HUABU_PUBLIC_ORIGIN`, `HUABU_BASIC_AUTH_USER`, and `HUABU_BASIC_AUTH_PASS`; the server fails before listening when any requirement is missing. `HUABU_PUBLIC_ORIGIN` is the single root HTTP(S) origin used to derive remote Canvas RFS and Agentlet WebSocket endpoints. It accepts public DNS names, IP literals, and non-default ports, normalizes a trailing slash, and rejects credentials, query strings, fragments, path prefixes, unsupported schemes, and loopback origins for network binds. Its hostname automatically joins the effective Host, CORS, and Origin allowlist. A partial Basic Auth pair also fails on loopback because silently disabling authentication is more dangerous than rejecting an invalid deployment. -`HUABU_ALLOWED_HOSTS` contains only hostnames or IP addresses, without scheme, port, or path. Loopback aliases remain built in. The same resolved set drives the Host guard, CORS, and the Origin fallback. +`HUABU_ALLOWED_HOSTS` is an optional list of additional browser aliases beyond the canonical public origin. It contains only hostnames or IP addresses, without scheme, port, or path. Loopback aliases remain built in. The merged set of loopback aliases, the public-origin hostname, and additional aliases drives the Host guard, CORS, and the Origin fallback. + +`SERVER_PORT` is the only Server-listen-port configuration. `pnpm start:web` treats it as fixed, defaults it to `3001` when absent, rejects invalid values, and fails on bind conflicts instead of silently advancing. Development launchers may still search forward from their preferred ports for intentional parallel instances. `pnpm dev` keeps zero-configuration access for loopback clients. Vite listens on all interfaces for development flexibility, but a non-loopback client must pass complete Basic Auth before receiving assets or reaching the API proxy. The Authorization header reaches Fastify, so owner authorization does not depend on Vite's loopback backend connection. diff --git a/docs/architecture/web-architecture.md b/docs/architecture/web-architecture.md index f11f8db74..c2ed898eb 100644 --- a/docs/architecture/web-architecture.md +++ b/docs/architecture/web-architecture.md @@ -392,7 +392,7 @@ Production requires `VITE_HANDBOOK_URL`; the checked-in [`apps/web/.env.producti The handbook is owned, built, and deployed from the public [microsoft/Huabu repository](https://github.com/microsoft/Huabu/tree/main/apps/docs); Huabu does not carry a second user-handbook application. -`pnpm start:web` serves the compiled SPA and API from one production-style Fastify process. Before importing the Server bundle, its launcher selects the first available port at or above `SERVER_PORT`/`PORT` (default 3001) and writes the resolved value to `SERVER_PORT`; the shared port probe also protects `dev` and `dev:desktop` from loopback-versus-wildcard binding conflicts. +`pnpm start:web` serves the compiled SPA and API from one production-style Fastify process. It binds the fixed `SERVER_PORT` (default 3001), rejects invalid values, and fails on conflicts rather than advancing to another port. The shared port probe remains limited to `dev` and `dev:desktop`, where parallel local instances are intentional and the resolved port is propagated to every consumer. Network deployment follows the single-owner boundary in [`deployment-security.md`](./deployment-security.md). Non-loopback `start:web` binds fail closed unless allowed hosts and complete Basic Auth are configured. Vite keeps zero-configuration loopback development but rejects non-loopback clients before serving assets or proxying APIs unless they pass the same Basic Auth gate. Settings reads the redacted deployment readiness endpoint and disables credential mutations when the standalone secret store is read-only. diff --git a/scripts/dev-desktop.mjs b/scripts/dev-desktop.mjs index bc34b5a7f..e03533d75 100644 --- a/scripts/dev-desktop.mjs +++ b/scripts/dev-desktop.mjs @@ -81,7 +81,7 @@ const env = loadEnv( ); const HOST = '127.0.0.1'; -const SERVER_PORT = Number.parseInt(env.SERVER_PORT || env.PORT || '3001', 10); +const SERVER_PORT = Number.parseInt(env.SERVER_PORT || '3001', 10); const VITE_PORT = Number.parseInt(env.VITE_PORT || env.WEB_PORT || '5173', 10); const HANDBOOK_URL = env.VITE_HANDBOOK_URL || 'https://microsoft.github.io/Huabu/docs/'; diff --git a/scripts/dev.mjs b/scripts/dev.mjs index 77127153d..7193e50ba 100644 --- a/scripts/dev.mjs +++ b/scripts/dev.mjs @@ -58,7 +58,7 @@ const env = loadEnv( path.join(repoRoot, 'apps/web/.env'), ); -const SERVER_PORT = Number.parseInt(env.SERVER_PORT || env.PORT || '3001', 10); +const SERVER_PORT = Number.parseInt(env.SERVER_PORT || '3001', 10); const WEB_PORT = Number.parseInt(env.WEB_PORT || env.VITE_PORT || '5173', 10); const SERVER_HOST = '127.0.0.1'; const HANDBOOK_URL = diff --git a/scripts/start-huabu.sh b/scripts/start-huabu.sh index 7fe5e7f9c..fffdd4c96 100755 --- a/scripts/start-huabu.sh +++ b/scripts/start-huabu.sh @@ -11,7 +11,7 @@ main() { local huabu_dir local tmux_session='app' local log_file='/tmp/huabu-app.log' - local server_port="${SERVER_PORT:-${PORT:-3001}}" + local server_port='' local readiness_timeout_seconds="${HUABU_CANARY_READINESS_TIMEOUT_SECONDS:-300}" for argument in "$@"; do @@ -58,6 +58,38 @@ main() { pwd -P )" + if [[ -n "${SERVER_PORT:-}" ]]; then + server_port="$SERVER_PORT" + elif [[ -f "$huabu_dir/.env" ]]; then + server_port="$( + node --input-type=module - "$huabu_dir/.env" <<'NODE' +import fs from 'node:fs'; + +const source = fs.readFileSync(process.argv[2], 'utf8'); +let value = ''; +for (const line of source.split(/\r?\n/u)) { + const assignment = line.match( + /^\s*(?:export\s+)?SERVER_PORT\s*=\s*(.*)$/u, + ); + if (!assignment) continue; + + const rawValue = assignment[1].trim(); + const quotedValue = rawValue.match(/^(["'])(.*?)\1\s*(?:#.*)?$/u); + value = quotedValue + ? quotedValue[2] + : rawValue.replace(/\s*#.*$/u, '').trim(); +} +process.stdout.write(value); +NODE + )" + fi + server_port="${server_port:-3001}" + if [[ ! "$server_port" =~ ^[1-9][0-9]*$ ]] || + ((10#$server_port > 65535)); then + echo "SERVER_PORT must be an integer between 1 and 65535." >&2 + return 2 + fi + if [[ "$(git -C "$huabu_dir" rev-parse --show-toplevel)" != "$huabu_dir" ]]; then echo "ERROR: $huabu_dir is not the Huabu repository root." >&2 return 1 @@ -100,15 +132,15 @@ main() { command kill -TERM "${pids[@]}" } - echo "==> Stopping services on ports 3001-3005" - portlisten -k 3001-3005 + echo "==> Stopping the service on port $server_port" + portlisten -k "$server_port" for attempt in {1..20}; do - if [[ -z "$(portlisten 3001-3005)" ]]; then + if [[ -z "$(portlisten "$server_port")" ]]; then break fi if [[ "$attempt" -eq 20 ]]; then - echo "ERROR: Ports 3001-3005 are still in use." >&2 - portlisten 3001-3005 + echo "ERROR: Port $server_port is still in use." >&2 + portlisten "$server_port" return 1 fi sleep 0.5 diff --git a/scripts/start-web.mjs b/scripts/start-web.mjs index 4b41d602a..93e1df57e 100644 --- a/scripts/start-web.mjs +++ b/scripts/start-web.mjs @@ -15,11 +15,8 @@ import { fileURLToPath } from 'node:url'; import dotenv from 'dotenv'; -import { findAvailablePort } from './dev-ports.mjs'; - const here = path.dirname(fileURLToPath(import.meta.url)); const repoRoot = path.resolve(here, '..'); -const DEFAULT_SERVER_PORT = 3001; process.env.HUABU_REPO_ROOT = repoRoot; process.env.HUABU_DEPLOYED_SHA = execFileSync('git', ['rev-parse', 'HEAD'], { @@ -32,24 +29,6 @@ process.env.HUABU_DEPLOYED_SHA = execFileSync('git', ['rev-parse', 'HEAD'], { // variables retain higher precedence because dotenv does not override them. dotenv.config({ path: path.join(repoRoot, '.env') }); -const configuredPort = Number.parseInt( - process.env.SERVER_PORT ?? process.env.PORT ?? '', - 10, -); -const preferredPort = - Number.isInteger(configuredPort) && - configuredPort > 0 && - configuredPort <= 65_535 - ? configuredPort - : DEFAULT_SERVER_PORT; -const serverPort = await findAvailablePort(preferredPort); -if (serverPort !== preferredPort) { - console.warn( - `[start:web] Port ${preferredPort} is in use; using ${serverPort} instead.`, - ); -} -process.env.SERVER_PORT = String(serverPort); - process.env.WEB_DIST_PATH = path.resolve( repoRoot, process.env.WEB_DIST_PATH ?? 'apps/web/dist', From 7cd87627503aaa972e8d3554aefc9a5ff913eaea Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Fri, 9 Oct 2026 10:27:12 +0000 Subject: [PATCH 06/36] feat(agentlet): add capability package SDK Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 3 + .../agentlet/packages/local/src/agentlet.ts | 4 + .../local/src/capability-sdk/index.ts | 85 +++++++++++++++++++ .../packages/local/tests/agentlet.test.ts | 5 ++ .../local/tests/capability-sdk.test.ts | 63 ++++++++++++++ 5 files changed, 160 insertions(+) create mode 100644 external/agentlet/packages/local/src/capability-sdk/index.ts create mode 100644 external/agentlet/packages/local/tests/capability-sdk.test.ts diff --git a/external/agentlet/README.md b/external/agentlet/README.md index 6288c165a..8b26afc3a 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -123,9 +123,12 @@ The standard environment includes: | `AGENTLET_REACHBACK_DIR` | Directory containing host-provided resources. | | `AGENTLET_SERVER` | Gateway URL supplied to the daemon. | | `AGENTLET_TOKEN` | Authentication token available to host-provided reachback tools. | +| `AGENTLET_CAPABILITY_SDK_URL` | Daemon-owned absolute `file://` URL for the ESM Capability SDK published under `dist/capability-sdk`. | Agentlet transports opaque resources and environment values; it does not interpret the host-specific tool protocol. +The optional Capability SDK exports `loadCapability(id)` and `withCapability(id, callback)`. It uses host-injected reachback coordinates to obtain an on-demand configuration lease and load a trusted host-provided client without persisting credentials. The daemon writes `AGENTLET_CAPABILITY_SDK_URL` after workload environment values so a session cannot replace the SDK module location. + ## Repository layout ```text diff --git a/external/agentlet/packages/local/src/agentlet.ts b/external/agentlet/packages/local/src/agentlet.ts index f9c137c4e..9324be822 100644 --- a/external/agentlet/packages/local/src/agentlet.ts +++ b/external/agentlet/packages/local/src/agentlet.ts @@ -900,5 +900,9 @@ export function buildAgentProcessEnv( ...envRegistry, ...sessionEnv, AGENTLET_TOKEN: token, + AGENTLET_CAPABILITY_SDK_URL: new URL( + './capability-sdk/index.js', + import.meta.url, + ).href, } } diff --git a/external/agentlet/packages/local/src/capability-sdk/index.ts b/external/agentlet/packages/local/src/capability-sdk/index.ts new file mode 100644 index 000000000..0912d4ff5 --- /dev/null +++ b/external/agentlet/packages/local/src/capability-sdk/index.ts @@ -0,0 +1,85 @@ +export interface CapabilityLease { + id: string + version: string + config: Record + client?: string +} + +export interface CapabilityContext { + config: CapabilityLease['config'] + client: Record | null + lease: CapabilityLease +} + +type CapabilityClientModule = { + createClient?: (context: { + config: CapabilityLease['config'] + }) => Record +} + +function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { + const value = process.env[name]?.trim() + if (!value) throw new Error(`Capability SDK requires ${name}`) + return value +} + +async function capabilityFetch(path: string, init?: RequestInit): Promise { + const baseUrl = requiredEnvironment('HUABU_RFS_URL').replace(/\/+$/, '') + const token = requiredEnvironment('AGENTLET_TOKEN') + const response = await fetch(`${baseUrl}${path}`, { + ...init, + headers: { + Authorization: `Bearer ${token}`, + ...(init?.headers ?? {}), + }, + }) + if (!response.ok) { + throw new Error(`Capability request failed (${response.status})`) + } + return response +} + +async function loadClient( + capabilityId: string, + lease: CapabilityLease, +): Promise | null> { + if (!lease.client) return null + const response = await capabilityFetch( + `/capability-packages/${encodeURIComponent(capabilityId)}/client`, + ) + const source = await response.text() + const moduleUrl = `data:text/javascript;base64,${Buffer.from(source, 'utf8').toString('base64')}` + const module = (await import(moduleUrl)) as CapabilityClientModule + if (typeof module.createClient !== 'function') { + throw new Error('Capability client must export createClient()') + } + return module.createClient({ config: lease.config }) +} + +export async function loadCapability( + capabilityId: string, +): Promise { + if (!/^[a-z][a-z0-9-]{0,63}$/.test(capabilityId)) { + throw new Error('Invalid Capability id') + } + const response = await capabilityFetch( + `/capability-packages/${encodeURIComponent(capabilityId)}/lease`, + { method: 'POST' }, + ) + const lease = (await response.json()) as CapabilityLease + if (lease.id !== capabilityId || typeof lease.version !== 'string') { + throw new Error('Invalid Capability lease') + } + return { + lease, + config: lease.config, + client: await loadClient(capabilityId, lease), + } +} + +export async function withCapability( + capabilityId: string, + run: (context: CapabilityContext) => Promise | T, +): Promise { + return run(await loadCapability(capabilityId)) +} diff --git a/external/agentlet/packages/local/tests/agentlet.test.ts b/external/agentlet/packages/local/tests/agentlet.test.ts index 74a4d278a..b897665cc 100644 --- a/external/agentlet/packages/local/tests/agentlet.test.ts +++ b/external/agentlet/packages/local/tests/agentlet.test.ts @@ -105,6 +105,9 @@ describe('spawned agent environment', () => { ).toEqual({ AGENTLET_SERVER: 'ws://127.0.0.1:3001/api/acp/agent', AGENTLET_TOKEN: 'cli-token', + AGENTLET_CAPABILITY_SDK_URL: expect.stringMatching( + /\/capability-sdk\/index\.js$/, + ), AGENTLET_REACHBACK_DIR: '/tmp/reachback', HUABU_RFS_URL: 'http://127.0.0.1:3001/api/rfs/canvas-1', }) @@ -115,10 +118,12 @@ describe('spawned agent environment', () => { buildAgentProcessEnv('ws://daemon.test', 'daemon-token', {}, { AGENTLET_SERVER: 'ws://host.test', AGENTLET_TOKEN: 'host-token', + AGENTLET_CAPABILITY_SDK_URL: 'file:///tmp/untrusted.js', }), ).toMatchObject({ AGENTLET_SERVER: 'ws://host.test', AGENTLET_TOKEN: 'daemon-token', + AGENTLET_CAPABILITY_SDK_URL: expect.not.stringContaining('untrusted'), }) }) }) diff --git a/external/agentlet/packages/local/tests/capability-sdk.test.ts b/external/agentlet/packages/local/tests/capability-sdk.test.ts new file mode 100644 index 000000000..c444f8db0 --- /dev/null +++ b/external/agentlet/packages/local/tests/capability-sdk.test.ts @@ -0,0 +1,63 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' + +import { loadCapability } from '../src/capability-sdk/index.js' + +afterEach(() => { + vi.unstubAllGlobals() + delete process.env.HUABU_RFS_URL + delete process.env.AGENTLET_TOKEN +}) + +describe('Capability SDK', () => { + it('leases config and loads the trusted package client without logging secrets', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' + process.env.AGENTLET_TOKEN = 'agentlet-token' + const fetchMock = vi + .fn() + .mockResolvedValueOnce( + new Response( + JSON.stringify({ + id: 'example', + version: '1.0.0', + config: { apiKey: 'provider-secret' }, + client: 'client.mjs', + }), + { status: 200 }, + ), + ) + .mockResolvedValueOnce( + new Response( + 'export function createClient({ config }) { return { configured: Boolean(config.apiKey) }; }', + { status: 200 }, + ), + ) + vi.stubGlobal('fetch', fetchMock) + + const capability = await loadCapability('example') + + expect(capability.client).toEqual({ configured: true }) + expect(fetchMock).toHaveBeenNthCalledWith( + 1, + 'https://huabu.example/api/rfs/canvas-1/capability-packages/example/lease', + expect.objectContaining({ + method: 'POST', + headers: { Authorization: 'Bearer agentlet-token' }, + }), + ) + }) + + it('does not include response bodies in provider-facing errors', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' + process.env.AGENTLET_TOKEN = 'agentlet-token' + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue( + new Response('provider-secret', { status: 409 }), + ), + ) + + await expect(loadCapability('example')).rejects.toThrow( + 'Capability request failed (409)', + ) + }) +}) From bb999ed2d5547003539a3d8782770745540f6bbd Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Fri, 9 Oct 2026 10:27:15 +0000 Subject: [PATCH 07/36] feat: add capability package provisioning Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/server/src/app.ts | 5 +- .../src/capabilities/image-gen/SKILL.md | 7 + .../capabilities/image-gen/capability.yaml | 65 +++ .../src/capabilities/image-gen/client.mjs | 37 ++ .../src/capabilities/image-gen/client.test.ts | 84 ++++ .../src/capabilities/ink-ocr/capability.yaml | 21 + .../src/capabilities/web-search/SKILL.md | 5 + .../capabilities/web-search/capability.yaml | 20 + .../src/capabilities/web-search/client.mjs | 28 ++ .../capabilities/web-search/client.test.ts | 64 +++ .../youtube-transcripts/capability.yaml | 17 + .../agent/conversation/ink-ocr.test.ts | 24 +- .../src/modules/agent/conversation/ink-ocr.ts | 14 +- .../agent/tools/handlers/image-generation.ts | 13 +- .../agent/tools/handlers/web-search.ts | 10 +- .../capabilities/capabilities.route.test.ts | 156 +++++++ .../capabilities/capabilities.route.ts | 102 +++++ apps/server/src/modules/capabilities/index.ts | 20 + .../capabilities/package-loader.test.ts | 38 ++ .../modules/capabilities/package-loader.ts | 87 ++++ .../capabilities/provision-service.test.ts | 137 ++++++ .../modules/capabilities/provision-service.ts | 391 ++++++++++++++++++ .../preprocessing/loaders/youtube.loader.ts | 23 +- .../src/modules/remote_fs/rfs.route.test.ts | 140 +++++++ .../server/src/modules/remote_fs/rfs.route.ts | 120 ++++++ .../src/prompt/external-agent/access-huabu.md | 31 ++ apps/server/tsup.config.ts | 7 + apps/web/src/api/_routes.ts | 2 + apps/web/src/api/capabilities.ts | 34 ++ .../Settings/SettingsModal.test.tsx | 18 +- .../src/components/Settings/SettingsModal.tsx | 12 +- .../sections/CapabilitiesSettings.test.tsx | 107 +++++ .../sections/CapabilitiesSettings.tsx | 320 ++++++++++++++ docs/README.md | 2 + docs/architecture/agent-reachback.md | 41 +- docs/architecture/api-design.md | 6 + docs/architecture/capability-packages.md | 101 +++++ docs/architecture/credential-storage.md | 2 + docs/proposals/capability-packages.md | 54 +++ .../src/types/api/capability-package.test.ts | 59 +++ .../src/types/api/capability-package.ts | 176 ++++++++ packages/shared/src/types/api/index.ts | 1 + 42 files changed, 2530 insertions(+), 71 deletions(-) create mode 100644 apps/server/src/capabilities/image-gen/SKILL.md create mode 100644 apps/server/src/capabilities/image-gen/capability.yaml create mode 100644 apps/server/src/capabilities/image-gen/client.mjs create mode 100644 apps/server/src/capabilities/image-gen/client.test.ts create mode 100644 apps/server/src/capabilities/ink-ocr/capability.yaml create mode 100644 apps/server/src/capabilities/web-search/SKILL.md create mode 100644 apps/server/src/capabilities/web-search/capability.yaml create mode 100644 apps/server/src/capabilities/web-search/client.mjs create mode 100644 apps/server/src/capabilities/web-search/client.test.ts create mode 100644 apps/server/src/capabilities/youtube-transcripts/capability.yaml create mode 100644 apps/server/src/modules/capabilities/capabilities.route.test.ts create mode 100644 apps/server/src/modules/capabilities/capabilities.route.ts create mode 100644 apps/server/src/modules/capabilities/index.ts create mode 100644 apps/server/src/modules/capabilities/package-loader.test.ts create mode 100644 apps/server/src/modules/capabilities/package-loader.ts create mode 100644 apps/server/src/modules/capabilities/provision-service.test.ts create mode 100644 apps/server/src/modules/capabilities/provision-service.ts create mode 100644 apps/web/src/api/capabilities.ts create mode 100644 apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx create mode 100644 apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx create mode 100644 docs/architecture/capability-packages.md create mode 100644 docs/proposals/capability-packages.md create mode 100644 packages/shared/src/types/api/capability-package.test.ts create mode 100644 packages/shared/src/types/api/capability-package.ts diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index d77c99ae7..7876a9af3 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -41,6 +41,7 @@ import canvasRoutes from './modules/canvas/canvas.route.js'; import { resetExternalNoteSessions } from './modules/canvas/external-watcher.js'; import externalNoteRoutes from './modules/canvas/external.route.js'; import syncRoutes from './modules/canvas/sync.route.js'; +import capabilityRoutes from './modules/capabilities/capabilities.route.js'; import integrationsRoutes from './modules/integrations/integrations.route.js'; import interactiveViewRoutes from './modules/interactive-view/interactive-view.route.js'; import { isPublicRfsSkillBootstrapRequest } from './modules/remote_fs/public-skill.js'; @@ -236,7 +237,8 @@ app.addHook('preHandler', async (request, reply) => { !url.startsWith('/api/workspace') && !url.startsWith('/api/deployment') && !url.startsWith('/api/llm') && - !url.startsWith('/api/integrations') + !url.startsWith('/api/integrations') && + !url.startsWith('/api/capabilities') ) { return reply.status(503).send({ message: @@ -257,6 +259,7 @@ app.register(artifactRoute, { prefix: '/api/canvas' }); app.register(llmRoutes, { prefix: '/api/llm' }); app.register(integrationsRoutes, { prefix: '/api/integrations' }); +app.register(capabilityRoutes, { prefix: '/api/capabilities' }); app.register(deploymentRoutes, { prefix: '/api/deployment' }); app.register(canaryRedeployRoutes, { prefix: '/api/deployment/canary', diff --git a/apps/server/src/capabilities/image-gen/SKILL.md b/apps/server/src/capabilities/image-gen/SKILL.md new file mode 100644 index 000000000..e23ba3f3b --- /dev/null +++ b/apps/server/src/capabilities/image-gen/SKILL.md @@ -0,0 +1,7 @@ +# Image Generation + +Use this Capability when the user asks you to generate an image through their configured Azure OpenAI image deployment. + +Load the Capability through the Agentlet SDK URL in `AGENTLET_CAPABILITY_SDK_URL`. Call the returned client's `generate()` method with a non-empty `prompt` and optional provider-supported image parameters. Provider credentials are supplied only to the loaded client; never print, persist, or include them in another request. + +The client returns the provider response. Decode or upload generated image bytes through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. diff --git a/apps/server/src/capabilities/image-gen/capability.yaml b/apps/server/src/capabilities/image-gen/capability.yaml new file mode 100644 index 000000000..966818f38 --- /dev/null +++ b/apps/server/src/capabilities/image-gen/capability.yaml @@ -0,0 +1,65 @@ +schema: huabu-capability/v1 +id: image-gen +version: 1.0.0 +name: Image Generation +description: Generate images with the configured Azure OpenAI deployment. +storage: + namespace: llm.imageConfig +consumers: + internal: true + pipeline: false + external: true +agent: + skill: SKILL.md + client: client.mjs +configuration: + - id: provider + label: Provider + type: enum + required: true + options: + - value: azure-openai + label: Azure OpenAI + - id: baseUrl + label: Endpoint + type: url + required: true + placeholder: https://resource.cognitiveservices.azure.com + - id: modelFamily + label: Model + type: enum + required: true + options: + - value: gpt-image-1 + label: gpt-image-1 + - value: gpt-image-1-mini + label: gpt-image-1-mini + - value: gpt-image-2 + label: gpt-image-2 + - id: model + label: Deployment + description: Optional Azure deployment name. Defaults to the model name. + type: text + required: false + - id: apiVersion + label: API version + type: text + required: true + - id: quality + label: Image quality + type: enum + required: true + options: + - value: low + label: low + - value: medium + label: medium + - value: high + label: high + - value: auto + label: auto + - id: apiKey + label: API key + type: secret + required: true + placeholder: Azure key diff --git a/apps/server/src/capabilities/image-gen/client.mjs b/apps/server/src/capabilities/image-gen/client.mjs new file mode 100644 index 000000000..05a26718d --- /dev/null +++ b/apps/server/src/capabilities/image-gen/client.mjs @@ -0,0 +1,37 @@ +export function createClient({ config }) { + return { + async generate(input) { + if (!input || typeof input.prompt !== 'string' || !input.prompt.trim()) { + throw new Error('Image generation requires a non-empty prompt'); + } + const endpoint = config.baseUrl.replace(/\/+$/, ''); + const deployment = config.model || config.modelFamily; + const v1Style = /(?:^|\/)(?:openai\/)?v1$/i.test(endpoint); + const url = v1Style + ? new URL(`${endpoint}/images/generations`) + : new URL( + `${endpoint}/openai/deployments/${encodeURIComponent(deployment)}/images/generations`, + ); + if (!v1Style) url.searchParams.set('api-version', config.apiVersion); + const response = await fetch(url, { + method: 'POST', + headers: { + ...(v1Style + ? { authorization: `Bearer ${config.apiKey}` } + : { 'api-key': config.apiKey }), + 'content-type': 'application/json', + }, + body: JSON.stringify({ + ...input, + prompt: input.prompt.trim(), + quality: input.quality || config.quality, + ...(v1Style ? { model: deployment } : {}), + }), + }); + if (!response.ok) { + throw new Error(`Image provider request failed (${response.status})`); + } + return response.json(); + }, + }; +} diff --git a/apps/server/src/capabilities/image-gen/client.test.ts b/apps/server/src/capabilities/image-gen/client.test.ts new file mode 100644 index 000000000..0a3f22bca --- /dev/null +++ b/apps/server/src/capabilities/image-gen/client.test.ts @@ -0,0 +1,84 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { readCapabilityPackageFile } from '../../modules/capabilities/package-loader.js'; + +async function loadClient() { + const source = readCapabilityPackageFile('image-gen', 'client.mjs'); + if (!source) throw new Error('Image Capability client is missing'); + return import( + `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` + ) as Promise<{ + createClient(input: { config: Record }): { + generate(input: Record): Promise; + }; + }>; +} + +afterEach(() => { + vi.unstubAllGlobals(); +}); + +describe('Image Capability client', () => { + it('uses classic Azure deployment routing', async () => { + const fetchMock = vi + .fn() + .mockResolvedValue(new Response(JSON.stringify({ data: [] }))); + vi.stubGlobal('fetch', fetchMock); + const { createClient } = await loadClient(); + + await createClient({ + config: { + apiKey: 'test-secret', + apiVersion: '2025-04-01-preview', + baseUrl: 'https://example.test', + model: 'image-deployment', + modelFamily: 'gpt-image-1', + quality: 'high', + }, + }).generate({ prompt: ' a fox ' }); + + const [url, init] = fetchMock.mock.calls[0] ?? []; + expect(String(url)).toBe( + 'https://example.test/openai/deployments/image-deployment/images/generations?api-version=2025-04-01-preview', + ); + expect(init?.headers).toMatchObject({ 'api-key': 'test-secret' }); + expect(JSON.parse(String(init?.body))).toMatchObject({ + prompt: 'a fox', + quality: 'high', + }); + }); + + it('uses OpenAI-compatible v1 routing and bearer authentication', async () => { + const fetchMock = vi + .fn() + .mockResolvedValue(new Response(JSON.stringify({ data: [] }))); + vi.stubGlobal('fetch', fetchMock); + const { createClient } = await loadClient(); + + await createClient({ + config: { + apiKey: 'test-secret', + apiVersion: 'unused', + baseUrl: 'https://example.test/openai/v1/', + model: 'image-deployment', + modelFamily: 'gpt-image-1', + quality: 'medium', + }, + }).generate({ prompt: 'a fox' }); + + const [url, init] = fetchMock.mock.calls[0] ?? []; + expect(String(url)).toBe( + 'https://example.test/openai/v1/images/generations', + ); + expect(init?.headers).toMatchObject({ + authorization: 'Bearer test-secret', + }); + expect(JSON.parse(String(init?.body))).toMatchObject({ + model: 'image-deployment', + prompt: 'a fox', + }); + }); +}); diff --git a/apps/server/src/capabilities/ink-ocr/capability.yaml b/apps/server/src/capabilities/ink-ocr/capability.yaml new file mode 100644 index 000000000..a20d77e64 --- /dev/null +++ b/apps/server/src/capabilities/ink-ocr/capability.yaml @@ -0,0 +1,21 @@ +schema: huabu-capability/v1 +id: ink-ocr +version: 1.0.0 +name: Handwriting Recognition +description: Recognize selected handwriting with Azure AI Vision. +storage: + namespace: integration.azureVisionInkOcr +consumers: + internal: true + pipeline: false + external: false +configuration: + - id: endpoint + label: Endpoint + type: url + required: true + placeholder: https://resource.cognitiveservices.azure.com + - id: apiKey + label: API key + type: secret + required: true diff --git a/apps/server/src/capabilities/web-search/SKILL.md b/apps/server/src/capabilities/web-search/SKILL.md new file mode 100644 index 000000000..1f9006be9 --- /dev/null +++ b/apps/server/src/capabilities/web-search/SKILL.md @@ -0,0 +1,5 @@ +# Web Search + +Use this Capability for current public web information when ordinary local knowledge is insufficient. + +Load it through the Agentlet SDK URL in `AGENTLET_CAPABILITY_SDK_URL`, then call the returned client's `search()` method with a non-empty query. Never print or persist the supplied credential. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. diff --git a/apps/server/src/capabilities/web-search/capability.yaml b/apps/server/src/capabilities/web-search/capability.yaml new file mode 100644 index 000000000..b543780ea --- /dev/null +++ b/apps/server/src/capabilities/web-search/capability.yaml @@ -0,0 +1,20 @@ +schema: huabu-capability/v1 +id: web-search +version: 1.0.0 +name: Web Search +description: Search the web with Tavily. +storage: + namespace: integration.tavily +consumers: + internal: true + pipeline: false + external: true +agent: + skill: SKILL.md + client: client.mjs +configuration: + - id: apiKey + label: API key + type: secret + required: true + placeholder: tvly-... diff --git a/apps/server/src/capabilities/web-search/client.mjs b/apps/server/src/capabilities/web-search/client.mjs new file mode 100644 index 000000000..afda92d09 --- /dev/null +++ b/apps/server/src/capabilities/web-search/client.mjs @@ -0,0 +1,28 @@ +export function createClient({ config }) { + return { + async search(input) { + const query = + typeof input === 'string' + ? input.trim() + : typeof input?.query === 'string' + ? input.query.trim() + : ''; + if (!query) throw new Error('Web search requires a non-empty query'); + const response = await fetch('https://api.tavily.com/search', { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + ...(typeof input === 'object' && input ? input : {}), + api_key: config.apiKey, + query, + }), + }); + if (!response.ok) { + throw new Error( + `Web search provider request failed (${response.status})`, + ); + } + return response.json(); + }, + }; +} diff --git a/apps/server/src/capabilities/web-search/client.test.ts b/apps/server/src/capabilities/web-search/client.test.ts new file mode 100644 index 000000000..99926a5eb --- /dev/null +++ b/apps/server/src/capabilities/web-search/client.test.ts @@ -0,0 +1,64 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { readCapabilityPackageFile } from '../../modules/capabilities/package-loader.js'; + +async function loadClient() { + const source = readCapabilityPackageFile('web-search', 'client.mjs'); + if (!source) throw new Error('Web Search Capability client is missing'); + return import( + `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` + ) as Promise<{ + createClient(input: { config: Record }): { + search(input: string | Record): Promise; + }; + }>; +} + +afterEach(() => { + vi.unstubAllGlobals(); +}); + +describe('Web Search Capability client', () => { + it('sends the configured Tavily key and normalized query', async () => { + const fetchMock = vi + .fn() + .mockResolvedValue(new Response(JSON.stringify({ results: [] }))); + vi.stubGlobal('fetch', fetchMock); + const { createClient } = await loadClient(); + + await createClient({ + config: { apiKey: 'test-secret' }, + }).search({ query: ' Huabu ', max_results: 3 }); + + const [url, init] = fetchMock.mock.calls[0] ?? []; + expect(url).toBe('https://api.tavily.com/search'); + expect(init).toMatchObject({ + method: 'POST', + headers: { 'content-type': 'application/json' }, + }); + expect(JSON.parse(String(init?.body))).toEqual({ + api_key: 'test-secret', + query: 'Huabu', + max_results: 3, + }); + }); + + it('does not include provider response bodies in errors', async () => { + vi.stubGlobal( + 'fetch', + vi + .fn() + .mockResolvedValue( + new Response('sensitive provider response', { status: 401 }), + ), + ); + const { createClient } = await loadClient(); + + await expect( + createClient({ config: { apiKey: 'test-secret' } }).search('Huabu'), + ).rejects.toThrow('Web search provider request failed (401)'); + }); +}); diff --git a/apps/server/src/capabilities/youtube-transcripts/capability.yaml b/apps/server/src/capabilities/youtube-transcripts/capability.yaml new file mode 100644 index 000000000..80e93c936 --- /dev/null +++ b/apps/server/src/capabilities/youtube-transcripts/capability.yaml @@ -0,0 +1,17 @@ +schema: huabu-capability/v1 +id: youtube-transcripts +version: 1.0.0 +name: YouTube Transcripts +description: Load YouTube transcripts through the existing RapidAPI preprocessing integration. +storage: + namespace: integration.rapidapi +consumers: + internal: false + pipeline: true + external: false +configuration: + - id: apiKey + label: API key + type: secret + required: true + placeholder: rapidapi-... diff --git a/apps/server/src/modules/agent/conversation/ink-ocr.test.ts b/apps/server/src/modules/agent/conversation/ink-ocr.test.ts index dae9ce52c..4d650cbff 100644 --- a/apps/server/src/modules/agent/conversation/ink-ocr.test.ts +++ b/apps/server/src/modules/agent/conversation/ink-ocr.test.ts @@ -6,11 +6,25 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { isInkOcrConfigured, recognizeInk } from './ink-ocr.js'; -vi.mock('../../integrations/ink-ocr-config.js', () => ({ - resolveInkOcrConfiguration: () => ({ - key: process.env.VISION_KEY?.trim() || null, - endpoint: process.env.VISION_ENDPOINT?.trim() || null, - }), +vi.mock('../../capabilities/index.js', () => ({ + capabilityProvisionService: { + getConfig: () => { + const apiKey = process.env.VISION_KEY?.trim() || ''; + const endpoint = process.env.VISION_ENDPOINT?.trim() || ''; + const configuredFields = [ + ...(apiKey ? ['apiKey'] : []), + ...(endpoint ? ['endpoint'] : []), + ]; + return { + configured: configuredFields.length === 2, + configuredFields, + }; + }, + resolveForServer: () => ({ + apiKey: process.env.VISION_KEY?.trim() || '', + endpoint: process.env.VISION_ENDPOINT?.trim() || '', + }), + }, })); const logger = pino({ enabled: false }); diff --git a/apps/server/src/modules/agent/conversation/ink-ocr.ts b/apps/server/src/modules/agent/conversation/ink-ocr.ts index fe85d09d4..ddd620113 100644 --- a/apps/server/src/modules/agent/conversation/ink-ocr.ts +++ b/apps/server/src/modules/agent/conversation/ink-ocr.ts @@ -5,7 +5,7 @@ import { z } from 'zod'; import { inkOcrEndpointSchema, inkRecognitionSchema } from '@huabu/shared'; -import { resolveInkOcrConfiguration } from '../../integrations/ink-ocr-config.js'; +import { capabilityProvisionService } from '../../capabilities/index.js'; import type { InkRecognition } from '@huabu/shared'; import type { FastifyBaseLogger } from 'fastify'; @@ -73,7 +73,17 @@ class InvalidResultError extends Error {} function readConfiguration(): Configuration { try { - const { key, endpoint } = resolveInkOcrConfiguration(); + const snapshot = capabilityProvisionService.getConfig('ink-ocr'); + if (!snapshot.configured) { + return { + outcome: + snapshot.configuredFields.length === 0 ? 'disabled' : 'config_error', + }; + } + const resolved = capabilityProvisionService.resolveForServer('ink-ocr'); + const key = typeof resolved.apiKey === 'string' ? resolved.apiKey : ''; + const endpoint = + typeof resolved.endpoint === 'string' ? resolved.endpoint : ''; if (!key && !endpoint) return { outcome: 'disabled' }; const parsedEndpoint = inkOcrEndpointSchema.safeParse(endpoint); if (!key || !parsedEndpoint.success) return { outcome: 'config_error' }; diff --git a/apps/server/src/modules/agent/tools/handlers/image-generation.ts b/apps/server/src/modules/agent/tools/handlers/image-generation.ts index 4655bee5e..63f07a353 100644 --- a/apps/server/src/modules/agent/tools/handlers/image-generation.ts +++ b/apps/server/src/modules/agent/tools/handlers/image-generation.ts @@ -52,11 +52,12 @@ import { } from '@huabu/shared'; import { getLogger } from '../../../../utils/logger.js'; +import { capabilityProvisionService } from '../../../capabilities/index.js'; import { space } from '../../../storage/index.js'; -import { getAzureImageConfig } from '../../llm.js'; import type { generateImageParamsSchema } from '../definitions.js'; import type { Static } from '@earendil-works/pi-ai'; +import type { ImageModelFamily } from '@huabu/shared'; const log = getLogger('tool.generate-image'); @@ -96,7 +97,15 @@ export async function handleGenerateImage( } const refs = args.referenceArtifactSrcs ?? []; - const azure = getAzureImageConfig(); // throws with actionable message + const resolved = capabilityProvisionService.resolveForServer('image-gen'); + const azure = { + endpoint: String(resolved.baseUrl), + deployment: String(resolved.model), + apiKey: String(resolved.apiKey), + apiVersion: String(resolved.apiVersion), + modelFamily: resolved.modelFamily as ImageModelFamily, + quality: resolved.quality as 'low' | 'medium' | 'high' | 'auto', + }; const caps = getImageCapabilities(azure.modelFamily); // ── Capability validation ──────────────────────────────────────────── diff --git a/apps/server/src/modules/agent/tools/handlers/web-search.ts b/apps/server/src/modules/agent/tools/handlers/web-search.ts index a52b9161d..fdce3d69f 100644 --- a/apps/server/src/modules/agent/tools/handlers/web-search.ts +++ b/apps/server/src/modules/agent/tools/handlers/web-search.ts @@ -15,7 +15,7 @@ */ import { getLogger } from '../../../../utils/logger.js'; -import { getTavilyApiKey } from '../../../integrations/integrations.js'; +import { capabilityProvisionService } from '../../../capabilities/index.js'; import type { webSearchParamsSchema } from '../definitions.js'; import type { Static } from '@earendil-works/pi-ai'; @@ -25,12 +25,8 @@ const log = getLogger('tool.web-search'); export type WebSearchArgs = Static; export async function handleWebSearch(args: WebSearchArgs): Promise { - const apiKey = getTavilyApiKey(); - if (!apiKey) { - throw new Error( - 'Missing Tavily API key. Add it in Settings → Integrations (or set TAVILY_API_KEY) to enable web_search.', - ); - } + const resolved = capabilityProvisionService.resolveForServer('web-search'); + const apiKey = typeof resolved.apiKey === 'string' ? resolved.apiKey : ''; const controller = new AbortController(); const timeoutMs = 15_000; diff --git a/apps/server/src/modules/capabilities/capabilities.route.test.ts b/apps/server/src/modules/capabilities/capabilities.route.test.ts new file mode 100644 index 000000000..ac4b13b30 --- /dev/null +++ b/apps/server/src/modules/capabilities/capabilities.route.test.ts @@ -0,0 +1,156 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import fastify, { type FastifyInstance } from 'fastify'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import type * as CapabilityModule from './index.js'; + +const mocks = vi.hoisted(() => ({ + getConfig: vi.fn(), + isOwner: vi.fn(), + list: vi.fn(), + updateConfig: vi.fn(), +})); + +vi.mock('./index.js', async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + capabilityProvisionService: { + getConfig: mocks.getConfig, + list: mocks.list, + updateConfig: mocks.updateConfig, + }, + }; +}); + +vi.mock('../security/owner.js', () => ({ + isOwnerRequest: mocks.isOwner, +})); + +const { default: capabilityRoutes } = await import('./capabilities.route.js'); + +let app: FastifyInstance | undefined; + +async function buildApp(): Promise { + const instance = fastify(); + await instance.register(capabilityRoutes, { prefix: '/capabilities' }); + await instance.ready(); + return instance; +} + +const maskedConfig = { + manifest: { + schema: 'huabu-capability/v1', + id: 'web-search', + version: '1.0.0', + name: 'Web Search', + description: 'Search the web.', + storage: { namespace: 'integration.tavily' }, + consumers: { internal: true, pipeline: false, external: true }, + agent: { skill: 'SKILL.md', client: 'client.mjs' }, + configuration: [ + { + id: 'apiKey', + label: 'API key', + type: 'secret', + required: true, + }, + ], + }, + values: { apiKey: null }, + configuredFields: ['apiKey'], + configured: true, +} as const; + +beforeEach(() => { + mocks.getConfig.mockReset(); + mocks.isOwner.mockReset().mockReturnValue(true); + mocks.list.mockReset(); + mocks.updateConfig.mockReset(); +}); + +afterEach(async () => { + await app?.close(); + app = undefined; +}); + +describe('Capability settings routes', () => { + it('returns discovery and masked configuration', async () => { + mocks.list.mockReturnValue([ + { + id: 'web-search', + version: '1.0.0', + name: 'Web Search', + description: 'Search the web.', + configured: true, + availableToInternalAgent: true, + availableToPipeline: false, + availableToExternalAgent: true, + }, + ]); + mocks.getConfig.mockReturnValue(maskedConfig); + app = await buildApp(); + + const discovery = await app.inject({ + method: 'GET', + url: '/capabilities', + }); + const config = await app.inject({ + method: 'GET', + url: '/capabilities/web-search', + }); + + expect(discovery.statusCode).toBe(200); + expect(discovery.json()).toMatchObject({ + capabilities: [{ id: 'web-search', configured: true }], + }); + expect(config.statusCode).toBe(200); + expect(config.json()).toMatchObject({ + manifest: { id: 'web-search' }, + values: { apiKey: null }, + configuredFields: ['apiKey'], + configured: true, + }); + expect(config.body).not.toContain('test-secret'); + }); + + it('requires owner authorization before updating configuration', async () => { + mocks.isOwner.mockReturnValue(false); + app = await buildApp(); + + const response = await app.inject({ + method: 'PUT', + url: '/capabilities/web-search', + payload: { values: { apiKey: 'test-secret' } }, + }); + + expect(response.statusCode).toBe(403); + expect(mocks.updateConfig).not.toHaveBeenCalled(); + }); + + it('validates and delegates owner updates', async () => { + mocks.updateConfig.mockResolvedValue(maskedConfig); + app = await buildApp(); + + const invalid = await app.inject({ + method: 'PUT', + url: '/capabilities/web-search', + payload: { values: { apiKey: { nested: true } } }, + }); + expect(invalid.statusCode).toBe(400); + expect(mocks.updateConfig).not.toHaveBeenCalled(); + + const updated = await app.inject({ + method: 'PUT', + url: '/capabilities/web-search', + payload: { values: { apiKey: 'test-secret' } }, + }); + expect(updated.statusCode).toBe(200); + expect(mocks.updateConfig).toHaveBeenCalledWith('web-search', { + apiKey: 'test-secret', + }); + expect(updated.body).not.toContain('test-secret'); + }); +}); diff --git a/apps/server/src/modules/capabilities/capabilities.route.ts b/apps/server/src/modules/capabilities/capabilities.route.ts new file mode 100644 index 000000000..75a9a91cd --- /dev/null +++ b/apps/server/src/modules/capabilities/capabilities.route.ts @@ -0,0 +1,102 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { + capabilityConfigUpdateSchema, + capabilityParamsSchema, +} from '@huabu/shared'; + +import { isOwnerRequest } from '../security/owner.js'; + +import { capabilityProvisionService, CapabilityServiceError } from './index.js'; + +import type { + ApiResult, + CapabilityConfig, + CapabilityConfigUpdate, + CapabilityListResponse, + CapabilityParams, +} from '@huabu/shared'; +import type { FastifyPluginAsync } from 'fastify'; + +function statusFor(error: CapabilityServiceError): number { + switch (error.code) { + case 'capability_not_found': + return 404; + case 'invalid_capability_config': + return 400; + default: + return 409; + } +} + +const capabilityRoutes: FastifyPluginAsync = async (app) => { + app.get<{ Reply: ApiResult }>('/', async () => ({ + capabilities: capabilityProvisionService.list(), + })); + + app.get<{ + Params: CapabilityParams; + Reply: ApiResult; + }>('/:capabilityId', async (request, reply) => { + const parsed = capabilityParamsSchema.safeParse(request.params); + if (!parsed.success) { + return reply.code(400).send({ + message: parsed.error.issues[0]?.message ?? 'Invalid Capability id', + }); + } + try { + return reply.send( + capabilityProvisionService.getConfig(parsed.data.capabilityId), + ); + } catch (error) { + if (error instanceof CapabilityServiceError) { + return reply + .code(statusFor(error)) + .send({ message: error.message, code: error.code }); + } + throw error; + } + }); + + app.put<{ + Params: CapabilityParams; + Body: CapabilityConfigUpdate; + Reply: ApiResult; + }>('/:capabilityId', async (request, reply) => { + if (!isOwnerRequest(request)) { + return reply.code(403).send({ + message: 'Forbidden: Capability settings require owner authorization', + }); + } + const params = capabilityParamsSchema.safeParse(request.params); + const body = capabilityConfigUpdateSchema.safeParse(request.body); + if (!params.success || !body.success) { + const issue = !params.success + ? params.error.issues[0] + : !body.success + ? body.error.issues[0] + : undefined; + return reply.code(400).send({ + message: issue?.message ?? 'Invalid Capability update', + }); + } + try { + return reply.send( + await capabilityProvisionService.updateConfig( + params.data.capabilityId, + body.data.values, + ), + ); + } catch (error) { + if (error instanceof CapabilityServiceError) { + return reply + .code(statusFor(error)) + .send({ message: error.message, code: error.code }); + } + throw error; + } + }); +}; + +export default capabilityRoutes; diff --git a/apps/server/src/modules/capabilities/index.ts b/apps/server/src/modules/capabilities/index.ts new file mode 100644 index 000000000..c4a8f8011 --- /dev/null +++ b/apps/server/src/modules/capabilities/index.ts @@ -0,0 +1,20 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { getBundledCapabilityPackages } from './package-loader.js'; +import { CapabilityProvisionService } from './provision-service.js'; + +export const capabilityProvisionService = new CapabilityProvisionService( + new Map( + [...getBundledCapabilityPackages()].map(([id, capability]) => [ + id, + capability.manifest, + ]), + ), +); + +export { + getBundledCapabilityPackage, + readCapabilityPackageFile, +} from './package-loader.js'; +export { CapabilityServiceError } from './provision-service.js'; diff --git a/apps/server/src/modules/capabilities/package-loader.test.ts b/apps/server/src/modules/capabilities/package-loader.test.ts new file mode 100644 index 000000000..34698934e --- /dev/null +++ b/apps/server/src/modules/capabilities/package-loader.test.ts @@ -0,0 +1,38 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { describe, expect, it } from 'vitest'; + +import { + getBundledCapabilityPackages, + readCapabilityPackageFile, +} from './package-loader.js'; + +describe('bundled Capability packages', () => { + it('loads all current Settings capabilities from validated YAML', () => { + const packages = getBundledCapabilityPackages(); + expect([...packages.keys()]).toEqual([ + 'image-gen', + 'web-search', + 'youtube-transcripts', + 'ink-ocr', + ]); + expect(packages.get('image-gen')?.manifest.storage.namespace).toBe( + 'llm.imageConfig', + ); + expect(packages.get('youtube-transcripts')?.manifest.agent).toBeUndefined(); + expect(packages.get('ink-ocr')?.manifest.agent).toBeUndefined(); + }); + + it('exposes real Agent files only for External packages', () => { + expect(readCapabilityPackageFile('image-gen', 'SKILL.md')).toContain( + '# Image Generation', + ); + expect(readCapabilityPackageFile('web-search', 'client.mjs')).toContain( + 'createClient', + ); + expect( + readCapabilityPackageFile('youtube-transcripts', 'SKILL.md'), + ).toBeNull(); + }); +}); diff --git a/apps/server/src/modules/capabilities/package-loader.ts b/apps/server/src/modules/capabilities/package-loader.ts new file mode 100644 index 000000000..ebf40ff73 --- /dev/null +++ b/apps/server/src/modules/capabilities/package-loader.ts @@ -0,0 +1,87 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { existsSync, readFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +import { parse } from 'yaml'; + +import { capabilityManifestSchema } from '@huabu/shared'; + +import { resolveDirectChildPath, safeJoin } from '../../utils/fs.js'; + +import type { CapabilityManifest } from '@huabu/shared'; + +const PACKAGE_IDS = [ + 'image-gen', + 'web-search', + 'youtube-transcripts', + 'ink-ocr', +] as const; + +export interface BundledCapabilityPackage { + root: string; + manifest: CapabilityManifest; +} + +function packageRoot(): string { + const moduleDir = dirname(fileURLToPath(import.meta.url)); + const bundled = resolve(moduleDir, 'capabilities'); + if (existsSync(bundled)) return bundled; + return resolve(moduleDir, '../../capabilities'); +} + +function readPackage(packageId: (typeof PACKAGE_IDS)[number]) { + const root = resolveDirectChildPath(packageRoot(), packageId); + const manifestPath = resolveDirectChildPath(root, 'capability.yaml'); + const parsed = capabilityManifestSchema.safeParse( + parse(readFileSync(manifestPath, 'utf8')), + ); + if (!parsed.success) { + throw new Error( + `Invalid bundled Capability manifest "${packageId}": ${parsed.error.issues[0]?.message ?? 'unknown error'}`, + ); + } + if (parsed.data.id !== packageId) { + throw new Error( + `Capability package directory must match id "${packageId}"`, + ); + } + for (const file of [ + parsed.data.agent?.skill, + parsed.data.agent?.client, + ].filter((value): value is string => Boolean(value))) { + const filePath = safeJoin(root, file); + if (!existsSync(filePath)) { + throw new Error(`Capability "${packageId}" references missing file`); + } + } + return { root, manifest: parsed.data }; +} + +let packages: ReadonlyMap | null = null; + +export function getBundledCapabilityPackages(): ReadonlyMap< + string, + BundledCapabilityPackage +> { + packages ??= new Map(PACKAGE_IDS.map((id) => [id, readPackage(id)])); + return packages; +} + +export function getBundledCapabilityPackage( + capabilityId: string, +): BundledCapabilityPackage | undefined { + return getBundledCapabilityPackages().get(capabilityId); +} + +export function readCapabilityPackageFile( + capabilityId: string, + file: string, +): string | null { + const capability = getBundledCapabilityPackage(capabilityId); + if (!capability) return null; + const filePath = safeJoin(capability.root, file); + return existsSync(filePath) ? readFileSync(filePath, 'utf8') : null; +} diff --git a/apps/server/src/modules/capabilities/provision-service.test.ts b/apps/server/src/modules/capabilities/provision-service.test.ts new file mode 100644 index 000000000..510dccb42 --- /dev/null +++ b/apps/server/src/modules/capabilities/provision-service.test.ts @@ -0,0 +1,137 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +const mocks = vi.hoisted(() => ({ + setImageConfig: vi.fn(), + setIntegrationsConfig: vi.fn(), + setInkOcrConfig: vi.fn(), +})); + +vi.mock('../agent/llm.js', () => ({ + getImageConfig: () => ({ + provider: 'azure-openai', + authenticated: true, + baseUrl: 'https://images.example.com', + model: 'image-deployment', + modelFamily: 'gpt-image-2', + apiVersion: '2025-04-01-preview', + quality: 'low', + }), + getAzureImageConfig: () => ({ + endpoint: 'https://images.example.com', + deployment: 'image-deployment', + apiKey: 'image-secret', + apiVersion: '2025-04-01-preview', + modelFamily: 'gpt-image-2', + quality: 'low', + }), + setImageConfig: mocks.setImageConfig, +})); + +vi.mock('../integrations/integrations.js', () => ({ + getTavilyApiKey: () => 'tavily-secret', + getRapidApiKey: () => 'rapid-secret', + setIntegrationsConfig: mocks.setIntegrationsConfig, +})); + +vi.mock('../integrations/ink-ocr-config.js', () => ({ + getInkOcrConfig: () => ({ + provider: 'azure-vision', + endpoint: 'https://vision.cognitiveservices.azure.com', + endpointSource: 'stored', + keySource: 'stored', + hasStoredKey: true, + configured: true, + }), + resolveInkOcrConfiguration: () => ({ + endpoint: 'https://vision.cognitiveservices.azure.com', + key: 'vision-secret', + }), + setInkOcrConfig: mocks.setInkOcrConfig, +})); + +vi.mock('../../security/secret-store.js', () => ({ + getSecret: () => 'image-secret', +})); + +import { getBundledCapabilityPackages } from './package-loader.js'; +import { CapabilityProvisionService } from './provision-service.js'; + +function service() { + return new CapabilityProvisionService( + new Map( + [...getBundledCapabilityPackages()].map(([id, capability]) => [ + id, + capability.manifest, + ]), + ), + ); +} + +beforeEach(() => { + vi.clearAllMocks(); +}); + +describe('Capability Provision Service storage bindings', () => { + it('reads every existing owner without causing a persistence write', () => { + const provision = service(); + + expect(provision.list()).toHaveLength(4); + expect(provision.getConfig('image-gen').configured).toBe(true); + expect(provision.getConfig('web-search').values.apiKey).toBeNull(); + expect(provision.resolveForServer('youtube-transcripts')).toEqual({ + apiKey: 'rapid-secret', + }); + + expect(mocks.setImageConfig).not.toHaveBeenCalled(); + expect(mocks.setIntegrationsConfig).not.toHaveBeenCalled(); + expect(mocks.setInkOcrConfig).not.toHaveBeenCalled(); + }); + + it('writes updates back through the registered existing owner', async () => { + const provision = service(); + + await provision.updateConfig('image-gen', { + baseUrl: 'https://next.example.com', + }); + await provision.updateConfig('web-search', { apiKey: 'next-tavily' }); + await provision.updateConfig('ink-ocr', { apiKey: null }); + + expect(mocks.setImageConfig).toHaveBeenCalledWith({ + baseUrl: 'https://next.example.com', + }); + expect(mocks.setIntegrationsConfig).toHaveBeenCalledWith({ + tavilyApiKey: 'next-tavily', + }); + expect(mocks.setInkOcrConfig).toHaveBeenCalledWith({ apiKey: null }); + }); + + it('leases only declared fields for configured External packages', () => { + const lease = service().lease('image-gen'); + + expect(lease).toMatchObject({ + id: 'image-gen', + client: 'client.mjs', + config: { + baseUrl: 'https://images.example.com', + apiKey: 'image-secret', + }, + }); + expect(Object.keys(lease.config).sort()).toEqual( + [ + 'apiKey', + 'apiVersion', + 'baseUrl', + 'model', + 'modelFamily', + 'provider', + 'quality', + ].sort(), + ); + expect(() => service().lease('ink-ocr')).toThrow( + 'not available to External Agents', + ); + }); +}); diff --git a/apps/server/src/modules/capabilities/provision-service.ts b/apps/server/src/modules/capabilities/provision-service.ts new file mode 100644 index 000000000..b7f7d7ad5 --- /dev/null +++ b/apps/server/src/modules/capabilities/provision-service.ts @@ -0,0 +1,391 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { + DEFAULT_AZURE_IMAGE_API_VERSION, + DEFAULT_IMAGE_MODEL_FAMILY, + getImageCapabilities, + inkOcrConfigUpdateSchema, + llmImageConfigUpdateSchema, +} from '@huabu/shared'; + +import { SECRET_IDS } from '../../security/secret-ids.js'; +import { getSecret } from '../../security/secret-store.js'; +import { + getImageConfig, + getAzureImageConfig, + setImageConfig, +} from '../agent/llm.js'; +import { + getInkOcrConfig, + resolveInkOcrConfiguration, + setInkOcrConfig, +} from '../integrations/ink-ocr-config.js'; +import { + getRapidApiKey, + getTavilyApiKey, + setIntegrationsConfig, +} from '../integrations/integrations.js'; + +import type { + CapabilityConfig, + CapabilityFieldValue, + CapabilityLease, + CapabilityManifest, + CapabilitySummary, + ImageModelFamily, + LLMImageConfigUpdate, +} from '@huabu/shared'; + +interface AdapterSnapshot { + values: Record; + configuredFields: string[]; +} + +interface CapabilityStorageAdapter { + read(): AdapterSnapshot; + update(values: Readonly>): Promise; + resolve(): Record; +} + +export class CapabilityServiceError extends Error { + constructor( + readonly code: + | 'capability_not_found' + | 'capability_not_external' + | 'capability_not_configured' + | 'invalid_capability_config', + message: string, + ) { + super(message); + this.name = 'CapabilityServiceError'; + } +} + +function presentFields( + values: Readonly>, +): string[] { + return Object.entries(values) + .filter(([, value]) => + typeof value === 'string' ? value.trim().length > 0 : value !== null, + ) + .map(([id]) => id); +} + +function imageSnapshot(): AdapterSnapshot { + const stored = getImageConfig(); + const modelFamily = stored.modelFamily ?? DEFAULT_IMAGE_MODEL_FAMILY; + const values: Record = { + provider: stored.provider || 'azure-openai', + baseUrl: stored.baseUrl ?? '', + modelFamily, + model: stored.model ?? '', + apiVersion: stored.apiVersion ?? DEFAULT_AZURE_IMAGE_API_VERSION, + quality: stored.quality ?? getImageCapabilities(modelFamily).defaultQuality, + apiKey: null, + }; + const configuredFields = presentFields(values).filter( + (field) => field !== 'apiKey', + ); + if (getSecret(SECRET_IDS.imageApiKey)) configuredFields.push('apiKey'); + return { values, configuredFields }; +} + +const imageAdapter: CapabilityStorageAdapter = { + read: imageSnapshot, + async update(values) { + const update: LLMImageConfigUpdate = {}; + if ('provider' in values) { + update.provider = + typeof values.provider === 'string' ? values.provider : ''; + } + if ('baseUrl' in values) { + update.baseUrl = typeof values.baseUrl === 'string' ? values.baseUrl : ''; + } + if ('model' in values) { + update.model = typeof values.model === 'string' ? values.model : ''; + } + if ('modelFamily' in values && typeof values.modelFamily === 'string') { + update.modelFamily = values.modelFamily as ImageModelFamily; + } + if ('apiVersion' in values) { + update.apiVersion = + typeof values.apiVersion === 'string' ? values.apiVersion : ''; + } + if ('quality' in values && typeof values.quality === 'string') { + update.quality = values.quality as 'low' | 'medium' | 'high' | 'auto'; + } + if ('apiKey' in values) { + update.apiKey = typeof values.apiKey === 'string' ? values.apiKey : null; + } + const parsed = llmImageConfigUpdateSchema.safeParse(update); + if (!parsed.success) { + throw new CapabilityServiceError( + 'invalid_capability_config', + parsed.error.issues[0]?.message ?? 'Invalid image configuration', + ); + } + await setImageConfig(parsed.data); + }, + resolve() { + const resolved = getAzureImageConfig(); + return { + provider: 'azure-openai', + baseUrl: resolved.endpoint, + model: resolved.deployment, + modelFamily: resolved.modelFamily, + apiVersion: resolved.apiVersion, + quality: + resolved.quality ?? + getImageCapabilities(resolved.modelFamily).defaultQuality, + apiKey: resolved.apiKey, + }; + }, +}; + +function secretAdapter(options: { + read: () => string | undefined; + update: (value: string | null) => Promise; +}): CapabilityStorageAdapter { + return { + read() { + const configured = Boolean(options.read()); + return { + values: { apiKey: null }, + configuredFields: configured ? ['apiKey'] : [], + }; + }, + async update(values) { + if (!('apiKey' in values)) return; + await options.update( + typeof values.apiKey === 'string' ? values.apiKey : null, + ); + }, + resolve() { + return { apiKey: options.read() ?? '' }; + }, + }; +} + +const inkOcrAdapter: CapabilityStorageAdapter = { + read() { + const config = getInkOcrConfig(); + return { + values: { endpoint: config.endpoint ?? '', apiKey: null }, + configuredFields: [ + ...(config.endpoint ? ['endpoint'] : []), + ...(config.keySource !== 'none' ? ['apiKey'] : []), + ], + }; + }, + async update(values) { + const update = { + ...('endpoint' in values + ? { + endpoint: + typeof values.endpoint === 'string' && values.endpoint.trim() + ? values.endpoint + : null, + } + : {}), + ...('apiKey' in values + ? { + apiKey: + typeof values.apiKey === 'string' && values.apiKey.trim() + ? values.apiKey + : null, + } + : {}), + }; + const parsed = inkOcrConfigUpdateSchema.safeParse(update); + if (!parsed.success) { + throw new CapabilityServiceError( + 'invalid_capability_config', + parsed.error.issues[0]?.message ?? 'Invalid Ink OCR configuration', + ); + } + await setInkOcrConfig(parsed.data); + }, + resolve() { + const config = resolveInkOcrConfiguration(); + return { endpoint: config.endpoint ?? '', apiKey: config.key ?? '' }; + }, +}; + +const adapters = new Map([ + ['llm.imageConfig', imageAdapter], + [ + 'integration.tavily', + secretAdapter({ + read: getTavilyApiKey, + update: (apiKey) => setIntegrationsConfig({ tavilyApiKey: apiKey }), + }), + ], + [ + 'integration.rapidapi', + secretAdapter({ + read: getRapidApiKey, + update: (apiKey) => setIntegrationsConfig({ rapidApiKey: apiKey }), + }), + ], + ['integration.azureVisionInkOcr', inkOcrAdapter], +]); + +function adapterFor(manifest: CapabilityManifest): CapabilityStorageAdapter { + const adapter = adapters.get(manifest.storage.namespace); + if (!adapter) { + throw new Error( + `Unknown Capability storage namespace: ${manifest.storage.namespace}`, + ); + } + return adapter; +} + +function isConfigured( + manifest: CapabilityManifest, + configuredFields: readonly string[], +): boolean { + const configured = new Set(configuredFields); + return manifest.configuration + .filter((field) => field.required) + .every((field) => configured.has(field.id)); +} + +function validateUpdate( + manifest: CapabilityManifest, + values: Readonly>, +): void { + const fields = new Map( + manifest.configuration.map((field) => [field.id, field]), + ); + for (const [id, value] of Object.entries(values)) { + const field = fields.get(id); + if (!field) { + throw new CapabilityServiceError( + 'invalid_capability_config', + `Unknown configuration field: ${id}`, + ); + } + if (value === null) continue; + if (field.type === 'boolean') { + if (typeof value !== 'boolean') { + throw new CapabilityServiceError( + 'invalid_capability_config', + `${field.label} must be a boolean`, + ); + } + continue; + } + if (typeof value !== 'string') { + throw new CapabilityServiceError( + 'invalid_capability_config', + `${field.label} must be text`, + ); + } + if (field.type === 'url' && value) { + try { + const url = new URL(value); + if (url.protocol !== 'https:') throw new Error(); + } catch { + throw new CapabilityServiceError( + 'invalid_capability_config', + `${field.label} must be an HTTPS URL`, + ); + } + } + if ( + field.type === 'enum' && + value && + !field.options?.some((option) => option.value === value) + ) { + throw new CapabilityServiceError( + 'invalid_capability_config', + `Invalid ${field.label}`, + ); + } + } +} + +export class CapabilityProvisionService { + constructor( + private readonly manifests: ReadonlyMap, + ) {} + + private manifest(capabilityId: string): CapabilityManifest { + const manifest = this.manifests.get(capabilityId); + if (!manifest) { + throw new CapabilityServiceError( + 'capability_not_found', + `Unknown Capability: ${capabilityId}`, + ); + } + return manifest; + } + + list(): CapabilitySummary[] { + return [...this.manifests.values()].map((manifest) => { + const snapshot = adapterFor(manifest).read(); + const configured = isConfigured(manifest, snapshot.configuredFields); + return { + id: manifest.id, + version: manifest.version, + name: manifest.name, + description: manifest.description, + configured, + availableToInternalAgent: configured && manifest.consumers.internal, + availableToPipeline: configured && manifest.consumers.pipeline, + availableToExternalAgent: configured && manifest.consumers.external, + }; + }); + } + + getConfig(capabilityId: string): CapabilityConfig { + const manifest = this.manifest(capabilityId); + const snapshot = adapterFor(manifest).read(); + return { + manifest, + values: snapshot.values, + configuredFields: snapshot.configuredFields, + configured: isConfigured(manifest, snapshot.configuredFields), + }; + } + + async updateConfig( + capabilityId: string, + values: Readonly>, + ): Promise { + const manifest = this.manifest(capabilityId); + validateUpdate(manifest, values); + await adapterFor(manifest).update(values); + return this.getConfig(capabilityId); + } + + resolveForServer(capabilityId: string): Record { + const manifest = this.manifest(capabilityId); + const adapter = adapterFor(manifest); + const snapshot = adapter.read(); + if (!isConfigured(manifest, snapshot.configuredFields)) { + throw new CapabilityServiceError( + 'capability_not_configured', + `Capability "${capabilityId}" is not configured`, + ); + } + return adapter.resolve(); + } + + lease(capabilityId: string): CapabilityLease { + const manifest = this.manifest(capabilityId); + if (!manifest.consumers.external) { + throw new CapabilityServiceError( + 'capability_not_external', + `Capability "${capabilityId}" is not available to External Agents`, + ); + } + return { + id: manifest.id, + version: manifest.version, + config: this.resolveForServer(capabilityId), + ...(manifest.agent?.client ? { client: manifest.agent.client } : {}), + }; + } +} diff --git a/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts b/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts index f37fecd31..a985815d6 100644 --- a/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts +++ b/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts @@ -3,12 +3,19 @@ import { extractYoutubeVideoId } from './youtube-id.js'; import { getLogger } from '../../../utils/logger.js'; -import { getRapidApiKey } from '../../integrations/integrations.js'; +import { capabilityProvisionService } from '../../capabilities/index.js'; import type { IDocumentLoader, LoadResult } from './loader.interface.js'; const log = getLogger('preprocessing.youtube'); +function resolveRapidApiKey(): string { + const resolved = capabilityProvisionService.resolveForServer( + 'youtube-transcripts', + ); + return typeof resolved.apiKey === 'string' ? resolved.apiKey : ''; +} + export interface YoutubeTranscriptItem { startMs: string; endMs: string; @@ -103,12 +110,7 @@ export class YoutubeLoader implements IDocumentLoader { transcript: YoutubeTranscriptItem[]; transcript_text?: string; }> { - const apiKey = getRapidApiKey(); - if (!apiKey) { - throw new Error( - 'Missing RapidAPI key. Add it in Settings → Integrations (or set RAPIDAPI_KEY).', - ); - } + const apiKey = resolveRapidApiKey(); const response = await fetch( `https://yt-api.p.rapidapi.com/get_transcript?id=${videoId}`, @@ -146,12 +148,7 @@ export class YoutubeLoader implements IDocumentLoader { private async fetchVideoInfo( videoId: string, ): Promise { - const apiKey = getRapidApiKey(); - if (!apiKey) { - throw new Error( - 'Missing RapidAPI key. Add it in Settings → Integrations (or set RAPIDAPI_KEY).', - ); - } + const apiKey = resolveRapidApiKey(); const abortController = new AbortController(); const timeoutMs = 15000; diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index 315925bf1..11139c328 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -35,6 +35,11 @@ const agentMocks = vi.hoisted(() => ({ handleRun: vi.fn(), })); +const capabilityMocks = vi.hoisted(() => ({ + lease: vi.fn(), + list: vi.fn(), +})); + vi.mock('../agent/agent.service.js', () => ({ runAgent: agentMocks.runAgent, })); @@ -47,6 +52,14 @@ vi.mock('../agent/agenetes/drivers.js', () => ({ }, })); +vi.mock('../capabilities/index.js', async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + capabilityProvisionService: capabilityMocks, + }; +}); + import rfsRoutes from './rfs.route.js'; import { toSafeFilename } from '../../utils/naming.js'; import { agentNodeService } from '../agent/agent-node.service.js'; @@ -56,6 +69,7 @@ import { agentThreadService, } from '../agent/agent-thread.service.js'; import * as selectableProfiles from '../agent/selectable-agent-profile.js'; +import { CapabilityServiceError } from '../capabilities/index.js'; import { getCanvasStore, resetStorageCache, space } from '../storage/index.js'; import { RunCompletionError, @@ -66,6 +80,7 @@ import { taskService } from '../task/task.service.js'; import { setWorkspacePath } from '../workspace.js'; import type { FixedAgentNodeTarget } from '../agent/agent-thread-resolver.js'; +import type * as CapabilityModule from '../capabilities/index.js'; import type { CanvasNodeId } from '@huabu/shared'; /** @@ -172,6 +187,8 @@ beforeEach(() => { agentMocks.record.mockReset(); agentMocks.get.mockReset(); agentMocks.handleRun.mockReset(); + capabilityMocks.lease.mockReset(); + capabilityMocks.list.mockReset(); agentMocks.runAgent.mockImplementation(async function* () { yield { type: 'done', data: { message: 'first answer' } }; return []; @@ -199,6 +216,8 @@ describe('GET /api/rfs/:canvasId/skill', () => { ); } expect(res.body).toContain('/capabilities/commands/$COMMAND'); + expect(res.body).toContain('AGENTLET_CAPABILITY_SDK_URL'); + expect(res.body).toContain('/capability-packages'); expect(res.body).toContain('$HUABU_RFS_URL/skill/tasks'); expect(res.body).toContain('**parent-local**'); expect(res.body).toContain('read-only `absolutePosition`'); @@ -575,6 +594,127 @@ describe('Task RFS adapters', () => { }); }); +describe('provider Capability Packages', () => { + it('publishes discovery and package files without configuration secrets', async () => { + capabilityMocks.list.mockReturnValue([ + { + id: 'image-gen', + version: '1.0.0', + name: 'Image Generation', + description: 'Generate images.', + configured: true, + availableToInternalAgent: true, + availableToPipeline: false, + availableToExternalAgent: true, + }, + ]); + const app = await buildApp(); + try { + const discovery = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages', + }); + const manifest = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages/image-gen/manifest', + }); + const skill = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages/image-gen/skill', + }); + const client = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages/image-gen/client', + }); + + expect(discovery.statusCode).toBe(200); + expect(discovery.json()).toMatchObject({ + capabilities: [{ id: 'image-gen', configured: true }], + }); + expect(manifest.statusCode).toBe(200); + expect(manifest.json()).toMatchObject({ + id: 'image-gen', + storage: { namespace: 'llm.imageConfig' }, + }); + expect(skill.statusCode).toBe(200); + expect(skill.headers['content-type']).toMatch(/text\/markdown/); + expect(client.statusCode).toBe(200); + expect(client.headers['content-type']).toMatch(/text\/javascript/); + expect(client.headers['cache-control']).toBe('public, max-age=300'); + + for (const response of [discovery, manifest, skill]) { + expect(response.body).not.toContain('test-secret'); + expect(response.body).not.toContain('api-key'); + } + } finally { + await app.close(); + } + }); + + it('rejects Package files that are absent or use invalid ids', async () => { + const app = await buildApp(); + try { + const noSkill = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages/ink-ocr/skill', + }); + const noClient = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages/youtube-transcripts/client', + }); + const invalid = await app.inject({ + method: 'GET', + url: '/rfs/c1/capability-packages/INVALID/manifest', + }); + + expect(noSkill.statusCode).toBe(404); + expect(noSkill.json()).toMatchObject({ code: 'skill_not_found' }); + expect(noClient.statusCode).toBe(404); + expect(noClient.json()).toMatchObject({ code: 'client_not_found' }); + expect(invalid.statusCode).toBe(400); + } finally { + await app.close(); + } + }); + + it('returns a no-store lease and maps provisioning failures', async () => { + capabilityMocks.lease.mockReturnValueOnce({ + capabilityId: 'image-gen', + config: { apiKey: 'test-secret' }, + }); + const app = await buildApp(); + try { + const lease = await app.inject({ + method: 'POST', + url: '/rfs/c1/capability-packages/image-gen/lease', + }); + expect(lease.statusCode).toBe(200); + expect(lease.headers['cache-control']).toBe('no-store'); + expect(lease.json()).toMatchObject({ + capabilityId: 'image-gen', + config: { apiKey: 'test-secret' }, + }); + + capabilityMocks.lease.mockImplementationOnce(() => { + throw new CapabilityServiceError( + 'capability_not_external', + 'Capability is not available to External Agents', + ); + }); + const rejected = await app.inject({ + method: 'POST', + url: '/rfs/c1/capability-packages/ink-ocr/lease', + }); + expect(rejected.statusCode).toBe(403); + expect(rejected.json()).toMatchObject({ + code: 'capability_not_external', + }); + } finally { + await app.close(); + } + }); +}); + describe('direct Space query discovery', () => { it('publishes bounded operation capabilities and generated schemas', async () => { const app = await buildApp(); diff --git a/apps/server/src/modules/remote_fs/rfs.route.ts b/apps/server/src/modules/remote_fs/rfs.route.ts index 5a4a43103..308010a79 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.ts @@ -44,6 +44,7 @@ import { createTaskRequestSchema, completeTaskRunRequestSchema, createInteractiveViewRequestSchema, + capabilityParamsSchema, interactiveViewLookupQuerySchema, interactiveViewResourceParamsSchema, rfsAgentCreateHeadersSchema, @@ -69,6 +70,7 @@ import { type RfsUploadResponse, type AgentStreamEvent, type StartTaskRunResponse, + type CapabilityParams, } from '@huabu/shared'; import { mimeForPath } from './mime.js'; @@ -116,6 +118,12 @@ import { import { CanvasNotFoundError } from '../canvas/canvas-executor.js'; import { executeSpaceQuery, SpaceQueryError } from '../canvas/space-query.js'; import { WorldPreviewMutationError } from '../canvas/world-preview-policy.js'; +import { + capabilityProvisionService, + CapabilityServiceError, + getBundledCapabilityPackage, + readCapabilityPackageFile, +} from '../capabilities/index.js'; import { InteractiveViewServiceError, interactiveViewService, @@ -523,6 +531,118 @@ const rfsRoutes: FastifyPluginAsync = async (app) => { reply.send(getRfsCapabilities()), ); + // ── Capability Packages ── + // + // `/capabilities` already owns direct Space-operation discovery. Keep the + // portable provider packages under a separate unambiguous resource root. + app.get('/:canvasId/capability-packages', async (_request, reply) => + reply.send({ capabilities: capabilityProvisionService.list() }), + ); + + app.get<{ + Params: CapabilityParams & { canvasId: string }; + }>( + '/:canvasId/capability-packages/:capabilityId/manifest', + async (request, reply) => { + const parsed = capabilityParamsSchema.safeParse({ + capabilityId: request.params.capabilityId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Capability id')); + } + const capability = getBundledCapabilityPackage(parsed.data.capabilityId); + if (!capability) { + return reply + .code(404) + .send(rfsError('Capability not found', 'capability_not_found')); + } + return reply.send(capability.manifest); + }, + ); + + app.get<{ + Params: CapabilityParams & { canvasId: string }; + }>( + '/:canvasId/capability-packages/:capabilityId/skill', + async (request, reply) => { + const parsed = capabilityParamsSchema.safeParse({ + capabilityId: request.params.capabilityId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Capability id')); + } + const capability = getBundledCapabilityPackage(parsed.data.capabilityId); + const skill = capability?.manifest.agent?.skill; + const content = skill + ? readCapabilityPackageFile(parsed.data.capabilityId, skill) + : null; + if (!content) { + return reply + .code(404) + .send(rfsError('Capability Skill not found', 'skill_not_found')); + } + return reply.type('text/markdown; charset=utf-8').send(content); + }, + ); + + app.get<{ + Params: CapabilityParams & { canvasId: string }; + }>( + '/:canvasId/capability-packages/:capabilityId/client', + async (request, reply) => { + const parsed = capabilityParamsSchema.safeParse({ + capabilityId: request.params.capabilityId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Capability id')); + } + const capability = getBundledCapabilityPackage(parsed.data.capabilityId); + const client = capability?.manifest.agent?.client; + const content = client + ? readCapabilityPackageFile(parsed.data.capabilityId, client) + : null; + if (!content) { + return reply + .code(404) + .send(rfsError('Capability client not found', 'client_not_found')); + } + return reply + .header('Cache-Control', 'public, max-age=300') + .type('text/javascript; charset=utf-8') + .send(content); + }, + ); + + app.post<{ + Params: CapabilityParams & { canvasId: string }; + }>( + '/:canvasId/capability-packages/:capabilityId/lease', + async (request, reply) => { + const parsed = capabilityParamsSchema.safeParse({ + capabilityId: request.params.capabilityId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Capability id')); + } + try { + return reply + .header('Cache-Control', 'no-store') + .send(capabilityProvisionService.lease(parsed.data.capabilityId)); + } catch (error) { + if (error instanceof CapabilityServiceError) { + const status = + error.code === 'capability_not_found' + ? 404 + : error.code === 'capability_not_external' + ? 403 + : 409; + return reply.code(status).send(rfsError(error.message, error.code)); + } + throw error; + } + }, + ); + app.get<{ Params: { canvasId: string; type: string } }>( '/:canvasId/capabilities/queries/:type', async (request, reply) => { diff --git a/apps/server/src/prompt/external-agent/access-huabu.md b/apps/server/src/prompt/external-agent/access-huabu.md index 482028b28..c0a0266ad 100644 --- a/apps/server/src/prompt/external-agent/access-huabu.md +++ b/apps/server/src/prompt/external-agent/access-huabu.md @@ -6,6 +6,7 @@ These environment variables are already set: - `HUABU_RFS_URL` — the base URL for this Space, with no trailing slash. - `AGENTLET_TOKEN` — the RFS bearer credential. +- `AGENTLET_CAPABILITY_SDK_URL` — the daemon-owned `file://` URL for loading configured provider Capabilities. - `HUABU_THREAD_ID` — your conversation ID. Pass it on `execute` (see §6) to attribute your edits. Prefer deterministic direct operations: @@ -16,6 +17,7 @@ Prefer deterministic direct operations: 4. Use the `SNAPSHOT_NODES` query to render image, sketch, or frame nodes into PNG artifacts you can inspect. 5. Use `execute` for validated Space commands. 6. Use `agent` only when you deliberately want the optional internal Huabu agent to interpret an open-ended request. +7. Discover configured provider services through `capability-packages` and follow the selected Package Skill before loading it through the Agentlet SDK. ## 1. Discover operations @@ -279,6 +281,35 @@ For available Profile discovery, launch configuration, create-only requests, opt curl -fsS -H "$AUTH" "$HUABU_RFS_URL/skill/agents" ``` +## Provider Capability Packages + +List the bundled provider services that Huabu can provision: + +```bash +curl -fsS -H "$AUTH" "$HUABU_RFS_URL/capability-packages" +``` + +Before using one, fetch and follow its Skill: + +```bash +curl -fsS -H "$AUTH" "$HUABU_RFS_URL/capability-packages/image-gen/skill" +``` + +Agent-facing packages can then be loaded from a short-lived `.mjs` script: + +```js +const { withCapability } = await import( + process.env.AGENTLET_CAPABILITY_SDK_URL +); + +await withCapability('image-gen', async ({ client }) => { + if (!client) throw new Error('Capability client is unavailable'); + console.log(await client.generate({ prompt: 'A watercolor landscape' })); +}); +``` + +The SDK obtains current configuration on demand. Never print, persist, or forward returned credentials. A package without an Agent Skill/client is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. + ## Advanced workflows Load these authenticated guides only when the request needs them: diff --git a/apps/server/tsup.config.ts b/apps/server/tsup.config.ts index 0e712f7e8..de07bfd94 100644 --- a/apps/server/tsup.config.ts +++ b/apps/server/tsup.config.ts @@ -80,6 +80,10 @@ export default defineConfig([ const dst = path.resolve('dist-bundle/prompt'); cpSync(src, dst, { recursive: true }); console.log(`[tsup] copied prompt templates -> ${dst}`); + const capabilitiesSrc = path.resolve('src/capabilities'); + const capabilitiesDst = path.resolve('dist-bundle/capabilities'); + cpSync(capabilitiesSrc, capabilitiesDst, { recursive: true }); + console.log(`[tsup] copied Capability packages -> ${capabilitiesDst}`); // @resvg/resvg-wasm — copied next to server.js so the // snapshot_nodes tool's bundle-layout fallback finds it via // bundled server module's file URL. @@ -108,6 +112,9 @@ export default defineConfig([ index: path.resolve( '../../external/agentlet/packages/local/src/index.ts', ), + 'capability-sdk/index': path.resolve( + '../../external/agentlet/packages/local/src/capability-sdk/index.ts', + ), }, format: ['esm'], outDir: 'dist-bundle/agentlet', diff --git a/apps/web/src/api/_routes.ts b/apps/web/src/api/_routes.ts index c5eb42722..3c354a999 100644 --- a/apps/web/src/api/_routes.ts +++ b/apps/web/src/api/_routes.ts @@ -45,6 +45,8 @@ export const routes = { // ── Integrations (third-party API keys) ────────────────────────── integrationsConfig: '/integrations/config', inkOcrConfig: '/integrations/ink-ocr/config', + capabilities: '/capabilities', + capability: (capabilityId: string) => `/capabilities/${enc(capabilityId)}`, // ── Canvas ──────────────────────────────────────────────────────── canvasList: '/canvas', diff --git a/apps/web/src/api/capabilities.ts b/apps/web/src/api/capabilities.ts new file mode 100644 index 000000000..330916713 --- /dev/null +++ b/apps/web/src/api/capabilities.ts @@ -0,0 +1,34 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { apiFetch } from './_client'; +import { routes } from './_routes'; + +import type { + CapabilityConfig, + CapabilityConfigUpdate, + CapabilityListResponse, +} from '@huabu/shared'; + +export function getCapabilities(): Promise { + return apiFetch(routes.capabilities, { + fallbackMessage: 'Failed to load Capabilities', + }); +} + +export function getCapability(id: string): Promise { + return apiFetch(routes.capability(id), { + fallbackMessage: 'Failed to load Capability configuration', + }); +} + +export function putCapability( + id: string, + update: CapabilityConfigUpdate, +): Promise { + return apiFetch(routes.capability(id), { + method: 'PUT', + json: update, + fallbackMessage: 'Failed to update Capability configuration', + }); +} diff --git a/apps/web/src/components/Settings/SettingsModal.test.tsx b/apps/web/src/components/Settings/SettingsModal.test.tsx index 236f7e074..a35b88f2f 100644 --- a/apps/web/src/components/Settings/SettingsModal.test.tsx +++ b/apps/web/src/components/Settings/SettingsModal.test.tsx @@ -80,14 +80,8 @@ vi.mock('./sections/GeneralSettings', () => ({ vi.mock('./sections/LLMSettings', () => ({ LLMSettings: () =>

, })); -vi.mock('./sections/ImageProviderSettings', () => ({ - ImageProviderSettings: () =>
, -})); -vi.mock('./sections/IntegrationsSettings', () => ({ - IntegrationsSettings: () =>
, -})); -vi.mock('./sections/InkOcrSettings', () => ({ - InkOcrSettings: () =>
, +vi.mock('./sections/CapabilitiesSettings', () => ({ + CapabilitiesSettings: () =>
, })); globalThis.IS_REACT_ACT_ENVIRONMENT = true; @@ -171,13 +165,7 @@ describe('Settings information architecture', () => { ?.classList.contains('space-y-4'), ).toBe(true); expect( - container.querySelector('[data-testid="image-settings"]'), - ).not.toBeNull(); - expect( - container.querySelector('[data-testid="integration-settings"]'), - ).not.toBeNull(); - expect( - container.querySelector('[data-testid="ocr-settings"]'), + container.querySelector('[data-testid="capabilities-settings"]'), ).not.toBeNull(); expect( container.querySelector('[data-testid="agent-defaults"]'), diff --git a/apps/web/src/components/Settings/SettingsModal.tsx b/apps/web/src/components/Settings/SettingsModal.tsx index 2de7e1d53..239007533 100644 --- a/apps/web/src/components/Settings/SettingsModal.tsx +++ b/apps/web/src/components/Settings/SettingsModal.tsx @@ -23,11 +23,9 @@ import { } from './agent-profiles/ExternalAgentsSettings'; import { DeploymentReadinessNotice } from './DeploymentReadinessNotice'; import { AgentBehaviorSettings } from './sections/AgentBehaviorSettings'; +import { CapabilitiesSettings } from './sections/CapabilitiesSettings'; import { ExternalAgentRuntimeSettings } from './sections/ExternalAgentRuntimeSettings'; import { GeneralSettings } from './sections/GeneralSettings'; -import { ImageProviderSettings } from './sections/ImageProviderSettings'; -import { InkOcrSettings } from './sections/InkOcrSettings'; -import { IntegrationsSettings } from './sections/IntegrationsSettings'; import { LLMSettings } from './sections/LLMSettings'; /** Identifiers for the settings tabs (left-nav order). */ @@ -55,9 +53,9 @@ interface SettingsModalProps { * `ShortcutsModal`) with a left-hand tab rail and a scrollable content * pane, so the panel height stays fixed as more settings are added. * - * Each tab renders the existing self-contained `*Settings` components: + * Each tab renders its owned Settings surface: * - **Agent** — Utility Agent, Built-In Pi setup, external Profiles, and behavior - * - **Capabilities** — Huabu-owned image, search, transcript, and OCR services + * - **Capabilities** — manifest-driven image, search, transcript, and OCR services * - **General** — application, canvas, input, and update preferences * * The app version sits at the bottom of the left tab rail (a product-wide @@ -313,9 +311,7 @@ export const SettingsModal: React.FC = ({ className="space-y-4 [&_section]:mb-0" data-testid="capability-sections" > - - - +
)} diff --git a/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx b/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx new file mode 100644 index 000000000..0e68db365 --- /dev/null +++ b/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx @@ -0,0 +1,107 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { act } from 'react'; +import { createRoot, type Root } from 'react-dom/client'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { CapabilitiesSettings } from './CapabilitiesSettings'; + +import type { CapabilityConfig } from '@huabu/shared'; + +const mocks = vi.hoisted(() => ({ + getCapabilities: vi.fn(), + getCapability: vi.fn(), +})); + +vi.mock('@/api/capabilities', () => ({ + getCapabilities: mocks.getCapabilities, + getCapability: mocks.getCapability, + putCapability: vi.fn(), +})); + +vi.mock('@/store/deploymentReadinessStore', () => ({ + useDeploymentReadinessStore: ( + selector: (state: { + readiness: { credentials: { writable: boolean } }; + }) => unknown, + ) => selector({ readiness: { credentials: { writable: true } } }), +})); + +globalThis.IS_REACT_ACT_ENVIRONMENT = true; + +const ids = [ + 'image-gen', + 'web-search', + 'youtube-transcripts', + 'ink-ocr', +] as const; + +function config(id: (typeof ids)[number]): CapabilityConfig { + return { + manifest: { + schema: 'huabu-capability/v1', + id, + version: '1.0.0', + name: id, + description: `${id} description`, + storage: { namespace: `integration.${id}` }, + consumers: { internal: false, pipeline: true, external: false }, + configuration: [ + { + id: 'apiKey', + label: 'API key', + type: 'secret', + required: true, + }, + ], + }, + values: { apiKey: null }, + configuredFields: [], + configured: false, + }; +} + +let root: Root; +let container: HTMLDivElement; + +beforeEach(() => { + container = document.createElement('div'); + document.body.appendChild(container); + root = createRoot(container); + mocks.getCapabilities.mockResolvedValue({ + capabilities: ids.map((id) => ({ + id, + version: '1.0.0', + name: id, + description: id, + configured: false, + availableToInternalAgent: false, + availableToPipeline: true, + availableToExternalAgent: false, + })), + }); + mocks.getCapability.mockImplementation(async (id: (typeof ids)[number]) => + config(id), + ); +}); + +afterEach(() => { + act(() => root.unmount()); + container.remove(); + vi.clearAllMocks(); +}); + +describe('CapabilitiesSettings', () => { + it('renders every current Capability from server manifests', async () => { + await act(async () => { + root.render(); + }); + + expect(mocks.getCapability).toHaveBeenCalledTimes(4); + for (const id of ids) { + expect(container.textContent).toContain(id); + } + expect(container.textContent).toContain('Not configured'); + }); +}); diff --git a/apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx b/apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx new file mode 100644 index 000000000..4262fe0a8 --- /dev/null +++ b/apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx @@ -0,0 +1,320 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { ChevronDown, Key, Trash2 } from 'lucide-react'; +import { useEffect, useMemo, useState } from 'react'; + +import { + getCapabilities, + getCapability, + putCapability, +} from '@/api/capabilities'; +import { Button } from '@/components/Common/Button'; +import { Select } from '@/components/Common/Select'; +import { TextInput } from '@/components/Common/TextInput'; +import { toast } from '@/components/Common/Toast'; +import { SettingControl } from '@/components/Settings/Common/SettingControl'; +import { SettingRow } from '@/components/Settings/Common/SettingRow'; +import { SettingSection } from '@/components/Settings/Common/SettingSection'; +import { useDeploymentReadinessStore } from '@/store/deploymentReadinessStore'; + +import type { + CapabilityConfig, + CapabilityConfigurationField, + CapabilityFieldValue, +} from '@huabu/shared'; + +function CapabilityField({ + field, + value, + configured, + disabled, + onChange, + onRemove, +}: { + field: CapabilityConfigurationField; + value: CapabilityFieldValue | undefined; + configured: boolean; + disabled: boolean; + onChange: (value: CapabilityFieldValue) => void; + onRemove: () => void; +}) { + if (field.type === 'enum') { + return ( + onChange(event.target.checked)} + aria-label={field.label} + disabled={disabled} + /> + ); + } + + const secret = field.type === 'secret'; + return ( +
+ onChange(event.target.value)} + placeholder={ + secret && configured ? 'Configured' : (field.placeholder ?? '') + } + aria-label={field.label} + autoComplete="off" + disabled={disabled} + className="w-full" + wrapperClassName="min-w-0 flex-1" + /> + {secret && configured ? ( + <> + + + + ) : null} +
+ ); +} + +function CapabilityForm({ + initial, + writesDisabled, +}: { + initial: CapabilityConfig; + writesDisabled: boolean; +}) { + const [config, setConfig] = useState(initial); + const [expanded, setExpanded] = useState(false); + const [draft, setDraft] = useState>( + initial.values, + ); + const [dirty, setDirty] = useState>(new Set()); + const [saving, setSaving] = useState(false); + + const configured = useMemo( + () => new Set(config.configuredFields), + [config.configuredFields], + ); + const writableDirty = useMemo( + () => + [...dirty].some((id) => { + const field = config.manifest.configuration.find( + (candidate) => candidate.id === id, + ); + return !( + writesDisabled && + (field?.type === 'secret' || + config.manifest.storage.namespace === + 'integration.azureVisionInkOcr') + ); + }), + [config.manifest, dirty, writesDisabled], + ); + + function change(id: string, value: CapabilityFieldValue) { + setDraft((current) => ({ ...current, [id]: value })); + setDirty((current) => new Set(current).add(id)); + } + + async function update(values: Record) { + setSaving(true); + try { + const next = await putCapability(config.manifest.id, { values }); + setConfig(next); + setDraft(next.values); + setDirty(new Set()); + } catch (error) { + toast(error instanceof Error ? error.message : 'Unable to save', { + tone: 'danger', + }); + } finally { + setSaving(false); + } + } + + function save() { + const values = Object.fromEntries( + [...dirty].flatMap((id) => { + const value = draft[id]; + if ( + config.manifest.configuration.find((field) => field.id === id) + ?.type === 'secret' && + value === '' + ) { + return []; + } + return [[id, value ?? null]]; + }), + ); + if (Object.keys(values).length > 0) void update(values); + } + + return ( + + +
+ + {config.configured ? 'Configured' : 'Not configured'} + + +
+ + {expanded ? ( + <> + {config.manifest.configuration.map((field) => ( + + + change(field.id, value)} + onRemove={() => void update({ [field.id]: null })} + /> + + + ))} + + + + + + + + ) : null} + + ); +} + +export function CapabilitiesSettings() { + const [configs, setConfigs] = useState([]); + const [error, setError] = useState(null); + const writesDisabled = useDeploymentReadinessStore( + (state) => state.readiness?.credentials.writable === false, + ); + + useEffect(() => { + let cancelled = false; + void getCapabilities() + .then(({ capabilities }) => + Promise.all(capabilities.map(({ id }) => getCapability(id))), + ) + .then((next) => { + if (!cancelled) setConfigs(next); + }) + .catch((cause) => { + if (!cancelled) { + setError( + cause instanceof Error + ? cause.message + : 'Failed to load Capabilities', + ); + } + }); + return () => { + cancelled = true; + }; + }, []); + + if (error) { + return ( +

+ {error} +

+ ); + } + if (configs.length === 0) { + return ( +

+ Loading Capabilities... +

+ ); + } + return configs.map((config) => ( + + )); +} diff --git a/docs/README.md b/docs/README.md index 9cd08d1ac..42f253e12 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,6 +54,7 @@ docs/ | [canvas-input-interactions.md](./architecture/canvas-input-interactions.md) | Mouse, touch, and pen preference resolution, gesture ownership, and multi-touch arbitration. | | [canvas-zoom-rendering.md](./architecture/canvas-zoom-rendering.md) | Node LOD, Frame/edge label readability, and interaction chrome across canvas zoom. | | [canvas-storage.md](./architecture/canvas-storage.md) | Disk layout plus Blob/structured ports, catalogue, compatibility, and `.memory/`. | +| [capability-packages.md](./architecture/capability-packages.md) | Manifest-driven provider configuration, storage bindings, consumers, RFS leases, and Agentlet SDK. | | [canary-deployment.md](./architecture/canary-deployment.md) | Personal Alpha Canary status, owner-triggered redeployment, and explicit reliability limits. | | [canvas-action-log.md](./architecture/canvas-action-log.md) | Persistent `events.jsonl` user-action trail; consumed by the memory curator. | | [canvas-realtime-sync.md](./architecture/canvas-realtime-sync.md) | Multi-agent real-time sync: SSE broadcast, dirty-node conflict model, per-thread change-review card. | @@ -89,6 +90,7 @@ docs/ | [canvas-realtime-sync-plan.md](./proposals/canvas-realtime-sync-plan.md) | In-Progress | Roadmap from multi-agent sync to multi-user co-editing. | | [content-before-ai-design.md](./proposals/content-before-ai-design.md) | Needs review | Block-level and inline authorship provenance. | | [credential-storage-hardening-followups.md](./proposals/credential-storage-hardening-followups.md) | Draft | Follow-up credential storage hardening. | +| [capability-packages.md](./proposals/capability-packages.md) | Accepted | #110 portable Capability Packages and zero-migration configuration bindings. | | [direct-space-operations.md](./proposals/direct-space-operations.md) | In-Progress | #348 deterministic RFS query and mutation operations for external agents. | | [external-agent-capability-cache-and-realization.md](./proposals/external-agent-capability-cache-and-realization.md) | Accepted | #160/#162 GET-only capability discovery and canonical first-interaction realization. | | [headless-executor-plan.md](./proposals/headless-executor-plan.md) | Partly shipped | Server-side headless canvas executor and structure/content sync. | diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 7888e12d3..963da4a8f 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -22,24 +22,27 @@ The shipped design record is [`agent-reachback-rfs.md`](../proposals/agent-reach All endpoints are mounted under `/api/rfs/:canvasId`; `HUABU_RFS_URL` already contains that canvas-scoped base. -| Endpoint | Responsibility | -| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `GET /skill` | Return the public bundled root guide; authenticated requests resolve the current root guide and append live Skill Frames. | -| `GET /skill/:skillId` | Return an authenticated advanced guide: `layout`, `tasks`, or `agents`. | -| `GET /download/` | Stream a known node, artifact, or staged-upload file. | -| `POST /upload/` | Stage bytes in the canvas `.upload/` directory without creating a node. | -| `DELETE /upload/` | Remove one exact staged upload. | -| `POST /agent` | Create a visible Agent Node and optionally start its first turn. | -| `POST /agent/:threadId/prompt` | Submit a turn to an existing Agent conversation over SSE. | -| `POST /agent/:threadId/ink-intent` | Submit a validated report for the matching active external Ink turn. | -| `GET /agent/profiles` | Return available Agent Profile IDs and aliases, marking the first selectable external fallback with `default: true` when available. | -| `POST /task/create` | Create a durable Task and its static Task Note. | -| `POST /task/:taskId/run/create` | Create a Run, its visible root Agent Node, and start the first turn. | -| `GET /capabilities` | Report the direct-operation protocol, limits, semantics, and supported operation types. | -| `GET /capabilities/queries/:type` | Return one query's generated JSON Schema, constraints, result description, and examples. | -| `GET /capabilities/commands/:type` | Return one command's generated JSON Schema, constraints, result description, and examples. | -| `POST /query` | Validate and execute one bounded `SpaceQuery`, returning a query-discriminated JSON result. | -| `POST /execute` | Validate and execute an ordered batch of agent-allowed `CanvasCommand` variants. | +| Endpoint | Responsibility | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `GET /skill` | Return the public bundled root guide; authenticated requests resolve the current root guide and append live Skill Frames. | +| `GET /skill/:skillId` | Return an authenticated advanced guide: `layout`, `tasks`, or `agents`. | +| `GET /download/` | Stream a known node, artifact, or staged-upload file. | +| `POST /upload/` | Stage bytes in the canvas `.upload/` directory without creating a node. | +| `DELETE /upload/` | Remove one exact staged upload. | +| `POST /agent` | Create a visible Agent Node and optionally start its first turn. | +| `POST /agent/:threadId/prompt` | Submit a turn to an existing Agent conversation over SSE. | +| `POST /agent/:threadId/ink-intent` | Submit a validated report for the matching active external Ink turn. | +| `GET /agent/profiles` | Return available Agent Profile IDs and aliases, marking the first selectable external fallback with `default: true` when available. | +| `POST /task/create` | Create a durable Task and its static Task Note. | +| `POST /task/:taskId/run/create` | Create a Run, its visible root Agent Node, and start the first turn. | +| `GET /capabilities` | Report the direct-operation protocol, limits, semantics, and supported operation types. | +| `GET /capabilities/queries/:type` | Return one query's generated JSON Schema, constraints, result description, and examples. | +| `GET /capabilities/commands/:type` | Return one command's generated JSON Schema, constraints, result description, and examples. | +| `GET /capability-packages` | List bundled provider Capability Packages and masked availability. | +| `GET /capability-packages/:id/*` | Return one Package's Manifest, Skill, or client source. | +| `POST /capability-packages/:id/lease` | Return the declared effective configuration for one configured External Package with `Cache-Control: no-store`. | +| `POST /query` | Validate and execute one bounded `SpaceQuery`, returning a query-discriminated JSON result. | +| `POST /execute` | Validate and execute an ordered batch of agent-allowed `CanvasCommand` variants. | There is no directory-listing endpoint. External agents receive exact node paths in selected-node context or ask the internal agent to discover relevant files. @@ -99,6 +102,8 @@ Parent lineage is best effort. The route resolves `parentThreadId` or `X-Huabu-H Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/`; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists the bootstrap as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. The preamble owns the authentication contract and curl header setup because every external Agent needs them before loading any Skill. The public basic guide is loaded without credentials from `GET /skill`; repeating that request with authentication adds the current root override and live Space Skill Frames. Advanced layout, Task, recursive-Agent, and Interactive View procedures are loaded on demand from authenticated `GET /skill/layout`, `/skill/tasks`, `/skill/agents`, and `/skill/interactive-views`. +Agentlet additionally injects its daemon-owned `AGENTLET_CAPABILITY_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/capability-sdk`. Session or Profile environment cannot override this value. The SDK wraps `/capability-packages` discovery, lease, and trusted client loading; provider credentials remain absent from startup environment and are resolved on demand. + Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. The guide is direct-first: an external agent can discover, query, download, snapshot, upload, execute, and verify without creating another Agent. `POST /agent` remains an optional high-level interpretation and delegation path. diff --git a/docs/architecture/api-design.md b/docs/architecture/api-design.md index 0c81b68ee..c288f95e1 100644 --- a/docs/architecture/api-design.md +++ b/docs/architecture/api-design.md @@ -160,6 +160,12 @@ Malformed request fields and malformed cursors return HTTP 400 with `code: "malf `POST /api/rfs/:canvasId/query` with `type: "INSPECT_NODES"` uses the canonical response contract in [`space-operations.ts`](../../packages/shared/src/types/api/space-operations.ts). Each Question Node result includes its non-empty persisted `threadId` when associated; non-Question Nodes and unbound Questions omit the field. The mapping is scoped by the authenticated RFS URL's Canvas and is read-only: inspection does not create a thread, workload, binding, realization, or invocation. Callers continue the mapped conversation through the existing `POST /api/rfs/:canvasId/agent/:threadId/prompt` SSE endpoint. +## Capability Packages + +`packages/shared/src/types/api/capability-package.ts` defines the strict manifest, Generic Settings update, masked configuration, summary, and External lease contracts. Owner Settings uses `GET /api/capabilities`, `GET /api/capabilities/:capabilityId`, and `PUT /api/capabilities/:capabilityId`; every path/body value is validated with the shared schemas before selecting a code-registered storage namespace. + +Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes provider packages under `/capability-packages`. Manifest, Skill, and client reads contain no credentials. `POST /capability-packages/:id/lease` rejects unknown, unconfigured, and non-External packages, returns only declared fields, and is non-cacheable. See [`capability-packages.md`](./capability-packages.md). + ## Anti-patterns | Don't | Do | diff --git a/docs/architecture/capability-packages.md b/docs/architecture/capability-packages.md new file mode 100644 index 000000000..91a632b14 --- /dev/null +++ b/docs/architecture/capability-packages.md @@ -0,0 +1,101 @@ +# Capability Packages + +> Current architecture for Huabu-managed provider capabilities. Last updated: 2026-10-09 + +## Scope + +Capability Packages make provider configuration declarative without forcing Internal Agent tools, product pipelines, and External Agents through one execution path. The package is the source of truth for Settings fields and Agent-facing files; reviewed Huabu code remains the source of truth for Server execution. + +The bundled packages live under `apps/server/src/capabilities//`: + +```text +/ +├── capability.yaml +├── SKILL.md # required only when External Agent-facing +└── client.mjs # required only for a direct Agent-side provider call +``` + +Phase 1 packages are trusted files shipped with Huabu. User upload, installation, remote registries, and Server execution of uploaded code are not supported. + +## Manifest contract + +`huabu-capability/v1` is defined by `capabilityManifestSchema` in `packages/shared/src/types/api/capability-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, and an External consumer without a Skill fail validation. + +Every package declares a stable ID and version, display metadata, one registered storage namespace, supported consumer classes, optional Agent files, and constrained configuration fields. Supported field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or client contract. + +The manifest cannot register Server tools, choose arbitrary persistence paths or SecretStore IDs, provide custom Settings components, or execute expressions. Agent files are forbidden when `consumers.external` is false, so a Server-only or Pipeline-only package cannot accidentally advertise placeholder Agent behavior. + +## Provision Service and storage bindings + +`CapabilityProvisionService` is the canonical access point for Generic Settings, Internal Agent tools, product pipelines, and External Agent leases. It validates field updates against the manifest, selects a code-registered namespace adapter, and exposes masked settings reads separately from trusted resolution. + +Namespace IDs are opaque adapter keys rather than object paths: + +| Package | Namespace | Existing authoritative owner | +| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------- | +| `image-gen` | `llm.imageConfig` | `llm-config.json` top-level `imageConfig` plus SecretStore `llm:image:api-key` | +| `web-search` | `integration.tavily` | SecretStore `integration:tavily:api-key` with `TAVILY_API_KEY` fallback | +| `youtube-transcripts` | `integration.rapidapi` | SecretStore `integration:rapidapi:api-key` with `RAPIDAPI_KEY` fallback | +| `ink-ocr` | `integration.azureVisionInkOcr` | Existing versioned Azure Vision record and its legacy/environment compatibility reads | + +This is a zero-persistent-data-migration compatibility layer. Reading Capability status performs no write; saving delegates to the original owner; no second record is created; credentials are not copied, rewritten, or re-encrypted. The original owner retains validation, defaults, environment fallback, atomicity, rollback, and explicit-null semantics. + +Masked Settings responses return `null` for secret values and identify configured fields separately. Trusted `resolveForServer()` and authenticated External leases resolve effective values, including environment fallbacks, only at the point of use. + +## Consumers + +Internal Agent tools keep their high-level Huabu integrations. `generate_image` still owns typed tool arguments, model capability validation, reference artifact reads, provider SDK behavior, image decoding, and artifact persistence; it obtains provider configuration through `resolveForServer('image-gen')`. + +Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Capability configuration but do not import package `client.mjs`. + +External Agent packages provide a real `SKILL.md` and, when direct provider execution is needed, a `client.mjs` exporting `createClient({ config })`. The bundled Image and Tavily packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore ship neither placeholder file. + +## Owner Settings API + +The owner UI uses: + +```text +GET /api/capabilities +GET /api/capabilities/:capabilityId +PUT /api/capabilities/:capabilityId +``` + +Wire schemas live in `packages/shared/src/types/api/capability-package.ts`. The Web app imports only their inferred types and renders `CapabilitiesSettings` from the returned manifests. Existing capability-specific endpoints remain compatible for non-migrated callers, but the Capabilities tab uses only the generic API. + +## External Agent RFS API + +The canvas-scoped RFS already reserves `/capabilities` for direct Space-operation discovery, so provider packages use the unambiguous `/capability-packages` resource: + +```text +GET /capability-packages +GET /capability-packages/:id/manifest +GET /capability-packages/:id/skill +GET /capability-packages/:id/client +POST /capability-packages/:id/lease +``` + +Manifest and Skill responses contain no credentials. Client source is a versioned bundled asset. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and non-External packages explicitly, returns only fields declared by the selected package, and uses `Cache-Control: no-store`. + +## Agentlet SDK + +Agentlet publishes `dist/capability-sdk/index.js`. The daemon computes its absolute `file://` URL relative to its own `import.meta.url` and injects it as the authoritative `AGENTLET_CAPABILITY_SDK_URL` after workload environment values, so a Profile or session cannot replace it. + +`loadCapability(id)` obtains a fresh lease and loads the trusted package client from Huabu without writing credentials to disk. `withCapability(id, callback)` is the convenience wrapper. The SDK reports bounded status-only request failures and does not include response bodies that could contain credentials. + +The SDK reduces accidental persistence but is not a sandbox. A trusted External Agent and loaded client share the Agent process's filesystem, network, RFS bearer, and provider credentials. Static provider credentials cannot be revoked after disclosure except by provider-side rotation. + +## Build and packaging + +Server development reads packages from `apps/server/src/capabilities`. The Server bundle copies that directory to `dist-bundle/capabilities`. The bundled Agentlet build emits both `agentlet/index.js` and `agentlet/capability-sdk/index.js`; the published Agentlet npm package already includes its complete `dist` tree. + +## Code entry points + +| File | Responsibility | +| -------------------------------------------------------------------- | ------------------------------------------------------ | +| `packages/shared/src/types/api/capability-package.ts` | Manifest, Generic Settings, summary, and lease schemas | +| `apps/server/src/modules/capabilities/package-loader.ts` | Bundled YAML parsing, validation, and path confinement | +| `apps/server/src/modules/capabilities/provision-service.ts` | Namespace adapters and trusted/masked projections | +| `apps/server/src/modules/capabilities/capabilities.route.ts` | Owner Generic Settings API | +| `apps/server/src/modules/remote_fs/rfs.route.ts` | Authenticated package discovery, files, and lease | +| `apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx` | Manifest-driven Capabilities UI | +| `external/agentlet/packages/local/src/capability-sdk/index.ts` | External Agent SDK | diff --git a/docs/architecture/credential-storage.md b/docs/architecture/credential-storage.md index e7858ca5d..b83130d35 100644 --- a/docs/architecture/credential-storage.md +++ b/docs/architecture/credential-storage.md @@ -31,6 +31,8 @@ Remote Server Basic Auth is separate from Huabu's `SecretStore`. Electron accept Settings API updates for optional capability credentials use an explicit three-state patch contract: omitting a key preserves the persisted value, a non-empty string sets or replaces it, and `null` removes the value stored by Huabu. Removing a persisted key preserves non-secret provider configuration and does not alter deployment-owned environment variables; an environment fallback may therefore keep the capability available at runtime. +Settings > Capabilities is rendered from bundled `huabu-capability/v1` manifests and writes through `CapabilityProvisionService`. Each manifest names a code-registered opaque storage namespace whose adapter delegates to the existing owner and SecretStore IDs. This compatibility layer performs no read-time migration and creates no generic duplicate record: Image, Tavily, RapidAPI, and Ink OCR retain their existing storage, fallback, masking, and update semantics. See [`capability-packages.md`](./capability-packages.md). + ### Agentlet connection token Settings > Agent > External Agent runtime stores an optional Agentlet connection-token override under `integration:agentlet:connection-token`. The effective value prefers that encrypted SecretStore entry, then non-empty `HUABU_CONNECTION_TOKEN`, then one random 256-bit hexadecimal token generated per server boot. Clearing the entry restores the next fallback and never rewrites deployment environment. Environment-only standalone deployments expose the active source as read-only and reject mutation. diff --git a/docs/proposals/capability-packages.md b/docs/proposals/capability-packages.md new file mode 100644 index 000000000..36c97e119 --- /dev/null +++ b/docs/proposals/capability-packages.md @@ -0,0 +1,54 @@ +# Huabu Capability Package 架构 + +Status: Accepted + +Last updated: 2026-10-09 + +## 摘要 + +本 Proposal 定义统一的 Capability Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace、消费者类型以及可选的 Agent Skill/client，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 + +Phase 1 将当前 Settings > Capabilities 中的 Image Generation、Tavily Web Search、YouTube Transcripts 与 Azure Vision Ink OCR 全部迁入 Package、Manifest-driven Settings 和统一 Provision Service。Phase 1 不开放用户上传。 + +## Package 形式 + +```text +/ +├── capability.yaml +├── SKILL.md # 仅 Agent-facing Capability 必须 +├── client.mjs # 仅 Agent 直接调用 provider 时必须 +├── references/ # 可选 +└── assets/ # 可选 +``` + +不创建 placeholder Skill 或 client。一个 Capability 如果只有 Server-native 或 Pipeline consumer，就在 Manifest 中明确声明并省略 Agent 文件，避免 External Agent 发现一个实际上不可用的能力。 + +## 配置与零迁移 + +Manifest 的 `storage.namespace` 是 Huabu code 注册的 opaque adapter ID，不是对象路径、文件路径或 SecretStore ID。`configuration[].id` 直接引用 Adapter 暴露的稳定逻辑 key；UI 使用可变的 `label` 展示，因此不需要重复的 `storage.fields` mapping。 + +所有 Capability 通过同一个 Provision Service 使用现有持久化底座。Image Generation 继续使用 `imageConfig` 与 `llm:image:api-key`，Tavily 和 RapidAPI 继续使用原 SecretStore ID，Ink OCR 继续使用现有 versioned record、legacy read 与 environment fallback。读取不写盘，保存写回原 owner，不复制、不删除、不重写、不重新加密，也不产生第二份配置。 + +## 消费者边界 + +Internal Pi 继续使用高层 Server Tool。`generate_image` 仍负责参数、模型能力、reference artifact、provider SDK、PNG decode 和 Space artifact，只把配置解析切换到 Provision Service。 + +Pipeline 继续使用 reviewed Server-side Adapter。YouTube transcript loader 与 Ink OCR 不导入 `client.mjs`。 + +External Agent 通过 Agentlet 注入的 `AGENTLET_CAPABILITY_SDK_URL` 加载 SDK，经 authenticated RFS 按需取得当前 Package 配置，并在 Agentlet 设备执行受信任的 `client.mjs`。Image Generation 与 Tavily Web Search 提供真实 Skill/client；YouTube Transcripts 与 Ink OCR 在 Phase 1 不声明 External consumer。 + +## API 与安全 + +Owner Settings 使用 `/api/capabilities` generic API。RFS 已将 `/capabilities` 用作 Space operation discovery，因此 Package 使用 `/capability-packages`，提供列表、Manifest、Skill、client 与 POST lease。 + +Lease 使用现有 canvas-scoped RFS bearer，响应 `Cache-Control: no-store`，只返回目标 Package 声明的配置。Manifest、Skill、Settings read 和日志不返回 secret。Agentlet SDK 降低意外落盘和日志泄露，但不是 sandbox；Agent 与 client 拥有同一进程权限，静态 provider key 一旦交付只能通过 provider rotation 真正撤销。 + +## Phase 1 + +Phase 1 交付严格的 `huabu-capability/v1` schema、bundled Package discovery、Generic Settings、code-registered storage adapters、RFS Package/lease surface、Agentlet SDK，以及全部四个现有 UI Capability 的 Package 化。Image Generation 是完整 External Agent vertical slice，Tavily 同时提供可工作的 External client。 + +Phase 1 明确排除用户上传、archive 安装、remote registry、任意 Server plugin、动态 UI/表达式、per-Profile/device grant、通用 provider result envelope 与自动 Node 创建。 + +## Phase 2 + +未来的用户上传只能默认产生 Agent-only Package，并需要 path-safe extraction、压缩与解压大小限制、文件数量限制、duplicate/symlink/special-file 拒绝、content hash、不可变版本、来源记录、显式任意代码执行同意，以及更新和卸载语义。Huabu Server 与 Pipeline 不执行上传的 `client.mjs`。 diff --git a/packages/shared/src/types/api/capability-package.test.ts b/packages/shared/src/types/api/capability-package.test.ts new file mode 100644 index 000000000..7aa8305ea --- /dev/null +++ b/packages/shared/src/types/api/capability-package.test.ts @@ -0,0 +1,59 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { describe, expect, it } from 'vitest'; + +import { + capabilityConfigUpdateSchema, + capabilityManifestSchema, +} from './capability-package.js'; + +const manifest = { + schema: 'huabu-capability/v1', + id: 'example', + version: '1.0.0', + name: 'Example', + description: 'Example Capability', + storage: { namespace: 'integration.example' }, + consumers: { internal: false, pipeline: true, external: false }, + configuration: [ + { + id: 'apiKey', + label: 'API key', + type: 'secret', + required: true, + }, + ], +}; + +describe('Capability Package contract', () => { + it('accepts a pipeline-only package without Agent files', () => { + expect(capabilityManifestSchema.parse(manifest)).toMatchObject({ + id: 'example', + consumers: { external: false }, + }); + }); + + it('requires a Skill for an External Agent package', () => { + const result = capabilityManifestSchema.safeParse({ + ...manifest, + consumers: { internal: false, pipeline: false, external: true }, + }); + expect(result.success).toBe(false); + }); + + it('rejects duplicate field ids and empty updates', () => { + expect( + capabilityManifestSchema.safeParse({ + ...manifest, + configuration: [ + ...manifest.configuration, + { ...manifest.configuration[0] }, + ], + }).success, + ).toBe(false); + expect(capabilityConfigUpdateSchema.safeParse({ values: {} }).success).toBe( + false, + ); + }); +}); diff --git a/packages/shared/src/types/api/capability-package.ts b/packages/shared/src/types/api/capability-package.ts new file mode 100644 index 000000000..492507bc2 --- /dev/null +++ b/packages/shared/src/types/api/capability-package.ts @@ -0,0 +1,176 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { z } from 'zod'; + +const capabilityIdSchema = z + .string() + .regex(/^[a-z][a-z0-9-]{0,63}$/, 'Invalid capability id'); +const capabilityFieldIdSchema = z + .string() + .regex(/^[a-z][a-zA-Z0-9]{0,63}$/, 'Invalid capability field id'); + +export const capabilityFieldOptionSchema = z.object({ + value: z.string().min(1).max(256), + label: z.string().min(1).max(256), +}); + +export const capabilityConfigurationFieldSchema = z + .object({ + id: capabilityFieldIdSchema, + label: z.string().min(1).max(256), + description: z.string().max(1024).optional(), + type: z.enum(['text', 'secret', 'url', 'boolean', 'enum']), + required: z.boolean().default(false), + options: z.array(capabilityFieldOptionSchema).min(1).max(100).optional(), + placeholder: z.string().max(512).optional(), + }) + .strict() + .superRefine((field, ctx) => { + if (field.type === 'enum' && !field.options) { + ctx.addIssue({ + code: 'custom', + path: ['options'], + message: 'Enum fields require options', + }); + } + if (field.type !== 'enum' && field.options) { + ctx.addIssue({ + code: 'custom', + path: ['options'], + message: 'Only enum fields may declare options', + }); + } + }); + +export const capabilityManifestSchema = z + .object({ + schema: z.literal('huabu-capability/v1'), + id: capabilityIdSchema, + version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Invalid package version'), + name: z.string().min(1).max(256), + description: z.string().min(1).max(1024), + storage: z + .object({ + namespace: z + .string() + .regex(/^[a-z][a-zA-Z0-9.]{0,127}$/, 'Invalid storage namespace'), + }) + .strict(), + consumers: z + .object({ + internal: z.boolean().default(false), + pipeline: z.boolean().default(false), + external: z.boolean().default(false), + }) + .strict(), + agent: z + .object({ + skill: z.string().min(1).max(256).optional(), + client: z.string().min(1).max(256).optional(), + }) + .strict() + .optional(), + configuration: z + .array(capabilityConfigurationFieldSchema) + .max(100) + .default([]), + }) + .strict() + .superRefine((manifest, ctx) => { + const ids = new Set(); + for (const [index, field] of manifest.configuration.entries()) { + if (ids.has(field.id)) { + ctx.addIssue({ + code: 'custom', + path: ['configuration', index, 'id'], + message: `Duplicate configuration field: ${field.id}`, + }); + } + ids.add(field.id); + } + if (manifest.consumers.external && !manifest.agent?.skill) { + ctx.addIssue({ + code: 'custom', + path: ['agent', 'skill'], + message: 'External capabilities require a Skill', + }); + } + if (!manifest.consumers.external && manifest.agent) { + ctx.addIssue({ + code: 'custom', + path: ['agent'], + message: 'Only external capabilities may declare Agent files', + }); + } + }); + +export type CapabilityManifest = z.infer; +export type CapabilityConfigurationField = z.infer< + typeof capabilityConfigurationFieldSchema +>; + +export const capabilityFieldValueSchema = z.union([ + z.string().max(8192), + z.boolean(), + z.null(), +]); +export type CapabilityFieldValue = z.infer; + +export const capabilityConfigUpdateSchema = z + .object({ + values: z.record(capabilityFieldIdSchema, capabilityFieldValueSchema), + }) + .strict() + .refine((body) => Object.keys(body.values).length > 0, { + message: 'Provide at least one capability configuration value', + }); +export type CapabilityConfigUpdate = z.infer< + typeof capabilityConfigUpdateSchema +>; + +export const capabilityParamsSchema = z + .object({ capabilityId: capabilityIdSchema }) + .strict(); +export type CapabilityParams = z.infer; + +export const capabilityConfigSchema = z + .object({ + manifest: capabilityManifestSchema, + values: z.record(capabilityFieldIdSchema, capabilityFieldValueSchema), + configuredFields: z.array(capabilityFieldIdSchema), + configured: z.boolean(), + }) + .strict(); +export type CapabilityConfig = z.infer; + +export const capabilitySummarySchema = z + .object({ + id: capabilityIdSchema, + version: z.string(), + name: z.string(), + description: z.string(), + configured: z.boolean(), + availableToInternalAgent: z.boolean(), + availableToPipeline: z.boolean(), + availableToExternalAgent: z.boolean(), + }) + .strict(); +export type CapabilitySummary = z.infer; + +export const capabilityListResponseSchema = z + .object({ capabilities: z.array(capabilitySummarySchema) }) + .strict(); +export type CapabilityListResponse = z.infer< + typeof capabilityListResponseSchema +>; + +export const capabilityLeaseSchema = z + .object({ + id: capabilityIdSchema, + version: z.string(), + config: z.record(capabilityFieldIdSchema, capabilityFieldValueSchema), + client: z.string().optional(), + }) + .strict(); +export type CapabilityLease = z.infer; diff --git a/packages/shared/src/types/api/index.ts b/packages/shared/src/types/api/index.ts index 7023d7186..be2d4e53a 100644 --- a/packages/shared/src/types/api/index.ts +++ b/packages/shared/src/types/api/index.ts @@ -38,3 +38,4 @@ export * from './task.js'; export * from './interactive-view.js'; export * from './deployment.js'; export * from './agent-node.js'; +export * from './capability-package.js'; From 38ffb9ef71cfe5122b21821ae7a79a5f95d9aaad Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 01:54:47 +0000 Subject: [PATCH 08/36] fix: add capability client license headers Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/server/src/capabilities/image-gen/client.mjs | 3 +++ apps/server/src/capabilities/web-search/client.mjs | 3 +++ 2 files changed, 6 insertions(+) diff --git a/apps/server/src/capabilities/image-gen/client.mjs b/apps/server/src/capabilities/image-gen/client.mjs index 05a26718d..225522087 100644 --- a/apps/server/src/capabilities/image-gen/client.mjs +++ b/apps/server/src/capabilities/image-gen/client.mjs @@ -1,3 +1,6 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + export function createClient({ config }) { return { async generate(input) { diff --git a/apps/server/src/capabilities/web-search/client.mjs b/apps/server/src/capabilities/web-search/client.mjs index afda92d09..476065fdc 100644 --- a/apps/server/src/capabilities/web-search/client.mjs +++ b/apps/server/src/capabilities/web-search/client.mjs @@ -1,3 +1,6 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + export function createClient({ config }) { return { async search(input) { From 709d228c71506a6ef147dcd37cc96b692d1391fc Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 02:13:17 +0000 Subject: [PATCH 09/36] refactor: derive agent capability from manifest Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../capabilities/image-gen/capability.yaml | 4 --- .../src/capabilities/ink-ocr/capability.yaml | 4 --- .../capabilities/web-search/capability.yaml | 4 --- .../youtube-transcripts/capability.yaml | 4 --- .../capabilities/capabilities.route.test.ts | 3 --- .../capabilities/package-loader.test.ts | 2 +- .../modules/capabilities/provision-service.ts | 6 ++--- .../src/modules/remote_fs/rfs.route.test.ts | 2 -- .../sections/CapabilitiesSettings.test.tsx | 3 --- docs/README.md | 2 +- docs/architecture/capability-packages.md | 12 ++++----- docs/proposals/capability-packages.md | 8 +++--- .../src/types/api/capability-package.test.ts | 8 +++--- .../src/types/api/capability-package.ts | 25 +------------------ 14 files changed, 18 insertions(+), 69 deletions(-) diff --git a/apps/server/src/capabilities/image-gen/capability.yaml b/apps/server/src/capabilities/image-gen/capability.yaml index 966818f38..d13ea68c2 100644 --- a/apps/server/src/capabilities/image-gen/capability.yaml +++ b/apps/server/src/capabilities/image-gen/capability.yaml @@ -5,10 +5,6 @@ name: Image Generation description: Generate images with the configured Azure OpenAI deployment. storage: namespace: llm.imageConfig -consumers: - internal: true - pipeline: false - external: true agent: skill: SKILL.md client: client.mjs diff --git a/apps/server/src/capabilities/ink-ocr/capability.yaml b/apps/server/src/capabilities/ink-ocr/capability.yaml index a20d77e64..480d8504e 100644 --- a/apps/server/src/capabilities/ink-ocr/capability.yaml +++ b/apps/server/src/capabilities/ink-ocr/capability.yaml @@ -5,10 +5,6 @@ name: Handwriting Recognition description: Recognize selected handwriting with Azure AI Vision. storage: namespace: integration.azureVisionInkOcr -consumers: - internal: true - pipeline: false - external: false configuration: - id: endpoint label: Endpoint diff --git a/apps/server/src/capabilities/web-search/capability.yaml b/apps/server/src/capabilities/web-search/capability.yaml index b543780ea..dba7dd2cc 100644 --- a/apps/server/src/capabilities/web-search/capability.yaml +++ b/apps/server/src/capabilities/web-search/capability.yaml @@ -5,10 +5,6 @@ name: Web Search description: Search the web with Tavily. storage: namespace: integration.tavily -consumers: - internal: true - pipeline: false - external: true agent: skill: SKILL.md client: client.mjs diff --git a/apps/server/src/capabilities/youtube-transcripts/capability.yaml b/apps/server/src/capabilities/youtube-transcripts/capability.yaml index 80e93c936..bc21c586a 100644 --- a/apps/server/src/capabilities/youtube-transcripts/capability.yaml +++ b/apps/server/src/capabilities/youtube-transcripts/capability.yaml @@ -5,10 +5,6 @@ name: YouTube Transcripts description: Load YouTube transcripts through the existing RapidAPI preprocessing integration. storage: namespace: integration.rapidapi -consumers: - internal: false - pipeline: true - external: false configuration: - id: apiKey label: API key diff --git a/apps/server/src/modules/capabilities/capabilities.route.test.ts b/apps/server/src/modules/capabilities/capabilities.route.test.ts index ac4b13b30..a811033b4 100644 --- a/apps/server/src/modules/capabilities/capabilities.route.test.ts +++ b/apps/server/src/modules/capabilities/capabilities.route.test.ts @@ -48,7 +48,6 @@ const maskedConfig = { name: 'Web Search', description: 'Search the web.', storage: { namespace: 'integration.tavily' }, - consumers: { internal: true, pipeline: false, external: true }, agent: { skill: 'SKILL.md', client: 'client.mjs' }, configuration: [ { @@ -85,8 +84,6 @@ describe('Capability settings routes', () => { name: 'Web Search', description: 'Search the web.', configured: true, - availableToInternalAgent: true, - availableToPipeline: false, availableToExternalAgent: true, }, ]); diff --git a/apps/server/src/modules/capabilities/package-loader.test.ts b/apps/server/src/modules/capabilities/package-loader.test.ts index 34698934e..aec417754 100644 --- a/apps/server/src/modules/capabilities/package-loader.test.ts +++ b/apps/server/src/modules/capabilities/package-loader.test.ts @@ -24,7 +24,7 @@ describe('bundled Capability packages', () => { expect(packages.get('ink-ocr')?.manifest.agent).toBeUndefined(); }); - it('exposes real Agent files only for External packages', () => { + it('exposes real Agent files only when the manifest declares Agent behavior', () => { expect(readCapabilityPackageFile('image-gen', 'SKILL.md')).toContain( '# Image Generation', ); diff --git a/apps/server/src/modules/capabilities/provision-service.ts b/apps/server/src/modules/capabilities/provision-service.ts index b7f7d7ad5..d081b0c92 100644 --- a/apps/server/src/modules/capabilities/provision-service.ts +++ b/apps/server/src/modules/capabilities/provision-service.ts @@ -332,9 +332,7 @@ export class CapabilityProvisionService { name: manifest.name, description: manifest.description, configured, - availableToInternalAgent: configured && manifest.consumers.internal, - availableToPipeline: configured && manifest.consumers.pipeline, - availableToExternalAgent: configured && manifest.consumers.external, + availableToExternalAgent: configured && Boolean(manifest.agent), }; }); } @@ -375,7 +373,7 @@ export class CapabilityProvisionService { lease(capabilityId: string): CapabilityLease { const manifest = this.manifest(capabilityId); - if (!manifest.consumers.external) { + if (!manifest.agent) { throw new CapabilityServiceError( 'capability_not_external', `Capability "${capabilityId}" is not available to External Agents`, diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index 11139c328..31d307f1b 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -603,8 +603,6 @@ describe('provider Capability Packages', () => { name: 'Image Generation', description: 'Generate images.', configured: true, - availableToInternalAgent: true, - availableToPipeline: false, availableToExternalAgent: true, }, ]); diff --git a/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx b/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx index 0e68db365..12773925d 100644 --- a/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx +++ b/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx @@ -46,7 +46,6 @@ function config(id: (typeof ids)[number]): CapabilityConfig { name: id, description: `${id} description`, storage: { namespace: `integration.${id}` }, - consumers: { internal: false, pipeline: true, external: false }, configuration: [ { id: 'apiKey', @@ -76,8 +75,6 @@ beforeEach(() => { name: id, description: id, configured: false, - availableToInternalAgent: false, - availableToPipeline: true, availableToExternalAgent: false, })), }); diff --git a/docs/README.md b/docs/README.md index 42f253e12..303b4a2c7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,7 +54,7 @@ docs/ | [canvas-input-interactions.md](./architecture/canvas-input-interactions.md) | Mouse, touch, and pen preference resolution, gesture ownership, and multi-touch arbitration. | | [canvas-zoom-rendering.md](./architecture/canvas-zoom-rendering.md) | Node LOD, Frame/edge label readability, and interaction chrome across canvas zoom. | | [canvas-storage.md](./architecture/canvas-storage.md) | Disk layout plus Blob/structured ports, catalogue, compatibility, and `.memory/`. | -| [capability-packages.md](./architecture/capability-packages.md) | Manifest-driven provider configuration, storage bindings, consumers, RFS leases, and Agentlet SDK. | +| [capability-packages.md](./architecture/capability-packages.md) | Manifest-driven provider configuration, storage bindings, Agent declarations, RFS leases, and SDK. | | [canary-deployment.md](./architecture/canary-deployment.md) | Personal Alpha Canary status, owner-triggered redeployment, and explicit reliability limits. | | [canvas-action-log.md](./architecture/canvas-action-log.md) | Persistent `events.jsonl` user-action trail; consumed by the memory curator. | | [canvas-realtime-sync.md](./architecture/canvas-realtime-sync.md) | Multi-agent real-time sync: SSE broadcast, dirty-node conflict model, per-thread change-review card. | diff --git a/docs/architecture/capability-packages.md b/docs/architecture/capability-packages.md index 91a632b14..ace41129a 100644 --- a/docs/architecture/capability-packages.md +++ b/docs/architecture/capability-packages.md @@ -1,6 +1,6 @@ # Capability Packages -> Current architecture for Huabu-managed provider capabilities. Last updated: 2026-10-09 +> Current architecture for Huabu-managed provider capabilities. Last updated: 2026-10-10 ## Scope @@ -19,11 +19,11 @@ Phase 1 packages are trusted files shipped with Huabu. User upload, installation ## Manifest contract -`huabu-capability/v1` is defined by `capabilityManifestSchema` in `packages/shared/src/types/api/capability-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, and an External consumer without a Skill fail validation. +`huabu-capability/v1` is defined by `capabilityManifestSchema` in `packages/shared/src/types/api/capability-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, and an `agent` block without a Skill fail validation. -Every package declares a stable ID and version, display metadata, one registered storage namespace, supported consumer classes, optional Agent files, and constrained configuration fields. Supported field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or client contract. +Every package declares a stable ID and version, display metadata, one registered storage namespace, optional Agent files, and constrained configuration fields. Supported field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or client contract. -The manifest cannot register Server tools, choose arbitrary persistence paths or SecretStore IDs, provide custom Settings components, or execute expressions. Agent files are forbidden when `consumers.external` is false, so a Server-only or Pipeline-only package cannot accidentally advertise placeholder Agent behavior. +The manifest does not declare Internal Agent or Pipeline consumers. Those execution paths are reviewed Huabu code and cannot be enabled by package metadata. The presence of an `agent` block is the complete declaration that a package supports External Agent use; its `skill` is required and its direct-provider `client` is optional. A package without `agent` cannot be leased to an External Agent. ## Provision Service and storage bindings @@ -42,7 +42,7 @@ This is a zero-persistent-data-migration compatibility layer. Reading Capability Masked Settings responses return `null` for secret values and identify configured fields separately. Trusted `resolveForServer()` and authenticated External leases resolve effective values, including environment fallbacks, only at the point of use. -## Consumers +## Execution paths Internal Agent tools keep their high-level Huabu integrations. `generate_image` still owns typed tool arguments, model capability validation, reference artifact reads, provider SDK behavior, image decoding, and artifact persistence; it obtains provider configuration through `resolveForServer('image-gen')`. @@ -74,7 +74,7 @@ GET /capability-packages/:id/client POST /capability-packages/:id/lease ``` -Manifest and Skill responses contain no credentials. Client source is a versioned bundled asset. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and non-External packages explicitly, returns only fields declared by the selected package, and uses `Cache-Control: no-store`. +Manifest and Skill responses contain no credentials. Client source is a versioned bundled asset. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and packages without an `agent` declaration explicitly, returns only fields declared by the selected package, and uses `Cache-Control: no-store`. ## Agentlet SDK diff --git a/docs/proposals/capability-packages.md b/docs/proposals/capability-packages.md index 36c97e119..ddece15ba 100644 --- a/docs/proposals/capability-packages.md +++ b/docs/proposals/capability-packages.md @@ -2,11 +2,11 @@ Status: Accepted -Last updated: 2026-10-09 +Last updated: 2026-10-10 ## 摘要 -本 Proposal 定义统一的 Capability Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace、消费者类型以及可选的 Agent Skill/client，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 +本 Proposal 定义统一的 Capability Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace 以及可选的 Agent Skill/client，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 Phase 1 将当前 Settings > Capabilities 中的 Image Generation、Tavily Web Search、YouTube Transcripts 与 Azure Vision Ink OCR 全部迁入 Package、Manifest-driven Settings 和统一 Provision Service。Phase 1 不开放用户上传。 @@ -21,7 +21,7 @@ Phase 1 将当前 Settings > Capabilities 中的 Image Generation、Tavily Web S └── assets/ # 可选 ``` -不创建 placeholder Skill 或 client。一个 Capability 如果只有 Server-native 或 Pipeline consumer，就在 Manifest 中明确声明并省略 Agent 文件，避免 External Agent 发现一个实际上不可用的能力。 +不创建 placeholder Skill 或 client。Manifest 不声明 Internal Agent 或 Pipeline consumer；这些执行路径只由 reviewed Huabu code 接线。存在 `agent` block 就表示 Package 提供 External Agent 行为，其中 `skill` 必须存在，直接调用 provider 时才需要可选的 `client`。没有 `agent` block 的 Package 不能被 External Agent lease。 ## 配置与零迁移 @@ -35,7 +35,7 @@ Internal Pi 继续使用高层 Server Tool。`generate_image` 仍负责参数、 Pipeline 继续使用 reviewed Server-side Adapter。YouTube transcript loader 与 Ink OCR 不导入 `client.mjs`。 -External Agent 通过 Agentlet 注入的 `AGENTLET_CAPABILITY_SDK_URL` 加载 SDK，经 authenticated RFS 按需取得当前 Package 配置，并在 Agentlet 设备执行受信任的 `client.mjs`。Image Generation 与 Tavily Web Search 提供真实 Skill/client；YouTube Transcripts 与 Ink OCR 在 Phase 1 不声明 External consumer。 +External Agent 通过 Agentlet 注入的 `AGENTLET_CAPABILITY_SDK_URL` 加载 SDK，经 authenticated RFS 按需取得当前 Package 配置，并在 Agentlet 设备执行受信任的 `client.mjs`。Image Generation 与 Tavily Web Search 提供真实 `agent.skill`/`agent.client`；YouTube Transcripts 与 Ink OCR 没有 `agent` block。 ## API 与安全 diff --git a/packages/shared/src/types/api/capability-package.test.ts b/packages/shared/src/types/api/capability-package.test.ts index 7aa8305ea..0d29617b6 100644 --- a/packages/shared/src/types/api/capability-package.test.ts +++ b/packages/shared/src/types/api/capability-package.test.ts @@ -15,7 +15,6 @@ const manifest = { name: 'Example', description: 'Example Capability', storage: { namespace: 'integration.example' }, - consumers: { internal: false, pipeline: true, external: false }, configuration: [ { id: 'apiKey', @@ -27,17 +26,16 @@ const manifest = { }; describe('Capability Package contract', () => { - it('accepts a pipeline-only package without Agent files', () => { + it('accepts a Server-consumed package without Agent files', () => { expect(capabilityManifestSchema.parse(manifest)).toMatchObject({ id: 'example', - consumers: { external: false }, }); }); - it('requires a Skill for an External Agent package', () => { + it('requires a Skill whenever the package declares Agent behavior', () => { const result = capabilityManifestSchema.safeParse({ ...manifest, - consumers: { internal: false, pipeline: false, external: true }, + agent: { client: 'client.mjs' }, }); expect(result.success).toBe(false); }); diff --git a/packages/shared/src/types/api/capability-package.ts b/packages/shared/src/types/api/capability-package.ts index 492507bc2..54a7f0604 100644 --- a/packages/shared/src/types/api/capability-package.ts +++ b/packages/shared/src/types/api/capability-package.ts @@ -57,16 +57,9 @@ export const capabilityManifestSchema = z .regex(/^[a-z][a-zA-Z0-9.]{0,127}$/, 'Invalid storage namespace'), }) .strict(), - consumers: z - .object({ - internal: z.boolean().default(false), - pipeline: z.boolean().default(false), - external: z.boolean().default(false), - }) - .strict(), agent: z .object({ - skill: z.string().min(1).max(256).optional(), + skill: z.string().min(1).max(256), client: z.string().min(1).max(256).optional(), }) .strict() @@ -89,20 +82,6 @@ export const capabilityManifestSchema = z } ids.add(field.id); } - if (manifest.consumers.external && !manifest.agent?.skill) { - ctx.addIssue({ - code: 'custom', - path: ['agent', 'skill'], - message: 'External capabilities require a Skill', - }); - } - if (!manifest.consumers.external && manifest.agent) { - ctx.addIssue({ - code: 'custom', - path: ['agent'], - message: 'Only external capabilities may declare Agent files', - }); - } }); export type CapabilityManifest = z.infer; @@ -151,8 +130,6 @@ export const capabilitySummarySchema = z name: z.string(), description: z.string(), configured: z.boolean(), - availableToInternalAgent: z.boolean(), - availableToPipeline: z.boolean(), availableToExternalAgent: z.boolean(), }) .strict(); From fcd10aa121a9657a6401e01d9750b4064cb7d1a4 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 02:35:38 +0000 Subject: [PATCH 10/36] Rename Agentlet capability SDK to service SDK Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 4 +- .../agentlet/packages/local/src/agentlet.ts | 4 +- .../local/src/capability-sdk/index.ts | 85 ------------------- .../packages/local/src/service-sdk/index.ts | 85 +++++++++++++++++++ .../packages/local/tests/agentlet.test.ts | 8 +- ...bility-sdk.test.ts => service-sdk.test.ts} | 14 +-- 6 files changed, 100 insertions(+), 100 deletions(-) delete mode 100644 external/agentlet/packages/local/src/capability-sdk/index.ts create mode 100644 external/agentlet/packages/local/src/service-sdk/index.ts rename external/agentlet/packages/local/tests/{capability-sdk.test.ts => service-sdk.test.ts} (79%) diff --git a/external/agentlet/README.md b/external/agentlet/README.md index 8b26afc3a..b9607ae0e 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -123,11 +123,11 @@ The standard environment includes: | `AGENTLET_REACHBACK_DIR` | Directory containing host-provided resources. | | `AGENTLET_SERVER` | Gateway URL supplied to the daemon. | | `AGENTLET_TOKEN` | Authentication token available to host-provided reachback tools. | -| `AGENTLET_CAPABILITY_SDK_URL` | Daemon-owned absolute `file://` URL for the ESM Capability SDK published under `dist/capability-sdk`. | +| `AGENTLET_SERVICE_SDK_URL` | Daemon-owned absolute `file://` URL for the ESM Service SDK published under `dist/service-sdk`. | Agentlet transports opaque resources and environment values; it does not interpret the host-specific tool protocol. -The optional Capability SDK exports `loadCapability(id)` and `withCapability(id, callback)`. It uses host-injected reachback coordinates to obtain an on-demand configuration lease and load a trusted host-provided client without persisting credentials. The daemon writes `AGENTLET_CAPABILITY_SDK_URL` after workload environment values so a session cannot replace the SDK module location. +The optional Service SDK exports `loadService(id)` and `withService(id, callback)`. It uses host-injected reachback coordinates to obtain an on-demand configuration lease and load a trusted host-provided client without persisting credentials. The daemon writes `AGENTLET_SERVICE_SDK_URL` after workload environment values so a session cannot replace the SDK module location. ## Repository layout diff --git a/external/agentlet/packages/local/src/agentlet.ts b/external/agentlet/packages/local/src/agentlet.ts index 9324be822..6b9e921c4 100644 --- a/external/agentlet/packages/local/src/agentlet.ts +++ b/external/agentlet/packages/local/src/agentlet.ts @@ -900,8 +900,8 @@ export function buildAgentProcessEnv( ...envRegistry, ...sessionEnv, AGENTLET_TOKEN: token, - AGENTLET_CAPABILITY_SDK_URL: new URL( - './capability-sdk/index.js', + AGENTLET_SERVICE_SDK_URL: new URL( + './service-sdk/index.js', import.meta.url, ).href, } diff --git a/external/agentlet/packages/local/src/capability-sdk/index.ts b/external/agentlet/packages/local/src/capability-sdk/index.ts deleted file mode 100644 index 0912d4ff5..000000000 --- a/external/agentlet/packages/local/src/capability-sdk/index.ts +++ /dev/null @@ -1,85 +0,0 @@ -export interface CapabilityLease { - id: string - version: string - config: Record - client?: string -} - -export interface CapabilityContext { - config: CapabilityLease['config'] - client: Record | null - lease: CapabilityLease -} - -type CapabilityClientModule = { - createClient?: (context: { - config: CapabilityLease['config'] - }) => Record -} - -function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { - const value = process.env[name]?.trim() - if (!value) throw new Error(`Capability SDK requires ${name}`) - return value -} - -async function capabilityFetch(path: string, init?: RequestInit): Promise { - const baseUrl = requiredEnvironment('HUABU_RFS_URL').replace(/\/+$/, '') - const token = requiredEnvironment('AGENTLET_TOKEN') - const response = await fetch(`${baseUrl}${path}`, { - ...init, - headers: { - Authorization: `Bearer ${token}`, - ...(init?.headers ?? {}), - }, - }) - if (!response.ok) { - throw new Error(`Capability request failed (${response.status})`) - } - return response -} - -async function loadClient( - capabilityId: string, - lease: CapabilityLease, -): Promise | null> { - if (!lease.client) return null - const response = await capabilityFetch( - `/capability-packages/${encodeURIComponent(capabilityId)}/client`, - ) - const source = await response.text() - const moduleUrl = `data:text/javascript;base64,${Buffer.from(source, 'utf8').toString('base64')}` - const module = (await import(moduleUrl)) as CapabilityClientModule - if (typeof module.createClient !== 'function') { - throw new Error('Capability client must export createClient()') - } - return module.createClient({ config: lease.config }) -} - -export async function loadCapability( - capabilityId: string, -): Promise { - if (!/^[a-z][a-z0-9-]{0,63}$/.test(capabilityId)) { - throw new Error('Invalid Capability id') - } - const response = await capabilityFetch( - `/capability-packages/${encodeURIComponent(capabilityId)}/lease`, - { method: 'POST' }, - ) - const lease = (await response.json()) as CapabilityLease - if (lease.id !== capabilityId || typeof lease.version !== 'string') { - throw new Error('Invalid Capability lease') - } - return { - lease, - config: lease.config, - client: await loadClient(capabilityId, lease), - } -} - -export async function withCapability( - capabilityId: string, - run: (context: CapabilityContext) => Promise | T, -): Promise { - return run(await loadCapability(capabilityId)) -} diff --git a/external/agentlet/packages/local/src/service-sdk/index.ts b/external/agentlet/packages/local/src/service-sdk/index.ts new file mode 100644 index 000000000..095044e03 --- /dev/null +++ b/external/agentlet/packages/local/src/service-sdk/index.ts @@ -0,0 +1,85 @@ +export interface ServiceLease { + id: string + version: string + config: Record + client?: string +} + +export interface ServiceContext { + config: ServiceLease['config'] + client: Record | null + lease: ServiceLease +} + +type ServiceClientModule = { + createClient?: (context: { + config: ServiceLease['config'] + }) => Record +} + +function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { + const value = process.env[name]?.trim() + if (!value) throw new Error(`Service SDK requires ${name}`) + return value +} + +async function serviceFetch(path: string, init?: RequestInit): Promise { + const baseUrl = requiredEnvironment('HUABU_RFS_URL').replace(/\/+$/, '') + const token = requiredEnvironment('AGENTLET_TOKEN') + const response = await fetch(`${baseUrl}${path}`, { + ...init, + headers: { + Authorization: `Bearer ${token}`, + ...(init?.headers ?? {}), + }, + }) + if (!response.ok) { + throw new Error(`Service request failed (${response.status})`) + } + return response +} + +async function loadClient( + serviceId: string, + lease: ServiceLease, +): Promise | null> { + if (!lease.client) return null + const response = await serviceFetch( + `/services/${encodeURIComponent(serviceId)}/client`, + ) + const source = await response.text() + const moduleUrl = `data:text/javascript;base64,${Buffer.from(source, 'utf8').toString('base64')}` + const module = (await import(moduleUrl)) as ServiceClientModule + if (typeof module.createClient !== 'function') { + throw new Error('Service client must export createClient()') + } + return module.createClient({ config: lease.config }) +} + +export async function loadService( + serviceId: string, +): Promise { + if (!/^[a-z][a-z0-9-]{0,63}$/.test(serviceId)) { + throw new Error('Invalid Service id') + } + const response = await serviceFetch( + `/services/${encodeURIComponent(serviceId)}/lease`, + { method: 'POST' }, + ) + const lease = (await response.json()) as ServiceLease + if (lease.id !== serviceId || typeof lease.version !== 'string') { + throw new Error('Invalid Service lease') + } + return { + lease, + config: lease.config, + client: await loadClient(serviceId, lease), + } +} + +export async function withService( + serviceId: string, + run: (context: ServiceContext) => Promise | T, +): Promise { + return run(await loadService(serviceId)) +} diff --git a/external/agentlet/packages/local/tests/agentlet.test.ts b/external/agentlet/packages/local/tests/agentlet.test.ts index b897665cc..ea01afee8 100644 --- a/external/agentlet/packages/local/tests/agentlet.test.ts +++ b/external/agentlet/packages/local/tests/agentlet.test.ts @@ -105,8 +105,8 @@ describe('spawned agent environment', () => { ).toEqual({ AGENTLET_SERVER: 'ws://127.0.0.1:3001/api/acp/agent', AGENTLET_TOKEN: 'cli-token', - AGENTLET_CAPABILITY_SDK_URL: expect.stringMatching( - /\/capability-sdk\/index\.js$/, + AGENTLET_SERVICE_SDK_URL: expect.stringMatching( + /\/service-sdk\/index\.js$/, ), AGENTLET_REACHBACK_DIR: '/tmp/reachback', HUABU_RFS_URL: 'http://127.0.0.1:3001/api/rfs/canvas-1', @@ -118,12 +118,12 @@ describe('spawned agent environment', () => { buildAgentProcessEnv('ws://daemon.test', 'daemon-token', {}, { AGENTLET_SERVER: 'ws://host.test', AGENTLET_TOKEN: 'host-token', - AGENTLET_CAPABILITY_SDK_URL: 'file:///tmp/untrusted.js', + AGENTLET_SERVICE_SDK_URL: 'file:///tmp/untrusted.js', }), ).toMatchObject({ AGENTLET_SERVER: 'ws://host.test', AGENTLET_TOKEN: 'daemon-token', - AGENTLET_CAPABILITY_SDK_URL: expect.not.stringContaining('untrusted'), + AGENTLET_SERVICE_SDK_URL: expect.not.stringContaining('untrusted'), }) }) }) diff --git a/external/agentlet/packages/local/tests/capability-sdk.test.ts b/external/agentlet/packages/local/tests/service-sdk.test.ts similarity index 79% rename from external/agentlet/packages/local/tests/capability-sdk.test.ts rename to external/agentlet/packages/local/tests/service-sdk.test.ts index c444f8db0..98265b72d 100644 --- a/external/agentlet/packages/local/tests/capability-sdk.test.ts +++ b/external/agentlet/packages/local/tests/service-sdk.test.ts @@ -1,6 +1,6 @@ import { afterEach, describe, expect, it, vi } from 'vitest' -import { loadCapability } from '../src/capability-sdk/index.js' +import { loadService } from '../src/service-sdk/index.js' afterEach(() => { vi.unstubAllGlobals() @@ -8,7 +8,7 @@ afterEach(() => { delete process.env.AGENTLET_TOKEN }) -describe('Capability SDK', () => { +describe('Service SDK', () => { it('leases config and loads the trusted package client without logging secrets', async () => { process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' process.env.AGENTLET_TOKEN = 'agentlet-token' @@ -33,12 +33,12 @@ describe('Capability SDK', () => { ) vi.stubGlobal('fetch', fetchMock) - const capability = await loadCapability('example') + const service = await loadService('example') - expect(capability.client).toEqual({ configured: true }) + expect(service.client).toEqual({ configured: true }) expect(fetchMock).toHaveBeenNthCalledWith( 1, - 'https://huabu.example/api/rfs/canvas-1/capability-packages/example/lease', + 'https://huabu.example/api/rfs/canvas-1/services/example/lease', expect.objectContaining({ method: 'POST', headers: { Authorization: 'Bearer agentlet-token' }, @@ -56,8 +56,8 @@ describe('Capability SDK', () => { ), ) - await expect(loadCapability('example')).rejects.toThrow( - 'Capability request failed (409)', + await expect(loadService('example')).rejects.toThrow( + 'Service request failed (409)', ) }) }) From 1b31c8cb4b0f5b02c3bae35f8a8abfa6d696a3a1 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 02:35:42 +0000 Subject: [PATCH 11/36] Rename capability packages to service packages Keep RFS operation discovery on /capabilities while moving third-party integrations to the Service manifest, API, Settings, and SDK contracts. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/server/src/app.ts | 6 +- .../src/capabilities/image-gen/SKILL.md | 7 - .../src/capabilities/web-search/SKILL.md | 5 - .../agent/conversation/ink-ocr.test.ts | 4 +- .../src/modules/agent/conversation/ink-ocr.ts | 6 +- .../agent/tools/handlers/image-generation.ts | 4 +- .../agent/tools/handlers/web-search.ts | 4 +- .../capabilities/capabilities.route.ts | 102 --------- apps/server/src/modules/capabilities/index.ts | 20 -- .../preprocessing/loaders/youtube.loader.ts | 6 +- .../src/modules/remote_fs/rfs.route.test.ts | 61 +++--- .../server/src/modules/remote_fs/rfs.route.ts | 200 ++++++++---------- apps/server/src/modules/services/index.ts | 20 ++ .../package-loader.test.ts | 16 +- .../package-loader.ts | 48 ++--- .../provisioner.test.ts} | 12 +- .../provisioner.ts} | 132 ++++++------ .../services.route.test.ts} | 26 +-- .../src/modules/services/services.route.ts | 97 +++++++++ .../src/prompt/external-agent/access-huabu.md | 20 +- apps/server/src/services/image-gen/SKILL.md | 7 + .../image-gen/client.mjs | 0 .../image-gen/client.test.ts | 8 +- .../image-gen/service.yaml} | 2 +- .../ink-ocr/service.yaml} | 2 +- apps/server/src/services/web-search/SKILL.md | 5 + .../web-search/client.mjs | 0 .../web-search/client.test.ts | 8 +- .../web-search/service.yaml} | 2 +- .../youtube-transcripts/service.yaml} | 2 +- apps/server/tsup.config.ts | 12 +- apps/web/src/api/_routes.ts | 4 +- apps/web/src/api/capabilities.ts | 34 --- apps/web/src/api/services.ts | 34 +++ .../Settings/SettingsModal.test.tsx | 16 +- .../src/components/Settings/SettingsModal.tsx | 16 +- ...ngs.test.tsx => ServicesSettings.test.tsx} | 34 +-- ...itiesSettings.tsx => ServicesSettings.tsx} | 52 ++--- apps/web/src/i18n/resources/en/common.json | 4 +- apps/web/src/i18n/resources/zh-CN/common.json | 4 +- apps/web/src/store/settingsUiStore.ts | 2 +- docs/README.md | 4 +- docs/architecture/agent-profiles.md | 2 +- docs/architecture/agent-reachback.md | 44 ++-- docs/architecture/api-design.md | 6 +- docs/architecture/capability-packages.md | 101 --------- docs/architecture/credential-storage.md | 6 +- docs/architecture/service-packages.md | 101 +++++++++ ...bility-packages.md => service-packages.md} | 20 +- packages/shared/src/types/api/index.ts | 2 +- ...ackage.test.ts => service-package.test.ts} | 20 +- ...pability-package.ts => service-package.ts} | 82 ++++--- 52 files changed, 700 insertions(+), 732 deletions(-) delete mode 100644 apps/server/src/capabilities/image-gen/SKILL.md delete mode 100644 apps/server/src/capabilities/web-search/SKILL.md delete mode 100644 apps/server/src/modules/capabilities/capabilities.route.ts delete mode 100644 apps/server/src/modules/capabilities/index.ts create mode 100644 apps/server/src/modules/services/index.ts rename apps/server/src/modules/{capabilities => services}/package-loader.test.ts (63%) rename apps/server/src/modules/{capabilities => services}/package-loader.ts (51%) rename apps/server/src/modules/{capabilities/provision-service.test.ts => services/provisioner.test.ts} (91%) rename apps/server/src/modules/{capabilities/provision-service.ts => services/provisioner.ts} (73%) rename apps/server/src/modules/{capabilities/capabilities.route.test.ts => services/services.route.test.ts} (84%) create mode 100644 apps/server/src/modules/services/services.route.ts create mode 100644 apps/server/src/services/image-gen/SKILL.md rename apps/server/src/{capabilities => services}/image-gen/client.mjs (100%) rename apps/server/src/{capabilities => services}/image-gen/client.test.ts (89%) rename apps/server/src/{capabilities/image-gen/capability.yaml => services/image-gen/service.yaml} (97%) rename apps/server/src/{capabilities/ink-ocr/capability.yaml => services/ink-ocr/service.yaml} (93%) create mode 100644 apps/server/src/services/web-search/SKILL.md rename apps/server/src/{capabilities => services}/web-search/client.mjs (100%) rename apps/server/src/{capabilities => services}/web-search/client.test.ts (85%) rename apps/server/src/{capabilities/web-search/capability.yaml => services/web-search/service.yaml} (91%) rename apps/server/src/{capabilities/youtube-transcripts/capability.yaml => services/youtube-transcripts/service.yaml} (91%) delete mode 100644 apps/web/src/api/capabilities.ts create mode 100644 apps/web/src/api/services.ts rename apps/web/src/components/Settings/sections/{CapabilitiesSettings.test.tsx => ServicesSettings.test.tsx} (68%) rename apps/web/src/components/Settings/sections/{CapabilitiesSettings.tsx => ServicesSettings.tsx} (87%) delete mode 100644 docs/architecture/capability-packages.md create mode 100644 docs/architecture/service-packages.md rename docs/proposals/{capability-packages.md => service-packages.md} (53%) rename packages/shared/src/types/api/{capability-package.test.ts => service-package.test.ts} (67%) rename packages/shared/src/types/api/{capability-package.ts => service-package.ts} (53%) diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index 7876a9af3..a819fb770 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -41,7 +41,6 @@ import canvasRoutes from './modules/canvas/canvas.route.js'; import { resetExternalNoteSessions } from './modules/canvas/external-watcher.js'; import externalNoteRoutes from './modules/canvas/external.route.js'; import syncRoutes from './modules/canvas/sync.route.js'; -import capabilityRoutes from './modules/capabilities/capabilities.route.js'; import integrationsRoutes from './modules/integrations/integrations.route.js'; import interactiveViewRoutes from './modules/interactive-view/interactive-view.route.js'; import { isPublicRfsSkillBootstrapRequest } from './modules/remote_fs/public-skill.js'; @@ -56,6 +55,7 @@ import { resolveAllowedHostnames, } from './modules/security/index.js'; import { createApplicationRateLimitOptions } from './modules/security/rate-limit.js'; +import serviceRoutes from './modules/services/services.route.js'; import { closeStorage } from './modules/storage/index.js'; import webRoutes from './modules/web/web.route.js'; import { @@ -238,7 +238,7 @@ app.addHook('preHandler', async (request, reply) => { !url.startsWith('/api/deployment') && !url.startsWith('/api/llm') && !url.startsWith('/api/integrations') && - !url.startsWith('/api/capabilities') + !url.startsWith('/api/services') ) { return reply.status(503).send({ message: @@ -259,7 +259,7 @@ app.register(artifactRoute, { prefix: '/api/canvas' }); app.register(llmRoutes, { prefix: '/api/llm' }); app.register(integrationsRoutes, { prefix: '/api/integrations' }); -app.register(capabilityRoutes, { prefix: '/api/capabilities' }); +app.register(serviceRoutes, { prefix: '/api/services' }); app.register(deploymentRoutes, { prefix: '/api/deployment' }); app.register(canaryRedeployRoutes, { prefix: '/api/deployment/canary', diff --git a/apps/server/src/capabilities/image-gen/SKILL.md b/apps/server/src/capabilities/image-gen/SKILL.md deleted file mode 100644 index e23ba3f3b..000000000 --- a/apps/server/src/capabilities/image-gen/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ -# Image Generation - -Use this Capability when the user asks you to generate an image through their configured Azure OpenAI image deployment. - -Load the Capability through the Agentlet SDK URL in `AGENTLET_CAPABILITY_SDK_URL`. Call the returned client's `generate()` method with a non-empty `prompt` and optional provider-supported image parameters. Provider credentials are supplied only to the loaded client; never print, persist, or include them in another request. - -The client returns the provider response. Decode or upload generated image bytes through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. diff --git a/apps/server/src/capabilities/web-search/SKILL.md b/apps/server/src/capabilities/web-search/SKILL.md deleted file mode 100644 index 1f9006be9..000000000 --- a/apps/server/src/capabilities/web-search/SKILL.md +++ /dev/null @@ -1,5 +0,0 @@ -# Web Search - -Use this Capability for current public web information when ordinary local knowledge is insufficient. - -Load it through the Agentlet SDK URL in `AGENTLET_CAPABILITY_SDK_URL`, then call the returned client's `search()` method with a non-empty query. Never print or persist the supplied credential. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. diff --git a/apps/server/src/modules/agent/conversation/ink-ocr.test.ts b/apps/server/src/modules/agent/conversation/ink-ocr.test.ts index 4d650cbff..966ce6453 100644 --- a/apps/server/src/modules/agent/conversation/ink-ocr.test.ts +++ b/apps/server/src/modules/agent/conversation/ink-ocr.test.ts @@ -6,8 +6,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { isInkOcrConfigured, recognizeInk } from './ink-ocr.js'; -vi.mock('../../capabilities/index.js', () => ({ - capabilityProvisionService: { +vi.mock('../../services/index.js', () => ({ + serviceProvisioner: { getConfig: () => { const apiKey = process.env.VISION_KEY?.trim() || ''; const endpoint = process.env.VISION_ENDPOINT?.trim() || ''; diff --git a/apps/server/src/modules/agent/conversation/ink-ocr.ts b/apps/server/src/modules/agent/conversation/ink-ocr.ts index ddd620113..30d0dbba2 100644 --- a/apps/server/src/modules/agent/conversation/ink-ocr.ts +++ b/apps/server/src/modules/agent/conversation/ink-ocr.ts @@ -5,7 +5,7 @@ import { z } from 'zod'; import { inkOcrEndpointSchema, inkRecognitionSchema } from '@huabu/shared'; -import { capabilityProvisionService } from '../../capabilities/index.js'; +import { serviceProvisioner } from '../../services/index.js'; import type { InkRecognition } from '@huabu/shared'; import type { FastifyBaseLogger } from 'fastify'; @@ -73,14 +73,14 @@ class InvalidResultError extends Error {} function readConfiguration(): Configuration { try { - const snapshot = capabilityProvisionService.getConfig('ink-ocr'); + const snapshot = serviceProvisioner.getConfig('ink-ocr'); if (!snapshot.configured) { return { outcome: snapshot.configuredFields.length === 0 ? 'disabled' : 'config_error', }; } - const resolved = capabilityProvisionService.resolveForServer('ink-ocr'); + const resolved = serviceProvisioner.resolveForServer('ink-ocr'); const key = typeof resolved.apiKey === 'string' ? resolved.apiKey : ''; const endpoint = typeof resolved.endpoint === 'string' ? resolved.endpoint : ''; diff --git a/apps/server/src/modules/agent/tools/handlers/image-generation.ts b/apps/server/src/modules/agent/tools/handlers/image-generation.ts index 63f07a353..2b2f2299b 100644 --- a/apps/server/src/modules/agent/tools/handlers/image-generation.ts +++ b/apps/server/src/modules/agent/tools/handlers/image-generation.ts @@ -52,7 +52,7 @@ import { } from '@huabu/shared'; import { getLogger } from '../../../../utils/logger.js'; -import { capabilityProvisionService } from '../../../capabilities/index.js'; +import { serviceProvisioner } from '../../../services/index.js'; import { space } from '../../../storage/index.js'; import type { generateImageParamsSchema } from '../definitions.js'; @@ -97,7 +97,7 @@ export async function handleGenerateImage( } const refs = args.referenceArtifactSrcs ?? []; - const resolved = capabilityProvisionService.resolveForServer('image-gen'); + const resolved = serviceProvisioner.resolveForServer('image-gen'); const azure = { endpoint: String(resolved.baseUrl), deployment: String(resolved.model), diff --git a/apps/server/src/modules/agent/tools/handlers/web-search.ts b/apps/server/src/modules/agent/tools/handlers/web-search.ts index fdce3d69f..40a8269dd 100644 --- a/apps/server/src/modules/agent/tools/handlers/web-search.ts +++ b/apps/server/src/modules/agent/tools/handlers/web-search.ts @@ -15,7 +15,7 @@ */ import { getLogger } from '../../../../utils/logger.js'; -import { capabilityProvisionService } from '../../../capabilities/index.js'; +import { serviceProvisioner } from '../../../services/index.js'; import type { webSearchParamsSchema } from '../definitions.js'; import type { Static } from '@earendil-works/pi-ai'; @@ -25,7 +25,7 @@ const log = getLogger('tool.web-search'); export type WebSearchArgs = Static; export async function handleWebSearch(args: WebSearchArgs): Promise { - const resolved = capabilityProvisionService.resolveForServer('web-search'); + const resolved = serviceProvisioner.resolveForServer('web-search'); const apiKey = typeof resolved.apiKey === 'string' ? resolved.apiKey : ''; const controller = new AbortController(); diff --git a/apps/server/src/modules/capabilities/capabilities.route.ts b/apps/server/src/modules/capabilities/capabilities.route.ts deleted file mode 100644 index 75a9a91cd..000000000 --- a/apps/server/src/modules/capabilities/capabilities.route.ts +++ /dev/null @@ -1,102 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -import { - capabilityConfigUpdateSchema, - capabilityParamsSchema, -} from '@huabu/shared'; - -import { isOwnerRequest } from '../security/owner.js'; - -import { capabilityProvisionService, CapabilityServiceError } from './index.js'; - -import type { - ApiResult, - CapabilityConfig, - CapabilityConfigUpdate, - CapabilityListResponse, - CapabilityParams, -} from '@huabu/shared'; -import type { FastifyPluginAsync } from 'fastify'; - -function statusFor(error: CapabilityServiceError): number { - switch (error.code) { - case 'capability_not_found': - return 404; - case 'invalid_capability_config': - return 400; - default: - return 409; - } -} - -const capabilityRoutes: FastifyPluginAsync = async (app) => { - app.get<{ Reply: ApiResult }>('/', async () => ({ - capabilities: capabilityProvisionService.list(), - })); - - app.get<{ - Params: CapabilityParams; - Reply: ApiResult; - }>('/:capabilityId', async (request, reply) => { - const parsed = capabilityParamsSchema.safeParse(request.params); - if (!parsed.success) { - return reply.code(400).send({ - message: parsed.error.issues[0]?.message ?? 'Invalid Capability id', - }); - } - try { - return reply.send( - capabilityProvisionService.getConfig(parsed.data.capabilityId), - ); - } catch (error) { - if (error instanceof CapabilityServiceError) { - return reply - .code(statusFor(error)) - .send({ message: error.message, code: error.code }); - } - throw error; - } - }); - - app.put<{ - Params: CapabilityParams; - Body: CapabilityConfigUpdate; - Reply: ApiResult; - }>('/:capabilityId', async (request, reply) => { - if (!isOwnerRequest(request)) { - return reply.code(403).send({ - message: 'Forbidden: Capability settings require owner authorization', - }); - } - const params = capabilityParamsSchema.safeParse(request.params); - const body = capabilityConfigUpdateSchema.safeParse(request.body); - if (!params.success || !body.success) { - const issue = !params.success - ? params.error.issues[0] - : !body.success - ? body.error.issues[0] - : undefined; - return reply.code(400).send({ - message: issue?.message ?? 'Invalid Capability update', - }); - } - try { - return reply.send( - await capabilityProvisionService.updateConfig( - params.data.capabilityId, - body.data.values, - ), - ); - } catch (error) { - if (error instanceof CapabilityServiceError) { - return reply - .code(statusFor(error)) - .send({ message: error.message, code: error.code }); - } - throw error; - } - }); -}; - -export default capabilityRoutes; diff --git a/apps/server/src/modules/capabilities/index.ts b/apps/server/src/modules/capabilities/index.ts deleted file mode 100644 index c4a8f8011..000000000 --- a/apps/server/src/modules/capabilities/index.ts +++ /dev/null @@ -1,20 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -import { getBundledCapabilityPackages } from './package-loader.js'; -import { CapabilityProvisionService } from './provision-service.js'; - -export const capabilityProvisionService = new CapabilityProvisionService( - new Map( - [...getBundledCapabilityPackages()].map(([id, capability]) => [ - id, - capability.manifest, - ]), - ), -); - -export { - getBundledCapabilityPackage, - readCapabilityPackageFile, -} from './package-loader.js'; -export { CapabilityServiceError } from './provision-service.js'; diff --git a/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts b/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts index a985815d6..eaba92a33 100644 --- a/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts +++ b/apps/server/src/modules/preprocessing/loaders/youtube.loader.ts @@ -3,16 +3,14 @@ import { extractYoutubeVideoId } from './youtube-id.js'; import { getLogger } from '../../../utils/logger.js'; -import { capabilityProvisionService } from '../../capabilities/index.js'; +import { serviceProvisioner } from '../../services/index.js'; import type { IDocumentLoader, LoadResult } from './loader.interface.js'; const log = getLogger('preprocessing.youtube'); function resolveRapidApiKey(): string { - const resolved = capabilityProvisionService.resolveForServer( - 'youtube-transcripts', - ); + const resolved = serviceProvisioner.resolveForServer('youtube-transcripts'); return typeof resolved.apiKey === 'string' ? resolved.apiKey : ''; } diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index 31d307f1b..7b6d1a262 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -35,7 +35,7 @@ const agentMocks = vi.hoisted(() => ({ handleRun: vi.fn(), })); -const capabilityMocks = vi.hoisted(() => ({ +const serviceMocks = vi.hoisted(() => ({ lease: vi.fn(), list: vi.fn(), })); @@ -52,11 +52,11 @@ vi.mock('../agent/agenetes/drivers.js', () => ({ }, })); -vi.mock('../capabilities/index.js', async (importOriginal) => { - const actual = await importOriginal(); +vi.mock('../services/index.js', async (importOriginal) => { + const actual = await importOriginal(); return { ...actual, - capabilityProvisionService: capabilityMocks, + serviceProvisioner: serviceMocks, }; }); @@ -69,7 +69,7 @@ import { agentThreadService, } from '../agent/agent-thread.service.js'; import * as selectableProfiles from '../agent/selectable-agent-profile.js'; -import { CapabilityServiceError } from '../capabilities/index.js'; +import { ServiceProvisionError } from '../services/index.js'; import { getCanvasStore, resetStorageCache, space } from '../storage/index.js'; import { RunCompletionError, @@ -80,7 +80,7 @@ import { taskService } from '../task/task.service.js'; import { setWorkspacePath } from '../workspace.js'; import type { FixedAgentNodeTarget } from '../agent/agent-thread-resolver.js'; -import type * as CapabilityModule from '../capabilities/index.js'; +import type * as ServiceModule from '../services/index.js'; import type { CanvasNodeId } from '@huabu/shared'; /** @@ -187,8 +187,8 @@ beforeEach(() => { agentMocks.record.mockReset(); agentMocks.get.mockReset(); agentMocks.handleRun.mockReset(); - capabilityMocks.lease.mockReset(); - capabilityMocks.list.mockReset(); + serviceMocks.lease.mockReset(); + serviceMocks.list.mockReset(); agentMocks.runAgent.mockImplementation(async function* () { yield { type: 'done', data: { message: 'first answer' } }; return []; @@ -216,8 +216,8 @@ describe('GET /api/rfs/:canvasId/skill', () => { ); } expect(res.body).toContain('/capabilities/commands/$COMMAND'); - expect(res.body).toContain('AGENTLET_CAPABILITY_SDK_URL'); - expect(res.body).toContain('/capability-packages'); + expect(res.body).toContain('AGENTLET_SERVICE_SDK_URL'); + expect(res.body).toContain('/services'); expect(res.body).toContain('$HUABU_RFS_URL/skill/tasks'); expect(res.body).toContain('**parent-local**'); expect(res.body).toContain('read-only `absolutePosition`'); @@ -594,9 +594,9 @@ describe('Task RFS adapters', () => { }); }); -describe('provider Capability Packages', () => { +describe('third-party Services', () => { it('publishes discovery and package files without configuration secrets', async () => { - capabilityMocks.list.mockReturnValue([ + serviceMocks.list.mockReturnValue([ { id: 'image-gen', version: '1.0.0', @@ -610,24 +610,24 @@ describe('provider Capability Packages', () => { try { const discovery = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages', + url: '/rfs/c1/services', }); const manifest = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages/image-gen/manifest', + url: '/rfs/c1/services/image-gen/manifest', }); const skill = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages/image-gen/skill', + url: '/rfs/c1/services/image-gen/skill', }); const client = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages/image-gen/client', + url: '/rfs/c1/services/image-gen/client', }); expect(discovery.statusCode).toBe(200); expect(discovery.json()).toMatchObject({ - capabilities: [{ id: 'image-gen', configured: true }], + services: [{ id: 'image-gen', configured: true }], }); expect(manifest.statusCode).toBe(200); expect(manifest.json()).toMatchObject({ @@ -654,15 +654,15 @@ describe('provider Capability Packages', () => { try { const noSkill = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages/ink-ocr/skill', + url: '/rfs/c1/services/ink-ocr/skill', }); const noClient = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages/youtube-transcripts/client', + url: '/rfs/c1/services/youtube-transcripts/client', }); const invalid = await app.inject({ method: 'GET', - url: '/rfs/c1/capability-packages/INVALID/manifest', + url: '/rfs/c1/services/INVALID/manifest', }); expect(noSkill.statusCode).toBe(404); @@ -676,36 +676,37 @@ describe('provider Capability Packages', () => { }); it('returns a no-store lease and maps provisioning failures', async () => { - capabilityMocks.lease.mockReturnValueOnce({ - capabilityId: 'image-gen', + serviceMocks.lease.mockReturnValueOnce({ + id: 'image-gen', + version: '1.0.0', config: { apiKey: 'test-secret' }, }); const app = await buildApp(); try { const lease = await app.inject({ method: 'POST', - url: '/rfs/c1/capability-packages/image-gen/lease', + url: '/rfs/c1/services/image-gen/lease', }); expect(lease.statusCode).toBe(200); expect(lease.headers['cache-control']).toBe('no-store'); expect(lease.json()).toMatchObject({ - capabilityId: 'image-gen', + id: 'image-gen', config: { apiKey: 'test-secret' }, }); - capabilityMocks.lease.mockImplementationOnce(() => { - throw new CapabilityServiceError( - 'capability_not_external', - 'Capability is not available to External Agents', + serviceMocks.lease.mockImplementationOnce(() => { + throw new ServiceProvisionError( + 'service_not_agent_accessible', + 'Service is not available to External Agents', ); }); const rejected = await app.inject({ method: 'POST', - url: '/rfs/c1/capability-packages/ink-ocr/lease', + url: '/rfs/c1/services/ink-ocr/lease', }); expect(rejected.statusCode).toBe(403); expect(rejected.json()).toMatchObject({ - code: 'capability_not_external', + code: 'service_not_agent_accessible', }); } finally { await app.close(); diff --git a/apps/server/src/modules/remote_fs/rfs.route.ts b/apps/server/src/modules/remote_fs/rfs.route.ts index 308010a79..b2a5adcbe 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.ts @@ -44,7 +44,7 @@ import { createTaskRequestSchema, completeTaskRunRequestSchema, createInteractiveViewRequestSchema, - capabilityParamsSchema, + serviceParamsSchema, interactiveViewLookupQuerySchema, interactiveViewResourceParamsSchema, rfsAgentCreateHeadersSchema, @@ -70,7 +70,7 @@ import { type RfsUploadResponse, type AgentStreamEvent, type StartTaskRunResponse, - type CapabilityParams, + type ServiceParams, } from '@huabu/shared'; import { mimeForPath } from './mime.js'; @@ -118,16 +118,16 @@ import { import { CanvasNotFoundError } from '../canvas/canvas-executor.js'; import { executeSpaceQuery, SpaceQueryError } from '../canvas/space-query.js'; import { WorldPreviewMutationError } from '../canvas/world-preview-policy.js'; -import { - capabilityProvisionService, - CapabilityServiceError, - getBundledCapabilityPackage, - readCapabilityPackageFile, -} from '../capabilities/index.js'; import { InteractiveViewServiceError, interactiveViewService, } from '../interactive-view/interactive-view.service.js'; +import { + serviceProvisioner, + ServiceProvisionError, + getBundledServicePackage, + readServicePackageFile, +} from '../services/index.js'; import { storageServes, unavailableCapabilityMessage, @@ -531,117 +531,105 @@ const rfsRoutes: FastifyPluginAsync = async (app) => { reply.send(getRfsCapabilities()), ); - // ── Capability Packages ── + // ── Service Packages ── // // `/capabilities` already owns direct Space-operation discovery. Keep the - // portable provider packages under a separate unambiguous resource root. - app.get('/:canvasId/capability-packages', async (_request, reply) => - reply.send({ capabilities: capabilityProvisionService.list() }), + // configured third-party services under a separate unambiguous root. + app.get('/:canvasId/services', async (_request, reply) => + reply.send({ services: serviceProvisioner.list() }), ); app.get<{ - Params: CapabilityParams & { canvasId: string }; - }>( - '/:canvasId/capability-packages/:capabilityId/manifest', - async (request, reply) => { - const parsed = capabilityParamsSchema.safeParse({ - capabilityId: request.params.capabilityId, - }); - if (!parsed.success) { - return reply.code(400).send(rfsError('Invalid Capability id')); - } - const capability = getBundledCapabilityPackage(parsed.data.capabilityId); - if (!capability) { - return reply - .code(404) - .send(rfsError('Capability not found', 'capability_not_found')); - } - return reply.send(capability.manifest); - }, - ); + Params: ServiceParams & { canvasId: string }; + }>('/:canvasId/services/:serviceId/manifest', async (request, reply) => { + const parsed = serviceParamsSchema.safeParse({ + serviceId: request.params.serviceId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Service id')); + } + const service = getBundledServicePackage(parsed.data.serviceId); + if (!service) { + return reply + .code(404) + .send(rfsError('Service not found', 'service_not_found')); + } + return reply.send(service.manifest); + }); app.get<{ - Params: CapabilityParams & { canvasId: string }; - }>( - '/:canvasId/capability-packages/:capabilityId/skill', - async (request, reply) => { - const parsed = capabilityParamsSchema.safeParse({ - capabilityId: request.params.capabilityId, - }); - if (!parsed.success) { - return reply.code(400).send(rfsError('Invalid Capability id')); - } - const capability = getBundledCapabilityPackage(parsed.data.capabilityId); - const skill = capability?.manifest.agent?.skill; - const content = skill - ? readCapabilityPackageFile(parsed.data.capabilityId, skill) - : null; - if (!content) { - return reply - .code(404) - .send(rfsError('Capability Skill not found', 'skill_not_found')); - } - return reply.type('text/markdown; charset=utf-8').send(content); - }, - ); + Params: ServiceParams & { canvasId: string }; + }>('/:canvasId/services/:serviceId/skill', async (request, reply) => { + const parsed = serviceParamsSchema.safeParse({ + serviceId: request.params.serviceId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Service id')); + } + const service = getBundledServicePackage(parsed.data.serviceId); + const skill = service?.manifest.agent?.skill; + const content = skill + ? readServicePackageFile(parsed.data.serviceId, skill) + : null; + if (!content) { + return reply + .code(404) + .send(rfsError('Service Skill not found', 'skill_not_found')); + } + return reply.type('text/markdown; charset=utf-8').send(content); + }); app.get<{ - Params: CapabilityParams & { canvasId: string }; - }>( - '/:canvasId/capability-packages/:capabilityId/client', - async (request, reply) => { - const parsed = capabilityParamsSchema.safeParse({ - capabilityId: request.params.capabilityId, - }); - if (!parsed.success) { - return reply.code(400).send(rfsError('Invalid Capability id')); - } - const capability = getBundledCapabilityPackage(parsed.data.capabilityId); - const client = capability?.manifest.agent?.client; - const content = client - ? readCapabilityPackageFile(parsed.data.capabilityId, client) - : null; - if (!content) { - return reply - .code(404) - .send(rfsError('Capability client not found', 'client_not_found')); - } + Params: ServiceParams & { canvasId: string }; + }>('/:canvasId/services/:serviceId/client', async (request, reply) => { + const parsed = serviceParamsSchema.safeParse({ + serviceId: request.params.serviceId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Service id')); + } + const service = getBundledServicePackage(parsed.data.serviceId); + const client = service?.manifest.agent?.client; + const content = client + ? readServicePackageFile(parsed.data.serviceId, client) + : null; + if (!content) { return reply - .header('Cache-Control', 'public, max-age=300') - .type('text/javascript; charset=utf-8') - .send(content); - }, - ); + .code(404) + .send(rfsError('Service client not found', 'client_not_found')); + } + return reply + .header('Cache-Control', 'public, max-age=300') + .type('text/javascript; charset=utf-8') + .send(content); + }); app.post<{ - Params: CapabilityParams & { canvasId: string }; - }>( - '/:canvasId/capability-packages/:capabilityId/lease', - async (request, reply) => { - const parsed = capabilityParamsSchema.safeParse({ - capabilityId: request.params.capabilityId, - }); - if (!parsed.success) { - return reply.code(400).send(rfsError('Invalid Capability id')); - } - try { - return reply - .header('Cache-Control', 'no-store') - .send(capabilityProvisionService.lease(parsed.data.capabilityId)); - } catch (error) { - if (error instanceof CapabilityServiceError) { - const status = - error.code === 'capability_not_found' - ? 404 - : error.code === 'capability_not_external' - ? 403 - : 409; - return reply.code(status).send(rfsError(error.message, error.code)); - } - throw error; + Params: ServiceParams & { canvasId: string }; + }>('/:canvasId/services/:serviceId/lease', async (request, reply) => { + const parsed = serviceParamsSchema.safeParse({ + serviceId: request.params.serviceId, + }); + if (!parsed.success) { + return reply.code(400).send(rfsError('Invalid Service id')); + } + try { + return reply + .header('Cache-Control', 'no-store') + .send(serviceProvisioner.lease(parsed.data.serviceId)); + } catch (error) { + if (error instanceof ServiceProvisionError) { + const status = + error.code === 'service_not_found' + ? 404 + : error.code === 'service_not_agent_accessible' + ? 403 + : 409; + return reply.code(status).send(rfsError(error.message, error.code)); } - }, - ); + throw error; + } + }); app.get<{ Params: { canvasId: string; type: string } }>( '/:canvasId/capabilities/queries/:type', diff --git a/apps/server/src/modules/services/index.ts b/apps/server/src/modules/services/index.ts new file mode 100644 index 000000000..40b23b3a1 --- /dev/null +++ b/apps/server/src/modules/services/index.ts @@ -0,0 +1,20 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { getBundledServicePackages } from './package-loader.js'; +import { ServiceProvisioner } from './provisioner.js'; + +export const serviceProvisioner = new ServiceProvisioner( + new Map( + [...getBundledServicePackages()].map(([id, service]) => [ + id, + service.manifest, + ]), + ), +); + +export { + getBundledServicePackage, + readServicePackageFile, +} from './package-loader.js'; +export { ServiceProvisionError } from './provisioner.js'; diff --git a/apps/server/src/modules/capabilities/package-loader.test.ts b/apps/server/src/modules/services/package-loader.test.ts similarity index 63% rename from apps/server/src/modules/capabilities/package-loader.test.ts rename to apps/server/src/modules/services/package-loader.test.ts index aec417754..31333dbfb 100644 --- a/apps/server/src/modules/capabilities/package-loader.test.ts +++ b/apps/server/src/modules/services/package-loader.test.ts @@ -4,13 +4,13 @@ import { describe, expect, it } from 'vitest'; import { - getBundledCapabilityPackages, - readCapabilityPackageFile, + getBundledServicePackages, + readServicePackageFile, } from './package-loader.js'; -describe('bundled Capability packages', () => { - it('loads all current Settings capabilities from validated YAML', () => { - const packages = getBundledCapabilityPackages(); +describe('bundled Service packages', () => { + it('loads all current Settings services from validated YAML', () => { + const packages = getBundledServicePackages(); expect([...packages.keys()]).toEqual([ 'image-gen', 'web-search', @@ -25,14 +25,14 @@ describe('bundled Capability packages', () => { }); it('exposes real Agent files only when the manifest declares Agent behavior', () => { - expect(readCapabilityPackageFile('image-gen', 'SKILL.md')).toContain( + expect(readServicePackageFile('image-gen', 'SKILL.md')).toContain( '# Image Generation', ); - expect(readCapabilityPackageFile('web-search', 'client.mjs')).toContain( + expect(readServicePackageFile('web-search', 'client.mjs')).toContain( 'createClient', ); expect( - readCapabilityPackageFile('youtube-transcripts', 'SKILL.md'), + readServicePackageFile('youtube-transcripts', 'SKILL.md'), ).toBeNull(); }); }); diff --git a/apps/server/src/modules/capabilities/package-loader.ts b/apps/server/src/modules/services/package-loader.ts similarity index 51% rename from apps/server/src/modules/capabilities/package-loader.ts rename to apps/server/src/modules/services/package-loader.ts index ebf40ff73..a402b8b56 100644 --- a/apps/server/src/modules/capabilities/package-loader.ts +++ b/apps/server/src/modules/services/package-loader.ts @@ -7,11 +7,11 @@ import { fileURLToPath } from 'node:url'; import { parse } from 'yaml'; -import { capabilityManifestSchema } from '@huabu/shared'; +import { serviceManifestSchema } from '@huabu/shared'; import { resolveDirectChildPath, safeJoin } from '../../utils/fs.js'; -import type { CapabilityManifest } from '@huabu/shared'; +import type { ServiceManifest } from '@huabu/shared'; const PACKAGE_IDS = [ 'image-gen', @@ -20,33 +20,31 @@ const PACKAGE_IDS = [ 'ink-ocr', ] as const; -export interface BundledCapabilityPackage { +export interface BundledServicePackage { root: string; - manifest: CapabilityManifest; + manifest: ServiceManifest; } function packageRoot(): string { const moduleDir = dirname(fileURLToPath(import.meta.url)); - const bundled = resolve(moduleDir, 'capabilities'); + const bundled = resolve(moduleDir, 'services'); if (existsSync(bundled)) return bundled; - return resolve(moduleDir, '../../capabilities'); + return resolve(moduleDir, '../../services'); } function readPackage(packageId: (typeof PACKAGE_IDS)[number]) { const root = resolveDirectChildPath(packageRoot(), packageId); - const manifestPath = resolveDirectChildPath(root, 'capability.yaml'); - const parsed = capabilityManifestSchema.safeParse( + const manifestPath = resolveDirectChildPath(root, 'service.yaml'); + const parsed = serviceManifestSchema.safeParse( parse(readFileSync(manifestPath, 'utf8')), ); if (!parsed.success) { throw new Error( - `Invalid bundled Capability manifest "${packageId}": ${parsed.error.issues[0]?.message ?? 'unknown error'}`, + `Invalid bundled Service manifest "${packageId}": ${parsed.error.issues[0]?.message ?? 'unknown error'}`, ); } if (parsed.data.id !== packageId) { - throw new Error( - `Capability package directory must match id "${packageId}"`, - ); + throw new Error(`Service package directory must match id "${packageId}"`); } for (const file of [ parsed.data.agent?.skill, @@ -54,34 +52,34 @@ function readPackage(packageId: (typeof PACKAGE_IDS)[number]) { ].filter((value): value is string => Boolean(value))) { const filePath = safeJoin(root, file); if (!existsSync(filePath)) { - throw new Error(`Capability "${packageId}" references missing file`); + throw new Error(`Service "${packageId}" references missing file`); } } return { root, manifest: parsed.data }; } -let packages: ReadonlyMap | null = null; +let packages: ReadonlyMap | null = null; -export function getBundledCapabilityPackages(): ReadonlyMap< +export function getBundledServicePackages(): ReadonlyMap< string, - BundledCapabilityPackage + BundledServicePackage > { packages ??= new Map(PACKAGE_IDS.map((id) => [id, readPackage(id)])); return packages; } -export function getBundledCapabilityPackage( - capabilityId: string, -): BundledCapabilityPackage | undefined { - return getBundledCapabilityPackages().get(capabilityId); +export function getBundledServicePackage( + serviceId: string, +): BundledServicePackage | undefined { + return getBundledServicePackages().get(serviceId); } -export function readCapabilityPackageFile( - capabilityId: string, +export function readServicePackageFile( + serviceId: string, file: string, ): string | null { - const capability = getBundledCapabilityPackage(capabilityId); - if (!capability) return null; - const filePath = safeJoin(capability.root, file); + const service = getBundledServicePackage(serviceId); + if (!service) return null; + const filePath = safeJoin(service.root, file); return existsSync(filePath) ? readFileSync(filePath, 'utf8') : null; } diff --git a/apps/server/src/modules/capabilities/provision-service.test.ts b/apps/server/src/modules/services/provisioner.test.ts similarity index 91% rename from apps/server/src/modules/capabilities/provision-service.test.ts rename to apps/server/src/modules/services/provisioner.test.ts index 510dccb42..85e8855c0 100644 --- a/apps/server/src/modules/capabilities/provision-service.test.ts +++ b/apps/server/src/modules/services/provisioner.test.ts @@ -56,15 +56,15 @@ vi.mock('../../security/secret-store.js', () => ({ getSecret: () => 'image-secret', })); -import { getBundledCapabilityPackages } from './package-loader.js'; -import { CapabilityProvisionService } from './provision-service.js'; +import { getBundledServicePackages } from './package-loader.js'; +import { ServiceProvisioner } from './provisioner.js'; function service() { - return new CapabilityProvisionService( + return new ServiceProvisioner( new Map( - [...getBundledCapabilityPackages()].map(([id, capability]) => [ + [...getBundledServicePackages()].map(([id, service]) => [ id, - capability.manifest, + service.manifest, ]), ), ); @@ -74,7 +74,7 @@ beforeEach(() => { vi.clearAllMocks(); }); -describe('Capability Provision Service storage bindings', () => { +describe('Service Provision Service storage bindings', () => { it('reads every existing owner without causing a persistence write', () => { const provision = service(); diff --git a/apps/server/src/modules/capabilities/provision-service.ts b/apps/server/src/modules/services/provisioner.ts similarity index 73% rename from apps/server/src/modules/capabilities/provision-service.ts rename to apps/server/src/modules/services/provisioner.ts index d081b0c92..93bdf4fb7 100644 --- a/apps/server/src/modules/capabilities/provision-service.ts +++ b/apps/server/src/modules/services/provisioner.ts @@ -28,42 +28,42 @@ import { } from '../integrations/integrations.js'; import type { - CapabilityConfig, - CapabilityFieldValue, - CapabilityLease, - CapabilityManifest, - CapabilitySummary, + ServiceConfig, + ServiceFieldValue, + ServiceLease, + ServiceManifest, + ServiceSummary, ImageModelFamily, LLMImageConfigUpdate, } from '@huabu/shared'; interface AdapterSnapshot { - values: Record; + values: Record; configuredFields: string[]; } -interface CapabilityStorageAdapter { +interface ServiceStorageAdapter { read(): AdapterSnapshot; - update(values: Readonly>): Promise; - resolve(): Record; + update(values: Readonly>): Promise; + resolve(): Record; } -export class CapabilityServiceError extends Error { +export class ServiceProvisionError extends Error { constructor( readonly code: - | 'capability_not_found' - | 'capability_not_external' - | 'capability_not_configured' - | 'invalid_capability_config', + | 'service_not_found' + | 'service_not_agent_accessible' + | 'service_not_configured' + | 'invalid_service_config', message: string, ) { super(message); - this.name = 'CapabilityServiceError'; + this.name = 'ServiceProvisionError'; } } function presentFields( - values: Readonly>, + values: Readonly>, ): string[] { return Object.entries(values) .filter(([, value]) => @@ -75,7 +75,7 @@ function presentFields( function imageSnapshot(): AdapterSnapshot { const stored = getImageConfig(); const modelFamily = stored.modelFamily ?? DEFAULT_IMAGE_MODEL_FAMILY; - const values: Record = { + const values: Record = { provider: stored.provider || 'azure-openai', baseUrl: stored.baseUrl ?? '', modelFamily, @@ -91,7 +91,7 @@ function imageSnapshot(): AdapterSnapshot { return { values, configuredFields }; } -const imageAdapter: CapabilityStorageAdapter = { +const imageAdapter: ServiceStorageAdapter = { read: imageSnapshot, async update(values) { const update: LLMImageConfigUpdate = {}; @@ -120,8 +120,8 @@ const imageAdapter: CapabilityStorageAdapter = { } const parsed = llmImageConfigUpdateSchema.safeParse(update); if (!parsed.success) { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', parsed.error.issues[0]?.message ?? 'Invalid image configuration', ); } @@ -146,7 +146,7 @@ const imageAdapter: CapabilityStorageAdapter = { function secretAdapter(options: { read: () => string | undefined; update: (value: string | null) => Promise; -}): CapabilityStorageAdapter { +}): ServiceStorageAdapter { return { read() { const configured = Boolean(options.read()); @@ -167,7 +167,7 @@ function secretAdapter(options: { }; } -const inkOcrAdapter: CapabilityStorageAdapter = { +const inkOcrAdapter: ServiceStorageAdapter = { read() { const config = getInkOcrConfig(); return { @@ -199,8 +199,8 @@ const inkOcrAdapter: CapabilityStorageAdapter = { }; const parsed = inkOcrConfigUpdateSchema.safeParse(update); if (!parsed.success) { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', parsed.error.issues[0]?.message ?? 'Invalid Ink OCR configuration', ); } @@ -212,7 +212,7 @@ const inkOcrAdapter: CapabilityStorageAdapter = { }, }; -const adapters = new Map([ +const adapters = new Map([ ['llm.imageConfig', imageAdapter], [ 'integration.tavily', @@ -231,18 +231,18 @@ const adapters = new Map([ ['integration.azureVisionInkOcr', inkOcrAdapter], ]); -function adapterFor(manifest: CapabilityManifest): CapabilityStorageAdapter { +function adapterFor(manifest: ServiceManifest): ServiceStorageAdapter { const adapter = adapters.get(manifest.storage.namespace); if (!adapter) { throw new Error( - `Unknown Capability storage namespace: ${manifest.storage.namespace}`, + `Unknown Service storage namespace: ${manifest.storage.namespace}`, ); } return adapter; } function isConfigured( - manifest: CapabilityManifest, + manifest: ServiceManifest, configuredFields: readonly string[], ): boolean { const configured = new Set(configuredFields); @@ -252,8 +252,8 @@ function isConfigured( } function validateUpdate( - manifest: CapabilityManifest, - values: Readonly>, + manifest: ServiceManifest, + values: Readonly>, ): void { const fields = new Map( manifest.configuration.map((field) => [field.id, field]), @@ -261,24 +261,24 @@ function validateUpdate( for (const [id, value] of Object.entries(values)) { const field = fields.get(id); if (!field) { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', `Unknown configuration field: ${id}`, ); } if (value === null) continue; if (field.type === 'boolean') { if (typeof value !== 'boolean') { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', `${field.label} must be a boolean`, ); } continue; } if (typeof value !== 'string') { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', `${field.label} must be text`, ); } @@ -287,8 +287,8 @@ function validateUpdate( const url = new URL(value); if (url.protocol !== 'https:') throw new Error(); } catch { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', `${field.label} must be an HTTPS URL`, ); } @@ -298,31 +298,31 @@ function validateUpdate( value && !field.options?.some((option) => option.value === value) ) { - throw new CapabilityServiceError( - 'invalid_capability_config', + throw new ServiceProvisionError( + 'invalid_service_config', `Invalid ${field.label}`, ); } } } -export class CapabilityProvisionService { +export class ServiceProvisioner { constructor( - private readonly manifests: ReadonlyMap, + private readonly manifests: ReadonlyMap, ) {} - private manifest(capabilityId: string): CapabilityManifest { - const manifest = this.manifests.get(capabilityId); + private manifest(serviceId: string): ServiceManifest { + const manifest = this.manifests.get(serviceId); if (!manifest) { - throw new CapabilityServiceError( - 'capability_not_found', - `Unknown Capability: ${capabilityId}`, + throw new ServiceProvisionError( + 'service_not_found', + `Unknown Service: ${serviceId}`, ); } return manifest; } - list(): CapabilitySummary[] { + list(): ServiceSummary[] { return [...this.manifests.values()].map((manifest) => { const snapshot = adapterFor(manifest).read(); const configured = isConfigured(manifest, snapshot.configuredFields); @@ -337,8 +337,8 @@ export class CapabilityProvisionService { }); } - getConfig(capabilityId: string): CapabilityConfig { - const manifest = this.manifest(capabilityId); + getConfig(serviceId: string): ServiceConfig { + const manifest = this.manifest(serviceId); const snapshot = adapterFor(manifest).read(); return { manifest, @@ -349,40 +349,40 @@ export class CapabilityProvisionService { } async updateConfig( - capabilityId: string, - values: Readonly>, - ): Promise { - const manifest = this.manifest(capabilityId); + serviceId: string, + values: Readonly>, + ): Promise { + const manifest = this.manifest(serviceId); validateUpdate(manifest, values); await adapterFor(manifest).update(values); - return this.getConfig(capabilityId); + return this.getConfig(serviceId); } - resolveForServer(capabilityId: string): Record { - const manifest = this.manifest(capabilityId); + resolveForServer(serviceId: string): Record { + const manifest = this.manifest(serviceId); const adapter = adapterFor(manifest); const snapshot = adapter.read(); if (!isConfigured(manifest, snapshot.configuredFields)) { - throw new CapabilityServiceError( - 'capability_not_configured', - `Capability "${capabilityId}" is not configured`, + throw new ServiceProvisionError( + 'service_not_configured', + `Service "${serviceId}" is not configured`, ); } return adapter.resolve(); } - lease(capabilityId: string): CapabilityLease { - const manifest = this.manifest(capabilityId); + lease(serviceId: string): ServiceLease { + const manifest = this.manifest(serviceId); if (!manifest.agent) { - throw new CapabilityServiceError( - 'capability_not_external', - `Capability "${capabilityId}" is not available to External Agents`, + throw new ServiceProvisionError( + 'service_not_agent_accessible', + `Service "${serviceId}" is not available to External Agents`, ); } return { id: manifest.id, version: manifest.version, - config: this.resolveForServer(capabilityId), + config: this.resolveForServer(serviceId), ...(manifest.agent?.client ? { client: manifest.agent.client } : {}), }; } diff --git a/apps/server/src/modules/capabilities/capabilities.route.test.ts b/apps/server/src/modules/services/services.route.test.ts similarity index 84% rename from apps/server/src/modules/capabilities/capabilities.route.test.ts rename to apps/server/src/modules/services/services.route.test.ts index a811033b4..9a74dd3fd 100644 --- a/apps/server/src/modules/capabilities/capabilities.route.test.ts +++ b/apps/server/src/modules/services/services.route.test.ts @@ -4,7 +4,7 @@ import fastify, { type FastifyInstance } from 'fastify'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; -import type * as CapabilityModule from './index.js'; +import type * as ServiceModule from './index.js'; const mocks = vi.hoisted(() => ({ getConfig: vi.fn(), @@ -14,10 +14,10 @@ const mocks = vi.hoisted(() => ({ })); vi.mock('./index.js', async (importOriginal) => { - const actual = await importOriginal(); + const actual = await importOriginal(); return { ...actual, - capabilityProvisionService: { + serviceProvisioner: { getConfig: mocks.getConfig, list: mocks.list, updateConfig: mocks.updateConfig, @@ -29,20 +29,20 @@ vi.mock('../security/owner.js', () => ({ isOwnerRequest: mocks.isOwner, })); -const { default: capabilityRoutes } = await import('./capabilities.route.js'); +const { default: serviceRoutes } = await import('./services.route.js'); let app: FastifyInstance | undefined; async function buildApp(): Promise { const instance = fastify(); - await instance.register(capabilityRoutes, { prefix: '/capabilities' }); + await instance.register(serviceRoutes, { prefix: '/services' }); await instance.ready(); return instance; } const maskedConfig = { manifest: { - schema: 'huabu-capability/v1', + schema: 'huabu-service/v1', id: 'web-search', version: '1.0.0', name: 'Web Search', @@ -75,7 +75,7 @@ afterEach(async () => { app = undefined; }); -describe('Capability settings routes', () => { +describe('Service settings routes', () => { it('returns discovery and masked configuration', async () => { mocks.list.mockReturnValue([ { @@ -92,16 +92,16 @@ describe('Capability settings routes', () => { const discovery = await app.inject({ method: 'GET', - url: '/capabilities', + url: '/services', }); const config = await app.inject({ method: 'GET', - url: '/capabilities/web-search', + url: '/services/web-search', }); expect(discovery.statusCode).toBe(200); expect(discovery.json()).toMatchObject({ - capabilities: [{ id: 'web-search', configured: true }], + services: [{ id: 'web-search', configured: true }], }); expect(config.statusCode).toBe(200); expect(config.json()).toMatchObject({ @@ -119,7 +119,7 @@ describe('Capability settings routes', () => { const response = await app.inject({ method: 'PUT', - url: '/capabilities/web-search', + url: '/services/web-search', payload: { values: { apiKey: 'test-secret' } }, }); @@ -133,7 +133,7 @@ describe('Capability settings routes', () => { const invalid = await app.inject({ method: 'PUT', - url: '/capabilities/web-search', + url: '/services/web-search', payload: { values: { apiKey: { nested: true } } }, }); expect(invalid.statusCode).toBe(400); @@ -141,7 +141,7 @@ describe('Capability settings routes', () => { const updated = await app.inject({ method: 'PUT', - url: '/capabilities/web-search', + url: '/services/web-search', payload: { values: { apiKey: 'test-secret' } }, }); expect(updated.statusCode).toBe(200); diff --git a/apps/server/src/modules/services/services.route.ts b/apps/server/src/modules/services/services.route.ts new file mode 100644 index 000000000..a31fd76d0 --- /dev/null +++ b/apps/server/src/modules/services/services.route.ts @@ -0,0 +1,97 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { serviceConfigUpdateSchema, serviceParamsSchema } from '@huabu/shared'; + +import { isOwnerRequest } from '../security/owner.js'; + +import { serviceProvisioner, ServiceProvisionError } from './index.js'; + +import type { + ApiResult, + ServiceConfig, + ServiceConfigUpdate, + ServiceListResponse, + ServiceParams, +} from '@huabu/shared'; +import type { FastifyPluginAsync } from 'fastify'; + +function statusFor(error: ServiceProvisionError): number { + switch (error.code) { + case 'service_not_found': + return 404; + case 'invalid_service_config': + return 400; + default: + return 409; + } +} + +const serviceRoutes: FastifyPluginAsync = async (app) => { + app.get<{ Reply: ApiResult }>('/', async () => ({ + services: serviceProvisioner.list(), + })); + + app.get<{ + Params: ServiceParams; + Reply: ApiResult; + }>('/:serviceId', async (request, reply) => { + const parsed = serviceParamsSchema.safeParse(request.params); + if (!parsed.success) { + return reply.code(400).send({ + message: parsed.error.issues[0]?.message ?? 'Invalid Service id', + }); + } + try { + return reply.send(serviceProvisioner.getConfig(parsed.data.serviceId)); + } catch (error) { + if (error instanceof ServiceProvisionError) { + return reply + .code(statusFor(error)) + .send({ message: error.message, code: error.code }); + } + throw error; + } + }); + + app.put<{ + Params: ServiceParams; + Body: ServiceConfigUpdate; + Reply: ApiResult; + }>('/:serviceId', async (request, reply) => { + if (!isOwnerRequest(request)) { + return reply.code(403).send({ + message: 'Forbidden: Service settings require owner authorization', + }); + } + const params = serviceParamsSchema.safeParse(request.params); + const body = serviceConfigUpdateSchema.safeParse(request.body); + if (!params.success || !body.success) { + const issue = !params.success + ? params.error.issues[0] + : !body.success + ? body.error.issues[0] + : undefined; + return reply.code(400).send({ + message: issue?.message ?? 'Invalid Service update', + }); + } + try { + return reply.send( + await serviceProvisioner.updateConfig( + params.data.serviceId, + body.data.values, + ), + ); + } catch (error) { + if (error instanceof ServiceProvisionError) { + return reply + .code(statusFor(error)) + .send({ message: error.message, code: error.code }); + } + throw error; + } + }); +}; + +export default serviceRoutes; diff --git a/apps/server/src/prompt/external-agent/access-huabu.md b/apps/server/src/prompt/external-agent/access-huabu.md index c0a0266ad..1c03266bc 100644 --- a/apps/server/src/prompt/external-agent/access-huabu.md +++ b/apps/server/src/prompt/external-agent/access-huabu.md @@ -6,7 +6,7 @@ These environment variables are already set: - `HUABU_RFS_URL` — the base URL for this Space, with no trailing slash. - `AGENTLET_TOKEN` — the RFS bearer credential. -- `AGENTLET_CAPABILITY_SDK_URL` — the daemon-owned `file://` URL for loading configured provider Capabilities. +- `AGENTLET_SERVICE_SDK_URL` — the daemon-owned `file://` URL for loading configured provider Services. - `HUABU_THREAD_ID` — your conversation ID. Pass it on `execute` (see §6) to attribute your edits. Prefer deterministic direct operations: @@ -17,7 +17,7 @@ Prefer deterministic direct operations: 4. Use the `SNAPSHOT_NODES` query to render image, sketch, or frame nodes into PNG artifacts you can inspect. 5. Use `execute` for validated Space commands. 6. Use `agent` only when you deliberately want the optional internal Huabu agent to interpret an open-ended request. -7. Discover configured provider services through `capability-packages` and follow the selected Package Skill before loading it through the Agentlet SDK. +7. Discover configured provider services through `services` and follow the selected Package Skill before loading it through the Agentlet SDK. ## 1. Discover operations @@ -281,34 +281,32 @@ For available Profile discovery, launch configuration, create-only requests, opt curl -fsS -H "$AUTH" "$HUABU_RFS_URL/skill/agents" ``` -## Provider Capability Packages +## Provider Services List the bundled provider services that Huabu can provision: ```bash -curl -fsS -H "$AUTH" "$HUABU_RFS_URL/capability-packages" +curl -fsS -H "$AUTH" "$HUABU_RFS_URL/services" ``` Before using one, fetch and follow its Skill: ```bash -curl -fsS -H "$AUTH" "$HUABU_RFS_URL/capability-packages/image-gen/skill" +curl -fsS -H "$AUTH" "$HUABU_RFS_URL/services/image-gen/skill" ``` Agent-facing packages can then be loaded from a short-lived `.mjs` script: ```js -const { withCapability } = await import( - process.env.AGENTLET_CAPABILITY_SDK_URL -); +const { withService } = await import(process.env.AGENTLET_SERVICE_SDK_URL); -await withCapability('image-gen', async ({ client }) => { - if (!client) throw new Error('Capability client is unavailable'); +await withService('image-gen', async ({ client }) => { + if (!client) throw new Error('Service client is unavailable'); console.log(await client.generate({ prompt: 'A watercolor landscape' })); }); ``` -The SDK obtains current configuration on demand. Never print, persist, or forward returned credentials. A package without an Agent Skill/client is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. +The SDK obtains current configuration on demand. Never print, persist, or forward returned credentials. A Service Package without an Agent Skill is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. ## Advanced workflows diff --git a/apps/server/src/services/image-gen/SKILL.md b/apps/server/src/services/image-gen/SKILL.md new file mode 100644 index 000000000..4aa569e6c --- /dev/null +++ b/apps/server/src/services/image-gen/SKILL.md @@ -0,0 +1,7 @@ +# Image Generation + +Use this Service when the user asks you to generate an image through their configured Azure OpenAI image deployment. + +Load the Service through the Agentlet SDK URL in `AGENTLET_SERVICE_SDK_URL`. Call the returned client's `generate()` method with a non-empty `prompt` and optional provider-supported image parameters. Provider credentials are supplied only to the loaded client; never print, persist, or include them in another request. + +The client returns the provider response. Decode or upload generated image bytes through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. diff --git a/apps/server/src/capabilities/image-gen/client.mjs b/apps/server/src/services/image-gen/client.mjs similarity index 100% rename from apps/server/src/capabilities/image-gen/client.mjs rename to apps/server/src/services/image-gen/client.mjs diff --git a/apps/server/src/capabilities/image-gen/client.test.ts b/apps/server/src/services/image-gen/client.test.ts similarity index 89% rename from apps/server/src/capabilities/image-gen/client.test.ts rename to apps/server/src/services/image-gen/client.test.ts index 0a3f22bca..7de4e3a5d 100644 --- a/apps/server/src/capabilities/image-gen/client.test.ts +++ b/apps/server/src/services/image-gen/client.test.ts @@ -3,11 +3,11 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; -import { readCapabilityPackageFile } from '../../modules/capabilities/package-loader.js'; +import { readServicePackageFile } from '../../modules/services/package-loader.js'; async function loadClient() { - const source = readCapabilityPackageFile('image-gen', 'client.mjs'); - if (!source) throw new Error('Image Capability client is missing'); + const source = readServicePackageFile('image-gen', 'client.mjs'); + if (!source) throw new Error('Image Service client is missing'); return import( `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` ) as Promise<{ @@ -21,7 +21,7 @@ afterEach(() => { vi.unstubAllGlobals(); }); -describe('Image Capability client', () => { +describe('Image Service client', () => { it('uses classic Azure deployment routing', async () => { const fetchMock = vi .fn() diff --git a/apps/server/src/capabilities/image-gen/capability.yaml b/apps/server/src/services/image-gen/service.yaml similarity index 97% rename from apps/server/src/capabilities/image-gen/capability.yaml rename to apps/server/src/services/image-gen/service.yaml index d13ea68c2..ddf20afed 100644 --- a/apps/server/src/capabilities/image-gen/capability.yaml +++ b/apps/server/src/services/image-gen/service.yaml @@ -1,4 +1,4 @@ -schema: huabu-capability/v1 +schema: huabu-service/v1 id: image-gen version: 1.0.0 name: Image Generation diff --git a/apps/server/src/capabilities/ink-ocr/capability.yaml b/apps/server/src/services/ink-ocr/service.yaml similarity index 93% rename from apps/server/src/capabilities/ink-ocr/capability.yaml rename to apps/server/src/services/ink-ocr/service.yaml index 480d8504e..79d398018 100644 --- a/apps/server/src/capabilities/ink-ocr/capability.yaml +++ b/apps/server/src/services/ink-ocr/service.yaml @@ -1,4 +1,4 @@ -schema: huabu-capability/v1 +schema: huabu-service/v1 id: ink-ocr version: 1.0.0 name: Handwriting Recognition diff --git a/apps/server/src/services/web-search/SKILL.md b/apps/server/src/services/web-search/SKILL.md new file mode 100644 index 000000000..d1db92b7f --- /dev/null +++ b/apps/server/src/services/web-search/SKILL.md @@ -0,0 +1,5 @@ +# Web Search + +Use this Service for current public web information when ordinary local knowledge is insufficient. + +Load it through the Agentlet SDK URL in `AGENTLET_SERVICE_SDK_URL`, then call the returned client's `search()` method with a non-empty query. Never print or persist the supplied credential. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. diff --git a/apps/server/src/capabilities/web-search/client.mjs b/apps/server/src/services/web-search/client.mjs similarity index 100% rename from apps/server/src/capabilities/web-search/client.mjs rename to apps/server/src/services/web-search/client.mjs diff --git a/apps/server/src/capabilities/web-search/client.test.ts b/apps/server/src/services/web-search/client.test.ts similarity index 85% rename from apps/server/src/capabilities/web-search/client.test.ts rename to apps/server/src/services/web-search/client.test.ts index 99926a5eb..bf61f9e5d 100644 --- a/apps/server/src/capabilities/web-search/client.test.ts +++ b/apps/server/src/services/web-search/client.test.ts @@ -3,11 +3,11 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; -import { readCapabilityPackageFile } from '../../modules/capabilities/package-loader.js'; +import { readServicePackageFile } from '../../modules/services/package-loader.js'; async function loadClient() { - const source = readCapabilityPackageFile('web-search', 'client.mjs'); - if (!source) throw new Error('Web Search Capability client is missing'); + const source = readServicePackageFile('web-search', 'client.mjs'); + if (!source) throw new Error('Web Search Service client is missing'); return import( `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` ) as Promise<{ @@ -21,7 +21,7 @@ afterEach(() => { vi.unstubAllGlobals(); }); -describe('Web Search Capability client', () => { +describe('Web Search Service client', () => { it('sends the configured Tavily key and normalized query', async () => { const fetchMock = vi .fn() diff --git a/apps/server/src/capabilities/web-search/capability.yaml b/apps/server/src/services/web-search/service.yaml similarity index 91% rename from apps/server/src/capabilities/web-search/capability.yaml rename to apps/server/src/services/web-search/service.yaml index dba7dd2cc..409e1ae66 100644 --- a/apps/server/src/capabilities/web-search/capability.yaml +++ b/apps/server/src/services/web-search/service.yaml @@ -1,4 +1,4 @@ -schema: huabu-capability/v1 +schema: huabu-service/v1 id: web-search version: 1.0.0 name: Web Search diff --git a/apps/server/src/capabilities/youtube-transcripts/capability.yaml b/apps/server/src/services/youtube-transcripts/service.yaml similarity index 91% rename from apps/server/src/capabilities/youtube-transcripts/capability.yaml rename to apps/server/src/services/youtube-transcripts/service.yaml index bc21c586a..21694d796 100644 --- a/apps/server/src/capabilities/youtube-transcripts/capability.yaml +++ b/apps/server/src/services/youtube-transcripts/service.yaml @@ -1,4 +1,4 @@ -schema: huabu-capability/v1 +schema: huabu-service/v1 id: youtube-transcripts version: 1.0.0 name: YouTube Transcripts diff --git a/apps/server/tsup.config.ts b/apps/server/tsup.config.ts index de07bfd94..4834e599d 100644 --- a/apps/server/tsup.config.ts +++ b/apps/server/tsup.config.ts @@ -80,10 +80,10 @@ export default defineConfig([ const dst = path.resolve('dist-bundle/prompt'); cpSync(src, dst, { recursive: true }); console.log(`[tsup] copied prompt templates -> ${dst}`); - const capabilitiesSrc = path.resolve('src/capabilities'); - const capabilitiesDst = path.resolve('dist-bundle/capabilities'); - cpSync(capabilitiesSrc, capabilitiesDst, { recursive: true }); - console.log(`[tsup] copied Capability packages -> ${capabilitiesDst}`); + const servicesSrc = path.resolve('src/services'); + const servicesDst = path.resolve('dist-bundle/services'); + cpSync(servicesSrc, servicesDst, { recursive: true }); + console.log(`[tsup] copied Service packages -> ${servicesDst}`); // @resvg/resvg-wasm — copied next to server.js so the // snapshot_nodes tool's bundle-layout fallback finds it via // bundled server module's file URL. @@ -112,8 +112,8 @@ export default defineConfig([ index: path.resolve( '../../external/agentlet/packages/local/src/index.ts', ), - 'capability-sdk/index': path.resolve( - '../../external/agentlet/packages/local/src/capability-sdk/index.ts', + 'service-sdk/index': path.resolve( + '../../external/agentlet/packages/local/src/service-sdk/index.ts', ), }, format: ['esm'], diff --git a/apps/web/src/api/_routes.ts b/apps/web/src/api/_routes.ts index 3c354a999..0f99f539b 100644 --- a/apps/web/src/api/_routes.ts +++ b/apps/web/src/api/_routes.ts @@ -45,8 +45,8 @@ export const routes = { // ── Integrations (third-party API keys) ────────────────────────── integrationsConfig: '/integrations/config', inkOcrConfig: '/integrations/ink-ocr/config', - capabilities: '/capabilities', - capability: (capabilityId: string) => `/capabilities/${enc(capabilityId)}`, + services: '/services', + service: (serviceId: string) => `/services/${enc(serviceId)}`, // ── Canvas ──────────────────────────────────────────────────────── canvasList: '/canvas', diff --git a/apps/web/src/api/capabilities.ts b/apps/web/src/api/capabilities.ts deleted file mode 100644 index 330916713..000000000 --- a/apps/web/src/api/capabilities.ts +++ /dev/null @@ -1,34 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -import { apiFetch } from './_client'; -import { routes } from './_routes'; - -import type { - CapabilityConfig, - CapabilityConfigUpdate, - CapabilityListResponse, -} from '@huabu/shared'; - -export function getCapabilities(): Promise { - return apiFetch(routes.capabilities, { - fallbackMessage: 'Failed to load Capabilities', - }); -} - -export function getCapability(id: string): Promise { - return apiFetch(routes.capability(id), { - fallbackMessage: 'Failed to load Capability configuration', - }); -} - -export function putCapability( - id: string, - update: CapabilityConfigUpdate, -): Promise { - return apiFetch(routes.capability(id), { - method: 'PUT', - json: update, - fallbackMessage: 'Failed to update Capability configuration', - }); -} diff --git a/apps/web/src/api/services.ts b/apps/web/src/api/services.ts new file mode 100644 index 000000000..f08eba82d --- /dev/null +++ b/apps/web/src/api/services.ts @@ -0,0 +1,34 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { apiFetch } from './_client'; +import { routes } from './_routes'; + +import type { + ServiceConfig, + ServiceConfigUpdate, + ServiceListResponse, +} from '@huabu/shared'; + +export function getServices(): Promise { + return apiFetch(routes.services, { + fallbackMessage: 'Failed to load Services', + }); +} + +export function getService(id: string): Promise { + return apiFetch(routes.service(id), { + fallbackMessage: 'Failed to load Service configuration', + }); +} + +export function putService( + id: string, + update: ServiceConfigUpdate, +): Promise { + return apiFetch(routes.service(id), { + method: 'PUT', + json: update, + fallbackMessage: 'Failed to update Service configuration', + }); +} diff --git a/apps/web/src/components/Settings/SettingsModal.test.tsx b/apps/web/src/components/Settings/SettingsModal.test.tsx index a35b88f2f..0ddb45588 100644 --- a/apps/web/src/components/Settings/SettingsModal.test.tsx +++ b/apps/web/src/components/Settings/SettingsModal.test.tsx @@ -9,7 +9,7 @@ import { SettingsModal } from './SettingsModal'; import type { Root } from 'react-dom/client'; -type RequestedTab = 'builtIn' | 'capabilities' | null; +type RequestedTab = 'builtIn' | 'services' | null; const mocks = vi.hoisted(() => ({ init: vi.fn(), @@ -80,8 +80,8 @@ vi.mock('./sections/GeneralSettings', () => ({ vi.mock('./sections/LLMSettings', () => ({ LLMSettings: () =>
, })); -vi.mock('./sections/CapabilitiesSettings', () => ({ - CapabilitiesSettings: () =>
, +vi.mock('./sections/ServicesSettings', () => ({ + ServicesSettings: () =>
, })); globalThis.IS_REACT_ACT_ENVIRONMENT = true; @@ -151,21 +151,21 @@ describe('Settings information architecture', () => { expect(mocks.llmInit).not.toHaveBeenCalled(); }); - it('keeps Huabu-owned capabilities separate from Agent configuration', async () => { + it('keeps Huabu-managed services separate from Agent configuration', async () => { await renderModal(); await act(async () => { - findTab('settings.capabilities').click(); + findTab('settings.services').click(); }); - expect(container.textContent).toContain('settings.capabilitiesDescription'); + expect(container.textContent).toContain('settings.servicesDescription'); expect( container - .querySelector('[data-testid="capability-sections"]') + .querySelector('[data-testid="service-sections"]') ?.classList.contains('space-y-4'), ).toBe(true); expect( - container.querySelector('[data-testid="capabilities-settings"]'), + container.querySelector('[data-testid="services-settings"]'), ).not.toBeNull(); expect( container.querySelector('[data-testid="agent-defaults"]'), diff --git a/apps/web/src/components/Settings/SettingsModal.tsx b/apps/web/src/components/Settings/SettingsModal.tsx index 239007533..3bd692e64 100644 --- a/apps/web/src/components/Settings/SettingsModal.tsx +++ b/apps/web/src/components/Settings/SettingsModal.tsx @@ -23,10 +23,10 @@ import { } from './agent-profiles/ExternalAgentsSettings'; import { DeploymentReadinessNotice } from './DeploymentReadinessNotice'; import { AgentBehaviorSettings } from './sections/AgentBehaviorSettings'; -import { CapabilitiesSettings } from './sections/CapabilitiesSettings'; import { ExternalAgentRuntimeSettings } from './sections/ExternalAgentRuntimeSettings'; import { GeneralSettings } from './sections/GeneralSettings'; import { LLMSettings } from './sections/LLMSettings'; +import { ServicesSettings } from './sections/ServicesSettings'; /** Identifiers for the settings tabs (left-nav order). */ type SettingsTab = SettingsTabId; @@ -34,12 +34,12 @@ type SettingsTab = SettingsTabId; interface TabDef { id: SettingsTab; /** i18n key for the tab label. */ - labelKey: 'settings.general' | 'settings.agent' | 'settings.capabilities'; + labelKey: 'settings.general' | 'settings.agent' | 'settings.services'; } const TABS: TabDef[] = [ { id: 'agent', labelKey: 'settings.agent' }, - { id: 'capabilities', labelKey: 'settings.capabilities' }, + { id: 'services', labelKey: 'settings.services' }, { id: 'general', labelKey: 'settings.general' }, ]; @@ -55,7 +55,7 @@ interface SettingsModalProps { * * Each tab renders its owned Settings surface: * - **Agent** — Utility Agent, Built-In Pi setup, external Profiles, and behavior - * - **Capabilities** — manifest-driven image, search, transcript, and OCR services + * - **Services** — manifest-driven image, search, transcript, and OCR providers * - **General** — application, canvas, input, and update preferences * * The app version sits at the bottom of the left tab rail (a product-wide @@ -302,16 +302,16 @@ export const SettingsModal: React.FC = ({ )} ))} - {activeTab === 'capabilities' && ( + {activeTab === 'services' && ( <>

- {t('settings.capabilitiesDescription')} + {t('settings.servicesDescription')}

- +
)} diff --git a/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx b/apps/web/src/components/Settings/sections/ServicesSettings.test.tsx similarity index 68% rename from apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx rename to apps/web/src/components/Settings/sections/ServicesSettings.test.tsx index 12773925d..0ae98c1d5 100644 --- a/apps/web/src/components/Settings/sections/CapabilitiesSettings.test.tsx +++ b/apps/web/src/components/Settings/sections/ServicesSettings.test.tsx @@ -5,19 +5,19 @@ import { act } from 'react'; import { createRoot, type Root } from 'react-dom/client'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; -import { CapabilitiesSettings } from './CapabilitiesSettings'; +import { ServicesSettings } from './ServicesSettings'; -import type { CapabilityConfig } from '@huabu/shared'; +import type { ServiceConfig } from '@huabu/shared'; const mocks = vi.hoisted(() => ({ - getCapabilities: vi.fn(), - getCapability: vi.fn(), + getServices: vi.fn(), + getService: vi.fn(), })); -vi.mock('@/api/capabilities', () => ({ - getCapabilities: mocks.getCapabilities, - getCapability: mocks.getCapability, - putCapability: vi.fn(), +vi.mock('@/api/services', () => ({ + getServices: mocks.getServices, + getService: mocks.getService, + putService: vi.fn(), })); vi.mock('@/store/deploymentReadinessStore', () => ({ @@ -37,10 +37,10 @@ const ids = [ 'ink-ocr', ] as const; -function config(id: (typeof ids)[number]): CapabilityConfig { +function config(id: (typeof ids)[number]): ServiceConfig { return { manifest: { - schema: 'huabu-capability/v1', + schema: 'huabu-service/v1', id, version: '1.0.0', name: id, @@ -68,8 +68,8 @@ beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); root = createRoot(container); - mocks.getCapabilities.mockResolvedValue({ - capabilities: ids.map((id) => ({ + mocks.getServices.mockResolvedValue({ + services: ids.map((id) => ({ id, version: '1.0.0', name: id, @@ -78,7 +78,7 @@ beforeEach(() => { availableToExternalAgent: false, })), }); - mocks.getCapability.mockImplementation(async (id: (typeof ids)[number]) => + mocks.getService.mockImplementation(async (id: (typeof ids)[number]) => config(id), ); }); @@ -89,13 +89,13 @@ afterEach(() => { vi.clearAllMocks(); }); -describe('CapabilitiesSettings', () => { - it('renders every current Capability from server manifests', async () => { +describe('ServicesSettings', () => { + it('renders every current Service from server manifests', async () => { await act(async () => { - root.render(); + root.render(); }); - expect(mocks.getCapability).toHaveBeenCalledTimes(4); + expect(mocks.getService).toHaveBeenCalledTimes(4); for (const id of ids) { expect(container.textContent).toContain(id); } diff --git a/apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx b/apps/web/src/components/Settings/sections/ServicesSettings.tsx similarity index 87% rename from apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx rename to apps/web/src/components/Settings/sections/ServicesSettings.tsx index 4262fe0a8..e23d15612 100644 --- a/apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx +++ b/apps/web/src/components/Settings/sections/ServicesSettings.tsx @@ -4,11 +4,7 @@ import { ChevronDown, Key, Trash2 } from 'lucide-react'; import { useEffect, useMemo, useState } from 'react'; -import { - getCapabilities, - getCapability, - putCapability, -} from '@/api/capabilities'; +import { getServices, getService, putService } from '@/api/services'; import { Button } from '@/components/Common/Button'; import { Select } from '@/components/Common/Select'; import { TextInput } from '@/components/Common/TextInput'; @@ -19,12 +15,12 @@ import { SettingSection } from '@/components/Settings/Common/SettingSection'; import { useDeploymentReadinessStore } from '@/store/deploymentReadinessStore'; import type { - CapabilityConfig, - CapabilityConfigurationField, - CapabilityFieldValue, + ServiceConfig, + ServiceConfigurationField, + ServiceFieldValue, } from '@huabu/shared'; -function CapabilityField({ +function ServiceField({ field, value, configured, @@ -32,11 +28,11 @@ function CapabilityField({ onChange, onRemove, }: { - field: CapabilityConfigurationField; - value: CapabilityFieldValue | undefined; + field: ServiceConfigurationField; + value: ServiceFieldValue | undefined; configured: boolean; disabled: boolean; - onChange: (value: CapabilityFieldValue) => void; + onChange: (value: ServiceFieldValue) => void; onRemove: () => void; }) { if (field.type === 'enum') { @@ -101,16 +97,16 @@ function CapabilityField({ ); } -function CapabilityForm({ +function ServiceForm({ initial, writesDisabled, }: { - initial: CapabilityConfig; + initial: ServiceConfig; writesDisabled: boolean; }) { const [config, setConfig] = useState(initial); const [expanded, setExpanded] = useState(false); - const [draft, setDraft] = useState>( + const [draft, setDraft] = useState>( initial.values, ); const [dirty, setDirty] = useState>(new Set()); @@ -136,15 +132,15 @@ function CapabilityForm({ [config.manifest, dirty, writesDisabled], ); - function change(id: string, value: CapabilityFieldValue) { + function change(id: string, value: ServiceFieldValue) { setDraft((current) => ({ ...current, [id]: value })); setDirty((current) => new Set(current).add(id)); } - async function update(values: Record) { + async function update(values: Record) { setSaving(true); try { - const next = await putCapability(config.manifest.id, { values }); + const next = await putService(config.manifest.id, { values }); setConfig(next); setDraft(next.values); setDirty(new Set()); @@ -217,7 +213,7 @@ function CapabilityForm({ description={field.description} > - ([]); +export function ServicesSettings() { + const [configs, setConfigs] = useState([]); const [error, setError] = useState(null); const writesDisabled = useDeploymentReadinessStore( (state) => state.readiness?.credentials.writable === false, @@ -275,9 +271,9 @@ export function CapabilitiesSettings() { useEffect(() => { let cancelled = false; - void getCapabilities() - .then(({ capabilities }) => - Promise.all(capabilities.map(({ id }) => getCapability(id))), + void getServices() + .then(({ services }) => + Promise.all(services.map(({ id }) => getService(id))), ) .then((next) => { if (!cancelled) setConfigs(next); @@ -285,9 +281,7 @@ export function CapabilitiesSettings() { .catch((cause) => { if (!cancelled) { setError( - cause instanceof Error - ? cause.message - : 'Failed to load Capabilities', + cause instanceof Error ? cause.message : 'Failed to load Services', ); } }); @@ -306,12 +300,12 @@ export function CapabilitiesSettings() { if (configs.length === 0) { return (

- Loading Capabilities... + Loading Services...

); } return configs.map((config) => ( - Agent is the single Agent configuration surface. It presents external Profile management first, followed by the Utility Agent used only for Huabu-owned auxiliary work, conditional Built-In Pi configuration, Agent behavior, and external-Agent runtime controls without changing their separate persistence owners. Top-level Agent modules use consistent section spacing. The Utility Agent explanation sits inside its Profile row rather than above the section, and its status row renders only when it has a warning, error, or save state to display. Changing the Utility Agent never changes a conversation binding or the browser-local recent conversational Agent. The external functional-model field is hidden for Built-In; its saved value survives switching. Built-In provider, login, Chat and Utility model controls load and render only for a Built-In Utility Agent or an explicit configuration visit from a Built-In conversation. The conversation's configuration button remains available after binding is locked and does not change Utility Agent settings. Settings > Capabilities separately owns Huabu-managed image generation, OCR, Web Search, and YouTube transcript configuration; all of these Huabu-managed services are configured on demand, appear as peer capabilities with consistent card spacing, and do not imply that an external Agent can invoke the corresponding Huabu tools. The larger Image Generation form starts collapsed while retaining its bordered card header and expands on demand. +Settings > Agent is the single Agent configuration surface. It presents external Profile management first, followed by the Utility Agent used only for Huabu-owned auxiliary work, conditional Built-In Pi configuration, Agent behavior, and external-Agent runtime controls without changing their separate persistence owners. Top-level Agent modules use consistent section spacing. The Utility Agent explanation sits inside its Profile row rather than above the section, and its status row renders only when it has a warning, error, or save state to display. Changing the Utility Agent never changes a conversation binding or the browser-local recent conversational Agent. The external functional-model field is hidden for Built-In; its saved value survives switching. Built-In provider, login, Chat and Utility model controls load and render only for a Built-In Utility Agent or an explicit configuration visit from a Built-In conversation. The conversation's configuration button remains available after binding is locked and does not change Utility Agent settings. Settings > Services separately owns Huabu-managed image generation, OCR, Web Search, and YouTube transcript configuration; all services are configured on demand and appear as peer cards with consistent spacing. An Agent-facing Service Package enables direct external-Agent use but does not imply access to the corresponding Huabu Internal Tool. The larger Image Generation form starts collapsed while retaining its bordered card header and expands on demand. Huabu-owned auxiliary tasks outside an Agent Node's bound thread follow the Utility Agent, including summaries, keywords, content/Frame titles, conversation titles, and image labels. The source conversation's backend does not determine its automatic title backend. Each invocation selects its backend once; changing Utility Agent settings does not reroute in-flight work. Built-In tasks reuse `llmComplete` with the existing `contentMeta`, `frameLabel`, and `imageLabel` roles, preserving Utility/Chat model resolution and vision handling. External tasks use independent ACP Jobs. Thread-owned work and its tools retain the thread binding; explicit internal Skill authoring remains available. Legacy background Memory starts only for a Built-In Utility Agent; external Memory and unified Skill authoring remain separate follow-ups. diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 963da4a8f..66a4814cc 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -22,27 +22,27 @@ The shipped design record is [`agent-reachback-rfs.md`](../proposals/agent-reach All endpoints are mounted under `/api/rfs/:canvasId`; `HUABU_RFS_URL` already contains that canvas-scoped base. -| Endpoint | Responsibility | -| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `GET /skill` | Return the public bundled root guide; authenticated requests resolve the current root guide and append live Skill Frames. | -| `GET /skill/:skillId` | Return an authenticated advanced guide: `layout`, `tasks`, or `agents`. | -| `GET /download/` | Stream a known node, artifact, or staged-upload file. | -| `POST /upload/` | Stage bytes in the canvas `.upload/` directory without creating a node. | -| `DELETE /upload/` | Remove one exact staged upload. | -| `POST /agent` | Create a visible Agent Node and optionally start its first turn. | -| `POST /agent/:threadId/prompt` | Submit a turn to an existing Agent conversation over SSE. | -| `POST /agent/:threadId/ink-intent` | Submit a validated report for the matching active external Ink turn. | -| `GET /agent/profiles` | Return available Agent Profile IDs and aliases, marking the first selectable external fallback with `default: true` when available. | -| `POST /task/create` | Create a durable Task and its static Task Note. | -| `POST /task/:taskId/run/create` | Create a Run, its visible root Agent Node, and start the first turn. | -| `GET /capabilities` | Report the direct-operation protocol, limits, semantics, and supported operation types. | -| `GET /capabilities/queries/:type` | Return one query's generated JSON Schema, constraints, result description, and examples. | -| `GET /capabilities/commands/:type` | Return one command's generated JSON Schema, constraints, result description, and examples. | -| `GET /capability-packages` | List bundled provider Capability Packages and masked availability. | -| `GET /capability-packages/:id/*` | Return one Package's Manifest, Skill, or client source. | -| `POST /capability-packages/:id/lease` | Return the declared effective configuration for one configured External Package with `Cache-Control: no-store`. | -| `POST /query` | Validate and execute one bounded `SpaceQuery`, returning a query-discriminated JSON result. | -| `POST /execute` | Validate and execute an ordered batch of agent-allowed `CanvasCommand` variants. | +| Endpoint | Responsibility | +| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `GET /skill` | Return the public bundled root guide; authenticated requests resolve the current root guide and append live Skill Frames. | +| `GET /skill/:skillId` | Return an authenticated advanced guide: `layout`, `tasks`, or `agents`. | +| `GET /download/` | Stream a known node, artifact, or staged-upload file. | +| `POST /upload/` | Stage bytes in the canvas `.upload/` directory without creating a node. | +| `DELETE /upload/` | Remove one exact staged upload. | +| `POST /agent` | Create a visible Agent Node and optionally start its first turn. | +| `POST /agent/:threadId/prompt` | Submit a turn to an existing Agent conversation over SSE. | +| `POST /agent/:threadId/ink-intent` | Submit a validated report for the matching active external Ink turn. | +| `GET /agent/profiles` | Return available Agent Profile IDs and aliases, marking the first selectable external fallback with `default: true` when available. | +| `POST /task/create` | Create a durable Task and its static Task Note. | +| `POST /task/:taskId/run/create` | Create a Run, its visible root Agent Node, and start the first turn. | +| `GET /capabilities` | Report the direct-operation protocol, limits, semantics, and supported operation types. | +| `GET /capabilities/queries/:type` | Return one query's generated JSON Schema, constraints, result description, and examples. | +| `GET /capabilities/commands/:type` | Return one command's generated JSON Schema, constraints, result description, and examples. | +| `GET /services` | List configured third-party Services and masked availability. | +| `GET /services/:id/*` | Return one Service Package's Manifest, Skill, or client source. | +| `POST /services/:id/lease` | Return the declared effective configuration for one configured Agent-facing Service with `Cache-Control: no-store`. | +| `POST /query` | Validate and execute one bounded `SpaceQuery`, returning a query-discriminated JSON result. | +| `POST /execute` | Validate and execute an ordered batch of agent-allowed `CanvasCommand` variants. | There is no directory-listing endpoint. External agents receive exact node paths in selected-node context or ask the internal agent to discover relevant files. @@ -102,7 +102,7 @@ Parent lineage is best effort. The route resolves `parentThreadId` or `X-Huabu-H Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/`; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists the bootstrap as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. The preamble owns the authentication contract and curl header setup because every external Agent needs them before loading any Skill. The public basic guide is loaded without credentials from `GET /skill`; repeating that request with authentication adds the current root override and live Space Skill Frames. Advanced layout, Task, recursive-Agent, and Interactive View procedures are loaded on demand from authenticated `GET /skill/layout`, `/skill/tasks`, `/skill/agents`, and `/skill/interactive-views`. -Agentlet additionally injects its daemon-owned `AGENTLET_CAPABILITY_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/capability-sdk`. Session or Profile environment cannot override this value. The SDK wraps `/capability-packages` discovery, lease, and trusted client loading; provider credentials remain absent from startup environment and are resolved on demand. +Agentlet additionally injects its daemon-owned `AGENTLET_SERVICE_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/service-sdk`. Session or Profile environment cannot override this value. The SDK wraps `/services` discovery, lease, and trusted client loading; provider credentials remain absent from startup environment and are resolved on demand. Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. diff --git a/docs/architecture/api-design.md b/docs/architecture/api-design.md index c288f95e1..ceee2c4c3 100644 --- a/docs/architecture/api-design.md +++ b/docs/architecture/api-design.md @@ -160,11 +160,11 @@ Malformed request fields and malformed cursors return HTTP 400 with `code: "malf `POST /api/rfs/:canvasId/query` with `type: "INSPECT_NODES"` uses the canonical response contract in [`space-operations.ts`](../../packages/shared/src/types/api/space-operations.ts). Each Question Node result includes its non-empty persisted `threadId` when associated; non-Question Nodes and unbound Questions omit the field. The mapping is scoped by the authenticated RFS URL's Canvas and is read-only: inspection does not create a thread, workload, binding, realization, or invocation. Callers continue the mapped conversation through the existing `POST /api/rfs/:canvasId/agent/:threadId/prompt` SSE endpoint. -## Capability Packages +## Service Packages -`packages/shared/src/types/api/capability-package.ts` defines the strict manifest, Generic Settings update, masked configuration, summary, and External lease contracts. Owner Settings uses `GET /api/capabilities`, `GET /api/capabilities/:capabilityId`, and `PUT /api/capabilities/:capabilityId`; every path/body value is validated with the shared schemas before selecting a code-registered storage namespace. +`packages/shared/src/types/api/service-package.ts` defines the strict manifest, Generic Settings update, masked configuration, summary, and External lease contracts. Owner Settings uses `GET /api/services`, `GET /api/services/:serviceId`, and `PUT /api/services/:serviceId`; every path/body value is validated with the shared schemas before selecting a code-registered storage namespace. -Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes provider packages under `/capability-packages`. Manifest, Skill, and client reads contain no credentials. `POST /capability-packages/:id/lease` rejects unknown, unconfigured, and non-External packages, returns only declared fields, and is non-cacheable. See [`capability-packages.md`](./capability-packages.md). +Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes third-party services under `/services`. Manifest, Skill, and client reads contain no credentials. `POST /services/:id/lease` rejects unknown, unconfigured, and packages without an Agent interface, returns only declared fields, and is non-cacheable. See [`service-packages.md`](./service-packages.md). ## Anti-patterns diff --git a/docs/architecture/capability-packages.md b/docs/architecture/capability-packages.md deleted file mode 100644 index ace41129a..000000000 --- a/docs/architecture/capability-packages.md +++ /dev/null @@ -1,101 +0,0 @@ -# Capability Packages - -> Current architecture for Huabu-managed provider capabilities. Last updated: 2026-10-10 - -## Scope - -Capability Packages make provider configuration declarative without forcing Internal Agent tools, product pipelines, and External Agents through one execution path. The package is the source of truth for Settings fields and Agent-facing files; reviewed Huabu code remains the source of truth for Server execution. - -The bundled packages live under `apps/server/src/capabilities//`: - -```text -/ -├── capability.yaml -├── SKILL.md # required only when External Agent-facing -└── client.mjs # required only for a direct Agent-side provider call -``` - -Phase 1 packages are trusted files shipped with Huabu. User upload, installation, remote registries, and Server execution of uploaded code are not supported. - -## Manifest contract - -`huabu-capability/v1` is defined by `capabilityManifestSchema` in `packages/shared/src/types/api/capability-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, and an `agent` block without a Skill fail validation. - -Every package declares a stable ID and version, display metadata, one registered storage namespace, optional Agent files, and constrained configuration fields. Supported field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or client contract. - -The manifest does not declare Internal Agent or Pipeline consumers. Those execution paths are reviewed Huabu code and cannot be enabled by package metadata. The presence of an `agent` block is the complete declaration that a package supports External Agent use; its `skill` is required and its direct-provider `client` is optional. A package without `agent` cannot be leased to an External Agent. - -## Provision Service and storage bindings - -`CapabilityProvisionService` is the canonical access point for Generic Settings, Internal Agent tools, product pipelines, and External Agent leases. It validates field updates against the manifest, selects a code-registered namespace adapter, and exposes masked settings reads separately from trusted resolution. - -Namespace IDs are opaque adapter keys rather than object paths: - -| Package | Namespace | Existing authoritative owner | -| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------- | -| `image-gen` | `llm.imageConfig` | `llm-config.json` top-level `imageConfig` plus SecretStore `llm:image:api-key` | -| `web-search` | `integration.tavily` | SecretStore `integration:tavily:api-key` with `TAVILY_API_KEY` fallback | -| `youtube-transcripts` | `integration.rapidapi` | SecretStore `integration:rapidapi:api-key` with `RAPIDAPI_KEY` fallback | -| `ink-ocr` | `integration.azureVisionInkOcr` | Existing versioned Azure Vision record and its legacy/environment compatibility reads | - -This is a zero-persistent-data-migration compatibility layer. Reading Capability status performs no write; saving delegates to the original owner; no second record is created; credentials are not copied, rewritten, or re-encrypted. The original owner retains validation, defaults, environment fallback, atomicity, rollback, and explicit-null semantics. - -Masked Settings responses return `null` for secret values and identify configured fields separately. Trusted `resolveForServer()` and authenticated External leases resolve effective values, including environment fallbacks, only at the point of use. - -## Execution paths - -Internal Agent tools keep their high-level Huabu integrations. `generate_image` still owns typed tool arguments, model capability validation, reference artifact reads, provider SDK behavior, image decoding, and artifact persistence; it obtains provider configuration through `resolveForServer('image-gen')`. - -Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Capability configuration but do not import package `client.mjs`. - -External Agent packages provide a real `SKILL.md` and, when direct provider execution is needed, a `client.mjs` exporting `createClient({ config })`. The bundled Image and Tavily packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore ship neither placeholder file. - -## Owner Settings API - -The owner UI uses: - -```text -GET /api/capabilities -GET /api/capabilities/:capabilityId -PUT /api/capabilities/:capabilityId -``` - -Wire schemas live in `packages/shared/src/types/api/capability-package.ts`. The Web app imports only their inferred types and renders `CapabilitiesSettings` from the returned manifests. Existing capability-specific endpoints remain compatible for non-migrated callers, but the Capabilities tab uses only the generic API. - -## External Agent RFS API - -The canvas-scoped RFS already reserves `/capabilities` for direct Space-operation discovery, so provider packages use the unambiguous `/capability-packages` resource: - -```text -GET /capability-packages -GET /capability-packages/:id/manifest -GET /capability-packages/:id/skill -GET /capability-packages/:id/client -POST /capability-packages/:id/lease -``` - -Manifest and Skill responses contain no credentials. Client source is a versioned bundled asset. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and packages without an `agent` declaration explicitly, returns only fields declared by the selected package, and uses `Cache-Control: no-store`. - -## Agentlet SDK - -Agentlet publishes `dist/capability-sdk/index.js`. The daemon computes its absolute `file://` URL relative to its own `import.meta.url` and injects it as the authoritative `AGENTLET_CAPABILITY_SDK_URL` after workload environment values, so a Profile or session cannot replace it. - -`loadCapability(id)` obtains a fresh lease and loads the trusted package client from Huabu without writing credentials to disk. `withCapability(id, callback)` is the convenience wrapper. The SDK reports bounded status-only request failures and does not include response bodies that could contain credentials. - -The SDK reduces accidental persistence but is not a sandbox. A trusted External Agent and loaded client share the Agent process's filesystem, network, RFS bearer, and provider credentials. Static provider credentials cannot be revoked after disclosure except by provider-side rotation. - -## Build and packaging - -Server development reads packages from `apps/server/src/capabilities`. The Server bundle copies that directory to `dist-bundle/capabilities`. The bundled Agentlet build emits both `agentlet/index.js` and `agentlet/capability-sdk/index.js`; the published Agentlet npm package already includes its complete `dist` tree. - -## Code entry points - -| File | Responsibility | -| -------------------------------------------------------------------- | ------------------------------------------------------ | -| `packages/shared/src/types/api/capability-package.ts` | Manifest, Generic Settings, summary, and lease schemas | -| `apps/server/src/modules/capabilities/package-loader.ts` | Bundled YAML parsing, validation, and path confinement | -| `apps/server/src/modules/capabilities/provision-service.ts` | Namespace adapters and trusted/masked projections | -| `apps/server/src/modules/capabilities/capabilities.route.ts` | Owner Generic Settings API | -| `apps/server/src/modules/remote_fs/rfs.route.ts` | Authenticated package discovery, files, and lease | -| `apps/web/src/components/Settings/sections/CapabilitiesSettings.tsx` | Manifest-driven Capabilities UI | -| `external/agentlet/packages/local/src/capability-sdk/index.ts` | External Agent SDK | diff --git a/docs/architecture/credential-storage.md b/docs/architecture/credential-storage.md index b83130d35..14b074379 100644 --- a/docs/architecture/credential-storage.md +++ b/docs/architecture/credential-storage.md @@ -29,9 +29,9 @@ The renderer never receives plaintext credentials. Existing HTTP read models con Remote Server Basic Auth is separate from Huabu's `SecretStore`. Electron accepts credentials only through a sandboxed prompt for the exact configured Server origin, submits them directly to Chromium's authentication callback, and does not write them to `safeStorage`, server data, process arguments, or renderer state. -Settings API updates for optional capability credentials use an explicit three-state patch contract: omitting a key preserves the persisted value, a non-empty string sets or replaces it, and `null` removes the value stored by Huabu. Removing a persisted key preserves non-secret provider configuration and does not alter deployment-owned environment variables; an environment fallback may therefore keep the capability available at runtime. +Settings API updates for optional service credentials use an explicit three-state patch contract: omitting a key preserves the persisted value, a non-empty string sets or replaces it, and `null` removes the value stored by Huabu. Removing a persisted key preserves non-secret provider configuration and does not alter deployment-owned environment variables; an environment fallback may therefore keep the service available at runtime. -Settings > Capabilities is rendered from bundled `huabu-capability/v1` manifests and writes through `CapabilityProvisionService`. Each manifest names a code-registered opaque storage namespace whose adapter delegates to the existing owner and SecretStore IDs. This compatibility layer performs no read-time migration and creates no generic duplicate record: Image, Tavily, RapidAPI, and Ink OCR retain their existing storage, fallback, masking, and update semantics. See [`capability-packages.md`](./capability-packages.md). +Settings > Services is rendered from bundled `huabu-service/v1` manifests and writes through `ServiceProvisioner`. Each manifest names a code-registered opaque storage namespace whose adapter delegates to the existing owner and SecretStore IDs. This compatibility layer performs no read-time migration and creates no generic duplicate record: Image, Tavily, RapidAPI, and Ink OCR retain their existing storage, fallback, masking, and update semantics. See [`service-packages.md`](./service-packages.md). ### Agentlet connection token @@ -41,7 +41,7 @@ Ordinary reads return only the source (`stored`, `environment`, or `generated`) ### Azure AI Vision handwriting OCR -Settings > Capabilities exposes optional handwriting recognition as a compact Azure AI Vision row alongside other Huabu-managed service capabilities, matching the key icon and Set API Key / Update Key interaction used by those services. One click opens visibly labeled Endpoint and API Key inputs in spaced, full-width field groups below the title and description, followed by Save and Cancel, without configuration-source paragraphs or instructional text. The row identifies Azure AI Vision and briefly discloses selected-stroke processing; the endpoint and key must belong to the same Azure resource. Errors and read-only restrictions remain explicit. There is no provider selector, connectivity probe, or generic OCR compatibility claim. +Settings > Services exposes optional handwriting recognition as a compact Azure AI Vision row alongside other Huabu-managed services, matching the key icon and Set API Key / Update Key interaction used by those services. One click opens visibly labeled Endpoint and API Key inputs in spaced, full-width field groups below the title and description, followed by Save and Cancel, without configuration-source paragraphs or instructional text. The row identifies Azure AI Vision and briefly discloses selected-stroke processing; the endpoint and key must belong to the same Azure resource. Errors and read-only restrictions remain explicit. There is no provider selector, connectivity probe, or generic OCR compatibility claim. Owner-only `GET` and `PUT /api/integrations/ink-ocr/config` use the shared OCR configuration schemas. Endpoint and API key overrides are stored together as one versioned JSON record under `integration:azure-vision:config` in the existing `SecretStore`. Serialized read-modify-write updates replace that single encrypted record, so recognition observes a complete old or new configuration rather than a partially written pair. This uses the existing standalone encrypted-file and Electron safeStorage backends; it does not depend on multi-secret desktop batching or a rollback across two files. diff --git a/docs/architecture/service-packages.md b/docs/architecture/service-packages.md new file mode 100644 index 000000000..21f9b26fb --- /dev/null +++ b/docs/architecture/service-packages.md @@ -0,0 +1,101 @@ +# Service Packages + +> Current architecture for Huabu-managed third-party services. Last updated: 2026-10-10 + +## Scope + +Service Packages make provider configuration declarative without forcing Internal Agent tools, product pipelines, and External Agents through one execution path. The package is the source of truth for Settings fields and Agent-facing files; reviewed Huabu code remains the source of truth for Server execution. + +The bundled packages live under `apps/server/src/services//`: + +```text +/ +├── service.yaml +├── SKILL.md # required only when External Agent-facing +└── client.mjs # required only for a direct Agent-side provider call +``` + +Phase 1 packages are trusted files shipped with Huabu. User upload, installation, remote registries, and Server execution of uploaded code are not supported. + +## Manifest contract + +`huabu-service/v1` is defined by `serviceManifestSchema` in `packages/shared/src/types/api/service-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, and an `agent` block without a Skill fail validation. + +Every package declares a stable ID and version, display metadata, one registered storage namespace, optional Agent files, and constrained configuration fields. Supported field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or client contract. + +The manifest does not declare Internal Agent or Pipeline consumers. Those execution paths are reviewed Huabu code and cannot be enabled by package metadata. The presence of an `agent` block is the complete declaration that a package supports External Agent use; its `skill` is required and its direct-provider `client` is optional. A package without `agent` cannot be leased to an External Agent. + +## Provision Service and storage bindings + +`ServiceProvisioner` is the canonical access point for Generic Settings, Internal Agent tools, product pipelines, and External Agent leases. It validates field updates against the manifest, selects a code-registered namespace adapter, and exposes masked settings reads separately from trusted resolution. + +Namespace IDs are opaque adapter keys rather than object paths: + +| Package | Namespace | Existing authoritative owner | +| --------------------- | ------------------------------- | ------------------------------------------------------------------------------------- | +| `image-gen` | `llm.imageConfig` | `llm-config.json` top-level `imageConfig` plus SecretStore `llm:image:api-key` | +| `web-search` | `integration.tavily` | SecretStore `integration:tavily:api-key` with `TAVILY_API_KEY` fallback | +| `youtube-transcripts` | `integration.rapidapi` | SecretStore `integration:rapidapi:api-key` with `RAPIDAPI_KEY` fallback | +| `ink-ocr` | `integration.azureVisionInkOcr` | Existing versioned Azure Vision record and its legacy/environment compatibility reads | + +This is a zero-persistent-data-migration compatibility layer. Reading Service status performs no write; saving delegates to the original owner; no second record is created; credentials are not copied, rewritten, or re-encrypted. The original owner retains validation, defaults, environment fallback, atomicity, rollback, and explicit-null semantics. + +Masked Settings responses return `null` for secret values and identify configured fields separately. Trusted `resolveForServer()` and authenticated External leases resolve effective values, including environment fallbacks, only at the point of use. + +## Execution paths + +Internal Agent tools keep their high-level Huabu integrations. `generate_image` still owns typed tool arguments, model capability validation, reference artifact reads, provider SDK behavior, image decoding, and artifact persistence; it obtains provider configuration through `resolveForServer('image-gen')`. + +Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Service configuration but do not import package `client.mjs`. + +External Agent packages provide a real `SKILL.md` and, when direct provider execution is needed, a `client.mjs` exporting `createClient({ config })`. The bundled Image and Tavily packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore ship neither placeholder file. + +## Owner Settings API + +The owner UI uses: + +```text +GET /api/services +GET /api/services/:serviceId +PUT /api/services/:serviceId +``` + +Wire schemas live in `packages/shared/src/types/api/service-package.ts`. The Web app imports only their inferred types and renders `ServicesSettings` from the returned manifests. Existing service-specific endpoints remain compatible for non-migrated callers, but the Services tab uses only the generic API. + +## External Agent RFS API + +The canvas-scoped RFS retains `/capabilities` for direct Space-operation discovery and exposes configured third-party services through a separate `/services` resource: + +```text +GET /services +GET /services/:id/manifest +GET /services/:id/skill +GET /services/:id/client +POST /services/:id/lease +``` + +Manifest and Skill responses contain no credentials. Client source is a versioned bundled asset. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and packages without an `agent` declaration explicitly, returns only fields declared by the selected package, and uses `Cache-Control: no-store`. + +## Agentlet SDK + +Agentlet publishes `dist/service-sdk/index.js`. The daemon computes its absolute `file://` URL relative to its own `import.meta.url` and injects it as the authoritative `AGENTLET_SERVICE_SDK_URL` after workload environment values, so a Profile or session cannot replace it. + +`loadService(id)` obtains a fresh lease and loads the trusted package client from Huabu without writing credentials to disk. `withService(id, callback)` is the convenience wrapper. The SDK reports bounded status-only request failures and does not include response bodies that could contain credentials. + +The SDK reduces accidental persistence but is not a sandbox. A trusted External Agent and loaded client share the Agent process's filesystem, network, RFS bearer, and provider credentials. Static provider credentials cannot be revoked after disclosure except by provider-side rotation. + +## Build and packaging + +Server development reads packages from `apps/server/src/services`. The Server bundle copies that directory to `dist-bundle/services`. The bundled Agentlet build emits both `agentlet/index.js` and `agentlet/service-sdk/index.js`; the published Agentlet npm package already includes its complete `dist` tree. + +## Code entry points + +| File | Responsibility | +| ---------------------------------------------------------------- | ------------------------------------------------------ | +| `packages/shared/src/types/api/service-package.ts` | Manifest, Generic Settings, summary, and lease schemas | +| `apps/server/src/modules/services/package-loader.ts` | Bundled YAML parsing, validation, and path confinement | +| `apps/server/src/modules/services/provisioner.ts` | Namespace adapters and trusted/masked projections | +| `apps/server/src/modules/services/services.route.ts` | Owner Generic Settings API | +| `apps/server/src/modules/remote_fs/rfs.route.ts` | Authenticated Service discovery, files, and lease | +| `apps/web/src/components/Settings/sections/ServicesSettings.tsx` | Manifest-driven Services UI | +| `external/agentlet/packages/local/src/service-sdk/index.ts` | External Agent SDK | diff --git a/docs/proposals/capability-packages.md b/docs/proposals/service-packages.md similarity index 53% rename from docs/proposals/capability-packages.md rename to docs/proposals/service-packages.md index ddece15ba..12092c31e 100644 --- a/docs/proposals/capability-packages.md +++ b/docs/proposals/service-packages.md @@ -1,4 +1,4 @@ -# Huabu Capability Package 架构 +# Huabu Service Package 架构 Status: Accepted @@ -6,16 +6,16 @@ Last updated: 2026-10-10 ## 摘要 -本 Proposal 定义统一的 Capability Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace 以及可选的 Agent Skill/client，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 +本 Proposal 定义统一的 Service Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace 以及可选的 Agent Skill/client，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 -Phase 1 将当前 Settings > Capabilities 中的 Image Generation、Tavily Web Search、YouTube Transcripts 与 Azure Vision Ink OCR 全部迁入 Package、Manifest-driven Settings 和统一 Provision Service。Phase 1 不开放用户上传。 +Phase 1 将当前 Settings > Services 中的 Image Generation、Tavily Web Search、YouTube Transcripts 与 Azure Vision Ink OCR 全部迁入 Package、Manifest-driven Settings 和统一 Provision Service。Phase 1 不开放用户上传。 ## Package 形式 ```text -/ -├── capability.yaml -├── SKILL.md # 仅 Agent-facing Capability 必须 +/ +├── service.yaml +├── SKILL.md # 仅 Agent-facing Service 必须 ├── client.mjs # 仅 Agent 直接调用 provider 时必须 ├── references/ # 可选 └── assets/ # 可选 @@ -27,7 +27,7 @@ Phase 1 将当前 Settings > Capabilities 中的 Image Generation、Tavily Web S Manifest 的 `storage.namespace` 是 Huabu code 注册的 opaque adapter ID，不是对象路径、文件路径或 SecretStore ID。`configuration[].id` 直接引用 Adapter 暴露的稳定逻辑 key；UI 使用可变的 `label` 展示，因此不需要重复的 `storage.fields` mapping。 -所有 Capability 通过同一个 Provision Service 使用现有持久化底座。Image Generation 继续使用 `imageConfig` 与 `llm:image:api-key`，Tavily 和 RapidAPI 继续使用原 SecretStore ID，Ink OCR 继续使用现有 versioned record、legacy read 与 environment fallback。读取不写盘，保存写回原 owner，不复制、不删除、不重写、不重新加密，也不产生第二份配置。 +所有 Service 通过同一个 Provision Service 使用现有持久化底座。Image Generation 继续使用 `imageConfig` 与 `llm:image:api-key`，Tavily 和 RapidAPI 继续使用原 SecretStore ID，Ink OCR 继续使用现有 versioned record、legacy read 与 environment fallback。读取不写盘，保存写回原 owner，不复制、不删除、不重写、不重新加密，也不产生第二份配置。 ## 消费者边界 @@ -35,17 +35,17 @@ Internal Pi 继续使用高层 Server Tool。`generate_image` 仍负责参数、 Pipeline 继续使用 reviewed Server-side Adapter。YouTube transcript loader 与 Ink OCR 不导入 `client.mjs`。 -External Agent 通过 Agentlet 注入的 `AGENTLET_CAPABILITY_SDK_URL` 加载 SDK，经 authenticated RFS 按需取得当前 Package 配置，并在 Agentlet 设备执行受信任的 `client.mjs`。Image Generation 与 Tavily Web Search 提供真实 `agent.skill`/`agent.client`；YouTube Transcripts 与 Ink OCR 没有 `agent` block。 +External Agent 通过 Agentlet 注入的 `AGENTLET_SERVICE_SDK_URL` 加载 SDK，经 authenticated RFS 按需取得当前 Package 配置，并在 Agentlet 设备执行受信任的 `client.mjs`。Image Generation 与 Tavily Web Search 提供真实 `agent.skill`/`agent.client`；YouTube Transcripts 与 Ink OCR 没有 `agent` block。 ## API 与安全 -Owner Settings 使用 `/api/capabilities` generic API。RFS 已将 `/capabilities` 用作 Space operation discovery，因此 Package 使用 `/capability-packages`，提供列表、Manifest、Skill、client 与 POST lease。 +Owner Settings 使用 `/api/services` generic API。RFS 保留 `/capabilities` 用作 Space operation discovery，并使用独立的 `/services` 提供第三方服务列表、Manifest、Skill、client 与 POST lease。 Lease 使用现有 canvas-scoped RFS bearer，响应 `Cache-Control: no-store`，只返回目标 Package 声明的配置。Manifest、Skill、Settings read 和日志不返回 secret。Agentlet SDK 降低意外落盘和日志泄露，但不是 sandbox；Agent 与 client 拥有同一进程权限，静态 provider key 一旦交付只能通过 provider rotation 真正撤销。 ## Phase 1 -Phase 1 交付严格的 `huabu-capability/v1` schema、bundled Package discovery、Generic Settings、code-registered storage adapters、RFS Package/lease surface、Agentlet SDK，以及全部四个现有 UI Capability 的 Package 化。Image Generation 是完整 External Agent vertical slice，Tavily 同时提供可工作的 External client。 +Phase 1 交付严格的 `huabu-service/v1` schema、bundled Package discovery、Generic Settings、code-registered storage adapters、RFS Package/lease surface、Agentlet SDK，以及全部四个现有 UI Service 的 Package 化。Image Generation 是完整 External Agent vertical slice，Tavily 同时提供可工作的 External client。 Phase 1 明确排除用户上传、archive 安装、remote registry、任意 Server plugin、动态 UI/表达式、per-Profile/device grant、通用 provider result envelope 与自动 Node 创建。 diff --git a/packages/shared/src/types/api/index.ts b/packages/shared/src/types/api/index.ts index be2d4e53a..0524abba2 100644 --- a/packages/shared/src/types/api/index.ts +++ b/packages/shared/src/types/api/index.ts @@ -38,4 +38,4 @@ export * from './task.js'; export * from './interactive-view.js'; export * from './deployment.js'; export * from './agent-node.js'; -export * from './capability-package.js'; +export * from './service-package.js'; diff --git a/packages/shared/src/types/api/capability-package.test.ts b/packages/shared/src/types/api/service-package.test.ts similarity index 67% rename from packages/shared/src/types/api/capability-package.test.ts rename to packages/shared/src/types/api/service-package.test.ts index 0d29617b6..691ffbb1b 100644 --- a/packages/shared/src/types/api/capability-package.test.ts +++ b/packages/shared/src/types/api/service-package.test.ts @@ -4,16 +4,16 @@ import { describe, expect, it } from 'vitest'; import { - capabilityConfigUpdateSchema, - capabilityManifestSchema, -} from './capability-package.js'; + serviceConfigUpdateSchema, + serviceManifestSchema, +} from './service-package.js'; const manifest = { - schema: 'huabu-capability/v1', + schema: 'huabu-service/v1', id: 'example', version: '1.0.0', name: 'Example', - description: 'Example Capability', + description: 'Example Service', storage: { namespace: 'integration.example' }, configuration: [ { @@ -25,15 +25,15 @@ const manifest = { ], }; -describe('Capability Package contract', () => { +describe('Service Package contract', () => { it('accepts a Server-consumed package without Agent files', () => { - expect(capabilityManifestSchema.parse(manifest)).toMatchObject({ + expect(serviceManifestSchema.parse(manifest)).toMatchObject({ id: 'example', }); }); it('requires a Skill whenever the package declares Agent behavior', () => { - const result = capabilityManifestSchema.safeParse({ + const result = serviceManifestSchema.safeParse({ ...manifest, agent: { client: 'client.mjs' }, }); @@ -42,7 +42,7 @@ describe('Capability Package contract', () => { it('rejects duplicate field ids and empty updates', () => { expect( - capabilityManifestSchema.safeParse({ + serviceManifestSchema.safeParse({ ...manifest, configuration: [ ...manifest.configuration, @@ -50,7 +50,7 @@ describe('Capability Package contract', () => { ], }).success, ).toBe(false); - expect(capabilityConfigUpdateSchema.safeParse({ values: {} }).success).toBe( + expect(serviceConfigUpdateSchema.safeParse({ values: {} }).success).toBe( false, ); }); diff --git a/packages/shared/src/types/api/capability-package.ts b/packages/shared/src/types/api/service-package.ts similarity index 53% rename from packages/shared/src/types/api/capability-package.ts rename to packages/shared/src/types/api/service-package.ts index 54a7f0604..4d19cb0e6 100644 --- a/packages/shared/src/types/api/capability-package.ts +++ b/packages/shared/src/types/api/service-package.ts @@ -3,26 +3,26 @@ import { z } from 'zod'; -const capabilityIdSchema = z +const serviceIdSchema = z .string() - .regex(/^[a-z][a-z0-9-]{0,63}$/, 'Invalid capability id'); -const capabilityFieldIdSchema = z + .regex(/^[a-z][a-z0-9-]{0,63}$/, 'Invalid service id'); +const serviceFieldIdSchema = z .string() - .regex(/^[a-z][a-zA-Z0-9]{0,63}$/, 'Invalid capability field id'); + .regex(/^[a-z][a-zA-Z0-9]{0,63}$/, 'Invalid service field id'); -export const capabilityFieldOptionSchema = z.object({ +export const serviceFieldOptionSchema = z.object({ value: z.string().min(1).max(256), label: z.string().min(1).max(256), }); -export const capabilityConfigurationFieldSchema = z +export const serviceConfigurationFieldSchema = z .object({ - id: capabilityFieldIdSchema, + id: serviceFieldIdSchema, label: z.string().min(1).max(256), description: z.string().max(1024).optional(), type: z.enum(['text', 'secret', 'url', 'boolean', 'enum']), required: z.boolean().default(false), - options: z.array(capabilityFieldOptionSchema).min(1).max(100).optional(), + options: z.array(serviceFieldOptionSchema).min(1).max(100).optional(), placeholder: z.string().max(512).optional(), }) .strict() @@ -43,10 +43,10 @@ export const capabilityConfigurationFieldSchema = z } }); -export const capabilityManifestSchema = z +export const serviceManifestSchema = z .object({ - schema: z.literal('huabu-capability/v1'), - id: capabilityIdSchema, + schema: z.literal('huabu-service/v1'), + id: serviceIdSchema, version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Invalid package version'), name: z.string().min(1).max(256), description: z.string().min(1).max(1024), @@ -65,7 +65,7 @@ export const capabilityManifestSchema = z .strict() .optional(), configuration: z - .array(capabilityConfigurationFieldSchema) + .array(serviceConfigurationFieldSchema) .max(100) .default([]), }) @@ -84,48 +84,46 @@ export const capabilityManifestSchema = z } }); -export type CapabilityManifest = z.infer; -export type CapabilityConfigurationField = z.infer< - typeof capabilityConfigurationFieldSchema +export type ServiceManifest = z.infer; +export type ServiceConfigurationField = z.infer< + typeof serviceConfigurationFieldSchema >; -export const capabilityFieldValueSchema = z.union([ +export const serviceFieldValueSchema = z.union([ z.string().max(8192), z.boolean(), z.null(), ]); -export type CapabilityFieldValue = z.infer; +export type ServiceFieldValue = z.infer; -export const capabilityConfigUpdateSchema = z +export const serviceConfigUpdateSchema = z .object({ - values: z.record(capabilityFieldIdSchema, capabilityFieldValueSchema), + values: z.record(serviceFieldIdSchema, serviceFieldValueSchema), }) .strict() .refine((body) => Object.keys(body.values).length > 0, { - message: 'Provide at least one capability configuration value', + message: 'Provide at least one service configuration value', }); -export type CapabilityConfigUpdate = z.infer< - typeof capabilityConfigUpdateSchema ->; +export type ServiceConfigUpdate = z.infer; -export const capabilityParamsSchema = z - .object({ capabilityId: capabilityIdSchema }) +export const serviceParamsSchema = z + .object({ serviceId: serviceIdSchema }) .strict(); -export type CapabilityParams = z.infer; +export type ServiceParams = z.infer; -export const capabilityConfigSchema = z +export const serviceConfigSchema = z .object({ - manifest: capabilityManifestSchema, - values: z.record(capabilityFieldIdSchema, capabilityFieldValueSchema), - configuredFields: z.array(capabilityFieldIdSchema), + manifest: serviceManifestSchema, + values: z.record(serviceFieldIdSchema, serviceFieldValueSchema), + configuredFields: z.array(serviceFieldIdSchema), configured: z.boolean(), }) .strict(); -export type CapabilityConfig = z.infer; +export type ServiceConfig = z.infer; -export const capabilitySummarySchema = z +export const serviceSummarySchema = z .object({ - id: capabilityIdSchema, + id: serviceIdSchema, version: z.string(), name: z.string(), description: z.string(), @@ -133,21 +131,19 @@ export const capabilitySummarySchema = z availableToExternalAgent: z.boolean(), }) .strict(); -export type CapabilitySummary = z.infer; +export type ServiceSummary = z.infer; -export const capabilityListResponseSchema = z - .object({ capabilities: z.array(capabilitySummarySchema) }) +export const serviceListResponseSchema = z + .object({ services: z.array(serviceSummarySchema) }) .strict(); -export type CapabilityListResponse = z.infer< - typeof capabilityListResponseSchema ->; +export type ServiceListResponse = z.infer; -export const capabilityLeaseSchema = z +export const serviceLeaseSchema = z .object({ - id: capabilityIdSchema, + id: serviceIdSchema, version: z.string(), - config: z.record(capabilityFieldIdSchema, capabilityFieldValueSchema), + config: z.record(serviceFieldIdSchema, serviceFieldValueSchema), client: z.string().optional(), }) .strict(); -export type CapabilityLease = z.infer; +export type ServiceLease = z.infer; From 5fbe2dba48a146b6758bab9b13a2e30d72822b93 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 05:08:02 +0000 Subject: [PATCH 12/36] Make Agentlet Service SDK lease-only Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 4 +- .../packages/local/src/service-sdk/index.ts | 44 +++--------------- .../packages/local/tests/service-sdk.test.ts | 45 ++++++++++++++----- 3 files changed, 42 insertions(+), 51 deletions(-) diff --git a/external/agentlet/README.md b/external/agentlet/README.md index b9607ae0e..2b016f38d 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -123,11 +123,11 @@ The standard environment includes: | `AGENTLET_REACHBACK_DIR` | Directory containing host-provided resources. | | `AGENTLET_SERVER` | Gateway URL supplied to the daemon. | | `AGENTLET_TOKEN` | Authentication token available to host-provided reachback tools. | -| `AGENTLET_SERVICE_SDK_URL` | Daemon-owned absolute `file://` URL for the ESM Service SDK published under `dist/service-sdk`. | +| `AGENTLET_SERVICE_SDK_URL` | Daemon-owned absolute `file://` URL used by Service Package entries to lease current configuration through the ESM Service SDK published under `dist/service-sdk`. | Agentlet transports opaque resources and environment values; it does not interpret the host-specific tool protocol. -The optional Service SDK exports `loadService(id)` and `withService(id, callback)`. It uses host-injected reachback coordinates to obtain an on-demand configuration lease and load a trusted host-provided client without persisting credentials. The daemon writes `AGENTLET_SERVICE_SDK_URL` after workload environment values so a session cannot replace the SDK module location. +The optional Service SDK exports `leaseService(id)` and `withServiceConfig(id, callback)`. It uses host-injected reachback coordinates to obtain current configuration without downloading Package code or persisting credentials. Downloaded Service Package entries import the SDK through `AGENTLET_SERVICE_SDK_URL`; the daemon writes that variable after workload environment values so a session cannot replace the SDK module location. ## Repository layout diff --git a/external/agentlet/packages/local/src/service-sdk/index.ts b/external/agentlet/packages/local/src/service-sdk/index.ts index 095044e03..7d21258e1 100644 --- a/external/agentlet/packages/local/src/service-sdk/index.ts +++ b/external/agentlet/packages/local/src/service-sdk/index.ts @@ -2,21 +2,13 @@ export interface ServiceLease { id: string version: string config: Record - client?: string } -export interface ServiceContext { +export interface ServiceConfigContext { config: ServiceLease['config'] - client: Record | null lease: ServiceLease } -type ServiceClientModule = { - createClient?: (context: { - config: ServiceLease['config'] - }) => Record -} - function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { const value = process.env[name]?.trim() if (!value) throw new Error(`Service SDK requires ${name}`) @@ -39,26 +31,7 @@ async function serviceFetch(path: string, init?: RequestInit): Promise return response } -async function loadClient( - serviceId: string, - lease: ServiceLease, -): Promise | null> { - if (!lease.client) return null - const response = await serviceFetch( - `/services/${encodeURIComponent(serviceId)}/client`, - ) - const source = await response.text() - const moduleUrl = `data:text/javascript;base64,${Buffer.from(source, 'utf8').toString('base64')}` - const module = (await import(moduleUrl)) as ServiceClientModule - if (typeof module.createClient !== 'function') { - throw new Error('Service client must export createClient()') - } - return module.createClient({ config: lease.config }) -} - -export async function loadService( - serviceId: string, -): Promise { +export async function leaseService(serviceId: string): Promise { if (!/^[a-z][a-z0-9-]{0,63}$/.test(serviceId)) { throw new Error('Invalid Service id') } @@ -70,16 +43,13 @@ export async function loadService( if (lease.id !== serviceId || typeof lease.version !== 'string') { throw new Error('Invalid Service lease') } - return { - lease, - config: lease.config, - client: await loadClient(serviceId, lease), - } + return lease } -export async function withService( +export async function withServiceConfig( serviceId: string, - run: (context: ServiceContext) => Promise | T, + run: (context: ServiceConfigContext) => Promise | T, ): Promise { - return run(await loadService(serviceId)) + const lease = await leaseService(serviceId) + return run({ lease, config: lease.config }) } diff --git a/external/agentlet/packages/local/tests/service-sdk.test.ts b/external/agentlet/packages/local/tests/service-sdk.test.ts index 98265b72d..811b4c83f 100644 --- a/external/agentlet/packages/local/tests/service-sdk.test.ts +++ b/external/agentlet/packages/local/tests/service-sdk.test.ts @@ -1,6 +1,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest' -import { loadService } from '../src/service-sdk/index.js' +import { + leaseService, + withServiceConfig, +} from '../src/service-sdk/index.js' afterEach(() => { vi.unstubAllGlobals() @@ -9,7 +12,7 @@ afterEach(() => { }) describe('Service SDK', () => { - it('leases config and loads the trusted package client without logging secrets', async () => { + it('leases config without loading package code', async () => { process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' process.env.AGENTLET_TOKEN = 'agentlet-token' const fetchMock = vi @@ -20,22 +23,16 @@ describe('Service SDK', () => { id: 'example', version: '1.0.0', config: { apiKey: 'provider-secret' }, - client: 'client.mjs', }), { status: 200 }, ), ) - .mockResolvedValueOnce( - new Response( - 'export function createClient({ config }) { return { configured: Boolean(config.apiKey) }; }', - { status: 200 }, - ), - ) vi.stubGlobal('fetch', fetchMock) - const service = await loadService('example') + const lease = await leaseService('example') - expect(service.client).toEqual({ configured: true }) + expect(lease.config).toEqual({ apiKey: 'provider-secret' }) + expect(fetchMock).toHaveBeenCalledTimes(1) expect(fetchMock).toHaveBeenNthCalledWith( 1, 'https://huabu.example/api/rfs/canvas-1/services/example/lease', @@ -46,6 +43,30 @@ describe('Service SDK', () => { ) }) + it('provides config and lease metadata to a scoped callback', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' + process.env.AGENTLET_TOKEN = 'agentlet-token' + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue( + new Response( + JSON.stringify({ + id: 'example', + version: '1.0.0', + config: { apiKey: 'provider-secret' }, + }), + ), + ), + ) + + await expect( + withServiceConfig('example', ({ config, lease }) => ({ + configured: Boolean(config.apiKey), + version: lease.version, + })), + ).resolves.toEqual({ configured: true, version: '1.0.0' }) + }) + it('does not include response bodies in provider-facing errors', async () => { process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' process.env.AGENTLET_TOKEN = 'agentlet-token' @@ -56,7 +77,7 @@ describe('Service SDK', () => { ), ) - await expect(loadService('example')).rejects.toThrow( + await expect(leaseService('example')).rejects.toThrow( 'Service request failed (409)', ) }) From d04e289c28c1c1a2d6004d4be9af6163821da3e2 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 05:08:18 +0000 Subject: [PATCH 13/36] Distribute executable Service Packages Replace Agent metadata with an exact package file allowlist, stream Agent-facing Packages as ZIP archives, and ship modifiable entry.mjs starting points that lease configuration at runtime. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/modules/remote_fs/rfs.route.test.ts | 61 ++++++-- .../server/src/modules/remote_fs/rfs.route.ts | 67 ++++++--- apps/server/src/modules/services/index.ts | 1 + .../modules/services/package-loader.test.ts | 13 +- .../src/modules/services/package-loader.ts | 57 ++++++-- .../src/modules/services/provisioner.test.ts | 1 - .../src/modules/services/provisioner.ts | 6 +- .../modules/services/services.route.test.ts | 2 +- .../src/prompt/external-agent/access-huabu.md | 25 ++-- apps/server/src/services/image-gen/SKILL.md | 6 +- apps/server/src/services/image-gen/client.mjs | 40 ------ apps/server/src/services/image-gen/entry.mjs | 134 ++++++++++++++++++ .../{client.test.ts => entry.test.ts} | 66 +++++++-- .../src/services/image-gen/service.yaml | 7 +- apps/server/src/services/ink-ocr/service.yaml | 2 + apps/server/src/services/web-search/SKILL.md | 4 +- .../server/src/services/web-search/client.mjs | 31 ---- apps/server/src/services/web-search/entry.mjs | 80 +++++++++++ .../{client.test.ts => entry.test.ts} | 26 ++-- .../src/services/web-search/service.yaml | 7 +- .../services/youtube-transcripts/service.yaml | 2 + .../sections/ServicesSettings.test.tsx | 1 + docs/architecture/agent-reachback.md | 6 +- docs/architecture/api-design.md | 2 +- docs/architecture/service-packages.md | 40 +++--- docs/proposals/service-packages.md | 18 +-- .../src/types/api/service-package.test.ts | 25 +++- .../shared/src/types/api/service-package.ts | 47 +++++- 28 files changed, 572 insertions(+), 205 deletions(-) delete mode 100644 apps/server/src/services/image-gen/client.mjs create mode 100644 apps/server/src/services/image-gen/entry.mjs rename apps/server/src/services/image-gen/{client.test.ts => entry.test.ts} (52%) delete mode 100644 apps/server/src/services/web-search/client.mjs create mode 100644 apps/server/src/services/web-search/entry.mjs rename apps/server/src/services/web-search/{client.test.ts => entry.test.ts} (69%) diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index 7b6d1a262..166c0e88c 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -18,6 +18,7 @@ import { join } from 'node:path'; import fastify from 'fastify'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import yauzl from 'yauzl'; import { AGENT_CANVAS_COMMAND_TYPES, @@ -104,6 +105,25 @@ async function buildApp() { return app; } +async function zipEntries(buffer: Buffer): Promise { + return new Promise((resolve, reject) => { + yauzl.fromBuffer(buffer, { lazyEntries: true }, (error, zip) => { + if (error || !zip) { + reject(error ?? new Error('Failed to open ZIP')); + return; + } + const entries: string[] = []; + zip.on('entry', (entry) => { + entries.push(entry.fileName); + zip.readEntry(); + }); + zip.on('end', () => resolve(entries)); + zip.on('error', reject); + zip.readEntry(); + }); + }); +} + /** * Seed a note node (topology entry + `nodes/.md` body) and * return its download path. Re-calling with the same id/label overwrites the @@ -620,9 +640,9 @@ describe('third-party Services', () => { method: 'GET', url: '/rfs/c1/services/image-gen/skill', }); - const client = await app.inject({ + const packageDownload = await app.inject({ method: 'GET', - url: '/rfs/c1/services/image-gen/client', + url: '/rfs/c1/download/services/image-gen.zip', }); expect(discovery.statusCode).toBe(200); @@ -636,11 +656,30 @@ describe('third-party Services', () => { }); expect(skill.statusCode).toBe(200); expect(skill.headers['content-type']).toMatch(/text\/markdown/); - expect(client.statusCode).toBe(200); - expect(client.headers['content-type']).toMatch(/text\/javascript/); - expect(client.headers['cache-control']).toBe('public, max-age=300'); + expect(packageDownload.statusCode).toBe(200); + expect(packageDownload.headers['content-type']).toMatch( + /application\/zip/, + ); + expect(packageDownload.headers['content-disposition']).toContain( + 'image-gen-1.0.0.zip', + ); + expect(packageDownload.headers['cache-control']).toBe( + 'private, max-age=300', + ); + expect(await zipEntries(packageDownload.rawPayload)).toEqual([ + 'image-gen/service.yaml', + 'image-gen/SKILL.md', + 'image-gen/entry.mjs', + ]); + + const notModified = await app.inject({ + method: 'GET', + url: '/rfs/c1/download/services/image-gen.zip', + headers: { 'if-none-match': packageDownload.headers.etag }, + }); + expect(notModified.statusCode).toBe(304); - for (const response of [discovery, manifest, skill]) { + for (const response of [discovery, manifest, skill, packageDownload]) { expect(response.body).not.toContain('test-secret'); expect(response.body).not.toContain('api-key'); } @@ -656,9 +695,9 @@ describe('third-party Services', () => { method: 'GET', url: '/rfs/c1/services/ink-ocr/skill', }); - const noClient = await app.inject({ + const noPackage = await app.inject({ method: 'GET', - url: '/rfs/c1/services/youtube-transcripts/client', + url: '/rfs/c1/download/services/youtube-transcripts.zip', }); const invalid = await app.inject({ method: 'GET', @@ -667,8 +706,10 @@ describe('third-party Services', () => { expect(noSkill.statusCode).toBe(404); expect(noSkill.json()).toMatchObject({ code: 'skill_not_found' }); - expect(noClient.statusCode).toBe(404); - expect(noClient.json()).toMatchObject({ code: 'client_not_found' }); + expect(noPackage.statusCode).toBe(403); + expect(noPackage.json()).toMatchObject({ + code: 'service_not_agent_accessible', + }); expect(invalid.statusCode).toBe(400); } finally { await app.close(); diff --git a/apps/server/src/modules/remote_fs/rfs.route.ts b/apps/server/src/modules/remote_fs/rfs.route.ts index b2a5adcbe..bfc6caba4 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.ts @@ -36,6 +36,8 @@ import { createReadStream, existsSync, statSync } from 'node:fs'; import { mkdir, rm, writeFile } from 'node:fs/promises'; import path from 'node:path'; +import archiver from 'archiver'; + import { AGENT_SSE_EVENTS, RFS_HEARTBEAT_DEFAULT_SEC, @@ -126,6 +128,7 @@ import { serviceProvisioner, ServiceProvisionError, getBundledServicePackage, + isAgentFacingService, readServicePackageFile, } from '../services/index.js'; import { @@ -566,11 +569,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => { if (!parsed.success) { return reply.code(400).send(rfsError('Invalid Service id')); } - const service = getBundledServicePackage(parsed.data.serviceId); - const skill = service?.manifest.agent?.skill; - const content = skill - ? readServicePackageFile(parsed.data.serviceId, skill) - : null; + const content = readServicePackageFile(parsed.data.serviceId, 'SKILL.md'); if (!content) { return reply .code(404) @@ -581,7 +580,7 @@ const rfsRoutes: FastifyPluginAsync = async (app) => { app.get<{ Params: ServiceParams & { canvasId: string }; - }>('/:canvasId/services/:serviceId/client', async (request, reply) => { + }>('/:canvasId/download/services/:serviceId.zip', async (request, reply) => { const parsed = serviceParamsSchema.safeParse({ serviceId: request.params.serviceId, }); @@ -589,19 +588,55 @@ const rfsRoutes: FastifyPluginAsync = async (app) => { return reply.code(400).send(rfsError('Invalid Service id')); } const service = getBundledServicePackage(parsed.data.serviceId); - const client = service?.manifest.agent?.client; - const content = client - ? readServicePackageFile(parsed.data.serviceId, client) - : null; - if (!content) { + if (!service) { return reply .code(404) - .send(rfsError('Service client not found', 'client_not_found')); + .send(rfsError('Service not found', 'service_not_found')); } - return reply - .header('Cache-Control', 'public, max-age=300') - .type('text/javascript; charset=utf-8') - .send(content); + if (!isAgentFacingService(service.manifest)) { + return reply + .code(403) + .send( + rfsError( + 'Service is not available to External Agents', + 'service_not_agent_accessible', + ), + ); + } + const etag = `"${service.contentHash}"`; + reply.header('ETag', etag); + if (ifNoneMatchSatisfied(request.headers['if-none-match'], etag)) { + return reply.code(304).send(); + } + const filename = `${service.manifest.id}-${service.manifest.version}.zip`; + reply + .header('Cache-Control', 'private, max-age=300') + .header('Content-Disposition', `attachment; filename="${filename}"`) + .type('application/zip'); + const archive = archiver('zip', { zlib: { level: 6 } }); + archive.on('warning', (error) => { + request.log.warn( + { err: error, serviceId: service.manifest.id }, + 'Service package archive warning', + ); + }); + archive.on('error', (error) => { + request.log.error( + { err: error, serviceId: service.manifest.id }, + 'Service package archive failed', + ); + }); + const archiveRoot = `${service.manifest.id}/`; + archive.file(service.manifestPath, { + name: `${archiveRoot}service.yaml`, + }); + for (const file of service.files) { + archive.file(file.absolutePath, { + name: `${archiveRoot}${file.relativePath}`, + }); + } + void archive.finalize(); + return reply.send(archive); }); app.post<{ diff --git a/apps/server/src/modules/services/index.ts b/apps/server/src/modules/services/index.ts index 40b23b3a1..187137276 100644 --- a/apps/server/src/modules/services/index.ts +++ b/apps/server/src/modules/services/index.ts @@ -15,6 +15,7 @@ export const serviceProvisioner = new ServiceProvisioner( export { getBundledServicePackage, + isAgentFacingService, readServicePackageFile, } from './package-loader.js'; export { ServiceProvisionError } from './provisioner.js'; diff --git a/apps/server/src/modules/services/package-loader.test.ts b/apps/server/src/modules/services/package-loader.test.ts index 31333dbfb..1a8deac62 100644 --- a/apps/server/src/modules/services/package-loader.test.ts +++ b/apps/server/src/modules/services/package-loader.test.ts @@ -20,17 +20,20 @@ describe('bundled Service packages', () => { expect(packages.get('image-gen')?.manifest.storage.namespace).toBe( 'llm.imageConfig', ); - expect(packages.get('youtube-transcripts')?.manifest.agent).toBeUndefined(); - expect(packages.get('ink-ocr')?.manifest.agent).toBeUndefined(); + expect(packages.get('youtube-transcripts')?.manifest.package.files).toEqual( + [], + ); + expect(packages.get('ink-ocr')?.manifest.package.files).toEqual([]); }); - it('exposes real Agent files only when the manifest declares Agent behavior', () => { + it('exposes only exact files declared by the package', () => { expect(readServicePackageFile('image-gen', 'SKILL.md')).toContain( '# Image Generation', ); - expect(readServicePackageFile('web-search', 'client.mjs')).toContain( - 'createClient', + expect(readServicePackageFile('web-search', 'entry.mjs')).toContain( + 'search', ); + expect(readServicePackageFile('image-gen', 'entry.test.ts')).toBeNull(); expect( readServicePackageFile('youtube-transcripts', 'SKILL.md'), ).toBeNull(); diff --git a/apps/server/src/modules/services/package-loader.ts b/apps/server/src/modules/services/package-loader.ts index a402b8b56..0fd138643 100644 --- a/apps/server/src/modules/services/package-loader.ts +++ b/apps/server/src/modules/services/package-loader.ts @@ -1,7 +1,8 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { existsSync, readFileSync } from 'node:fs'; +import { createHash } from 'node:crypto'; +import { existsSync, lstatSync, readFileSync } from 'node:fs'; import { dirname, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; @@ -23,6 +24,14 @@ const PACKAGE_IDS = [ export interface BundledServicePackage { root: string; manifest: ServiceManifest; + manifestPath: string; + files: readonly ServicePackageFile[]; + contentHash: string; +} + +export interface ServicePackageFile { + relativePath: string; + absolutePath: string; } function packageRoot(): string { @@ -35,9 +44,8 @@ function packageRoot(): string { function readPackage(packageId: (typeof PACKAGE_IDS)[number]) { const root = resolveDirectChildPath(packageRoot(), packageId); const manifestPath = resolveDirectChildPath(root, 'service.yaml'); - const parsed = serviceManifestSchema.safeParse( - parse(readFileSync(manifestPath, 'utf8')), - ); + const manifestSource = readFileSync(manifestPath, 'utf8'); + const parsed = serviceManifestSchema.safeParse(parse(manifestSource)); if (!parsed.success) { throw new Error( `Invalid bundled Service manifest "${packageId}": ${parsed.error.issues[0]?.message ?? 'unknown error'}`, @@ -46,16 +54,31 @@ function readPackage(packageId: (typeof PACKAGE_IDS)[number]) { if (parsed.data.id !== packageId) { throw new Error(`Service package directory must match id "${packageId}"`); } - for (const file of [ - parsed.data.agent?.skill, - parsed.data.agent?.client, - ].filter((value): value is string => Boolean(value))) { - const filePath = safeJoin(root, file); - if (!existsSync(filePath)) { - throw new Error(`Service "${packageId}" references missing file`); + const files = parsed.data.package.files.map((relativePath) => { + const absolutePath = safeJoin(root, relativePath); + if (!existsSync(absolutePath) || !lstatSync(absolutePath).isFile()) { + throw new Error( + `Service "${packageId}" references missing or non-regular file "${relativePath}"`, + ); } + return { relativePath, absolutePath }; + }); + const hash = createHash('sha256'); + hash.update('service.yaml\0').update(manifestSource).update('\0'); + for (const file of files) { + hash + .update(file.relativePath) + .update('\0') + .update(readFileSync(file.absolutePath)) + .update('\0'); } - return { root, manifest: parsed.data }; + return { + root, + manifest: parsed.data, + manifestPath, + files, + contentHash: hash.digest('hex'), + }; } let packages: ReadonlyMap | null = null; @@ -80,6 +103,12 @@ export function readServicePackageFile( ): string | null { const service = getBundledServicePackage(serviceId); if (!service) return null; - const filePath = safeJoin(service.root, file); - return existsSync(filePath) ? readFileSync(filePath, 'utf8') : null; + const packageFile = service.files.find( + (candidate) => candidate.relativePath === file, + ); + return packageFile ? readFileSync(packageFile.absolutePath, 'utf8') : null; +} + +export function isAgentFacingService(manifest: ServiceManifest): boolean { + return manifest.package.files.includes('SKILL.md'); } diff --git a/apps/server/src/modules/services/provisioner.test.ts b/apps/server/src/modules/services/provisioner.test.ts index 85e8855c0..b8a439b47 100644 --- a/apps/server/src/modules/services/provisioner.test.ts +++ b/apps/server/src/modules/services/provisioner.test.ts @@ -113,7 +113,6 @@ describe('Service Provision Service storage bindings', () => { expect(lease).toMatchObject({ id: 'image-gen', - client: 'client.mjs', config: { baseUrl: 'https://images.example.com', apiKey: 'image-secret', diff --git a/apps/server/src/modules/services/provisioner.ts b/apps/server/src/modules/services/provisioner.ts index 93bdf4fb7..7b310b2c7 100644 --- a/apps/server/src/modules/services/provisioner.ts +++ b/apps/server/src/modules/services/provisioner.ts @@ -9,6 +9,7 @@ import { llmImageConfigUpdateSchema, } from '@huabu/shared'; +import { isAgentFacingService } from './package-loader.js'; import { SECRET_IDS } from '../../security/secret-ids.js'; import { getSecret } from '../../security/secret-store.js'; import { @@ -332,7 +333,7 @@ export class ServiceProvisioner { name: manifest.name, description: manifest.description, configured, - availableToExternalAgent: configured && Boolean(manifest.agent), + availableToExternalAgent: configured && isAgentFacingService(manifest), }; }); } @@ -373,7 +374,7 @@ export class ServiceProvisioner { lease(serviceId: string): ServiceLease { const manifest = this.manifest(serviceId); - if (!manifest.agent) { + if (!isAgentFacingService(manifest)) { throw new ServiceProvisionError( 'service_not_agent_accessible', `Service "${serviceId}" is not available to External Agents`, @@ -383,7 +384,6 @@ export class ServiceProvisioner { id: manifest.id, version: manifest.version, config: this.resolveForServer(serviceId), - ...(manifest.agent?.client ? { client: manifest.agent.client } : {}), }; } } diff --git a/apps/server/src/modules/services/services.route.test.ts b/apps/server/src/modules/services/services.route.test.ts index 9a74dd3fd..e7f8c12da 100644 --- a/apps/server/src/modules/services/services.route.test.ts +++ b/apps/server/src/modules/services/services.route.test.ts @@ -48,7 +48,7 @@ const maskedConfig = { name: 'Web Search', description: 'Search the web.', storage: { namespace: 'integration.tavily' }, - agent: { skill: 'SKILL.md', client: 'client.mjs' }, + package: { files: ['SKILL.md', 'entry.mjs'] }, configuration: [ { id: 'apiKey', diff --git a/apps/server/src/prompt/external-agent/access-huabu.md b/apps/server/src/prompt/external-agent/access-huabu.md index 1c03266bc..61ed0d03f 100644 --- a/apps/server/src/prompt/external-agent/access-huabu.md +++ b/apps/server/src/prompt/external-agent/access-huabu.md @@ -6,7 +6,7 @@ These environment variables are already set: - `HUABU_RFS_URL` — the base URL for this Space, with no trailing slash. - `AGENTLET_TOKEN` — the RFS bearer credential. -- `AGENTLET_SERVICE_SDK_URL` — the daemon-owned `file://` URL for loading configured provider Services. +- `AGENTLET_SERVICE_SDK_URL` — the daemon-owned `file://` URL used internally by downloaded Service Package entries to lease current configuration. - `HUABU_THREAD_ID` — your conversation ID. Pass it on `execute` (see §6) to attribute your edits. Prefer deterministic direct operations: @@ -17,7 +17,7 @@ Prefer deterministic direct operations: 4. Use the `SNAPSHOT_NODES` query to render image, sketch, or frame nodes into PNG artifacts you can inspect. 5. Use `execute` for validated Space commands. 6. Use `agent` only when you deliberately want the optional internal Huabu agent to interpret an open-ended request. -7. Discover configured provider services through `services` and follow the selected Package Skill before loading it through the Agentlet SDK. +7. Discover configured provider services through `services`, read the selected Package Skill, and download its complete Package before running or extending its entry. ## 1. Discover operations @@ -295,18 +295,21 @@ Before using one, fetch and follow its Skill: curl -fsS -H "$AUTH" "$HUABU_RFS_URL/services/image-gen/skill" ``` -Agent-facing packages can then be loaded from a short-lived `.mjs` script: +Download the complete Package to a path in your working directory: -```js -const { withService } = await import(process.env.AGENTLET_SERVICE_SDK_URL); - -await withService('image-gen', async ({ client }) => { - if (!client) throw new Error('Service client is unavailable'); - console.log(await client.generate({ prompt: 'A watercolor landscape' })); -}); +```bash +curl -fsS -H "$AUTH" \ + "$HUABU_RFS_URL/download/services/image-gen.zip" \ + -o image-gen.zip +unzip image-gen.zip +cd image-gen ``` -The SDK obtains current configuration on demand. Never print, persist, or forward returned credentials. A Service Package without an Agent Skill is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. +Every archive contains one top-level directory named after the Service, so extracting `image-gen.zip` creates `image-gen/` rather than placing files directly in the current directory. `service.yaml` and every file declared by `package.files` are included; undeclared development files are not. + +Read the extracted `SKILL.md`, then run the optional `entry.mjs` with Node as documented there. The entry obtains current configuration on demand through `AGENTLET_SERVICE_SDK_URL`; you normally do not need to import or call that SDK yourself. An entry is a modifiable starting point rather than a complete provider SDK: when the task needs another provider endpoint, follow the official documentation linked by the Skill and modify only your local Package copy. + +Never print, persist, or forward leased credentials. A Service Package without `SKILL.md` is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. ## Advanced workflows diff --git a/apps/server/src/services/image-gen/SKILL.md b/apps/server/src/services/image-gen/SKILL.md index 4aa569e6c..452a6dcb1 100644 --- a/apps/server/src/services/image-gen/SKILL.md +++ b/apps/server/src/services/image-gen/SKILL.md @@ -2,6 +2,8 @@ Use this Service when the user asks you to generate an image through their configured Azure OpenAI image deployment. -Load the Service through the Agentlet SDK URL in `AGENTLET_SERVICE_SDK_URL`. Call the returned client's `generate()` method with a non-empty `prompt` and optional provider-supported image parameters. Provider credentials are supplied only to the loaded client; never print, persist, or include them in another request. +`entry.mjs` is an executable starting point for basic prompt-to-image generation, not a complete provider SDK. Run `node entry.mjs --prompt "" --quality --output `, or use `--prompt-file ` for a file-backed prompt. It obtains current configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credentials. -The client returns the provider response. Decode or upload generated image bytes through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. +When the task needs image editing or another provider feature that the entry does not implement, read the [Azure OpenAI image generation documentation](https://learn.microsoft.com/azure/ai-services/openai/how-to/dall-e), modify the local Package copy, and keep configuration retrieval through `AGENTLET_SERVICE_SDK_URL`. + +The entry writes the generated image to the requested local path. Upload it through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. diff --git a/apps/server/src/services/image-gen/client.mjs b/apps/server/src/services/image-gen/client.mjs deleted file mode 100644 index 225522087..000000000 --- a/apps/server/src/services/image-gen/client.mjs +++ /dev/null @@ -1,40 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -export function createClient({ config }) { - return { - async generate(input) { - if (!input || typeof input.prompt !== 'string' || !input.prompt.trim()) { - throw new Error('Image generation requires a non-empty prompt'); - } - const endpoint = config.baseUrl.replace(/\/+$/, ''); - const deployment = config.model || config.modelFamily; - const v1Style = /(?:^|\/)(?:openai\/)?v1$/i.test(endpoint); - const url = v1Style - ? new URL(`${endpoint}/images/generations`) - : new URL( - `${endpoint}/openai/deployments/${encodeURIComponent(deployment)}/images/generations`, - ); - if (!v1Style) url.searchParams.set('api-version', config.apiVersion); - const response = await fetch(url, { - method: 'POST', - headers: { - ...(v1Style - ? { authorization: `Bearer ${config.apiKey}` } - : { 'api-key': config.apiKey }), - 'content-type': 'application/json', - }, - body: JSON.stringify({ - ...input, - prompt: input.prompt.trim(), - quality: input.quality || config.quality, - ...(v1Style ? { model: deployment } : {}), - }), - }); - if (!response.ok) { - throw new Error(`Image provider request failed (${response.status})`); - } - return response.json(); - }, - }; -} diff --git a/apps/server/src/services/image-gen/entry.mjs b/apps/server/src/services/image-gen/entry.mjs new file mode 100644 index 000000000..1c65b5375 --- /dev/null +++ b/apps/server/src/services/image-gen/entry.mjs @@ -0,0 +1,134 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { readFile, writeFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; + +const QUALITIES = new Set(['low', 'medium', 'high', 'auto']); + +function valueAfter(argv, index, option) { + const value = argv[index + 1]; + if (!value || value.startsWith('-')) { + throw new Error(`${option} requires a value`); + } + return value; +} + +function parseArgs(argv) { + const options = {}; + for (let index = 0; index < argv.length; index += 1) { + const argument = argv[index]; + if (argument === '--prompt' || argument === '-p') { + options.prompt = valueAfter(argv, index, argument); + index += 1; + } else if (argument === '--prompt-file') { + options.promptFile = valueAfter(argv, index, argument); + index += 1; + } else if (argument === '--quality') { + options.quality = valueAfter(argv, index, argument); + index += 1; + } else if (argument === '--output' || argument === '-o') { + options.output = valueAfter(argv, index, argument); + index += 1; + } else { + throw new Error(`Unknown argument: ${argument}`); + } + } + if (options.prompt && options.promptFile) { + throw new Error('Use either --prompt or --prompt-file, not both'); + } + if (!options.prompt && !options.promptFile) { + throw new Error('Image generation requires --prompt or --prompt-file'); + } + if (!options.output) { + throw new Error('Image generation requires --output'); + } + if (options.quality && !QUALITIES.has(options.quality)) { + throw new Error('--quality must be low, medium, high, or auto'); + } + return options; +} + +async function promptFrom(options) { + const prompt = options.promptFile + ? await readFile(options.promptFile, 'utf8') + : options.prompt; + if (!prompt?.trim()) { + throw new Error('Image generation requires a non-empty prompt'); + } + return prompt.trim(); +} + +export async function generate({ config, input }) { + if (!input || typeof input.prompt !== 'string' || !input.prompt.trim()) { + throw new Error('Image generation requires a non-empty prompt'); + } + const endpoint = config.baseUrl.replace(/\/+$/, ''); + const deployment = config.model || config.modelFamily; + const v1Style = /(?:^|\/)(?:openai\/)?v1$/i.test(endpoint); + const url = v1Style + ? new URL(`${endpoint}/images/generations`) + : new URL( + `${endpoint}/openai/deployments/${encodeURIComponent(deployment)}/images/generations`, + ); + if (!v1Style) url.searchParams.set('api-version', config.apiVersion); + const response = await fetch(url, { + method: 'POST', + headers: { + ...(v1Style + ? { authorization: `Bearer ${config.apiKey}` } + : { 'api-key': config.apiKey }), + 'content-type': 'application/json', + }, + body: JSON.stringify({ + ...input, + prompt: input.prompt.trim(), + quality: input.quality || config.quality, + ...(v1Style ? { model: deployment } : {}), + }), + }); + if (!response.ok) { + throw new Error(`Image provider request failed (${response.status})`); + } + return response.json(); +} + +async function imageBytes(result) { + const image = result?.data?.[0]; + if (typeof image?.b64_json === 'string') { + return Buffer.from(image.b64_json, 'base64'); + } + if (typeof image?.url === 'string') { + const response = await fetch(image.url); + if (!response.ok) { + throw new Error(`Image download failed (${response.status})`); + } + return Buffer.from(await response.arrayBuffer()); + } + throw new Error('Image provider response did not contain image bytes'); +} + +export async function main(argv = process.argv.slice(2)) { + const options = parseArgs(argv); + const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; + if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); + const { withServiceConfig } = await import(sdkUrl); + await withServiceConfig('image-gen', async ({ config }) => { + const result = await generate({ + config, + input: { + prompt: await promptFrom(options), + ...(options.quality ? { quality: options.quality } : {}), + }, + }); + await writeFile(options.output, await imageBytes(result)); + }); +} + +const invokedPath = process.argv[1] + ? pathToFileURL(resolve(process.argv[1])).href + : null; +if (invokedPath === import.meta.url) { + await main(); +} diff --git a/apps/server/src/services/image-gen/client.test.ts b/apps/server/src/services/image-gen/entry.test.ts similarity index 52% rename from apps/server/src/services/image-gen/client.test.ts rename to apps/server/src/services/image-gen/entry.test.ts index 7de4e3a5d..86f3da3c6 100644 --- a/apps/server/src/services/image-gen/client.test.ts +++ b/apps/server/src/services/image-gen/entry.test.ts @@ -5,31 +5,34 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { readServicePackageFile } from '../../modules/services/package-loader.js'; -async function loadClient() { - const source = readServicePackageFile('image-gen', 'client.mjs'); - if (!source) throw new Error('Image Service client is missing'); +async function loadEntry() { + const source = readServicePackageFile('image-gen', 'entry.mjs'); + if (!source) throw new Error('Image Service entry is missing'); return import( `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` ) as Promise<{ - createClient(input: { config: Record }): { - generate(input: Record): Promise; - }; + generate(input: { + config: Record; + input: Record; + }): Promise; + main(argv: string[]): Promise; }>; } afterEach(() => { vi.unstubAllGlobals(); + delete process.env.AGENTLET_SERVICE_SDK_URL; }); -describe('Image Service client', () => { +describe('Image Service entry', () => { it('uses classic Azure deployment routing', async () => { const fetchMock = vi .fn() .mockResolvedValue(new Response(JSON.stringify({ data: [] }))); vi.stubGlobal('fetch', fetchMock); - const { createClient } = await loadClient(); + const { generate } = await loadEntry(); - await createClient({ + await generate({ config: { apiKey: 'test-secret', apiVersion: '2025-04-01-preview', @@ -38,7 +41,8 @@ describe('Image Service client', () => { modelFamily: 'gpt-image-1', quality: 'high', }, - }).generate({ prompt: ' a fox ' }); + input: { prompt: ' a fox ' }, + }); const [url, init] = fetchMock.mock.calls[0] ?? []; expect(String(url)).toBe( @@ -56,9 +60,9 @@ describe('Image Service client', () => { .fn() .mockResolvedValue(new Response(JSON.stringify({ data: [] }))); vi.stubGlobal('fetch', fetchMock); - const { createClient } = await loadClient(); + const { generate } = await loadEntry(); - await createClient({ + await generate({ config: { apiKey: 'test-secret', apiVersion: 'unused', @@ -67,7 +71,8 @@ describe('Image Service client', () => { modelFamily: 'gpt-image-1', quality: 'medium', }, - }).generate({ prompt: 'a fox' }); + input: { prompt: 'a fox' }, + }); const [url, init] = fetchMock.mock.calls[0] ?? []; expect(String(url)).toBe( @@ -81,4 +86,39 @@ describe('Image Service client', () => { prompt: 'a fox', }); }); + + it('runs as an executable entry using leased configuration', async () => { + const bytes = Buffer.from('generated-image'); + const fetchMock = vi.fn().mockResolvedValue( + new Response( + JSON.stringify({ + data: [{ b64_json: bytes.toString('base64') }], + }), + ), + ); + vi.stubGlobal('fetch', fetchMock); + const sdkSource = ` + export async function withServiceConfig(id, run) { + if (id !== 'image-gen') throw new Error('Unexpected Service'); + return run({ config: { + apiKey: 'test-secret', + apiVersion: '2025-04-01-preview', + baseUrl: 'https://example.test', + model: 'image-deployment', + modelFamily: 'gpt-image-1', + quality: 'medium' + } }); + } + `; + process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + const output = `${process.env.TMPDIR ?? '/tmp'}/huabu-image-entry-${process.pid}.png`; + const { main } = await loadEntry(); + + await main(['--prompt', 'a fox', '--output', output]); + + await expect( + import('node:fs/promises').then((fs) => fs.readFile(output)), + ).resolves.toEqual(bytes); + await import('node:fs/promises').then((fs) => fs.rm(output)); + }); }); diff --git a/apps/server/src/services/image-gen/service.yaml b/apps/server/src/services/image-gen/service.yaml index ddf20afed..d8c93ca94 100644 --- a/apps/server/src/services/image-gen/service.yaml +++ b/apps/server/src/services/image-gen/service.yaml @@ -5,9 +5,10 @@ name: Image Generation description: Generate images with the configured Azure OpenAI deployment. storage: namespace: llm.imageConfig -agent: - skill: SKILL.md - client: client.mjs +package: + files: + - SKILL.md + - entry.mjs configuration: - id: provider label: Provider diff --git a/apps/server/src/services/ink-ocr/service.yaml b/apps/server/src/services/ink-ocr/service.yaml index 79d398018..95b9719b9 100644 --- a/apps/server/src/services/ink-ocr/service.yaml +++ b/apps/server/src/services/ink-ocr/service.yaml @@ -5,6 +5,8 @@ name: Handwriting Recognition description: Recognize selected handwriting with Azure AI Vision. storage: namespace: integration.azureVisionInkOcr +package: + files: [] configuration: - id: endpoint label: Endpoint diff --git a/apps/server/src/services/web-search/SKILL.md b/apps/server/src/services/web-search/SKILL.md index d1db92b7f..4573a4332 100644 --- a/apps/server/src/services/web-search/SKILL.md +++ b/apps/server/src/services/web-search/SKILL.md @@ -2,4 +2,6 @@ Use this Service for current public web information when ordinary local knowledge is insufficient. -Load it through the Agentlet SDK URL in `AGENTLET_SERVICE_SDK_URL`, then call the returned client's `search()` method with a non-empty query. Never print or persist the supplied credential. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. +`entry.mjs` is an executable starting point for basic Tavily search, not a complete provider SDK. Run `node entry.mjs --query ""` and optionally pass `--output ` to write the JSON response to a file. It obtains current configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credential. + +When the task needs provider options that the entry does not implement, read the [Tavily Search API documentation](https://docs.tavily.com/documentation/api-reference/endpoint/search) and modify the local Package copy. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. diff --git a/apps/server/src/services/web-search/client.mjs b/apps/server/src/services/web-search/client.mjs deleted file mode 100644 index 476065fdc..000000000 --- a/apps/server/src/services/web-search/client.mjs +++ /dev/null @@ -1,31 +0,0 @@ -// Copyright (c) Microsoft Corporation. -// Licensed under the MIT license. - -export function createClient({ config }) { - return { - async search(input) { - const query = - typeof input === 'string' - ? input.trim() - : typeof input?.query === 'string' - ? input.query.trim() - : ''; - if (!query) throw new Error('Web search requires a non-empty query'); - const response = await fetch('https://api.tavily.com/search', { - method: 'POST', - headers: { 'content-type': 'application/json' }, - body: JSON.stringify({ - ...(typeof input === 'object' && input ? input : {}), - api_key: config.apiKey, - query, - }), - }); - if (!response.ok) { - throw new Error( - `Web search provider request failed (${response.status})`, - ); - } - return response.json(); - }, - }; -} diff --git a/apps/server/src/services/web-search/entry.mjs b/apps/server/src/services/web-search/entry.mjs new file mode 100644 index 000000000..d60538f3f --- /dev/null +++ b/apps/server/src/services/web-search/entry.mjs @@ -0,0 +1,80 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { writeFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; + +function valueAfter(argv, index, option) { + const value = argv[index + 1]; + if (!value || value.startsWith('-')) { + throw new Error(`${option} requires a value`); + } + return value; +} + +function parseArgs(argv) { + const options = {}; + for (let index = 0; index < argv.length; index += 1) { + const argument = argv[index]; + if (argument === '--query' || argument === '-q') { + options.query = valueAfter(argv, index, argument); + index += 1; + } else if (argument === '--output' || argument === '-o') { + options.output = valueAfter(argv, index, argument); + index += 1; + } else { + throw new Error(`Unknown argument: ${argument}`); + } + } + if (!options.query?.trim()) { + throw new Error('Web search requires --query'); + } + return options; +} + +export async function search({ config, input }) { + const query = + typeof input === 'string' + ? input.trim() + : typeof input?.query === 'string' + ? input.query.trim() + : ''; + if (!query) throw new Error('Web search requires a non-empty query'); + const response = await fetch('https://api.tavily.com/search', { + method: 'POST', + headers: { 'content-type': 'application/json' }, + body: JSON.stringify({ + ...(typeof input === 'object' && input ? input : {}), + api_key: config.apiKey, + query, + }), + }); + if (!response.ok) { + throw new Error(`Web search provider request failed (${response.status})`); + } + return response.json(); +} + +export async function main(argv = process.argv.slice(2)) { + const options = parseArgs(argv); + const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; + if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); + const { withServiceConfig } = await import(sdkUrl); + await withServiceConfig('web-search', async ({ config }) => { + const result = await search({ config, input: options.query }); + const output = `${JSON.stringify(result, null, 2)}\n`; + if (options.output) { + await writeFile(options.output, output); + } else { + process.stdout.write(output); + } + }); +} + +const invokedPath = process.argv[1] + ? pathToFileURL(resolve(process.argv[1])).href + : null; +if (invokedPath === import.meta.url) { + await main(); +} diff --git a/apps/server/src/services/web-search/client.test.ts b/apps/server/src/services/web-search/entry.test.ts similarity index 69% rename from apps/server/src/services/web-search/client.test.ts rename to apps/server/src/services/web-search/entry.test.ts index bf61f9e5d..92ae28b88 100644 --- a/apps/server/src/services/web-search/client.test.ts +++ b/apps/server/src/services/web-search/entry.test.ts @@ -5,15 +5,16 @@ import { afterEach, describe, expect, it, vi } from 'vitest'; import { readServicePackageFile } from '../../modules/services/package-loader.js'; -async function loadClient() { - const source = readServicePackageFile('web-search', 'client.mjs'); - if (!source) throw new Error('Web Search Service client is missing'); +async function loadEntry() { + const source = readServicePackageFile('web-search', 'entry.mjs'); + if (!source) throw new Error('Web Search Service entry is missing'); return import( `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` ) as Promise<{ - createClient(input: { config: Record }): { - search(input: string | Record): Promise; - }; + search(input: { + config: Record; + input: string | Record; + }): Promise; }>; } @@ -21,17 +22,18 @@ afterEach(() => { vi.unstubAllGlobals(); }); -describe('Web Search Service client', () => { +describe('Web Search Service entry', () => { it('sends the configured Tavily key and normalized query', async () => { const fetchMock = vi .fn() .mockResolvedValue(new Response(JSON.stringify({ results: [] }))); vi.stubGlobal('fetch', fetchMock); - const { createClient } = await loadClient(); + const { search } = await loadEntry(); - await createClient({ + await search({ config: { apiKey: 'test-secret' }, - }).search({ query: ' Huabu ', max_results: 3 }); + input: { query: ' Huabu ', max_results: 3 }, + }); const [url, init] = fetchMock.mock.calls[0] ?? []; expect(url).toBe('https://api.tavily.com/search'); @@ -55,10 +57,10 @@ describe('Web Search Service client', () => { new Response('sensitive provider response', { status: 401 }), ), ); - const { createClient } = await loadClient(); + const { search } = await loadEntry(); await expect( - createClient({ config: { apiKey: 'test-secret' } }).search('Huabu'), + search({ config: { apiKey: 'test-secret' }, input: 'Huabu' }), ).rejects.toThrow('Web search provider request failed (401)'); }); }); diff --git a/apps/server/src/services/web-search/service.yaml b/apps/server/src/services/web-search/service.yaml index 409e1ae66..cbbeeafb5 100644 --- a/apps/server/src/services/web-search/service.yaml +++ b/apps/server/src/services/web-search/service.yaml @@ -5,9 +5,10 @@ name: Web Search description: Search the web with Tavily. storage: namespace: integration.tavily -agent: - skill: SKILL.md - client: client.mjs +package: + files: + - SKILL.md + - entry.mjs configuration: - id: apiKey label: API key diff --git a/apps/server/src/services/youtube-transcripts/service.yaml b/apps/server/src/services/youtube-transcripts/service.yaml index 21694d796..d498a719a 100644 --- a/apps/server/src/services/youtube-transcripts/service.yaml +++ b/apps/server/src/services/youtube-transcripts/service.yaml @@ -5,6 +5,8 @@ name: YouTube Transcripts description: Load YouTube transcripts through the existing RapidAPI preprocessing integration. storage: namespace: integration.rapidapi +package: + files: [] configuration: - id: apiKey label: API key diff --git a/apps/web/src/components/Settings/sections/ServicesSettings.test.tsx b/apps/web/src/components/Settings/sections/ServicesSettings.test.tsx index 0ae98c1d5..ce045f085 100644 --- a/apps/web/src/components/Settings/sections/ServicesSettings.test.tsx +++ b/apps/web/src/components/Settings/sections/ServicesSettings.test.tsx @@ -46,6 +46,7 @@ function config(id: (typeof ids)[number]): ServiceConfig { name: id, description: `${id} description`, storage: { namespace: `integration.${id}` }, + package: { files: [] }, configuration: [ { id: 'apiKey', diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 66a4814cc..5e8057f00 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -39,8 +39,10 @@ All endpoints are mounted under `/api/rfs/:canvasId`; `HUABU_RFS_URL` already co | `GET /capabilities/queries/:type` | Return one query's generated JSON Schema, constraints, result description, and examples. | | `GET /capabilities/commands/:type` | Return one command's generated JSON Schema, constraints, result description, and examples. | | `GET /services` | List configured third-party Services and masked availability. | -| `GET /services/:id/*` | Return one Service Package's Manifest, Skill, or client source. | +| `GET /services/:id/manifest` | Return one Service Package's validated Manifest without credentials. | +| `GET /services/:id/skill` | Return an Agent-facing Service Package's root `SKILL.md`. | | `POST /services/:id/lease` | Return the declared effective configuration for one configured Agent-facing Service with `Cache-Control: no-store`. | +| `GET /download/services/:id.zip` | Stream one Agent-facing Package as `/service.yaml` plus its exact Manifest-declared files. | | `POST /query` | Validate and execute one bounded `SpaceQuery`, returning a query-discriminated JSON result. | | `POST /execute` | Validate and execute an ordered batch of agent-allowed `CanvasCommand` variants. | @@ -102,7 +104,7 @@ Parent lineage is best effort. The route resolves `parentThreadId` or `X-Huabu-H Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/`; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists the bootstrap as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. The preamble owns the authentication contract and curl header setup because every external Agent needs them before loading any Skill. The public basic guide is loaded without credentials from `GET /skill`; repeating that request with authentication adds the current root override and live Space Skill Frames. Advanced layout, Task, recursive-Agent, and Interactive View procedures are loaded on demand from authenticated `GET /skill/layout`, `/skill/tasks`, `/skill/agents`, and `/skill/interactive-views`. -Agentlet additionally injects its daemon-owned `AGENTLET_SERVICE_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/service-sdk`. Session or Profile environment cannot override this value. The SDK wraps `/services` discovery, lease, and trusted client loading; provider credentials remain absent from startup environment and are resolved on demand. +Agentlet additionally injects its daemon-owned `AGENTLET_SERVICE_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/service-sdk`. Session or Profile environment cannot override this value. Downloaded Service Package entries use the SDK only to obtain current configuration leases; the SDK does not discover or load Package code, and provider credentials remain absent from startup environment until an entry requests them. Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. diff --git a/docs/architecture/api-design.md b/docs/architecture/api-design.md index ceee2c4c3..135f3f1e7 100644 --- a/docs/architecture/api-design.md +++ b/docs/architecture/api-design.md @@ -164,7 +164,7 @@ Malformed request fields and malformed cursors return HTTP 400 with `code: "malf `packages/shared/src/types/api/service-package.ts` defines the strict manifest, Generic Settings update, masked configuration, summary, and External lease contracts. Owner Settings uses `GET /api/services`, `GET /api/services/:serviceId`, and `PUT /api/services/:serviceId`; every path/body value is validated with the shared schemas before selecting a code-registered storage namespace. -Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes third-party services under `/services`. Manifest, Skill, and client reads contain no credentials. `POST /services/:id/lease` rejects unknown, unconfigured, and packages without an Agent interface, returns only declared fields, and is non-cacheable. See [`service-packages.md`](./service-packages.md). +Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes third-party services under `/services`. Manifest and Skill reads contain no credentials. `POST /services/:id/lease` rejects unknown, unconfigured, and Packages without `SKILL.md`, returns only declared fields, and is non-cacheable. `GET /download/services/:id.zip` streams the validated `service.yaml + package.files` set beneath one `/` archive root and uses the Package content hash as its ETag. See [`service-packages.md`](./service-packages.md). ## Anti-patterns diff --git a/docs/architecture/service-packages.md b/docs/architecture/service-packages.md index 21f9b26fb..755aa80e6 100644 --- a/docs/architecture/service-packages.md +++ b/docs/architecture/service-packages.md @@ -12,18 +12,18 @@ The bundled packages live under `apps/server/src/services//`: / ├── service.yaml ├── SKILL.md # required only when External Agent-facing -└── client.mjs # required only for a direct Agent-side provider call +└── entry.mjs # optional executable and modifiable starting point ``` Phase 1 packages are trusted files shipped with Huabu. User upload, installation, remote registries, and Server execution of uploaded code are not supported. ## Manifest contract -`huabu-service/v1` is defined by `serviceManifestSchema` in `packages/shared/src/types/api/service-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, and an `agent` block without a Skill fail validation. +`huabu-service/v1` is defined by `serviceManifestSchema` in `packages/shared/src/types/api/service-package.ts`. Unknown properties, malformed IDs, duplicate configuration IDs, invalid enum declarations, ambiguous Package paths, duplicate Package files, and `entry.mjs` without `SKILL.md` fail validation. -Every package declares a stable ID and version, display metadata, one registered storage namespace, optional Agent files, and constrained configuration fields. Supported field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or client contract. +Every package declares a stable ID and version, display metadata, one registered storage namespace, an exact `package.files` allowlist, and constrained configuration fields. `service.yaml` is included implicitly; every other distributable file must be listed as a portable ASCII Package-root-relative regular-file path using `/` separators. Directories, glob patterns, exclusions, symlinks, duplicate paths, platform-specific paths, and traversal are not supported. Supported configuration field types are text, secret, HTTPS URL, boolean, and bounded enum. `configuration[].id` directly names a stable logical key exposed by the namespace adapter; `label` is display text and can change without changing the storage or entry contract. -The manifest does not declare Internal Agent or Pipeline consumers. Those execution paths are reviewed Huabu code and cannot be enabled by package metadata. The presence of an `agent` block is the complete declaration that a package supports External Agent use; its `skill` is required and its direct-provider `client` is optional. A package without `agent` cannot be leased to an External Agent. +The manifest does not declare consumers. Internal Agent and Pipeline execution paths are reviewed Huabu code and cannot be enabled by package metadata. A root `SKILL.md` in `package.files` declares External Agent support; an optional root `entry.mjs` provides a directly executable and modifiable starting point. A Package without `SKILL.md` cannot be leased or downloaded through External RFS, and `entry.mjs` cannot be published without `SKILL.md`. ## Provision Service and storage bindings @@ -46,9 +46,9 @@ Masked Settings responses return `null` for secret values and identify configure Internal Agent tools keep their high-level Huabu integrations. `generate_image` still owns typed tool arguments, model capability validation, reference artifact reads, provider SDK behavior, image decoding, and artifact persistence; it obtains provider configuration through `resolveForServer('image-gen')`. -Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Service configuration but do not import package `client.mjs`. +Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Service configuration but do not import Package entries. -External Agent packages provide a real `SKILL.md` and, when direct provider execution is needed, a `client.mjs` exporting `createClient({ config })`. The bundled Image and Tavily packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore ship neither placeholder file. +External Agent Packages provide a real `SKILL.md` and may provide an `entry.mjs` that imports `AGENTLET_SERVICE_SDK_URL`, leases current configuration, and implements only a useful baseline provider workflow. The entry is not a complete provider SDK: the Skill links official provider documentation, and an Agent may modify its downloaded local copy for additional endpoints. The bundled Image and Tavily Packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore publish neither placeholder file. ## Owner Settings API @@ -70,32 +70,34 @@ The canvas-scoped RFS retains `/capabilities` for direct Space-operation discove GET /services GET /services/:id/manifest GET /services/:id/skill -GET /services/:id/client POST /services/:id/lease +GET /download/services/:id.zip ``` -Manifest and Skill responses contain no credentials. Client source is a versioned bundled asset. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and packages without an `agent` declaration explicitly, returns only fields declared by the selected package, and uses `Cache-Control: no-store`. +Manifest and Skill responses contain no credentials. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and Packages without `SKILL.md` explicitly, returns only fields declared by the selected Package, and uses `Cache-Control: no-store`. + +Package download streams a ZIP on demand from the validated Package record without a temporary file or ZIP cache. The archive contains one `/` root directory, `service.yaml`, and exactly the files declared by `package.files`; undeclared tests and development files are excluded. The response uses the Package content hash as its ETag. Phase 1 resolves records from bundled directories; a future validated custom-Service installation can expose the same immutable root, exact file list, and hash without changing the route. ## Agentlet SDK Agentlet publishes `dist/service-sdk/index.js`. The daemon computes its absolute `file://` URL relative to its own `import.meta.url` and injects it as the authoritative `AGENTLET_SERVICE_SDK_URL` after workload environment values, so a Profile or session cannot replace it. -`loadService(id)` obtains a fresh lease and loads the trusted package client from Huabu without writing credentials to disk. `withService(id, callback)` is the convenience wrapper. The SDK reports bounded status-only request failures and does not include response bodies that could contain credentials. +`leaseService(id)` obtains a fresh configuration lease without downloading or loading Package code. `withServiceConfig(id, callback)` is the scoped convenience wrapper used by `entry.mjs`. The SDK reports bounded status-only request failures and does not include response bodies that could contain credentials. The SDK reduces accidental persistence but is not a sandbox. A trusted External Agent and loaded client share the Agent process's filesystem, network, RFS bearer, and provider credentials. Static provider credentials cannot be revoked after disclosure except by provider-side rotation. ## Build and packaging -Server development reads packages from `apps/server/src/services`. The Server bundle copies that directory to `dist-bundle/services`. The bundled Agentlet build emits both `agentlet/index.js` and `agentlet/service-sdk/index.js`; the published Agentlet npm package already includes its complete `dist` tree. +Server development reads Packages from `apps/server/src/services`. The Server bundle copies that directory to `dist-bundle/services`, while RFS distribution still selects only Manifest-declared files. The bundled Agentlet build emits both `agentlet/index.js` and `agentlet/service-sdk/index.js`; the published Agentlet npm package already includes its complete `dist` tree. ## Code entry points -| File | Responsibility | -| ---------------------------------------------------------------- | ------------------------------------------------------ | -| `packages/shared/src/types/api/service-package.ts` | Manifest, Generic Settings, summary, and lease schemas | -| `apps/server/src/modules/services/package-loader.ts` | Bundled YAML parsing, validation, and path confinement | -| `apps/server/src/modules/services/provisioner.ts` | Namespace adapters and trusted/masked projections | -| `apps/server/src/modules/services/services.route.ts` | Owner Generic Settings API | -| `apps/server/src/modules/remote_fs/rfs.route.ts` | Authenticated Service discovery, files, and lease | -| `apps/web/src/components/Settings/sections/ServicesSettings.tsx` | Manifest-driven Services UI | -| `external/agentlet/packages/local/src/service-sdk/index.ts` | External Agent SDK | +| File | Responsibility | +| ---------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `packages/shared/src/types/api/service-package.ts` | Manifest, Generic Settings, summary, and lease schemas | +| `apps/server/src/modules/services/package-loader.ts` | Bundled YAML parsing, exact file validation, hashing, and path confinement | +| `apps/server/src/modules/services/provisioner.ts` | Namespace adapters and trusted/masked projections | +| `apps/server/src/modules/services/services.route.ts` | Owner Generic Settings API | +| `apps/server/src/modules/remote_fs/rfs.route.ts` | Authenticated Service discovery, files, and lease | +| `apps/web/src/components/Settings/sections/ServicesSettings.tsx` | Manifest-driven Services UI | +| `external/agentlet/packages/local/src/service-sdk/index.ts` | External Agent SDK | diff --git a/docs/proposals/service-packages.md b/docs/proposals/service-packages.md index 12092c31e..d0bbcd3a8 100644 --- a/docs/proposals/service-packages.md +++ b/docs/proposals/service-packages.md @@ -6,7 +6,7 @@ Last updated: 2026-10-10 ## 摘要 -本 Proposal 定义统一的 Service Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace 以及可选的 Agent Skill/client，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 +本 Proposal 定义统一的 Service Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace 与精确发布文件，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 Phase 1 将当前 Settings > Services 中的 Image Generation、Tavily Web Search、YouTube Transcripts 与 Azure Vision Ink OCR 全部迁入 Package、Manifest-driven Settings 和统一 Provision Service。Phase 1 不开放用户上传。 @@ -16,12 +16,12 @@ Phase 1 将当前 Settings > Services 中的 Image Generation、Tavily Web Searc / ├── service.yaml ├── SKILL.md # 仅 Agent-facing Service 必须 -├── client.mjs # 仅 Agent 直接调用 provider 时必须 +├── entry.mjs # 可选的可执行、可修改基础入口 ├── references/ # 可选 └── assets/ # 可选 ``` -不创建 placeholder Skill 或 client。Manifest 不声明 Internal Agent 或 Pipeline consumer；这些执行路径只由 reviewed Huabu code 接线。存在 `agent` block 就表示 Package 提供 External Agent 行为，其中 `skill` 必须存在，直接调用 provider 时才需要可选的 `client`。没有 `agent` block 的 Package 不能被 External Agent lease。 +Manifest 的 `package.files` 只接受精确的 Package-root-relative 普通文件路径，不接受目录、glob 或 exclude；`service.yaml` 始终隐式进入分发包。Manifest 不声明 consumer；Internal Agent 与 Pipeline 执行路径只由 reviewed Huabu code 接线。`package.files` 中存在根目录 `SKILL.md` 就表示 Package 提供 External Agent 行为，可选的根目录 `entry.mjs` 提供基础执行入口。没有 `SKILL.md` 的 Package 不能被 External Agent lease 或下载，且不创建 placeholder Skill 或 entry。 ## 配置与零迁移 @@ -33,22 +33,22 @@ Manifest 的 `storage.namespace` 是 Huabu code 注册的 opaque adapter ID， Internal Pi 继续使用高层 Server Tool。`generate_image` 仍负责参数、模型能力、reference artifact、provider SDK、PNG decode 和 Space artifact，只把配置解析切换到 Provision Service。 -Pipeline 继续使用 reviewed Server-side Adapter。YouTube transcript loader 与 Ink OCR 不导入 `client.mjs`。 +Pipeline 继续使用 reviewed Server-side Adapter。YouTube transcript loader 与 Ink OCR 不导入 Package entry。 -External Agent 通过 Agentlet 注入的 `AGENTLET_SERVICE_SDK_URL` 加载 SDK，经 authenticated RFS 按需取得当前 Package 配置，并在 Agentlet 设备执行受信任的 `client.mjs`。Image Generation 与 Tavily Web Search 提供真实 `agent.skill`/`agent.client`；YouTube Transcripts 与 Ink OCR 没有 `agent` block。 +External Agent 经 authenticated RFS 下载完整 Package ZIP，在任意工作目录解压并执行或修改 `entry.mjs`。Entry 通过 Agentlet 注入的 `AGENTLET_SERVICE_SDK_URL` 按需取得当前配置，只实现有用的基础 provider workflow，而不是完整第三方 SDK；`SKILL.md` 链接官方文档供 Agent 扩展本地副本。Image Generation 与 Tavily Web Search 发布真实 `SKILL.md`/`entry.mjs`；YouTube Transcripts 与 Ink OCR 不发布 Agent 文件。 ## API 与安全 -Owner Settings 使用 `/api/services` generic API。RFS 保留 `/capabilities` 用作 Space operation discovery，并使用独立的 `/services` 提供第三方服务列表、Manifest、Skill、client 与 POST lease。 +Owner Settings 使用 `/api/services` generic API。RFS 保留 `/capabilities` 用作 Space operation discovery，并使用独立的 `/services` 提供第三方服务列表、Manifest、Skill 与 POST lease；`GET /download/services/:id.zip` on-the-fly 流式打包一个 `/` 根目录，其中只包含 `service.yaml` 和 `package.files` 声明的文件。 -Lease 使用现有 canvas-scoped RFS bearer，响应 `Cache-Control: no-store`，只返回目标 Package 声明的配置。Manifest、Skill、Settings read 和日志不返回 secret。Agentlet SDK 降低意外落盘和日志泄露，但不是 sandbox；Agent 与 client 拥有同一进程权限，静态 provider key 一旦交付只能通过 provider rotation 真正撤销。 +Lease 使用现有 canvas-scoped RFS bearer，响应 `Cache-Control: no-store`，只返回目标 Package 声明的配置。Manifest、Skill、ZIP、Settings read 和日志不返回 secret。Agentlet SDK 只提供 `leaseService()` 与 `withServiceConfig()`，不下载 Package code；它降低意外落盘和日志泄露，但不是 sandbox。Agent 与其修改的 entry 拥有同一进程权限，静态 provider key 一旦交付只能通过 provider rotation 真正撤销。 ## Phase 1 -Phase 1 交付严格的 `huabu-service/v1` schema、bundled Package discovery、Generic Settings、code-registered storage adapters、RFS Package/lease surface、Agentlet SDK，以及全部四个现有 UI Service 的 Package 化。Image Generation 是完整 External Agent vertical slice，Tavily 同时提供可工作的 External client。 +Phase 1 交付严格的 `huabu-service/v1` schema、bundled Package discovery、Generic Settings、code-registered storage adapters、RFS Package ZIP/lease surface、lease-only Agentlet SDK，以及全部四个现有 UI Service 的 Package 化。Image Generation 与 Tavily 同时提供可工作的基础 entry。 Phase 1 明确排除用户上传、archive 安装、remote registry、任意 Server plugin、动态 UI/表达式、per-Profile/device grant、通用 provider result envelope 与自动 Node 创建。 ## Phase 2 -未来的用户上传只能默认产生 Agent-only Package，并需要 path-safe extraction、压缩与解压大小限制、文件数量限制、duplicate/symlink/special-file 拒绝、content hash、不可变版本、来源记录、显式任意代码执行同意，以及更新和卸载语义。Huabu Server 与 Pipeline 不执行上传的 `client.mjs`。 +未来的用户上传只能默认产生 Agent-only Package，并需要 path-safe extraction、压缩与解压大小限制、文件数量限制、exact file allowlist、duplicate/symlink/special-file 拒绝、content hash、不可变版本、来源记录、显式任意代码执行同意，以及更新和卸载语义。上传内容先规范化为 immutable Package record，下载 route 再从该 record 流式生成 ZIP；Huabu Server 与 Pipeline 不执行上传的 `entry.mjs`。 diff --git a/packages/shared/src/types/api/service-package.test.ts b/packages/shared/src/types/api/service-package.test.ts index 691ffbb1b..ce143a75b 100644 --- a/packages/shared/src/types/api/service-package.test.ts +++ b/packages/shared/src/types/api/service-package.test.ts @@ -32,15 +32,34 @@ describe('Service Package contract', () => { }); }); - it('requires a Skill whenever the package declares Agent behavior', () => { + it('requires SKILL.md whenever the package publishes entry.mjs', () => { const result = serviceManifestSchema.safeParse({ ...manifest, - agent: { client: 'client.mjs' }, + package: { files: ['entry.mjs'] }, }); expect(result.success).toBe(false); }); - it('rejects duplicate field ids and empty updates', () => { + it('rejects ambiguous package paths, duplicate field ids, and empty updates', () => { + for (const file of [ + 'scripts/', + '../entry.mjs', + 'scripts\\entry.mjs', + 'C:/entry.mjs', + ]) { + expect( + serviceManifestSchema.safeParse({ + ...manifest, + package: { files: [file] }, + }).success, + ).toBe(false); + } + expect( + serviceManifestSchema.safeParse({ + ...manifest, + package: { files: ['SKILL.md', 'SKILL.md'] }, + }).success, + ).toBe(false); expect( serviceManifestSchema.safeParse({ ...manifest, diff --git a/packages/shared/src/types/api/service-package.ts b/packages/shared/src/types/api/service-package.ts index 4d19cb0e6..f9764e4fb 100644 --- a/packages/shared/src/types/api/service-package.ts +++ b/packages/shared/src/types/api/service-package.ts @@ -9,6 +9,20 @@ const serviceIdSchema = z const serviceFieldIdSchema = z .string() .regex(/^[a-z][a-zA-Z0-9]{0,63}$/, 'Invalid service field id'); +const servicePackageFileSchema = z + .string() + .min(1) + .max(512) + .refine( + (value) => + !value.startsWith('/') && + !value.endsWith('/') && + !value.includes('\\') && + value + .split('/') + .every((segment) => /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(segment)), + 'Package files must be portable exact relative file paths', + ); export const serviceFieldOptionSchema = z.object({ value: z.string().min(1).max(256), @@ -57,13 +71,12 @@ export const serviceManifestSchema = z .regex(/^[a-z][a-zA-Z0-9.]{0,127}$/, 'Invalid storage namespace'), }) .strict(), - agent: z + package: z .object({ - skill: z.string().min(1).max(256), - client: z.string().min(1).max(256).optional(), + files: z.array(servicePackageFileSchema).max(256).default([]), }) .strict() - .optional(), + .default({ files: [] }), configuration: z .array(serviceConfigurationFieldSchema) .max(100) @@ -71,6 +84,31 @@ export const serviceManifestSchema = z }) .strict() .superRefine((manifest, ctx) => { + const files = new Set(); + for (const [index, file] of manifest.package.files.entries()) { + if (file === 'service.yaml') { + ctx.addIssue({ + code: 'custom', + path: ['package', 'files', index], + message: 'service.yaml is included automatically', + }); + } + if (files.has(file)) { + ctx.addIssue({ + code: 'custom', + path: ['package', 'files', index], + message: `Duplicate package file: ${file}`, + }); + } + files.add(file); + } + if (files.has('entry.mjs') && !files.has('SKILL.md')) { + ctx.addIssue({ + code: 'custom', + path: ['package', 'files'], + message: 'entry.mjs requires SKILL.md', + }); + } const ids = new Set(); for (const [index, field] of manifest.configuration.entries()) { if (ids.has(field.id)) { @@ -143,7 +181,6 @@ export const serviceLeaseSchema = z id: serviceIdSchema, version: z.string(), config: z.record(serviceFieldIdSchema, serviceFieldValueSchema), - client: z.string().optional(), }) .strict(); export type ServiceLease = z.infer; From eb01c0e25c9ee5130c3ff5d7b34b2b66de62aae6 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 06:55:31 +0000 Subject: [PATCH 14/36] Clarify Azure image Service entry Use Node's built-in argument parser in executable Service entries, identify the image Service as AOAI, and point its Skill to the current Microsoft Foundry image generation guide. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/modules/remote_fs/rfs.route.test.ts | 4 +- .../modules/services/package-loader.test.ts | 2 +- apps/server/src/services/image-gen/SKILL.md | 4 +- apps/server/src/services/image-gen/entry.mjs | 49 ++++++++----------- .../src/services/image-gen/entry.test.ts | 2 +- .../src/services/image-gen/service.yaml | 2 +- apps/server/src/services/web-search/entry.mjs | 36 +++++--------- .../src/services/web-search/entry.test.ts | 28 +++++++++++ 8 files changed, 68 insertions(+), 59 deletions(-) diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index 166c0e88c..04b176b11 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -666,10 +666,10 @@ describe('third-party Services', () => { expect(packageDownload.headers['cache-control']).toBe( 'private, max-age=300', ); - expect(await zipEntries(packageDownload.rawPayload)).toEqual([ - 'image-gen/service.yaml', + expect((await zipEntries(packageDownload.rawPayload)).sort()).toEqual([ 'image-gen/SKILL.md', 'image-gen/entry.mjs', + 'image-gen/service.yaml', ]); const notModified = await app.inject({ diff --git a/apps/server/src/modules/services/package-loader.test.ts b/apps/server/src/modules/services/package-loader.test.ts index 1a8deac62..3d47b9f5f 100644 --- a/apps/server/src/modules/services/package-loader.test.ts +++ b/apps/server/src/modules/services/package-loader.test.ts @@ -28,7 +28,7 @@ describe('bundled Service packages', () => { it('exposes only exact files declared by the package', () => { expect(readServicePackageFile('image-gen', 'SKILL.md')).toContain( - '# Image Generation', + '# Azure OpenAI Image Generation', ); expect(readServicePackageFile('web-search', 'entry.mjs')).toContain( 'search', diff --git a/apps/server/src/services/image-gen/SKILL.md b/apps/server/src/services/image-gen/SKILL.md index 452a6dcb1..95011c6b5 100644 --- a/apps/server/src/services/image-gen/SKILL.md +++ b/apps/server/src/services/image-gen/SKILL.md @@ -1,9 +1,9 @@ -# Image Generation +# Azure OpenAI Image Generation Use this Service when the user asks you to generate an image through their configured Azure OpenAI image deployment. `entry.mjs` is an executable starting point for basic prompt-to-image generation, not a complete provider SDK. Run `node entry.mjs --prompt "" --quality --output `, or use `--prompt-file ` for a file-backed prompt. It obtains current configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credentials. -When the task needs image editing or another provider feature that the entry does not implement, read the [Azure OpenAI image generation documentation](https://learn.microsoft.com/azure/ai-services/openai/how-to/dall-e), modify the local Package copy, and keep configuration retrieval through `AGENTLET_SERVICE_SDK_URL`. +When the task needs image editing or another provider feature that the entry does not implement, read the [Azure OpenAI image generation documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/dall-e?tabs=command-line%2Ckeyless%2Ctypescript-keyless&pivots=programming-language-typescript), modify the local Package copy, and keep configuration retrieval through `AGENTLET_SERVICE_SDK_URL`. The entry writes the generated image to the requested local path. Upload it through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. diff --git a/apps/server/src/services/image-gen/entry.mjs b/apps/server/src/services/image-gen/entry.mjs index 1c65b5375..055f8aaf7 100644 --- a/apps/server/src/services/image-gen/entry.mjs +++ b/apps/server/src/services/image-gen/entry.mjs @@ -4,37 +4,28 @@ import { readFile, writeFile } from 'node:fs/promises'; import { resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; +import { parseArgs } from 'node:util'; const QUALITIES = new Set(['low', 'medium', 'high', 'auto']); -function valueAfter(argv, index, option) { - const value = argv[index + 1]; - if (!value || value.startsWith('-')) { - throw new Error(`${option} requires a value`); - } - return value; -} - -function parseArgs(argv) { - const options = {}; - for (let index = 0; index < argv.length; index += 1) { - const argument = argv[index]; - if (argument === '--prompt' || argument === '-p') { - options.prompt = valueAfter(argv, index, argument); - index += 1; - } else if (argument === '--prompt-file') { - options.promptFile = valueAfter(argv, index, argument); - index += 1; - } else if (argument === '--quality') { - options.quality = valueAfter(argv, index, argument); - index += 1; - } else if (argument === '--output' || argument === '-o') { - options.output = valueAfter(argv, index, argument); - index += 1; - } else { - throw new Error(`Unknown argument: ${argument}`); - } - } +function parseCliArgs(argv) { + const { values } = parseArgs({ + args: argv, + options: { + prompt: { type: 'string', short: 'p' }, + 'prompt-file': { type: 'string' }, + quality: { type: 'string' }, + output: { type: 'string', short: 'o' }, + }, + strict: true, + allowPositionals: false, + }); + const options = { + prompt: values.prompt, + promptFile: values['prompt-file'], + quality: values.quality, + output: values.output, + }; if (options.prompt && options.promptFile) { throw new Error('Use either --prompt or --prompt-file, not both'); } @@ -110,7 +101,7 @@ async function imageBytes(result) { } export async function main(argv = process.argv.slice(2)) { - const options = parseArgs(argv); + const options = parseCliArgs(argv); const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); const { withServiceConfig } = await import(sdkUrl); diff --git a/apps/server/src/services/image-gen/entry.test.ts b/apps/server/src/services/image-gen/entry.test.ts index 86f3da3c6..aa8e9419f 100644 --- a/apps/server/src/services/image-gen/entry.test.ts +++ b/apps/server/src/services/image-gen/entry.test.ts @@ -114,7 +114,7 @@ describe('Image Service entry', () => { const output = `${process.env.TMPDIR ?? '/tmp'}/huabu-image-entry-${process.pid}.png`; const { main } = await loadEntry(); - await main(['--prompt', 'a fox', '--output', output]); + await main(['-p', 'a fox', '-o', output]); await expect( import('node:fs/promises').then((fs) => fs.readFile(output)), diff --git a/apps/server/src/services/image-gen/service.yaml b/apps/server/src/services/image-gen/service.yaml index d8c93ca94..33f2544b3 100644 --- a/apps/server/src/services/image-gen/service.yaml +++ b/apps/server/src/services/image-gen/service.yaml @@ -1,7 +1,7 @@ schema: huabu-service/v1 id: image-gen version: 1.0.0 -name: Image Generation +name: Image Generation (AOAI) description: Generate images with the configured Azure OpenAI deployment. storage: namespace: llm.imageConfig diff --git a/apps/server/src/services/web-search/entry.mjs b/apps/server/src/services/web-search/entry.mjs index d60538f3f..86a457cfd 100644 --- a/apps/server/src/services/web-search/entry.mjs +++ b/apps/server/src/services/web-search/entry.mjs @@ -4,29 +4,19 @@ import { writeFile } from 'node:fs/promises'; import { resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; +import { parseArgs } from 'node:util'; -function valueAfter(argv, index, option) { - const value = argv[index + 1]; - if (!value || value.startsWith('-')) { - throw new Error(`${option} requires a value`); - } - return value; -} - -function parseArgs(argv) { - const options = {}; - for (let index = 0; index < argv.length; index += 1) { - const argument = argv[index]; - if (argument === '--query' || argument === '-q') { - options.query = valueAfter(argv, index, argument); - index += 1; - } else if (argument === '--output' || argument === '-o') { - options.output = valueAfter(argv, index, argument); - index += 1; - } else { - throw new Error(`Unknown argument: ${argument}`); - } - } +function parseCliArgs(argv) { + const { values } = parseArgs({ + args: argv, + options: { + query: { type: 'string', short: 'q' }, + output: { type: 'string', short: 'o' }, + }, + strict: true, + allowPositionals: false, + }); + const options = { query: values.query, output: values.output }; if (!options.query?.trim()) { throw new Error('Web search requires --query'); } @@ -57,7 +47,7 @@ export async function search({ config, input }) { } export async function main(argv = process.argv.slice(2)) { - const options = parseArgs(argv); + const options = parseCliArgs(argv); const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); const { withServiceConfig } = await import(sdkUrl); diff --git a/apps/server/src/services/web-search/entry.test.ts b/apps/server/src/services/web-search/entry.test.ts index 92ae28b88..695d7a0bb 100644 --- a/apps/server/src/services/web-search/entry.test.ts +++ b/apps/server/src/services/web-search/entry.test.ts @@ -11,6 +11,7 @@ async function loadEntry() { return import( `data:text/javascript;base64,${Buffer.from(source).toString('base64')}` ) as Promise<{ + main(argv: string[]): Promise; search(input: { config: Record; input: string | Record; @@ -20,6 +21,7 @@ async function loadEntry() { afterEach(() => { vi.unstubAllGlobals(); + delete process.env.AGENTLET_SERVICE_SDK_URL; }); describe('Web Search Service entry', () => { @@ -63,4 +65,30 @@ describe('Web Search Service entry', () => { search({ config: { apiKey: 'test-secret' }, input: 'Huabu' }), ).rejects.toThrow('Web search provider request failed (401)'); }); + + it('runs as an executable entry using leased configuration', async () => { + const result = { results: [{ title: 'Huabu' }] }; + vi.stubGlobal( + 'fetch', + vi + .fn() + .mockResolvedValue(new Response(JSON.stringify(result))), + ); + const sdkSource = ` + export async function withServiceConfig(id, run) { + if (id !== 'web-search') throw new Error('Unexpected Service'); + return run({ config: { apiKey: 'test-secret' } }); + } + `; + process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + const output = `${process.env.TMPDIR ?? '/tmp'}/huabu-web-search-entry-${process.pid}.json`; + const { main } = await loadEntry(); + + await main(['-q', 'Huabu', '-o', output]); + + await expect( + import('node:fs/promises').then((fs) => fs.readFile(output, 'utf8')), + ).resolves.toBe(`${JSON.stringify(result, null, 2)}\n`); + await import('node:fs/promises').then((fs) => fs.rm(output)); + }); }); From c204453c05bc0640985768a2fc5b1d3e6c07233d Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 07:29:55 +0000 Subject: [PATCH 15/36] Expose coherent Service runtime contexts Return the validated Manifest alongside leased configuration and replace the config-only callback with withServiceContext. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 2 +- .../packages/local/src/service-sdk/index.ts | 54 +++++++++++++++---- .../packages/local/tests/service-sdk.test.ts | 36 +++++++++++-- 3 files changed, 77 insertions(+), 15 deletions(-) diff --git a/external/agentlet/README.md b/external/agentlet/README.md index 2b016f38d..3a61ddffb 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -127,7 +127,7 @@ The standard environment includes: Agentlet transports opaque resources and environment values; it does not interpret the host-specific tool protocol. -The optional Service SDK exports `leaseService(id)` and `withServiceConfig(id, callback)`. It uses host-injected reachback coordinates to obtain current configuration without downloading Package code or persisting credentials. Downloaded Service Package entries import the SDK through `AGENTLET_SERVICE_SDK_URL`; the daemon writes that variable after workload environment values so a session cannot replace the SDK module location. +The optional Service SDK exports `leaseService(id)` and `withServiceContext(id, callback)`. It uses host-injected reachback coordinates to obtain one version-coherent runtime context containing the validated Service Manifest and current configuration without downloading Package code or persisting credentials. Downloaded Service Package entries import the SDK through `AGENTLET_SERVICE_SDK_URL`; the daemon writes that variable after workload environment values so a session cannot replace the SDK module location. ## Repository layout diff --git a/external/agentlet/packages/local/src/service-sdk/index.ts b/external/agentlet/packages/local/src/service-sdk/index.ts index 7d21258e1..37f2653d7 100644 --- a/external/agentlet/packages/local/src/service-sdk/index.ts +++ b/external/agentlet/packages/local/src/service-sdk/index.ts @@ -1,12 +1,34 @@ -export interface ServiceLease { +export interface ServiceFieldOption { + value: string + label: string +} + +export interface ServiceConfigurationField { + id: string + label: string + description?: string + type: 'text' | 'secret' | 'url' | 'boolean' | 'enum' + required: boolean + options?: ServiceFieldOption[] + placeholder?: string +} + +export interface ServiceManifest { + schema: 'huabu-service/v1' id: string version: string - config: Record + name: string + description: string + storage: { namespace: string } + package: { files: string[] } + configuration: ServiceConfigurationField[] } -export interface ServiceConfigContext { - config: ServiceLease['config'] - lease: ServiceLease +export interface ServiceLease { + id: string + version: string + manifest: ServiceManifest + config: Record } function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { @@ -40,16 +62,28 @@ export async function leaseService(serviceId: string): Promise { { method: 'POST' }, ) const lease = (await response.json()) as ServiceLease - if (lease.id !== serviceId || typeof lease.version !== 'string') { + const declaredFields = new Set( + lease.manifest?.configuration?.map((field) => field.id) ?? [], + ) + if ( + lease.id !== serviceId || + typeof lease.version !== 'string' || + lease.manifest?.id !== serviceId || + lease.manifest.version !== lease.version || + !Array.isArray(lease.manifest.configuration) || + !lease.config || + typeof lease.config !== 'object' || + Array.isArray(lease.config) || + Object.keys(lease.config).some((fieldId) => !declaredFields.has(fieldId)) + ) { throw new Error('Invalid Service lease') } return lease } -export async function withServiceConfig( +export async function withServiceContext( serviceId: string, - run: (context: ServiceConfigContext) => Promise | T, + run: (service: ServiceLease) => Promise | T, ): Promise { - const lease = await leaseService(serviceId) - return run({ lease, config: lease.config }) + return run(await leaseService(serviceId)) } diff --git a/external/agentlet/packages/local/tests/service-sdk.test.ts b/external/agentlet/packages/local/tests/service-sdk.test.ts index 811b4c83f..10225a82d 100644 --- a/external/agentlet/packages/local/tests/service-sdk.test.ts +++ b/external/agentlet/packages/local/tests/service-sdk.test.ts @@ -2,9 +2,34 @@ import { afterEach, describe, expect, it, vi } from 'vitest' import { leaseService, - withServiceConfig, + withServiceContext, } from '../src/service-sdk/index.js' +const manifest = { + schema: 'huabu-service/v1', + id: 'example', + version: '1.0.0', + name: 'Example', + description: 'Example Service', + storage: { namespace: 'integration.example' }, + package: { files: ['SKILL.md', 'entry.mjs'] }, + configuration: [ + { + id: 'quality', + label: 'Quality', + type: 'enum', + required: true, + options: [{ value: 'high', label: 'high' }], + }, + { + id: 'apiKey', + label: 'API key', + type: 'secret', + required: true, + }, + ], +} as const + afterEach(() => { vi.unstubAllGlobals() delete process.env.HUABU_RFS_URL @@ -22,6 +47,7 @@ describe('Service SDK', () => { JSON.stringify({ id: 'example', version: '1.0.0', + manifest, config: { apiKey: 'provider-secret' }, }), { status: 200 }, @@ -32,6 +58,7 @@ describe('Service SDK', () => { const lease = await leaseService('example') expect(lease.config).toEqual({ apiKey: 'provider-secret' }) + expect(lease.manifest.configuration[0]?.id).toBe('quality') expect(fetchMock).toHaveBeenCalledTimes(1) expect(fetchMock).toHaveBeenNthCalledWith( 1, @@ -53,6 +80,7 @@ describe('Service SDK', () => { JSON.stringify({ id: 'example', version: '1.0.0', + manifest, config: { apiKey: 'provider-secret' }, }), ), @@ -60,11 +88,11 @@ describe('Service SDK', () => { ) await expect( - withServiceConfig('example', ({ config, lease }) => ({ + withServiceContext('example', ({ config, manifest: serviceManifest }) => ({ configured: Boolean(config.apiKey), - version: lease.version, + name: serviceManifest.name, })), - ).resolves.toEqual({ configured: true, version: '1.0.0' }) + ).resolves.toEqual({ configured: true, name: 'Example' }) }) it('does not include response bodies in provider-facing errors', async () => { From 8a618e59d2c12829d98c386a27dc3ac33126ff25 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 07:29:59 +0000 Subject: [PATCH 16/36] Drive Service entry help from runtime context Include the exact Manifest in each lease, render entry help from runtime schema and configured defaults, and validate CLI overrides against Manifest choices. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/modules/remote_fs/rfs.route.test.ts | 11 +++ .../src/modules/services/provisioner.test.ts | 6 ++ .../src/modules/services/provisioner.ts | 1 + .../src/prompt/external-agent/access-huabu.md | 2 +- apps/server/src/services/image-gen/SKILL.md | 2 +- apps/server/src/services/image-gen/entry.mjs | 58 +++++++++++++--- .../src/services/image-gen/entry.test.ts | 69 ++++++++++++++++--- apps/server/src/services/web-search/SKILL.md | 2 +- apps/server/src/services/web-search/entry.mjs | 29 ++++++-- .../src/services/web-search/entry.test.ts | 30 +++++++- docs/architecture/api-design.md | 2 +- docs/architecture/service-packages.md | 6 +- docs/proposals/service-packages.md | 2 +- .../src/types/api/service-package.test.ts | 20 ++++++ .../shared/src/types/api/service-package.ts | 31 ++++++++- 15 files changed, 238 insertions(+), 33 deletions(-) diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index 04b176b11..f620fe45c 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -720,6 +720,16 @@ describe('third-party Services', () => { serviceMocks.lease.mockReturnValueOnce({ id: 'image-gen', version: '1.0.0', + manifest: { + schema: 'huabu-service/v1', + id: 'image-gen', + version: '1.0.0', + name: 'Image Generation (AOAI)', + description: 'Generate images.', + storage: { namespace: 'llm.imageConfig' }, + package: { files: ['SKILL.md', 'entry.mjs'] }, + configuration: [], + }, config: { apiKey: 'test-secret' }, }); const app = await buildApp(); @@ -732,6 +742,7 @@ describe('third-party Services', () => { expect(lease.headers['cache-control']).toBe('no-store'); expect(lease.json()).toMatchObject({ id: 'image-gen', + manifest: { id: 'image-gen', version: '1.0.0' }, config: { apiKey: 'test-secret' }, }); diff --git a/apps/server/src/modules/services/provisioner.test.ts b/apps/server/src/modules/services/provisioner.test.ts index b8a439b47..5896cdb77 100644 --- a/apps/server/src/modules/services/provisioner.test.ts +++ b/apps/server/src/modules/services/provisioner.test.ts @@ -113,6 +113,12 @@ describe('Service Provision Service storage bindings', () => { expect(lease).toMatchObject({ id: 'image-gen', + manifest: { + id: 'image-gen', + configuration: expect.arrayContaining([ + expect.objectContaining({ id: 'quality', type: 'enum' }), + ]), + }, config: { baseUrl: 'https://images.example.com', apiKey: 'image-secret', diff --git a/apps/server/src/modules/services/provisioner.ts b/apps/server/src/modules/services/provisioner.ts index 7b310b2c7..31a1cabf4 100644 --- a/apps/server/src/modules/services/provisioner.ts +++ b/apps/server/src/modules/services/provisioner.ts @@ -383,6 +383,7 @@ export class ServiceProvisioner { return { id: manifest.id, version: manifest.version, + manifest, config: this.resolveForServer(serviceId), }; } diff --git a/apps/server/src/prompt/external-agent/access-huabu.md b/apps/server/src/prompt/external-agent/access-huabu.md index 61ed0d03f..c2818b3c2 100644 --- a/apps/server/src/prompt/external-agent/access-huabu.md +++ b/apps/server/src/prompt/external-agent/access-huabu.md @@ -307,7 +307,7 @@ cd image-gen Every archive contains one top-level directory named after the Service, so extracting `image-gen.zip` creates `image-gen/` rather than placing files directly in the current directory. `service.yaml` and every file declared by `package.files` are included; undeclared development files are not. -Read the extracted `SKILL.md`, then run the optional `entry.mjs` with Node as documented there. The entry obtains current configuration on demand through `AGENTLET_SERVICE_SDK_URL`; you normally do not need to import or call that SDK yourself. An entry is a modifiable starting point rather than a complete provider SDK: when the task needs another provider endpoint, follow the official documentation linked by the Skill and modify only your local Package copy. +Read the extracted `SKILL.md`, then run `node entry.mjs --help` before invoking the optional entry. Runtime help uses the leased Manifest and configuration to show current choices and configured defaults that may not be visible from the source alone. The entry obtains that coherent Service context on demand through `AGENTLET_SERVICE_SDK_URL`; you normally do not need to import or call the SDK yourself. An entry is a modifiable starting point rather than a complete provider SDK: when the task needs another provider endpoint, follow the official documentation linked by the Skill and modify only your local Package copy. Never print, persist, or forward leased credentials. A Service Package without `SKILL.md` is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. diff --git a/apps/server/src/services/image-gen/SKILL.md b/apps/server/src/services/image-gen/SKILL.md index 95011c6b5..389cc4a54 100644 --- a/apps/server/src/services/image-gen/SKILL.md +++ b/apps/server/src/services/image-gen/SKILL.md @@ -2,7 +2,7 @@ Use this Service when the user asks you to generate an image through their configured Azure OpenAI image deployment. -`entry.mjs` is an executable starting point for basic prompt-to-image generation, not a complete provider SDK. Run `node entry.mjs --prompt "" --quality --output `, or use `--prompt-file ` for a file-backed prompt. It obtains current configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credentials. +`entry.mjs` is an executable starting point for basic prompt-to-image generation, not a complete provider SDK. Run `node entry.mjs --help` first to read the runtime options, current configured defaults, and Manifest-defined choices. Then run `node entry.mjs --prompt "" --quality --output `, or use `--prompt-file ` for a file-backed prompt. It obtains the current Manifest and configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credentials. When the task needs image editing or another provider feature that the entry does not implement, read the [Azure OpenAI image generation documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/dall-e?tabs=command-line%2Ckeyless%2Ctypescript-keyless&pivots=programming-language-typescript), modify the local Package copy, and keep configuration retrieval through `AGENTLET_SERVICE_SDK_URL`. diff --git a/apps/server/src/services/image-gen/entry.mjs b/apps/server/src/services/image-gen/entry.mjs index 055f8aaf7..35d7d77c6 100644 --- a/apps/server/src/services/image-gen/entry.mjs +++ b/apps/server/src/services/image-gen/entry.mjs @@ -6,12 +6,11 @@ import { resolve } from 'node:path'; import { pathToFileURL } from 'node:url'; import { parseArgs } from 'node:util'; -const QUALITIES = new Set(['low', 'medium', 'high', 'auto']); - function parseCliArgs(argv) { const { values } = parseArgs({ args: argv, options: { + help: { type: 'boolean', short: 'h' }, prompt: { type: 'string', short: 'p' }, 'prompt-file': { type: 'string' }, quality: { type: 'string' }, @@ -20,12 +19,16 @@ function parseCliArgs(argv) { strict: true, allowPositionals: false, }); - const options = { + return { + help: values.help, prompt: values.prompt, promptFile: values['prompt-file'], quality: values.quality, output: values.output, }; +} + +function validateOptions(options, qualityChoices) { if (options.prompt && options.promptFile) { throw new Error('Use either --prompt or --prompt-file, not both'); } @@ -35,10 +38,41 @@ function parseCliArgs(argv) { if (!options.output) { throw new Error('Image generation requires --output'); } - if (options.quality && !QUALITIES.has(options.quality)) { - throw new Error('--quality must be low, medium, high, or auto'); + if (options.quality && !qualityChoices.includes(options.quality)) { + throw new Error(`--quality must be one of: ${qualityChoices.join(', ')}`); + } +} + +function qualityContext(manifest, config) { + const field = manifest.configuration.find(({ id }) => id === 'quality'); + if (field?.type !== 'enum' || !Array.isArray(field.options)) { + throw new Error('Image Service quality schema is unavailable'); + } + const choices = field.options.map(({ value }) => value); + const configured = + typeof config.quality === 'string' ? config.quality : undefined; + if (!configured || !choices.includes(configured)) { + throw new Error('Configured image quality is invalid'); } - return options; + return { choices, configured }; +} + +function printHelp(manifest, quality) { + process.stdout.write(`${manifest.name} + +Usage: + node entry.mjs --prompt --output [options] + node entry.mjs --prompt-file --output [options] + +Options: + -p, --prompt Image prompt + --prompt-file Read the prompt from a file + --quality Override configured image quality + Choices: ${quality.choices.join(', ')} + Default: ${quality.configured ?? 'configured Service value'} (config.quality) + -o, --output Output image path + -h, --help Show this help +`); } async function promptFrom(options) { @@ -75,7 +109,7 @@ export async function generate({ config, input }) { body: JSON.stringify({ ...input, prompt: input.prompt.trim(), - quality: input.quality || config.quality, + quality: input.quality ?? config.quality, ...(v1Style ? { model: deployment } : {}), }), }); @@ -104,8 +138,14 @@ export async function main(argv = process.argv.slice(2)) { const options = parseCliArgs(argv); const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); - const { withServiceConfig } = await import(sdkUrl); - await withServiceConfig('image-gen', async ({ config }) => { + const { withServiceContext } = await import(sdkUrl); + await withServiceContext('image-gen', async ({ manifest, config }) => { + const quality = qualityContext(manifest, config); + if (options.help) { + printHelp(manifest, quality); + return; + } + validateOptions(options, quality.choices); const result = await generate({ config, input: { diff --git a/apps/server/src/services/image-gen/entry.test.ts b/apps/server/src/services/image-gen/entry.test.ts index aa8e9419f..e9ea98508 100644 --- a/apps/server/src/services/image-gen/entry.test.ts +++ b/apps/server/src/services/image-gen/entry.test.ts @@ -20,6 +20,7 @@ async function loadEntry() { } afterEach(() => { + vi.restoreAllMocks(); vi.unstubAllGlobals(); delete process.env.AGENTLET_SERVICE_SDK_URL; }); @@ -98,16 +99,31 @@ describe('Image Service entry', () => { ); vi.stubGlobal('fetch', fetchMock); const sdkSource = ` - export async function withServiceConfig(id, run) { + export async function withServiceContext(id, run) { if (id !== 'image-gen') throw new Error('Unexpected Service'); - return run({ config: { - apiKey: 'test-secret', - apiVersion: '2025-04-01-preview', - baseUrl: 'https://example.test', - model: 'image-deployment', - modelFamily: 'gpt-image-1', - quality: 'medium' - } }); + return run({ + manifest: { + name: 'Image Generation (AOAI)', + configuration: [{ + id: 'quality', + type: 'enum', + options: [ + { value: 'low', label: 'low' }, + { value: 'medium', label: 'medium' }, + { value: 'high', label: 'high' }, + { value: 'auto', label: 'auto' } + ] + }] + }, + config: { + apiKey: 'test-secret', + apiVersion: '2025-04-01-preview', + baseUrl: 'https://example.test', + model: 'image-deployment', + modelFamily: 'gpt-image-1', + quality: 'medium' + } + }); } `; process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; @@ -121,4 +137,39 @@ describe('Image Service entry', () => { ).resolves.toEqual(bytes); await import('node:fs/promises').then((fs) => fs.rm(output)); }); + + it('renders runtime quality choices and configured default in help', async () => { + const sdkSource = ` + export async function withServiceContext(id, run) { + return run({ + manifest: { + name: 'Image Generation (AOAI)', + configuration: [{ + id: 'quality', + type: 'enum', + options: [ + { value: 'draft', label: 'Draft' }, + { value: 'final', label: 'Final' } + ] + }] + }, + config: { quality: 'draft' } + }); + } + `; + process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + const stdout = vi + .spyOn(process.stdout, 'write') + .mockImplementation(() => true); + const { main } = await loadEntry(); + + await main(['--help']); + + expect(stdout).toHaveBeenCalledWith( + expect.stringContaining('Choices: draft, final'), + ); + expect(stdout).toHaveBeenCalledWith( + expect.stringContaining('Default: draft (config.quality)'), + ); + }); }); diff --git a/apps/server/src/services/web-search/SKILL.md b/apps/server/src/services/web-search/SKILL.md index 4573a4332..a2dccdaef 100644 --- a/apps/server/src/services/web-search/SKILL.md +++ b/apps/server/src/services/web-search/SKILL.md @@ -2,6 +2,6 @@ Use this Service for current public web information when ordinary local knowledge is insufficient. -`entry.mjs` is an executable starting point for basic Tavily search, not a complete provider SDK. Run `node entry.mjs --query ""` and optionally pass `--output ` to write the JSON response to a file. It obtains current configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credential. +`entry.mjs` is an executable starting point for basic Tavily search, not a complete provider SDK. Run `node entry.mjs --help` first, then run `node entry.mjs --query ""` and optionally pass `--output ` to write the JSON response to a file. It obtains the current Manifest and configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credential. When the task needs provider options that the entry does not implement, read the [Tavily Search API documentation](https://docs.tavily.com/documentation/api-reference/endpoint/search) and modify the local Package copy. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. diff --git a/apps/server/src/services/web-search/entry.mjs b/apps/server/src/services/web-search/entry.mjs index 86a457cfd..6bec1c0e4 100644 --- a/apps/server/src/services/web-search/entry.mjs +++ b/apps/server/src/services/web-search/entry.mjs @@ -10,17 +10,33 @@ function parseCliArgs(argv) { const { values } = parseArgs({ args: argv, options: { + help: { type: 'boolean', short: 'h' }, query: { type: 'string', short: 'q' }, output: { type: 'string', short: 'o' }, }, strict: true, allowPositionals: false, }); - const options = { query: values.query, output: values.output }; + return { help: values.help, query: values.query, output: values.output }; +} + +function validateOptions(options) { if (!options.query?.trim()) { throw new Error('Web search requires --query'); } - return options; +} + +function printHelp(manifest) { + process.stdout.write(`${manifest.name} + +Usage: + node entry.mjs --query [options] + +Options: + -q, --query Search query + -o, --output Write JSON results to a file instead of stdout + -h, --help Show this help +`); } export async function search({ config, input }) { @@ -50,8 +66,13 @@ export async function main(argv = process.argv.slice(2)) { const options = parseCliArgs(argv); const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); - const { withServiceConfig } = await import(sdkUrl); - await withServiceConfig('web-search', async ({ config }) => { + const { withServiceContext } = await import(sdkUrl); + await withServiceContext('web-search', async ({ manifest, config }) => { + if (options.help) { + printHelp(manifest); + return; + } + validateOptions(options); const result = await search({ config, input: options.query }); const output = `${JSON.stringify(result, null, 2)}\n`; if (options.output) { diff --git a/apps/server/src/services/web-search/entry.test.ts b/apps/server/src/services/web-search/entry.test.ts index 695d7a0bb..07f3792ed 100644 --- a/apps/server/src/services/web-search/entry.test.ts +++ b/apps/server/src/services/web-search/entry.test.ts @@ -20,6 +20,7 @@ async function loadEntry() { } afterEach(() => { + vi.restoreAllMocks(); vi.unstubAllGlobals(); delete process.env.AGENTLET_SERVICE_SDK_URL; }); @@ -75,9 +76,12 @@ describe('Web Search Service entry', () => { .mockResolvedValue(new Response(JSON.stringify(result))), ); const sdkSource = ` - export async function withServiceConfig(id, run) { + export async function withServiceContext(id, run) { if (id !== 'web-search') throw new Error('Unexpected Service'); - return run({ config: { apiKey: 'test-secret' } }); + return run({ + manifest: { name: 'Tavily Web Search' }, + config: { apiKey: 'test-secret' } + }); } `; process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; @@ -91,4 +95,26 @@ describe('Web Search Service entry', () => { ).resolves.toBe(`${JSON.stringify(result, null, 2)}\n`); await import('node:fs/promises').then((fs) => fs.rm(output)); }); + + it('renders entry help without requiring a query', async () => { + const sdkSource = ` + export async function withServiceContext(id, run) { + return run({ + manifest: { name: 'Tavily Web Search' }, + config: { apiKey: 'test-secret' } + }); + } + `; + process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + const stdout = vi + .spyOn(process.stdout, 'write') + .mockImplementation(() => true); + const { main } = await loadEntry(); + + await main(['-h']); + + expect(stdout).toHaveBeenCalledWith( + expect.stringContaining('node entry.mjs --query '), + ); + }); }); diff --git a/docs/architecture/api-design.md b/docs/architecture/api-design.md index 135f3f1e7..285245d9f 100644 --- a/docs/architecture/api-design.md +++ b/docs/architecture/api-design.md @@ -164,7 +164,7 @@ Malformed request fields and malformed cursors return HTTP 400 with `code: "malf `packages/shared/src/types/api/service-package.ts` defines the strict manifest, Generic Settings update, masked configuration, summary, and External lease contracts. Owner Settings uses `GET /api/services`, `GET /api/services/:serviceId`, and `PUT /api/services/:serviceId`; every path/body value is validated with the shared schemas before selecting a code-registered storage namespace. -Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes third-party services under `/services`. Manifest and Skill reads contain no credentials. `POST /services/:id/lease` rejects unknown, unconfigured, and Packages without `SKILL.md`, returns only declared fields, and is non-cacheable. `GET /download/services/:id.zip` streams the validated `service.yaml + package.files` set beneath one `/` archive root and uses the Package content hash as its ETag. See [`service-packages.md`](./service-packages.md). +Canvas-scoped RFS keeps the existing `/capabilities` path for Space-operation discovery and exposes third-party services under `/services`. Manifest and Skill reads contain no credentials. `POST /services/:id/lease` rejects unknown, unconfigured, and Packages without `SKILL.md`, returns the exact validated Manifest and only its declared configuration fields as one version-coherent runtime context, and is non-cacheable. `GET /download/services/:id.zip` streams the validated `service.yaml + package.files` set beneath one `/` archive root and uses the Package content hash as its ETag. See [`service-packages.md`](./service-packages.md). ## Anti-patterns diff --git a/docs/architecture/service-packages.md b/docs/architecture/service-packages.md index 755aa80e6..6c36b7b4f 100644 --- a/docs/architecture/service-packages.md +++ b/docs/architecture/service-packages.md @@ -48,7 +48,7 @@ Internal Agent tools keep their high-level Huabu integrations. `generate_image` Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Service configuration but do not import Package entries. -External Agent Packages provide a real `SKILL.md` and may provide an `entry.mjs` that imports `AGENTLET_SERVICE_SDK_URL`, leases current configuration, and implements only a useful baseline provider workflow. The entry is not a complete provider SDK: the Skill links official provider documentation, and an Agent may modify its downloaded local copy for additional endpoints. The bundled Image and Tavily Packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore publish neither placeholder file. +External Agent Packages provide a real `SKILL.md` and may provide an `entry.mjs` that imports `AGENTLET_SERVICE_SDK_URL`, leases one coherent runtime context containing the current Manifest and configuration, and implements only a useful baseline provider workflow. Every executable entry supports `-h` and `--help`; an Agent runs help before invocation because runtime Manifest constraints and configured defaults may not be derivable from the source alone. Entries define their own CLI mapping, use Manifest enum options as the authoritative choices, use explicitly mapped configuration fields as defaults, and let an explicit operation argument override only those defaults. The entry is not a complete provider SDK: the Skill links official provider documentation, and an Agent may modify its downloaded local copy for additional endpoints. The bundled Image and Tavily Packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore publish neither placeholder file. ## Owner Settings API @@ -74,7 +74,7 @@ POST /services/:id/lease GET /download/services/:id.zip ``` -Manifest and Skill responses contain no credentials. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and Packages without `SKILL.md` explicitly, returns only fields declared by the selected Package, and uses `Cache-Control: no-store`. +Manifest and Skill responses contain no credentials. Lease requires the normal authenticated RFS context, rejects unknown, unconfigured, and Packages without `SKILL.md` explicitly, returns the exact validated Manifest together with only configuration fields declared by that Package, and uses `Cache-Control: no-store`. Returning both in one response keeps runtime choices, defaults, and Package version coherent. Package download streams a ZIP on demand from the validated Package record without a temporary file or ZIP cache. The archive contains one `/` root directory, `service.yaml`, and exactly the files declared by `package.files`; undeclared tests and development files are excluded. The response uses the Package content hash as its ETag. Phase 1 resolves records from bundled directories; a future validated custom-Service installation can expose the same immutable root, exact file list, and hash without changing the route. @@ -82,7 +82,7 @@ Package download streams a ZIP on demand from the validated Package record witho Agentlet publishes `dist/service-sdk/index.js`. The daemon computes its absolute `file://` URL relative to its own `import.meta.url` and injects it as the authoritative `AGENTLET_SERVICE_SDK_URL` after workload environment values, so a Profile or session cannot replace it. -`leaseService(id)` obtains a fresh configuration lease without downloading or loading Package code. `withServiceConfig(id, callback)` is the scoped convenience wrapper used by `entry.mjs`. The SDK reports bounded status-only request failures and does not include response bodies that could contain credentials. +`leaseService(id)` obtains a fresh `{ id, version, manifest, config }` context without downloading or loading Package code. `withServiceContext(id, callback)` is the scoped convenience wrapper used by `entry.mjs`. The SDK verifies that the leased Manifest identity and version match the enclosing context, reports bounded status-only request failures, and does not include response bodies that could contain credentials. The SDK reduces accidental persistence but is not a sandbox. A trusted External Agent and loaded client share the Agent process's filesystem, network, RFS bearer, and provider credentials. Static provider credentials cannot be revoked after disclosure except by provider-side rotation. diff --git a/docs/proposals/service-packages.md b/docs/proposals/service-packages.md index d0bbcd3a8..2b7b7a7db 100644 --- a/docs/proposals/service-packages.md +++ b/docs/proposals/service-packages.md @@ -41,7 +41,7 @@ External Agent 经 authenticated RFS 下载完整 Package ZIP，在任意工作 Owner Settings 使用 `/api/services` generic API。RFS 保留 `/capabilities` 用作 Space operation discovery，并使用独立的 `/services` 提供第三方服务列表、Manifest、Skill 与 POST lease；`GET /download/services/:id.zip` on-the-fly 流式打包一个 `/` 根目录，其中只包含 `service.yaml` 和 `package.files` 声明的文件。 -Lease 使用现有 canvas-scoped RFS bearer，响应 `Cache-Control: no-store`，只返回目标 Package 声明的配置。Manifest、Skill、ZIP、Settings read 和日志不返回 secret。Agentlet SDK 只提供 `leaseService()` 与 `withServiceConfig()`，不下载 Package code；它降低意外落盘和日志泄露，但不是 sandbox。Agent 与其修改的 entry 拥有同一进程权限，静态 provider key 一旦交付只能通过 provider rotation 真正撤销。 +Lease 使用现有 canvas-scoped RFS bearer，响应 `Cache-Control: no-store`，并将 exact validated Manifest 与目标 Package 声明的配置作为同一 version-coherent runtime context 返回。Manifest、Skill、ZIP、Settings read 和日志不返回 secret。Agentlet SDK 提供 `leaseService()` 与 `withServiceContext()`，不下载 Package code；entry 必须支持 `--help`，从 runtime Manifest 读取 choices、从显式映射的 config 字段读取 default，并只允许 CLI operation input 覆盖这些 default。SDK 降低意外落盘和日志泄露，但不是 sandbox。Agent 与其修改的 entry 拥有同一进程权限，静态 provider key 一旦交付只能通过 provider rotation 真正撤销。 ## Phase 1 diff --git a/packages/shared/src/types/api/service-package.test.ts b/packages/shared/src/types/api/service-package.test.ts index ce143a75b..64a0d6a1b 100644 --- a/packages/shared/src/types/api/service-package.test.ts +++ b/packages/shared/src/types/api/service-package.test.ts @@ -5,6 +5,7 @@ import { describe, expect, it } from 'vitest'; import { serviceConfigUpdateSchema, + serviceLeaseSchema, serviceManifestSchema, } from './service-package.js'; @@ -73,4 +74,23 @@ describe('Service Package contract', () => { false, ); }); + + it('requires a version-coherent Manifest in each lease', () => { + expect( + serviceLeaseSchema.safeParse({ + id: 'example', + version: '1.0.0', + manifest: { ...manifest, version: '2.0.0' }, + config: { apiKey: 'secret' }, + }).success, + ).toBe(false); + expect( + serviceLeaseSchema.safeParse({ + id: 'example', + version: '1.0.0', + manifest, + config: { undeclared: 'value' }, + }).success, + ).toBe(false); + }); }); diff --git a/packages/shared/src/types/api/service-package.ts b/packages/shared/src/types/api/service-package.ts index f9764e4fb..6f0b8e29f 100644 --- a/packages/shared/src/types/api/service-package.ts +++ b/packages/shared/src/types/api/service-package.ts @@ -180,7 +180,36 @@ export const serviceLeaseSchema = z .object({ id: serviceIdSchema, version: z.string(), + manifest: serviceManifestSchema, config: z.record(serviceFieldIdSchema, serviceFieldValueSchema), }) - .strict(); + .strict() + .superRefine((lease, ctx) => { + if (lease.manifest.id !== lease.id) { + ctx.addIssue({ + code: 'custom', + path: ['manifest', 'id'], + message: 'Lease Manifest id must match the Service id', + }); + } + if (lease.manifest.version !== lease.version) { + ctx.addIssue({ + code: 'custom', + path: ['manifest', 'version'], + message: 'Lease Manifest version must match the Service version', + }); + } + const fieldIds = new Set( + lease.manifest.configuration.map((field) => field.id), + ); + for (const fieldId of Object.keys(lease.config)) { + if (!fieldIds.has(fieldId)) { + ctx.addIssue({ + code: 'custom', + path: ['config', fieldId], + message: `Lease config field is not declared: ${fieldId}`, + }); + } + } + }); export type ServiceLease = z.infer; From f8db3210a3c1fd2a5732f7f8bde04f1b7c2ca6dc Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sat, 10 Oct 2026 07:49:09 +0000 Subject: [PATCH 17/36] fix: reconnect stalled canvas sync streams Add an opt-in SSE inactivity watchdog so Canvas Sync can recover from half-open connections using its existing retry and snapshot reconciliation path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/web/src/api/_sse.test.ts | 72 ++++++++++++++ apps/web/src/api/_sse.ts | 44 ++++++++- apps/web/src/store/canvasSyncStore.test.ts | 105 +++++++++++++++++++++ apps/web/src/store/canvasSyncStore.ts | 2 + docs/architecture/canvas-realtime-sync.md | 4 +- 5 files changed, 225 insertions(+), 2 deletions(-) create mode 100644 apps/web/src/api/_sse.test.ts create mode 100644 apps/web/src/store/canvasSyncStore.test.ts diff --git a/apps/web/src/api/_sse.test.ts b/apps/web/src/api/_sse.test.ts new file mode 100644 index 000000000..28254c198 --- /dev/null +++ b/apps/web/src/api/_sse.test.ts @@ -0,0 +1,72 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { readSSEStream } from './_sse'; + +const encoder = new TextEncoder(); + +describe('readSSEStream inactivity timeout', () => { + beforeEach(() => { + vi.useFakeTimers(); + }); + + afterEach(() => { + vi.useRealTimers(); + }); + + it('rejects and cancels a stream that receives no data', async () => { + const cancel = vi.fn(); + const stream = new ReadableStream({ + cancel, + }); + const reading = readSSEStream(new Response(stream), vi.fn(), undefined, { + inactivityTimeoutMs: 1_000, + }); + const rejection = expect(reading).rejects.toThrow( + 'SSE stream received no data for 1000 ms', + ); + + await vi.advanceTimersByTimeAsync(1_000); + + await rejection; + expect(cancel).toHaveBeenCalledOnce(); + }); + + it('treats heartbeat comments as activity', async () => { + const streamState: { + controller?: ReadableStreamDefaultController; + } = {}; + const onEvent = vi.fn(); + const stream = new ReadableStream({ + start(nextController) { + streamState.controller = nextController; + }, + }); + const reading = readSSEStream(new Response(stream), onEvent, undefined, { + inactivityTimeoutMs: 1_000, + }); + const enqueue = (value: string) => { + const controller = streamState.controller; + if (!controller) throw new Error('Stream controller was not initialized'); + controller.enqueue(encoder.encode(value)); + }; + + await vi.advanceTimersByTimeAsync(900); + enqueue(': ping\n\n'); + await vi.advanceTimersByTimeAsync(900); + enqueue('event: update\ndata: {"version":2}\n\n'); + const controller = streamState.controller; + if (!controller) { + throw new Error('Stream controller was not initialized'); + } + controller.close(); + await reading; + + expect(onEvent).toHaveBeenCalledWith({ + type: 'update', + data: { version: 2 }, + }); + }); +}); diff --git a/apps/web/src/api/_sse.ts b/apps/web/src/api/_sse.ts index f349defc6..ac60a5850 100644 --- a/apps/web/src/api/_sse.ts +++ b/apps/web/src/api/_sse.ts @@ -22,6 +22,37 @@ export interface SSEEvent { export type SSEEventHandler = (event: SSEEvent) => void; +export interface SSEReadOptions { + inactivityTimeoutMs?: number; +} + +async function readWithInactivityTimeout( + reader: ReadableStreamDefaultReader, + inactivityTimeoutMs: number | undefined, +): Promise> { + if (inactivityTimeoutMs === undefined) { + return reader.read(); + } + + let timeout: ReturnType | undefined; + try { + return await Promise.race([ + reader.read(), + new Promise((_, reject) => { + timeout = setTimeout(() => { + reject( + new Error( + `SSE stream received no data for ${inactivityTimeoutMs} ms`, + ), + ); + }, inactivityTimeoutMs); + }), + ]); + } finally { + if (timeout !== undefined) clearTimeout(timeout); + } +} + /** * Read an SSE response body to completion, invoking `onEvent` for every * fully-formed event. Returns when the stream ends or `signal` aborts. @@ -30,6 +61,7 @@ export async function readSSEStream>( response: Response, onEvent: SSEEventHandler, signal?: AbortSignal, + options: SSEReadOptions = {}, ): Promise { if (!response.body) return; const reader = response.body.getReader(); @@ -39,7 +71,10 @@ export async function readSSEStream>( try { while (true) { if (signal?.aborted) return; - const { done, value } = await reader.read(); + const { done, value } = await readWithInactivityTimeout( + reader, + options.inactivityTimeoutMs, + ); if (done) break; buffer += decoder.decode(value, { stream: true }); @@ -57,6 +92,11 @@ export async function readSSEStream>( } } } finally { + try { + await reader.cancel(); + } catch { + // The fetch signal may already have closed the stream. + } reader.releaseLock?.(); } } @@ -102,10 +142,12 @@ export async function readTypedSSEStream< response: Response, onEvent: (event: E) => void, signal?: AbortSignal, + options?: SSEReadOptions, ): Promise { await readSSEStream( response, (event) => onEvent(event as unknown as E), signal, + options, ); } diff --git a/apps/web/src/store/canvasSyncStore.test.ts b/apps/web/src/store/canvasSyncStore.test.ts new file mode 100644 index 000000000..7e58bff40 --- /dev/null +++ b/apps/web/src/store/canvasSyncStore.test.ts @@ -0,0 +1,105 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { useCanvasSyncStore } from './canvasSyncStore'; + +const mocks = vi.hoisted(() => { + const canvasState = { + canvasId: 'canvas-1', + version: 1, + isLoading: false, + nodes: [], + pendingContentNodeIds: vi.fn(() => []), + applyDeltasFromAgent: vi.fn(() => []), + loadCanvas: vi.fn(async () => undefined), + }; + return { canvasState }; +}); + +vi.mock('@/api/_client', () => ({ + apiErrorFromResponse: vi.fn(), + getRateLimitRetryAfterSeconds: vi.fn(() => null), +})); +vi.mock('@/api/canvasSync', () => ({ + canvasSyncStreamUrl: (canvasId: string) => + `/api/canvas/${canvasId}/sync/stream`, +})); +vi.mock('@/components/Common/Toast', () => ({ + dismissToast: vi.fn(), + toast: vi.fn(), +})); +vi.mock('@/hooks/agentStreamCoordinator', () => ({ + hasAgentStreamClaim: vi.fn(() => false), +})); +vi.mock('@/store/acpThreadChangesStore', () => ({ + useAcpThreadChangesStore: { + getState: () => ({ replaceFromBroadcast: vi.fn() }), + }, +})); +vi.mock('@/store/canvasStore', () => ({ + default: { + getState: () => mocks.canvasState, + }, +})); +vi.mock('@/store/chatStore', () => ({ + useChatStore: { + getState: () => ({ setHistoryLoaded: vi.fn() }), + }, +})); +vi.mock('@/store/panelStore', () => ({ + usePanelStore: { + getState: () => ({ requestOpenRightPanel: vi.fn() }), + }, +})); +vi.mock('@/store/previewWorkspace/actions', () => ({ + openPreviewNode: vi.fn(), +})); + +const encoder = new TextEncoder(); + +describe('canvasSyncStore stream recovery', () => { + beforeEach(() => { + vi.useFakeTimers(); + vi.spyOn(console, 'warn').mockImplementation(() => undefined); + mocks.canvasState.loadCanvas.mockClear(); + useCanvasSyncStore.setState({ canvasId: null }); + }); + + afterEach(() => { + useCanvasSyncStore.getState().disconnect(); + vi.unstubAllGlobals(); + vi.restoreAllMocks(); + vi.useRealTimers(); + }); + + it('reconnects an inactive stream and heals from the new snapshot', async () => { + const cancelStalledStream = vi.fn(); + const stalledStream = new ReadableStream({ + cancel: cancelStalledStream, + }); + const recoveredStream = new ReadableStream({ + start(controller) { + controller.enqueue( + encoder.encode('event: snapshot\ndata: {"version":2}\n\n'), + ); + controller.close(); + }, + }); + const fetchMock = vi + .fn() + .mockResolvedValueOnce(new Response(stalledStream)) + .mockResolvedValueOnce(new Response(recoveredStream)); + vi.stubGlobal('fetch', fetchMock); + + useCanvasSyncStore.getState().connect('canvas-1'); + await vi.advanceTimersByTimeAsync(45_500); + + expect(cancelStalledStream).toHaveBeenCalledOnce(); + expect(fetchMock).toHaveBeenCalledTimes(2); + expect(mocks.canvasState.loadCanvas).toHaveBeenCalledWith('canvas-1', { + resetHistory: true, + }); + }); +}); diff --git a/apps/web/src/store/canvasSyncStore.ts b/apps/web/src/store/canvasSyncStore.ts index 16ef365e1..a93db8c90 100644 --- a/apps/web/src/store/canvasSyncStore.ts +++ b/apps/web/src/store/canvasSyncStore.ts @@ -49,6 +49,7 @@ interface CanvasSyncState { let abortController: AbortController | null = null; const INITIAL_RECONNECT_DELAY_MS = 500; const MAX_RECONNECT_DELAY_MS = 10_000; +const STREAM_INACTIVITY_TIMEOUT_MS = 45_000; type SyncPendingEffects = { mutatedNodes: Node[]; @@ -264,6 +265,7 @@ export const useCanvasSyncStore = create((set, get) => ({ ); }, signal, + { inactivityTimeoutMs: STREAM_INACTIVITY_TIMEOUT_MS }, ); if (!signal.aborted) { throw new Error('Canvas sync stream ended unexpectedly'); diff --git a/docs/architecture/canvas-realtime-sync.md b/docs/architecture/canvas-realtime-sync.md index 2c80ff8f5..e2ff47e43 100644 --- a/docs/architecture/canvas-realtime-sync.md +++ b/docs/architecture/canvas-realtime-sync.md @@ -229,7 +229,9 @@ The auto-accept preference still suppresses new Agent review records only. It do The sync route subscribes before reading the initial Canvas version, buffers updates committed during that read, sends the snapshot first, and then flushes the buffered updates. This closes the snapshot/subscribe loss window while preserving snapshot-before-update ordering. -The server emits a heartbeat comment every 15 seconds. `canvasSyncStore.connect()` treats non-OK responses, malformed events, network errors, and unexpected EOF as failures and reconnects with exponential backoff capped at 10 seconds. An intentional Canvas switch or disconnect aborts the current request and pending delay, while every successful event resets the backoff. The reconnect snapshot/version handshake remains the convergence mechanism. +The server emits a heartbeat comment every 15 seconds. Canvas Sync applies a 45-second byte-activity watchdog to the shared SSE reader; every received chunk, including a heartbeat comment that does not produce an application event, resets the timeout. Three missed heartbeat windows terminate a silently stalled or half-open stream so the existing retry loop can recover without a manual page refresh. The timeout is opt-in and does not affect other SSE consumers. + +`canvasSyncStore.connect()` treats inactivity timeouts, non-OK responses, malformed events, network errors, and unexpected EOF as failures and reconnects with exponential backoff capped at 10 seconds. An intentional Canvas switch or disconnect aborts the current request and pending delay, while every successful event resets the backoff. The reconnect snapshot/version handshake remains the convergence mechanism. ## Known reliability gap From ac0517bb78abaaf1241ee387a7e4ca2d485f7524 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sun, 11 Oct 2026 07:26:09 +0000 Subject: [PATCH 18/36] feat(chat): add fragment comments to thread input Capture selected completed response text, collect localized quote/comment templates in the owning thread draft, and preserve explicit Send as the only generation action. Cover selection, draft lifecycle and production chat regressions; document the demo MVP boundary. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/web/e2e/chat-activation.config.ts | 2 +- apps/web/e2e/fragment-feedback.spec.ts | 226 ++++++++++++++++++ .../AIMessage/FragmentCommentPopover.tsx | 89 +++++++ .../MilkdownMessageCard.comments.test.tsx | 192 +++++++++++++++ .../AIMessage/MilkdownMessageCard.tsx | 118 +++++++-- .../AIMessage/fragmentComment.test.ts | 82 +++++++ .../Messages/AIMessage/fragmentComment.ts | 45 ++++ .../components/Messages/AIMessage/index.tsx | 10 +- .../src/components/Messages/MessageList.tsx | 1 + .../components/Milkdown/MilkdownPreview.tsx | 79 +++++- .../__tests__/previewAccessibility.test.tsx | 27 +++ .../Milkdown/__tests__/textSelection.test.ts | 78 ++++++ .../src/components/Milkdown/createMilkdown.ts | 42 ++++ apps/web/src/i18n/resources/en/common.json | 6 + apps/web/src/i18n/resources/zh-CN/common.json | 6 + .../ChatPerformancePlaygroundPage.tsx | 13 +- docs/architecture/agent-context.md | 2 + docs/architecture/note-node.md | 2 + docs/architecture/preview-workspace.md | 4 + 19 files changed, 1001 insertions(+), 23 deletions(-) create mode 100644 apps/web/e2e/fragment-feedback.spec.ts create mode 100644 apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx create mode 100644 apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx create mode 100644 apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts create mode 100644 apps/web/src/components/Messages/AIMessage/fragmentComment.ts create mode 100644 apps/web/src/components/Milkdown/__tests__/textSelection.test.ts diff --git a/apps/web/e2e/chat-activation.config.ts b/apps/web/e2e/chat-activation.config.ts index d07ad30a9..196e3a162 100644 --- a/apps/web/e2e/chat-activation.config.ts +++ b/apps/web/e2e/chat-activation.config.ts @@ -12,7 +12,7 @@ const baseURL = `http://127.0.0.1:${port}`; export default defineConfig({ testDir: '.', - testMatch: 'chat-activation.spec.ts', + testMatch: ['chat-activation.spec.ts', 'fragment-feedback.spec.ts'], metadata: { chatActivationProduction: true }, outputDir: '../test-results/chat-activation', timeout: 60_000, diff --git a/apps/web/e2e/fragment-feedback.spec.ts b/apps/web/e2e/fragment-feedback.spec.ts new file mode 100644 index 000000000..1ccf51ba0 --- /dev/null +++ b/apps/web/e2e/fragment-feedback.spec.ts @@ -0,0 +1,226 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { expect, test, type Locator, type Page } from '@playwright/test'; + +function panel(page: Page, tab = 'a') { + return page.locator(`[data-activation-panel="${tab}"]`); +} + +async function selectText(surface: Locator, from: string, to = from) { + await surface.scrollIntoViewIfNeeded(); + await surface.evaluate( + (element, endpoints) => { + const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT); + const nodes: Node[] = []; + let text = ''; + let node: Node | null; + while ((node = walker.nextNode())) { + nodes.push(node); + text += node.textContent ?? ''; + } + const from = text.indexOf(endpoints.from); + const to = text.indexOf(endpoints.to, from); + if (from < 0 || to < 0) throw new Error('Selection endpoints not found'); + const range = document.createRange(); + let offset = 0; + const end = to + endpoints.to.length; + for (const node of nodes) { + const length = node.textContent?.length ?? 0; + if (from >= offset && from < offset + length) { + range.setStart(node, from - offset); + } + if (end > offset && end <= offset + length) { + range.setEnd(node, end - offset); + break; + } + offset += length; + } + element.focus(); + const selection = document.getSelection(); + selection?.removeAllRanges(); + selection?.addRange(range); + element.dispatchEvent(new MouseEvent('mouseup', { bubbles: true })); + }, + { from, to }, + ); +} + +async function comment(page: Page, text: string) { + await page.getByRole('button', { name: 'Comment', exact: true }).click(); + const editor = page.getByRole('textbox', { name: 'Comment', exact: true }); + await expect(editor).toBeFocused(); + await editor.fill(text); + await page.getByRole('button', { name: 'Add to input', exact: true }).click(); +} + +test.beforeEach(async ({ page }, info) => { + test.skip( + info.config.metadata.chatActivationProduction !== true, + 'Uses the isolated production chat fixture', + ); + await page.route('**/api/**', (route) => + route.fulfill({ + status: 503, + contentType: 'application/json', + body: JSON.stringify({ message: 'Fixture has no backend' }), + }), + ); + await page.goto('/playground/chat-performance?mode=activation&turns=3'); + await expect(panel(page).locator('.ProseMirror').first()).toBeVisible(); +}); + +test('collects inline and cross-paragraph comments, edits input and explicitly submits once', async ({ + page, +}) => { + const composer = panel(page).locator('textarea[name="agent-message"]'); + await composer.fill('Existing draft'); + const answer = panel(page) + .locator('[data-chat-message-id="a-turn-3-tool"] .ProseMirror') + .last(); + await answer.locator('strong').dblclick(); + await page.getByRole('button', { name: 'Comment', exact: true }).click(); + await expect( + page.getByRole('button', { name: 'Add to input' }), + ).toBeDisabled(); + await page + .getByRole('textbox', { name: 'Comment', exact: true }) + .fill('Keep this.'); + // The append must read the latest draft, not the one at selection time. + await composer.fill('Draft edited while commenting'); + await page.getByRole('button', { name: 'Cancel', exact: true }).click(); + // Reselect and add against the latest draft. + await selectText(answer, 'cached'); + await comment(page, 'Keep this.'); + await expect(composer).toBeFocused(); + await expect(composer).toHaveValue( + /Draft edited while commenting\n\nQuote from an earlier reply:\n> cached/, + ); + await selectText( + answer, + 'Preserve full history', + 'Older turns stay available.', + ); + await comment(page, '请展开'); + await expect(composer).toHaveValue( + /前面回答中的引用：\n> Preserve full history/, + ); + await expect(composer).toHaveValue( + /> \n> Render recent turns\n> \n> Older turns stay available\./, + ); + await expect(panel(page)).toHaveAttribute('data-submitted-draft', ''); + const draft = (await composer.inputValue()).replace( + 'Keep this.', + 'Keep the reasoning.', + ); + await composer.fill(`${draft}\n\nDiscuss only these points.`); + await composer.press('Enter'); + await expect(panel(page)).toHaveAttribute( + 'data-submitted-draft', + `${draft}\n\nDiscuss only these points.`, + ); + await expect(composer).toHaveValue(''); +}); + +test('supports code and keyboard selection and does not change the original answer', async ({ + page, +}) => { + const answer = panel(page).locator( + '[data-chat-message-id="a-turn-3-answer"] .ProseMirror', + ); + const original = await answer.innerText(); + await selectText(answer, 'const cachedTurn = 3;'); + await comment(page, 'Explain this code.'); + await expect( + panel(page).locator('textarea[name="agent-message"]'), + ).toHaveValue(/> const cachedTurn = 3;/); + await expect(answer).toHaveText(original, { useInnerText: true }); + const paragraph = answer.locator('p').last(); + await paragraph.click(); + await page.keyboard.press('Home'); + await page.keyboard.press('Shift+End'); + await expect( + page.getByRole('button', { name: 'Comment', exact: true }), + ).toBeVisible(); + await page.getByRole('button', { name: 'Comment', exact: true }).click(); + await page.keyboard.press('Escape'); + await expect( + page.getByRole('textbox', { name: 'Comment', exact: true }), + ).toHaveCount(0); +}); + +test('rejects selections spanning messages and excludes streaming output', async ({ + page, +}) => { + const answers = panel(page).locator('.ProseMirror'); + await answers.last().scrollIntoViewIfNeeded(); + await answers.last().evaluate((last) => { + const first = document.querySelector( + '[data-activation-panel="a"] .ProseMirror', + ); + if (!first) throw new Error('Missing first answer'); + const range = document.createRange(); + range.setStart(first, 0); + range.setEnd(last, last.childNodes.length); + const selection = document.getSelection(); + selection?.removeAllRanges(); + selection?.addRange(range); + last.dispatchEvent(new MouseEvent('mouseup', { bubbles: true })); + }); + await expect( + page.getByRole('button', { name: 'Comment', exact: true }), + ).toHaveCount(0); + await page.getByRole('button', { name: 'Start turn', exact: true }).click(); + const streaming = panel(page).locator( + '[data-chat-message-id="a-turn-4-answer"] .ProseMirror', + ); + await selectText(streaming, 'const cachedTurn = 4;'); + await expect( + page.getByRole('button', { name: 'Comment', exact: true }), + ).toHaveCount(0); + await page + .getByRole('button', { name: 'Complete turn', exact: true }) + .click(); + await selectText(streaming, 'const cachedTurn = 4;'); + await comment(page, 'Explain.'); +}); + +test('keeps comments thread-local through tab switching and drops unsent drafts on reload', async ({ + page, +}) => { + await selectText( + panel(page).locator( + '[data-chat-message-id="a-turn-3-answer"] .ProseMirror', + ), + 'const cachedTurn = 3;', + ); + await comment(page, 'Keep in A.'); + const draft = await panel(page) + .locator('textarea[name="agent-message"]') + .inputValue(); + await page.getByRole('button', { name: 'Tab B', exact: true }).click(); + await expect( + panel(page, 'b').locator('textarea[name="agent-message"]'), + ).toHaveValue(''); + await selectText( + panel(page, 'b').locator( + '[data-chat-message-id="b-turn-3-answer"] .ProseMirror', + ), + 'const cachedTurn = 3;', + ); + await page.getByRole('button', { name: 'Comment', exact: true }).click(); + await page + .getByRole('textbox', { name: 'Comment', exact: true }) + .fill('Not appended.'); + await page.getByRole('button', { name: 'Tab A', exact: true }).click(); + await expect( + page.getByRole('textbox', { name: 'Comment', exact: true }), + ).toHaveCount(0); + await expect( + panel(page).locator('textarea[name="agent-message"]'), + ).toHaveValue(draft); + await page.reload(); + await expect( + panel(page).locator('textarea[name="agent-message"]'), + ).toHaveValue(''); +}); diff --git a/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx b/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx new file mode 100644 index 000000000..0fc646134 --- /dev/null +++ b/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx @@ -0,0 +1,89 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { useRef, useState } from 'react'; +import { useTranslation } from 'react-i18next'; + +import { Button } from '@/components/Common/Button'; +import { Popover } from '@/components/Common/Popover'; +import { TextInput } from '@/components/Common/TextInput'; + +import type { MilkdownPreviewSelection } from '@/components/Milkdown/MilkdownPreview'; + +interface FragmentCommentPopoverProps { + selection: MilkdownPreviewSelection; + onBegin: () => void; + onAdd: (comment: string) => void; + onDismiss: () => void; +} + +export function FragmentCommentPopover({ + selection, + onBegin, + onAdd, + onDismiss, +}: FragmentCommentPopoverProps) { + const { t } = useTranslation(); + const [editing, setEditing] = useState(false); + const [comment, setComment] = useState(''); + const inputRef = useRef(null); + + return ( + inputRef.current?.focus({ preventScroll: true }) + : undefined + } + > + {editing ? ( +
{ + event.preventDefault(); + if (comment.trim()) onAdd(comment); + }} + > +
+ {selection.text} +
+ setComment(event.target.value)} + onKeyDown={(event) => { + if (event.key === 'Enter' && event.nativeEvent.isComposing) { + event.preventDefault(); + } + }} + /> +
+ + +
+ + ) : ( + + )} +
+ ); +} diff --git a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx new file mode 100644 index 000000000..d743ecd88 --- /dev/null +++ b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx @@ -0,0 +1,192 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { act } from 'react'; +import { createRoot, type Root } from 'react-dom/client'; +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; + +import { i18n } from '@/i18n'; +import { selectThreadDraft, useChatStore } from '@/store/chatStore'; +import { usePanelStore } from '@/store/panelStore'; + +import { MilkdownMessageCard } from './MilkdownMessageCard'; + +import type { MilkdownPreviewSelection } from '@/components/Milkdown/MilkdownPreview'; + +const preview = vi.hoisted(() => ({ + onTextSelection: undefined as + | ((selection: MilkdownPreviewSelection | null) => void) + | undefined, +})); +vi.mock('@/components/Milkdown', () => ({ + MilkdownPreview: ({ + onTextSelection, + }: { + onTextSelection?: typeof preview.onTextSelection; + }) => { + preview.onTextSelection = onTextSelection; + return
Answer
; + }, +})); +vi.mock('@/store/canvasStore', () => ({ + default: (selector: (state: { canvasId: string | null }) => unknown) => + selector({ canvasId: null }), +})); + +const selection: MilkdownPreviewSelection = { + range: { from: 1, to: 8 }, + text: 'selected\n\npassage', + contextBefore: 'Before ', + contextAfter: ' after', + position: { x: 20, y: 20 }, +}; +let root: Root; +let host: HTMLDivElement; + +beforeEach(async () => { + await i18n.changeLanguage('en'); + useChatStore.setState({ threadsById: {} }); + host = document.createElement('div'); + document.body.appendChild(host); + root = createRoot(host); +}); +afterEach(() => { + act(() => root.unmount()); + host.remove(); + vi.restoreAllMocks(); +}); + +function render(enabled = true, content = 'Original answer') { + act(() => + root.render( + , + ), + ); +} +function button(name: string) { + const found = [...document.querySelectorAll('button')].find( + (item) => item.textContent?.trim() === name, + ); + if (!found) throw new Error(`Missing button: ${name}`); + return found; +} +function click(name: string) { + act(() => button(name).click()); +} +function input() { + const element = document.querySelector( + 'input[aria-label="Comment"]', + ); + if (!element) throw new Error('Missing comment editor'); + return element; +} +function type(value: string) { + act(() => { + Object.getOwnPropertyDescriptor( + HTMLInputElement.prototype, + 'value', + )?.set?.call(input(), value); + input().dispatchEvent(new Event('input', { bubbles: true })); + }); +} +function select() { + act(() => preview.onTextSelection?.(selection)); + click('Comment'); +} + +describe('AI response comments', () => { + it('opens a snapshot editor, requires a comment and cancels without changing the draft', () => { + render(); + select(); + expect(document.querySelector('blockquote')?.textContent).toBe( + selection.text, + ); + expect(button('Add to input').disabled).toBe(true); + type(' '); + expect(button('Add to input').disabled).toBe(true); + type('Keep it.'); + click('Cancel'); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toBe(''); + expect(document.querySelector('blockquote')).toBeNull(); + }); + + it('appends to the latest owning-thread draft and supports multiple comments without sending', () => { + const addMessage = vi.spyOn(useChatStore.getState(), 'addMessage'); + useChatStore.getState().setDraft('thread-a', 'Before opening'); + useChatStore.getState().setDraft('thread-b', 'Other thread'); + render(); + select(); + type('Keep it.'); + act(() => + useChatStore.getState().setDraft('thread-a', 'Edited while commenting'), + ); + click('Add to input'); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toBe( + 'Edited while commenting\n\nQuote from an earlier reply:\n> selected\n> \n> passage\n\nNearby context ([…] marks the quoted passage):\nBefore […] after\n\nComment:\nKeep it.', + ); + expect(usePanelStore.getState().focusChatInputRequest?.threadId).toBe( + 'thread-a', + ); + select(); + type('请展开'); + click('Add to input'); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toContain( + '评论：\n请展开', + ); + expect(selectThreadDraft(useChatStore.getState(), 'thread-b')).toBe( + 'Other thread', + ); + expect(addMessage).not.toHaveBeenCalled(); + }); + + it('keeps capture-time text after focus and source changes and never rewrites emitted input', () => { + render(); + select(); + act(() => preview.onTextSelection?.(null)); + render(true, 'Replaced answer'); + type('Explore this.'); + click('Add to input'); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toContain( + '> selected', + ); + act(() => + useChatStore + .getState() + .setDraft('thread-a', 'Manually edited comment\nFinal instruction'), + ); + render(true, 'Changed again'); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toBe( + 'Manually edited comment\nFinal instruction', + ); + }); + + it('does not emit during Chinese IME composition', () => { + render(); + select(); + type('你好'); + const event = new KeyboardEvent('keydown', { + key: 'Enter', + bubbles: true, + cancelable: true, + }); + Object.defineProperty(event, 'isComposing', { value: true }); + act(() => input().dispatchEvent(event)); + expect(event.defaultPrevented).toBe(true); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toBe(''); + }); + + it('disables selection feedback on inactive or streaming surfaces and resets the editor', () => { + render(); + select(); + render(false); + expect(preview.onTextSelection).toBeUndefined(); + expect(document.querySelector('blockquote')).toBeNull(); + render(); + expect(document.querySelector('blockquote')).toBeNull(); + }); +}); diff --git a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx index 5eb0dea53..d9e9d23c6 100644 --- a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx +++ b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx @@ -5,15 +5,26 @@ * Milkdown-backed renderer for AI chat messages. */ -import { memo, useCallback } from 'react'; +import { memo, useCallback, useEffect, useRef, useState } from 'react'; +import { useTranslation } from 'react-i18next'; import { parseArtifactUrl } from '@huabu/shared'; import { MilkdownPreview } from '@/components/Milkdown'; import useCanvasStore from '@/store/canvasStore'; +import { selectThreadDraft, useChatStore } from '@/store/chatStore'; +import { usePanelStore } from '@/store/panelStore'; import { setDragPayload } from '@/utils/io/dragDrop'; import { openDocumentLink } from '@/utils/openDocumentLink'; +import { + appendFragmentComment, + commentTemplateLanguage, + renderFragmentComment, +} from './fragmentComment'; +import { FragmentCommentPopover } from './FragmentCommentPopover'; + +import type { MilkdownPreviewSelection } from '@/components/Milkdown/MilkdownPreview'; import type { ImageDragPayload, NoteDragPayload } from '@/utils/io/dragDrop'; import type { NodeOrigin } from '@huabu/shared'; @@ -26,6 +37,9 @@ interface MilkdownMessageCardProps { * we don't subscribe N times for N rendered cards. */ threadId: string; + messageId?: string; + segmentIndex?: number; + enableComments?: boolean; } /** @@ -92,31 +106,97 @@ export function buildImageDragPayload( export const MilkdownMessageCard = memo(function MilkdownMessageCard({ content, threadId, + messageId, + segmentIndex = 0, + enableComments = false, }: MilkdownMessageCardProps) { + const { i18n } = useTranslation(); const canvasId = useCanvasStore((s) => s.canvasId); + const [selection, setSelection] = useState( + null, + ); + const editingRef = useRef(false); + const handleTextSelection = useCallback( + (next: MilkdownPreviewSelection | null) => { + if (!editingRef.current) setSelection(next); + }, + [], + ); + const dismissComment = useCallback(() => { + editingRef.current = false; + setSelection(null); + }, []); + useEffect(() => { + if (!enableComments) dismissComment(); + }, [enableComments, dismissComment]); const handleLinkClick = useCallback( (href: string) => openDocumentLink(href, { threadId }), [threadId], ); return ( - { - const built = - buildImageDragPayload(markdown, threadId, canvasId) ?? - buildNoteDragPayload(markdown, threadId); - if (!built) return; - - setDragPayload( - nativeEvent as unknown as React.DragEvent, - built.payload, - ); - }} - /> + <> + { + const built = + buildImageDragPayload(markdown, threadId, canvasId) ?? + buildNoteDragPayload(markdown, threadId); + if (!built) return; + + setDragPayload( + nativeEvent as unknown as React.DragEvent, + built.payload, + ); + }} + /> + {enableComments && messageId && selection ? ( + { + editingRef.current = true; + }} + onDismiss={dismissComment} + onAdd={(comment) => { + const templateT = i18n.getFixedT( + commentTemplateLanguage( + comment, + i18n.resolvedLanguage ?? i18n.language, + ), + ); + const rendered = renderFragmentComment( + { + ...selection, + sourceMessageId: messageId, + segmentIndex, + comment, + }, + { + quote: templateT('messages.fragmentQuoteLabel'), + comment: templateT('messages.fragmentCommentLabel'), + context: templateT('messages.fragmentContextLabel'), + }, + ); + const chat = useChatStore.getState(); + chat.setDraft( + threadId, + appendFragmentComment( + selectThreadDraft(chat, threadId), + rendered, + ), + ); + dismissComment(); + usePanelStore.getState().requestFocusChatInput(threadId); + }} + /> + ) : null} + ); }); diff --git a/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts b/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts new file mode 100644 index 000000000..4a91f18f2 --- /dev/null +++ b/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts @@ -0,0 +1,82 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { describe, expect, it } from 'vitest'; + +import { + appendFragmentComment, + commentTemplateLanguage, + renderFragmentComment, + type FragmentComment, +} from './fragmentComment'; + +const labels = { quote: 'Quote:', comment: 'Comment:', context: 'Context:' }; +const fragment: FragmentComment = { + sourceMessageId: 'answer-1', + segmentIndex: 0, + range: { from: 1, to: 8 }, + text: 'one\n\ntwo', + contextBefore: '', + contextAfter: '', + comment: 'Keep this.', +}; + +describe('fragment comment templates', () => { + it.each([ + ['请保留 API', 'en', 'zh-CN'], + ['Please keep this', 'zh-CN', 'en'], + ['你好', 'en', 'zh-CN'], + ['123 👍', 'zh-CN', 'zh-CN'], + ['123 👍', 'en', 'en'], + ['/review', 'zh-CN', 'en'], + ])('chooses a template for %s with UI %s', (comment, ui, expected) => { + expect(commentTemplateLanguage(comment, ui)).toBe(expected); + }); + + it('quotes every line and preserves code, Unicode and user comments', () => { + expect( + renderFragmentComment( + { + ...fragment, + text: '/review\n\nconst value = "你好";', + comment: ' Keep\nthese lines. ', + }, + labels, + ), + ).toBe( + 'Quote:\n> /review\n> \n> const value = "你好";\n\nComment:\nKeep\nthese lines.', + ); + }); + + it('includes captured context without exposing local identity or offsets', () => { + const rendered = renderFragmentComment( + { + ...fragment, + contextBefore: 'first\noccurrence ', + contextAfter: ' continues', + }, + labels, + ); + expect(rendered).toContain('Context:\nfirst occurrence […] continues'); + expect(rendered).not.toContain('answer-1'); + expect(rendered).not.toContain('from'); + }); + + it.each(['', 'Draft', 'Draft\n', 'Draft\n\n'])( + 'appends to %j without losing text', + (draft) => { + const first = appendFragmentComment( + draft, + renderFragmentComment(fragment, labels), + ); + const second = appendFragmentComment( + first, + renderFragmentComment({ ...fragment, comment: 'Explore.' }, labels), + ); + expect(second.startsWith(draft)).toBe(true); + expect(second).toContain('Comment:\nKeep this.'); + expect(second).toContain('Comment:\nExplore.'); + expect(second).not.toContain('\n\n\nQuote:'); + }, + ); +}); diff --git a/apps/web/src/components/Messages/AIMessage/fragmentComment.ts b/apps/web/src/components/Messages/AIMessage/fragmentComment.ts new file mode 100644 index 000000000..b3db482e2 --- /dev/null +++ b/apps/web/src/components/Messages/AIMessage/fragmentComment.ts @@ -0,0 +1,45 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import type { MilkdownTextSelection } from '@/components/Milkdown/createMilkdown'; + +export interface FragmentComment extends MilkdownTextSelection { + sourceMessageId: string; + segmentIndex: number; + comment: string; +} + +export function commentTemplateLanguage( + comment: string, + uiLanguage: string, +): 'en' | 'zh-CN' { + if (/\p{Script=Han}/u.test(comment)) return 'zh-CN'; + if (/[a-z]/i.test(comment)) return 'en'; + return uiLanguage.toLowerCase().startsWith('zh') ? 'zh-CN' : 'en'; +} + +export function renderFragmentComment( + fragment: FragmentComment, + labels: { quote: string; comment: string; context: string }, +): string { + const quote = fragment.text + .split(/\r?\n/) + .map((line) => `> ${line}`) + .join('\n'); + const before = fragment.contextBefore.trim(); + const after = fragment.contextAfter.trim(); + const context = + before || after + ? `\n\n${labels.context}\n${[before, '[…]', after] + .filter(Boolean) + .map((part) => part.replace(/\s+/g, ' ')) + .join(' ')}` + : ''; + return `${labels.quote}\n${quote}${context}\n\n${labels.comment}\n${fragment.comment.trim()}`; +} + +export function appendFragmentComment(draft: string, rendered: string): string { + return draft + ? `${draft}${draft.endsWith('\n\n') ? '' : draft.endsWith('\n') ? '\n' : '\n\n'}${rendered}` + : rendered; +} diff --git a/apps/web/src/components/Messages/AIMessage/index.tsx b/apps/web/src/components/Messages/AIMessage/index.tsx index 7221b13b7..2a3ef0dd4 100644 --- a/apps/web/src/components/Messages/AIMessage/index.tsx +++ b/apps/web/src/components/Messages/AIMessage/index.tsx @@ -36,6 +36,7 @@ interface AIMessageProps { segments: AssistantSegment[]; isStreaming?: boolean; hideActions?: boolean; + enableComments?: boolean; } const NoteIcon = NODE_ICON.note; @@ -116,6 +117,7 @@ export const AIMessage = memo(function AIMessage({ segments, isStreaming, hideActions, + enableComments = false, }: AIMessageProps) { const { t } = useTranslation(); const addNode = useCanvasStore((state) => state.addNode); @@ -239,7 +241,13 @@ export const AIMessage = memo(function AIMessage({ className="text-fg-default bg-surface ml-1 rounded-2xl border border-none px-4 text-sm" >
- +
); diff --git a/apps/web/src/components/Messages/MessageList.tsx b/apps/web/src/components/Messages/MessageList.tsx index 6821cdfb1..def9f4269 100644 --- a/apps/web/src/components/Messages/MessageList.tsx +++ b/apps/web/src/components/Messages/MessageList.tsx @@ -674,6 +674,7 @@ export const MessageList = memo(function MessageList({ segments={msg.segments} isStreaming={msg.id === streamingAssistantId} hideActions={hideAIActions} + enableComments={isActive && !isHistoryLoading} />
, ); diff --git a/apps/web/src/components/Milkdown/MilkdownPreview.tsx b/apps/web/src/components/Milkdown/MilkdownPreview.tsx index bd7ef05e7..5c46b4612 100644 --- a/apps/web/src/components/Milkdown/MilkdownPreview.tsx +++ b/apps/web/src/components/Milkdown/MilkdownPreview.tsx @@ -28,7 +28,11 @@ import { resolveArtifactUrl } from '@/api/artifact'; import { useLinkFollowModifierHeld } from '@/hooks/useMultiSelectModifier'; import { attachBlockDragListeners } from './blockDrag'; -import { createMilkdown, type MilkdownInstance } from './createMilkdown'; +import { + createMilkdown, + type MilkdownInstance, + type MilkdownTextSelection, +} from './createMilkdown'; import { markdownEquals, normalizeMarkdown } from './markdownUtils'; import type { MilkdownBlockDragEvent, MilkdownLinkActivation } from './types'; @@ -52,6 +56,12 @@ export interface MilkdownPreviewProps { enableBlockDrag?: boolean; /** Fires alongside Crepe's native drag handler when a block drag begins. */ onBlockDragStart?: (event: MilkdownBlockDragEvent) => void; + /** Reports only native text selections wholly inside this preview. */ + onTextSelection?: (selection: MilkdownPreviewSelection | null) => void; +} + +export interface MilkdownPreviewSelection extends MilkdownTextSelection { + position: { x: number; y: number }; } /** @@ -105,6 +115,7 @@ export function MilkdownPreview( onBlockDragStart, linkActivation = 'plain', onLinkClick, + onTextSelection, } = props; const resolvedAriaLabel = ariaLabel ?? t('editor.readOnlyContent'); const followModifierHeld = useLinkFollowModifierHeld( @@ -127,6 +138,9 @@ export function MilkdownPreview( const onLinkClickRef = useRef(onLinkClick); onLinkClickRef.current = onLinkClick; const hasLinkCallback = !!onLinkClick; + const onTextSelectionRef = useRef(onTextSelection); + onTextSelectionRef.current = onTextSelection; + const reportsTextSelection = !!onTextSelection; useEffect(() => { let cancelled = false; @@ -203,6 +217,69 @@ export function MilkdownPreview( // Re-mount when drag mode toggles (rare, expected). }, [enableBlockDrag, linkActivation, hasLinkCallback]); + useEffect(() => { + const mountRoot = containerRef.current; + if (!reportsTextSelection || !mountRoot) return; + let frame: number | undefined; + let hasReportedSelection = false; + const report = () => { + frame = undefined; + const instance = instanceRef.current; + const native = mountRoot.ownerDocument.getSelection(); + const editor = mountRoot.querySelector('.ProseMirror'); + if ( + !instance || + !editor || + !native || + native.isCollapsed || + native.rangeCount !== 1 || + !native.anchorNode || + !native.focusNode || + !editor.contains(native.anchorNode) || + !editor.contains(native.focusNode) + ) { + hasReportedSelection = false; + onTextSelectionRef.current?.(null); + return; + } + const snapshot = instance.getTextSelection(); + const rect = instance.getSelectionClientRect(); + hasReportedSelection = !!snapshot && !!rect; + onTextSelectionRef.current?.( + snapshot && rect + ? { ...snapshot, position: { x: rect.left, y: rect.bottom } } + : null, + ); + }; + const schedule = () => { + const native = mountRoot.ownerDocument.getSelection(); + if ( + !hasReportedSelection && + !mountRoot.contains(native?.anchorNode ?? null) && + !mountRoot.contains(native?.focusNode ?? null) + ) { + return; + } + if (frame !== undefined) cancelAnimationFrame(frame); + frame = requestAnimationFrame(report); + }; + const doc = mountRoot.ownerDocument; + doc.addEventListener('selectionchange', schedule); + mountRoot.addEventListener('mouseup', schedule); + mountRoot.addEventListener('keyup', schedule); + window.addEventListener('scroll', schedule, true); + window.addEventListener('resize', schedule); + return () => { + if (frame !== undefined) cancelAnimationFrame(frame); + doc.removeEventListener('selectionchange', schedule); + mountRoot.removeEventListener('mouseup', schedule); + mountRoot.removeEventListener('keyup', schedule); + window.removeEventListener('scroll', schedule, true); + window.removeEventListener('resize', schedule); + onTextSelectionRef.current?.(null); + }; + }, [reportsTextSelection]); + useEffect(() => { if (markdownEquals(markdown, lastSyncedRef.current)) return; const next = normalizeMarkdown(markdown); diff --git a/apps/web/src/components/Milkdown/__tests__/previewAccessibility.test.tsx b/apps/web/src/components/Milkdown/__tests__/previewAccessibility.test.tsx index e699416da..7d7f51aae 100644 --- a/apps/web/src/components/Milkdown/__tests__/previewAccessibility.test.tsx +++ b/apps/web/src/components/Milkdown/__tests__/previewAccessibility.test.tsx @@ -23,6 +23,33 @@ afterEach(() => { }); describe('MilkdownPreview accessibility', () => { + it('does not remount the editor when fragment selection reporting toggles', async () => { + container = document.createElement('div'); + document.body.appendChild(container); + root = createRoot(container); + const onTextSelection = vi.fn(); + const render = (enabled: boolean) => { + act(() => { + root?.render( + , + ); + }); + }; + render(false); + await vi.waitFor(() => { + expect(container?.querySelector('.ProseMirror')).not.toBeNull(); + }); + const editor = container.querySelector('.ProseMirror'); + render(true); + expect(container.querySelector('.ProseMirror')).toBe(editor); + render(false); + expect(container.querySelector('.ProseMirror')).toBe(editor); + }); + it('keeps links hit-testable when the preview host is not', async () => { container = document.createElement('div'); document.body.appendChild(container); diff --git a/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts b/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts new file mode 100644 index 000000000..8c4597549 --- /dev/null +++ b/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts @@ -0,0 +1,78 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { afterEach, describe, expect, it } from 'vitest'; + +import { createMilkdown, type MilkdownInstance } from '../createMilkdown'; + +let instance: MilkdownInstance | undefined; +let root: HTMLDivElement | undefined; + +afterEach(async () => { + await instance?.destroy(); + root?.remove(); +}); + +async function mount(markdown: string) { + root = document.createElement('div'); + document.body.appendChild(root); + instance = await createMilkdown({ + root, + initialMarkdown: markdown, + editable: true, + previewMode: true, + toolbarMode: 'none', + }); + return instance; +} + +describe('Milkdown text selection snapshots', () => { + it('captures inline formatted text with its actual range and neighboring context', async () => { + const editor = await mount('Before **selected** after.'); + editor.__selectTextBetweenForTest?.('selected', 'selected'); + expect(editor.getTextSelection()).toMatchObject({ + text: 'selected', + contextBefore: 'Before ', + contextAfter: ' after.', + }); + expect(editor.getTextSelection()?.range).toEqual( + editor.getSelectionRange(), + ); + expect(editor.getMarkdown()).toContain('**selected**'); + }); + + it('preserves paragraph breaks and code line breaks without mutating the answer', async () => { + const editor = await mount( + 'First paragraph.\n\nSecond paragraph.\n\n```ts\nconst a = 1;\nconst b = 2;\n```\n\nEnd.', + ); + const original = editor.getMarkdown(); + editor.__selectTextBetweenForTest?.('First paragraph.', 'const b = 2;'); + expect(editor.getTextSelection()?.text).toBe( + 'First paragraph.\n\nSecond paragraph.\n\nconst a = 1;\nconst b = 2;', + ); + expect(editor.getMarkdown()).toBe(original); + }); + + it('distinguishes a repeated quote by range and surrounding text', async () => { + const editor = await mount('first same\n\nsecond same'); + editor.__selectTextBetweenForTest?.('second same', 'second same'); + expect(editor.getTextSelection()?.text).toBe('second same'); + expect(editor.getTextSelection()?.contextBefore).toContain('first same'); + }); + + it('preserves explicit line breaks within a paragraph', async () => { + const editor = await mount('First line. \nSecond line.'); + editor.__selectAllTextForTest?.(); + expect(editor.getTextSelection()?.text).toBe('First line.\nSecond line.'); + }); + + it('captures Unicode and rejects collapsed and block-node selections', async () => { + const editor = await mount('你好 👋 world.'); + editor.__selectAllTextForTest?.(); + expect(editor.getTextSelection()?.text).toBe('你好 👋 world.'); + editor.__setCursorAfterTextForTest?.('你好'); + expect(editor.getTextSelection()).toBeNull(); + editor.__selectCurrentBlockForTest?.(); + expect(editor.getTextSelection()).toBeNull(); + }); +}); diff --git a/apps/web/src/components/Milkdown/createMilkdown.ts b/apps/web/src/components/Milkdown/createMilkdown.ts index 8706482b2..9eacf4c0e 100644 --- a/apps/web/src/components/Milkdown/createMilkdown.ts +++ b/apps/web/src/components/Milkdown/createMilkdown.ts @@ -277,6 +277,13 @@ export interface MilkdownTextRange { to: number; } +export interface MilkdownTextSelection { + range: MilkdownTextRange; + text: string; + contextBefore: string; + contextAfter: string; +} + export interface MilkdownLinkState { href: string; range: MilkdownTextRange; @@ -341,6 +348,8 @@ export interface MilkdownInstance { getSelectionRange(includeEmpty?: boolean): MilkdownTextRange | null; /** Plain text in the current non-empty text selection. */ getSelectionText(): string | null; + /** Capture selected text and nearby context, preserving block separators. */ + getTextSelection(): MilkdownTextSelection | null; /** Active link under the current selection or cursor. */ getActiveLink(): MilkdownLinkState | null; /** Capture one whole link or unlinked selected text, without moving selection. */ @@ -2678,6 +2687,39 @@ export async function createMilkdown( }); return result; }, + getTextSelection: () => { + let result: MilkdownTextSelection | null = null; + crepe.editor.action((ctx) => { + const { selection, doc } = ctx.get(editorViewCtx).state; + if (selection.empty || selection instanceof NodeSelection) return; + const leafText = (node: ProseNode) => + node.type.name === 'hardbreak' ? '\n' : ''; + const text = doc.textBetween( + selection.from, + selection.to, + '\n\n', + leafText, + ); + if (!text.trim()) return; + result = { + range: { from: selection.from, to: selection.to }, + text, + contextBefore: doc.textBetween( + Math.max(0, selection.from - 40), + selection.from, + ' ', + leafText, + ), + contextAfter: doc.textBetween( + selection.to, + Math.min(doc.content.size, selection.to + 40), + ' ', + leafText, + ), + }; + }); + return result; + }, getActiveLink: () => { let result: MilkdownLinkState | null = null; crepe.editor.action((ctx) => { diff --git a/apps/web/src/i18n/resources/en/common.json b/apps/web/src/i18n/resources/en/common.json index fab7dbc61..0d5ce21c8 100644 --- a/apps/web/src/i18n/resources/en/common.json +++ b/apps/web/src/i18n/resources/en/common.json @@ -920,6 +920,12 @@ "addAsNote": "Add as note", "copyMessage": "Copy message", "copy": "Copy", + "fragmentComment": "Comment", + "fragmentCommentPlaceholder": "What would you like to say about this passage?", + "addCommentToInput": "Add to input", + "fragmentQuoteLabel": "Quote from an earlier reply:", + "fragmentCommentLabel": "Comment:", + "fragmentContextLabel": "Nearby context ([…] marks the quoted passage):", "thinking": "Thinking…", "plan": "Plan", "copyPlan": "Copy plan", diff --git a/apps/web/src/i18n/resources/zh-CN/common.json b/apps/web/src/i18n/resources/zh-CN/common.json index b141fa021..5098e1f00 100644 --- a/apps/web/src/i18n/resources/zh-CN/common.json +++ b/apps/web/src/i18n/resources/zh-CN/common.json @@ -920,6 +920,12 @@ "addAsNote": "添加为笔记", "copyMessage": "复制消息", "copy": "复制", + "fragmentComment": "评论", + "fragmentCommentPlaceholder": "你想对这段内容说什么？", + "addCommentToInput": "加入输入框", + "fragmentQuoteLabel": "前面回答中的引用：", + "fragmentCommentLabel": "评论：", + "fragmentContextLabel": "邻近上下文（[…] 表示被引用的片段）：", "thinking": "正在思考…", "plan": "计划", "copyPlan": "复制计划", diff --git a/apps/web/src/pages/playground/ChatPerformancePlaygroundPage.tsx b/apps/web/src/pages/playground/ChatPerformancePlaygroundPage.tsx index e1a9e9e82..7a002876d 100644 --- a/apps/web/src/pages/playground/ChatPerformancePlaygroundPage.tsx +++ b/apps/web/src/pages/playground/ChatPerformancePlaygroundPage.tsx @@ -8,6 +8,7 @@ import { MessageList } from '@/components/Messages/MessageList'; import { ThreadChatInput } from '@/components/Panels/ChatPanel/ThreadChatInput'; import { selectRetainedPreviewTabs } from '@/components/Panels/PreviewWorkspace/retainedPreviewTabs'; import { ChatSessionProvider } from '@/hooks/useChatSession'; +import { useChatStore } from '@/store/chatStore'; import { activateTab } from '@/store/previewWorkspace/model'; import type { ChatMessage } from '@/store/chatTypes'; @@ -173,6 +174,7 @@ function ActivationPanel({ recentTurnCount: number | undefined; }) { const [mountId] = useState(() => crypto.randomUUID()); + const [submittedDraft, setSubmittedDraft] = useState(''); const session = useMemo( () => ({ ...SESSION, threadId: `activation-fixture-${tabId}` }), [tabId], @@ -185,6 +187,7 @@ function ActivationPanel({ data-mount-id={mountId} data-activation-id={activationId} data-cached-messages={thread.messages.length} + data-submitted-draft={submittedDraft} className="flex min-h-0 flex-1 flex-col" >
- + { + event.preventDefault(); + setSubmittedDraft(draft); + useChatStore.getState().setDraft(session.threadId, ''); + }} + onStop={NOOP} + mode="ask" + />
diff --git a/docs/architecture/agent-context.md b/docs/architecture/agent-context.md index b5fa3157c..e4d2d9d44 100644 --- a/docs/architecture/agent-context.md +++ b/docs/architecture/agent-context.md @@ -101,6 +101,8 @@ The envelope splits "where the user pointed this turn" into orthogonal parts ([e Key differences: **selection / anchor point at existing canvas nodes** (enriched with a `preview` via node-ref; content via tools); **attachment is a one-off off-canvas asset** (content inlined directly). Anchor is "a single focus point + neighbourhood"; selection is "a set of node metadata". +Chat fragment comments are distinct from all three Canvas pointing signals. The browser captures selected visible assistant text and neighboring context, then renders a quotation-plus-comment template into the owning thread's ordinary input draft on explicit **Add to input**. These templates become normal user text only when the user sends; they introduce no wire field, annotation sidecar, prompt-rewrite operation or permanent preference. Quoted response content is context, not an invoked slash command or elevated instruction. The existing text submission, binding/mode, attachment, permission and Stop behavior remains authoritative. A quotation is a capture-time snapshot, not a live reference: later source edits or message identity reconciliation do not remap the quote. See [Preview Workspace](./preview-workspace.md#1-ownership-boundaries) for editing, template language and draft lifetime. + ### 4.1 Anchored conversation ownership The web retains `AgentConversationView` for anchored Question conversations. Its `presentationAnchor` and `conversationOwner` identify the same Canvas and node, with the owner also carrying `threadId`. Validation requires that Canvas to be active and the live Question's thread to match. Legacy World `nodeRef` presentation and its source-reference resolver are removed; a Space Preview cannot open a source-owned conversation in the host Canvas. diff --git a/docs/architecture/note-node.md b/docs/architecture/note-node.md index 66123c585..0ba3aef30 100644 --- a/docs/architecture/note-node.md +++ b/docs/architecture/note-node.md @@ -153,6 +153,8 @@ An anchor's `javascript:` URL can only be activated by a click — browsers refu ## 7. Note-specific behaviours +The shared `MilkdownPreview` optionally reports native text-selection snapshots for Chat fragment comments. Reports require both selection endpoints inside the same ProseMirror surface; selected text preserves paragraph separators and code line breaks and includes its ProseMirror range and short neighboring context. This callback does not change Note editing, link activation, block drag or provenance behavior. Chat owns the Comment editor and input insertion; Note previews do not enable this callback. + These exist only for notes, and none of them are guessable from the node model above. When a later agent rewrite restores a modified block to its original user-owned baseline, its pending `modified` provenance record is removed. The first edit saves the full-document normalized block fingerprint as `baselineKey`, without a duplicate occurrence suffix, and later edits retain it alongside `baselineMarkdown`. This preserves reference-link and reference-image identity even though the stored Markdown fragment omits document-level definitions. Legacy records without `baselineKey` retain best-effort fragment comparison; missing original definitions cannot be reconstructed reliably, so those records may retain a pending marker. Other pending records and operation history are unchanged. diff --git a/docs/architecture/preview-workspace.md b/docs/architecture/preview-workspace.md index a06daa283..2ff090069 100644 --- a/docs/architecture/preview-workspace.md +++ b/docs/architecture/preview-workspace.md @@ -24,6 +24,10 @@ Newest-page refreshes after reconnect or stream completion merge from stable ser Within a mounted Chat renderer, the thread-scoped composer owns the draft subscription. Draft updates therefore rerender the composer without invalidating `MessageList`; unchanged historical message cards are memoized, while message-array updates and streaming changes continue through the history tree normally. +Completed, loaded assistant text supports fragment comments in the active Chat. A native text selection may span lines or paragraphs within one Milkdown text segment, but never separate messages or tool/thinking surfaces. Comment opens an editor with a capture-time quotation; its sole confirmation is **Add to input**, with Cancel and empty-comment prevention. Selection, comment editing and insertion never invoke generation. Add to input appends a readable quote/context/comment template to the latest draft of the owning thread, preserves existing text, closes the editor and requests that thread's composer focus. The input is the only editing and review authority after insertion; several comments and free-form instructions can be combined before ordinary Send. + +Each comment selects its template language independently: Han characters choose Chinese, otherwise ASCII letters choose English, otherwise the current UI language chooses the Chinese or English template. Original quotations and comments are never translated. The source message/segment, ProseMirror range and short neighboring context are transient capture data, not permanent annotation identities or raw Markdown offsets. Source changes and live/history ID reconciliation never rewrite inserted text or block Send. There is no separate saved-comment list, emitted-state tracking, two-way synchronization or durable annotation store. Unsent templates are ordinary runtime drafts and disappear on reload/cache eviction; sent templates follow existing transcript persistence and provider/harness handling. + `panelStore` owns and persists the outer right-column collapse state, owns the transient Preview fullscreen state, and owns thread-addressed composer focus requests. Opening a Preview target expands the right column; closing a tab does not delete its underlying node or conversation history. `MainLayout` treats the persisted collapse state as authoritative whenever no panel motion is active. A settled collapsed slot is zero-width and clips overflow, while an active open/close motion temporarily releases that clipping; interrupted startup hydration therefore cannot leave translated panel content visible over the Canvas in either persisted state. Fullscreen is intentionally not persisted across reloads. ```text From 24eaf878d40af401ed3d2887cd1d8182c478b753 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Sun, 11 Oct 2026 16:17:11 +0000 Subject: [PATCH 19/36] feat(chat): unify selected response promotion actions Add Copy and Add as note alongside Comment in the selected-text popover. Preserve selected Markdown with the canonical Milkdown serializer, retain whole-response actions, and cover clipboard, note payload and browser interactions. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/web/e2e/fragment-feedback.spec.ts | 36 +++++++++ .../AIMessage/FragmentCommentPopover.tsx | 73 ++++++++++++++++--- .../MilkdownMessageCard.comments.test.tsx | 64 +++++++++++++++- .../AIMessage/MilkdownMessageCard.tsx | 12 +++ .../AIMessage/fragmentComment.test.ts | 1 + .../Milkdown/__tests__/textSelection.test.ts | 42 +++++++++++ .../src/components/Milkdown/createMilkdown.ts | 6 ++ apps/web/src/i18n/resources/en/common.json | 1 + apps/web/src/i18n/resources/zh-CN/common.json | 1 + docs/architecture/note-node.md | 2 +- docs/architecture/preview-workspace.md | 2 + 11 files changed, 225 insertions(+), 15 deletions(-) diff --git a/apps/web/e2e/fragment-feedback.spec.ts b/apps/web/e2e/fragment-feedback.spec.ts index 1ccf51ba0..78355ca06 100644 --- a/apps/web/e2e/fragment-feedback.spec.ts +++ b/apps/web/e2e/fragment-feedback.spec.ts @@ -122,6 +122,42 @@ test('collects inline and cross-paragraph comments, edits input and explicitly s await expect(composer).toHaveValue(''); }); +test('offers three selection icons and copies only the selected text while retaining whole-response actions', async ({ + page, +}) => { + await page.context().grantPermissions(['clipboard-read', 'clipboard-write']); + const composer = panel(page).locator('textarea[name="agent-message"]'); + await composer.fill('Unchanged draft'); + const wholeNoteActions = panel(page).getByRole('button', { + name: 'Add as note', + exact: true, + }); + const originalCount = await wholeNoteActions.count(); + const answer = panel(page) + .locator('[data-chat-message-id="a-turn-3-tool"] .ProseMirror') + .last(); + await answer.locator('strong').dblclick(); + const commentButton = page.getByRole('button', { + name: 'Comment', + exact: true, + }); + await expect(commentButton).toBeVisible(); + await commentButton.hover(); + await expect(page.getByRole('tooltip')).toContainText('Comment'); + await expect( + page.getByRole('button', { name: 'Add as note', exact: true }), + ).toHaveCount(originalCount + 1); + const selectionCopy = page.getByLabel('Copy', { exact: true }); + await selectionCopy.click(); + await expect + .poll(() => page.evaluate(() => navigator.clipboard.readText())) + .toBe('cached'); + await expect(commentButton).toHaveCount(0); + await expect(wholeNoteActions).toHaveCount(originalCount); + await expect(composer).toHaveValue('Unchanged draft'); + await expect(answer.locator('strong')).toHaveText('cached'); +}); + test('supports code and keyboard selection and does not change the original answer', async ({ page, }) => { diff --git a/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx b/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx index 0fc646134..45fbb4dad 100644 --- a/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx +++ b/apps/web/src/components/Messages/AIMessage/FragmentCommentPopover.tsx @@ -1,12 +1,14 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +import { Copy, MessageSquare } from 'lucide-react'; import { useRef, useState } from 'react'; import { useTranslation } from 'react-i18next'; import { Button } from '@/components/Common/Button'; import { Popover } from '@/components/Common/Popover'; import { TextInput } from '@/components/Common/TextInput'; +import { NODE_ICON } from '@/config/nodeIcons'; import type { MilkdownPreviewSelection } from '@/components/Milkdown/MilkdownPreview'; @@ -14,6 +16,8 @@ interface FragmentCommentPopoverProps { selection: MilkdownPreviewSelection; onBegin: () => void; onAdd: (comment: string) => void; + onCopy: () => Promise; + onSaveAsNote: () => void; onDismiss: () => void; } @@ -21,12 +25,17 @@ export function FragmentCommentPopover({ selection, onBegin, onAdd, + onCopy, + onSaveAsNote, onDismiss, }: FragmentCommentPopoverProps) { const { t } = useTranslation(); const [editing, setEditing] = useState(false); const [comment, setComment] = useState(''); + const [copyError, setCopyError] = useState(false); + const [copying, setCopying] = useState(false); const inputRef = useRef(null); + const NoteIcon = NODE_ICON.note; return ( ) : ( - + <> +
+ + + +
+ {copyError ? ( +

+ {t('messages.fragmentCopyFailed')} +

+ ) : null} + )} ); diff --git a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx index d743ecd88..9f47fa340 100644 --- a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx +++ b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.comments.test.tsx @@ -8,12 +8,14 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { i18n } from '@/i18n'; import { selectThreadDraft, useChatStore } from '@/store/chatStore'; import { usePanelStore } from '@/store/panelStore'; +import { copyToClipboard } from '@/utils/io/clipboard'; import { MilkdownMessageCard } from './MilkdownMessageCard'; import type { MilkdownPreviewSelection } from '@/components/Milkdown/MilkdownPreview'; const preview = vi.hoisted(() => ({ + addNode: vi.fn(), onTextSelection: undefined as | ((selection: MilkdownPreviewSelection | null) => void) | undefined, @@ -29,13 +31,20 @@ vi.mock('@/components/Milkdown', () => ({ }, })); vi.mock('@/store/canvasStore', () => ({ - default: (selector: (state: { canvasId: string | null }) => unknown) => - selector({ canvasId: null }), + default: Object.assign( + (selector: (state: { canvasId: string | null }) => unknown) => + selector({ canvasId: null }), + { getState: () => ({ addNode: preview.addNode }) }, + ), +})); +vi.mock('@/utils/io/clipboard', () => ({ + copyToClipboard: vi.fn().mockResolvedValue(undefined), })); const selection: MilkdownPreviewSelection = { range: { from: 1, to: 8 }, text: 'selected\n\npassage', + markdown: '**selected**\n\npassage', contextBefore: 'Before ', contextAfter: ' after', position: { x: 20, y: 20 }, @@ -45,6 +54,8 @@ let host: HTMLDivElement; beforeEach(async () => { await i18n.changeLanguage('en'); + preview.addNode.mockClear(); + vi.mocked(copyToClipboard).mockReset().mockResolvedValue(undefined); useChatStore.setState({ threadsById: {} }); host = document.createElement('div'); document.body.appendChild(host); @@ -70,7 +81,9 @@ function render(enabled = true, content = 'Original answer') { } function button(name: string) { const found = [...document.querySelectorAll('button')].find( - (item) => item.textContent?.trim() === name, + (item) => + item.textContent?.trim() === name || + item.getAttribute('aria-label') === name, ); if (!found) throw new Error(`Missing button: ${name}`); return found; @@ -100,6 +113,51 @@ function select() { } describe('AI response comments', () => { + it('copies only the selected plain text without writing a note or changing the draft', async () => { + useChatStore.getState().setDraft('thread-a', 'Keep my draft.'); + render(); + act(() => preview.onTextSelection?.(selection)); + await act(async () => button('Copy').click()); + expect(copyToClipboard).toHaveBeenCalledExactlyOnceWith(selection.text); + expect(preview.addNode).not.toHaveBeenCalled(); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toBe( + 'Keep my draft.', + ); + expect(document.querySelector('button[aria-label="Comment"]')).toBeNull(); + }); + + it('surfaces clipboard failures and allows retrying the same snapshot', async () => { + vi.mocked(copyToClipboard).mockRejectedValueOnce( + new Error('Clipboard unavailable'), + ); + render(); + act(() => preview.onTextSelection?.(selection)); + await act(async () => button('Copy').click()); + expect(document.querySelector('[role="alert"]')?.textContent).toContain( + 'Could not copy', + ); + expect(button('Copy').disabled).toBe(false); + await act(async () => button('Copy').click()); + expect(copyToClipboard).toHaveBeenCalledTimes(2); + expect(document.querySelector('[role="alert"]')).toBeNull(); + }); + + it('saves the selected Markdown with the same note origin as the whole-response action', () => { + render(); + act(() => preview.onTextSelection?.(selection)); + click('Add as note'); + expect(preview.addNode).toHaveBeenCalledExactlyOnceWith({ + nodeType: 'note', + data: { + content: selection.markdown, + origin: { type: 'user-from-chat', threadId: 'thread-a' }, + }, + }); + expect(copyToClipboard).not.toHaveBeenCalled(); + expect(selectThreadDraft(useChatStore.getState(), 'thread-a')).toBe(''); + expect(document.querySelector('button[aria-label="Comment"]')).toBeNull(); + }); + it('opens a snapshot editor, requires a comment and cancels without changing the draft', () => { render(); select(); diff --git a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx index d9e9d23c6..aad2f042f 100644 --- a/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx +++ b/apps/web/src/components/Messages/AIMessage/MilkdownMessageCard.tsx @@ -14,6 +14,7 @@ import { MilkdownPreview } from '@/components/Milkdown'; import useCanvasStore from '@/store/canvasStore'; import { selectThreadDraft, useChatStore } from '@/store/chatStore'; import { usePanelStore } from '@/store/panelStore'; +import { copyToClipboard } from '@/utils/io/clipboard'; import { setDragPayload } from '@/utils/io/dragDrop'; import { openDocumentLink } from '@/utils/openDocumentLink'; @@ -160,6 +161,17 @@ export const MilkdownMessageCard = memo(function MilkdownMessageCard({ {enableComments && messageId && selection ? ( copyToClipboard(selection.text)} + onSaveAsNote={() => { + useCanvasStore.getState().addNode({ + nodeType: 'note', + data: { + content: selection.markdown, + origin: { type: 'user-from-chat', threadId }, + }, + }); + dismissComment(); + }} onBegin={() => { editingRef.current = true; }} diff --git a/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts b/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts index 4a91f18f2..25e902cb6 100644 --- a/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts +++ b/apps/web/src/components/Messages/AIMessage/fragmentComment.test.ts @@ -16,6 +16,7 @@ const fragment: FragmentComment = { segmentIndex: 0, range: { from: 1, to: 8 }, text: 'one\n\ntwo', + markdown: 'one\n\ntwo', contextBefore: '', contextAfter: '', comment: 'Keep this.', diff --git a/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts b/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts index 8c4597549..099a6a79f 100644 --- a/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts +++ b/apps/web/src/components/Milkdown/__tests__/textSelection.test.ts @@ -32,6 +32,7 @@ describe('Milkdown text selection snapshots', () => { editor.__selectTextBetweenForTest?.('selected', 'selected'); expect(editor.getTextSelection()).toMatchObject({ text: 'selected', + markdown: '**selected**\n', contextBefore: 'Before ', contextAfter: ' after.', }); @@ -41,6 +42,47 @@ describe('Milkdown text selection snapshots', () => { expect(editor.getMarkdown()).toContain('**selected**'); }); + it.each([ + ['Before **selected** after.', 'lect', 'lect', '**lect**'], + [ + 'Before [selected](https://example.com) after.', + 'lect', + 'lect', + '[lect](https://example.com)', + ], + [ + '- First item\n- Second **item**\n- Third item\n\nEnd.', + 'Second', + 'item', + '* Second **item**', + ], + [ + '```ts\nconst first = 1;\nconst second = 2;\n```\n\nEnd.', + 'const second', + '2;', + '```ts\nconst second = 2;\n```', + ], + ])( + 'serializes only the selected Markdown in %s', + async (source, from, to, expected) => { + const editor = await mount(source); + const original = editor.getMarkdown(); + editor.__selectTextBetweenForTest?.(from, to); + expect(editor.getTextSelection()?.markdown).toBe(`${expected}\n`); + expect(editor.getMarkdown()).toBe(original); + }, + ); + + it('preserves cross-paragraph Markdown without including unselected boundary text', async () => { + const editor = await mount( + 'Before **first**.\n\nSecond [link](https://example.com) after.', + ); + editor.__selectTextBetweenForTest?.('first', 'link'); + expect(editor.getTextSelection()?.markdown).toBe( + '**first**.\n\nSecond [link](https://example.com)\n', + ); + }); + it('preserves paragraph breaks and code line breaks without mutating the answer', async () => { const editor = await mount( 'First paragraph.\n\nSecond paragraph.\n\n```ts\nconst a = 1;\nconst b = 2;\n```\n\nEnd.', diff --git a/apps/web/src/components/Milkdown/createMilkdown.ts b/apps/web/src/components/Milkdown/createMilkdown.ts index 9eacf4c0e..8f862da91 100644 --- a/apps/web/src/components/Milkdown/createMilkdown.ts +++ b/apps/web/src/components/Milkdown/createMilkdown.ts @@ -280,6 +280,7 @@ export interface MilkdownTextRange { export interface MilkdownTextSelection { range: MilkdownTextRange; text: string; + markdown: string; contextBefore: string; contextAfter: string; } @@ -2701,9 +2702,14 @@ export async function createMilkdown( leafText, ); if (!text.trim()) return; + const slice = doc.slice(selection.from, selection.to, true); + const markdown = ctx.get(serializerCtx)( + doc.type.create(null, slice.content), + ); result = { range: { from: selection.from, to: selection.to }, text, + markdown, contextBefore: doc.textBetween( Math.max(0, selection.from - 40), selection.from, diff --git a/apps/web/src/i18n/resources/en/common.json b/apps/web/src/i18n/resources/en/common.json index 0d5ce21c8..bc3e6549d 100644 --- a/apps/web/src/i18n/resources/en/common.json +++ b/apps/web/src/i18n/resources/en/common.json @@ -921,6 +921,7 @@ "copyMessage": "Copy message", "copy": "Copy", "fragmentComment": "Comment", + "fragmentCopyFailed": "Could not copy the selected text. Please try again.", "fragmentCommentPlaceholder": "What would you like to say about this passage?", "addCommentToInput": "Add to input", "fragmentQuoteLabel": "Quote from an earlier reply:", diff --git a/apps/web/src/i18n/resources/zh-CN/common.json b/apps/web/src/i18n/resources/zh-CN/common.json index 5098e1f00..cedb755f5 100644 --- a/apps/web/src/i18n/resources/zh-CN/common.json +++ b/apps/web/src/i18n/resources/zh-CN/common.json @@ -921,6 +921,7 @@ "copyMessage": "复制消息", "copy": "复制", "fragmentComment": "评论", + "fragmentCopyFailed": "无法复制所选文字，请重试。", "fragmentCommentPlaceholder": "你想对这段内容说什么？", "addCommentToInput": "加入输入框", "fragmentQuoteLabel": "前面回答中的引用：", diff --git a/docs/architecture/note-node.md b/docs/architecture/note-node.md index 0ba3aef30..14cb53ef8 100644 --- a/docs/architecture/note-node.md +++ b/docs/architecture/note-node.md @@ -153,7 +153,7 @@ An anchor's `javascript:` URL can only be activated by a click — browsers refu ## 7. Note-specific behaviours -The shared `MilkdownPreview` optionally reports native text-selection snapshots for Chat fragment comments. Reports require both selection endpoints inside the same ProseMirror surface; selected text preserves paragraph separators and code line breaks and includes its ProseMirror range and short neighboring context. This callback does not change Note editing, link activation, block drag or provenance behavior. Chat owns the Comment editor and input insertion; Note previews do not enable this callback. +The shared `MilkdownPreview` optionally reports native text-selection snapshots for Chat selection actions. Reports require both selection endpoints inside the same ProseMirror surface; selected text preserves paragraph separators and code line breaks and includes its ProseMirror range, selected Markdown and short neighboring context. Markdown is serialized through the existing Milkdown serializer from a document slice with enclosing parents, preserving selected inline marks and block/list/code structure without unselected text. This callback does not change Note editing, link activation, block drag or provenance behavior. Chat owns Copy, Add as note and the Comment editor/input insertion; Note previews do not enable this callback. These exist only for notes, and none of them are guessable from the node model above. diff --git a/docs/architecture/preview-workspace.md b/docs/architecture/preview-workspace.md index 2ff090069..c31b262e3 100644 --- a/docs/architecture/preview-workspace.md +++ b/docs/architecture/preview-workspace.md @@ -26,6 +26,8 @@ Within a mounted Chat renderer, the thread-scoped composer owns the draft subscr Completed, loaded assistant text supports fragment comments in the active Chat. A native text selection may span lines or paragraphs within one Milkdown text segment, but never separate messages or tool/thinking surfaces. Comment opens an editor with a capture-time quotation; its sole confirmation is **Add to input**, with Cancel and empty-comment prevention. Selection, comment editing and insertion never invoke generation. Add to input appends a readable quote/context/comment template to the latest draft of the owning thread, preserves existing text, closes the editor and requests that thread's composer focus. The input is the only editing and review authority after insertion; several comments and free-form instructions can be combined before ordinary Send. +The selection popover offers **Copy**, **Add as note**, and **Comment** as icon buttons with localized tooltips and accessible names. Copy writes only the selected plain text and reports clipboard failures with retry available. Add as note serializes only the selected ProseMirror slice as Markdown, retaining marks, links and enclosing block/list/code structure, then uses the same `canvasStore.addNode` path and `user-from-chat` thread origin as the whole-response action. Neither action adds neighboring context or comments, modifies the source, changes the input draft, or invokes generation. Successful copy or note creation dismisses the popover. The existing response-bottom Copy and Add as note buttons remain unchanged and still act on the entire visible response. + Each comment selects its template language independently: Han characters choose Chinese, otherwise ASCII letters choose English, otherwise the current UI language chooses the Chinese or English template. Original quotations and comments are never translated. The source message/segment, ProseMirror range and short neighboring context are transient capture data, not permanent annotation identities or raw Markdown offsets. Source changes and live/history ID reconciliation never rewrite inserted text or block Send. There is no separate saved-comment list, emitted-state tracking, two-way synchronization or durable annotation store. Unsent templates are ordinary runtime drafts and disappear on reload/cache eviction; sent templates follow existing transcript persistence and provider/harness handling. `panelStore` owns and persists the outer right-column collapse state, owns the transient Preview fullscreen state, and owns thread-addressed composer focus requests. Opening a Preview target expands the right column; closing a tab does not delete its underlying node or conversation history. `MainLayout` treats the persisted collapse state as authoritative whenever no panel motion is active. A settled collapsed slot is zero-width and clips overflow, while an active open/close motion temporarily releases that clipping; interrupted startup hydration therefore cannot leave translated panel content visible over the Canvas in either persisted state. Fullscreen is intentionally not persisted across reloads. From 07ab242f79150c78803ba1711bbd54dd73de39e9 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 05:29:09 +0000 Subject: [PATCH 20/36] feat(agentlet): add explicit immutable agent bootstrap environment Validate generic bootstrap and session conflicts at the final child env merge, remove the implicit reachback directory, and report rejected control handshakes with a failing exit status. Preserve the existing SDK until its coordinated host migration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 23 +++- .../packages/local/src/agent-process.ts | 7 +- .../agentlet/packages/local/src/agentlet.ts | 107 +++++++++--------- .../packages/local/src/bootstrap-env.ts | 87 ++++++++++++++ external/agentlet/packages/local/src/cli.ts | 9 ++ .../local/tests/agent-process.test.ts | 7 ++ .../packages/local/tests/agentlet.test.ts | 14 ++- .../local/tests/bootstrap-env.test.ts | 103 +++++++++++++++++ .../local/tests/daemon-integration.test.ts | 56 ++++++++- .../packages/protocol/src/messages.ts | 3 +- external/agentlet/spec/agent-reachback.md | 26 +++-- external/agentlet/spec/protocol.md | 4 +- 12 files changed, 364 insertions(+), 82 deletions(-) create mode 100644 external/agentlet/packages/local/src/bootstrap-env.ts create mode 100644 external/agentlet/packages/local/tests/bootstrap-env.test.ts diff --git a/external/agentlet/README.md b/external/agentlet/README.md index 3a61ddffb..fbb945fb1 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -44,8 +44,7 @@ The remote host supplies the Gateway WebSocket URL and authentication token: ```bash agentlet daemon \ - --server "wss://host.example/api/bridge" \ - --token "$AGENTLET_TOKEN" + --server "wss://host.example/api/bridge" ``` For local development only, `ws://` can be enabled explicitly: @@ -53,7 +52,6 @@ For local development only, `ws://` can be enabled explicitly: ```bash agentlet daemon \ --server "ws://127.0.0.1:3001/api/bridge" \ - --token "development-token" \ --allow-insecure ``` @@ -68,6 +66,9 @@ Important options: | `--heartbeat ` | WebSocket ping interval; `0` disables heartbeats. | | `--log-level ` | `debug`, `info`, `warn`, or `error`. | | `--log-file ` | Optional JSON-lines log destination. | +| `--env-inject ` | Repeatable non-secret, opaque bootstrap value forwarded to every spawned agent. | + +Set `AGENTLET_TOKEN` in the daemon's environment before running these examples. The generic `--token` option remains available, but environment credentials avoid putting the token in process arguments. A rejected control handshake exits nonzero; an ordinary shutdown exits zero. The control and session connections use the same `agentletId`. Each spawned ACP session has its own `sessionId` and WebSocket, so control-channel and session-channel failures remain independent. The machine control channel reconnects automatically; a closed session channel stops that session's relay and is not automatically reconnected. @@ -114,13 +115,25 @@ The complete daemon/Gateway wire behavior is documented in [`spec/protocol.md`]( ## Agent Reachback -The host may push scripts or other resources through `server/sendResource`. The daemon resolves destinations against its environment registry, writes the resource locally, and injects the same environment into spawned processes. +The host may push scripts or other resources through `server/sendResource`. The daemon interpolates destinations against its explicit bootstrap map, writes the resource locally, and injects that map into spawned processes. It does not provision a default reachback directory or infer bootstrap values from its ambient environment. + +```bash +agentlet daemon --server "wss://host.example/api/bridge" \ + --env-inject TOOL_ENTRY="/device/tools/entry.js" \ + --env-inject AGENTLET_REACHBACK_DIR="/device/resources" +``` + +The bootstrap map defaults to empty. The equivalent programmatic option is `bootstrapEnv`. Values are copied and frozen at construction, split at the first `=` by the CLI, and remain opaque: spaces, empty values, additional equals signs, and relative paths are preserved without expansion or path resolution. Keys must match `[A-Za-z_][A-Za-z0-9_]*`; NUL, duplicate keys, and `AGENTLET_TOKEN` declarations are rejected without printing values. Do not pass credentials through `--env-inject`, because arguments are visible to other processes. + +Bootstrap overrides inherited values. A session that declares any bootstrap key or `AGENTLET_TOKEN` is rejected before process launch, even if its value is identical. Windows matching is case-insensitive and the final child environment removes inherited case variants; Unix matching is case-sensitive. Ordinary session values, including `AGENTLET_SERVER`, retain their override behavior. This protects launch configuration, not the executing agent's ability to change its own environment. + +Hosts previously relying on automatic `AGENTLET_REACHBACK_DIR` must supply it explicitly; ambient values are no longer an interpolation registry and no path is automatically resolved. The standard environment includes: | Variable | Purpose | | --- | --- | -| `AGENTLET_REACHBACK_DIR` | Directory containing host-provided resources. | +| `AGENTLET_REACHBACK_DIR` | Optional host-defined bootstrap value, with no built-in default or path interpretation. | | `AGENTLET_SERVER` | Gateway URL supplied to the daemon. | | `AGENTLET_TOKEN` | Authentication token available to host-provided reachback tools. | | `AGENTLET_SERVICE_SDK_URL` | Daemon-owned absolute `file://` URL used by Service Package entries to lease current configuration through the ESM Service SDK published under `dist/service-sdk`. | diff --git a/external/agentlet/packages/local/src/agent-process.ts b/external/agentlet/packages/local/src/agent-process.ts index c8712148c..75ec26211 100644 --- a/external/agentlet/packages/local/src/agent-process.ts +++ b/external/agentlet/packages/local/src/agent-process.ts @@ -5,7 +5,8 @@ import { EventEmitter } from 'node:events' export interface AgentProcessOptions { command: string cwd?: string - env?: Record + env?: NodeJS.ProcessEnv + inheritEnv?: boolean } export interface AgentProcessEvents { @@ -43,7 +44,9 @@ export class AgentProcess extends EventEmitter { this.process = spawn(this.options.command, { shell: true, cwd: this.options.cwd, - env: { ...process.env, ...this.options.env }, + env: this.options.inheritEnv === false + ? this.options.env + : { ...process.env, ...this.options.env }, stdio: ['pipe', 'pipe', 'pipe'], }) diff --git a/external/agentlet/packages/local/src/agentlet.ts b/external/agentlet/packages/local/src/agentlet.ts index 6b9e921c4..cc083262c 100644 --- a/external/agentlet/packages/local/src/agentlet.ts +++ b/external/agentlet/packages/local/src/agentlet.ts @@ -1,5 +1,5 @@ import { arch, hostname, platform } from 'node:os' -import { join, resolve } from 'node:path' +import { resolve } from 'node:path' import { existsSync, mkdirSync, writeFileSync } from 'node:fs' import WebSocket from 'ws' import { @@ -31,6 +31,11 @@ import { } from './session-bootstrap.js' import type { AgentletOptions } from './cli.js' import { resolveDeviceIdentity } from './device-identity.js' +import { + createBootstrapEnv, + interpolateBootstrapDestination, + mergeAgentEnvironment, +} from './bootstrap-env.js' interface ManagedAgent { sessionId: string @@ -85,28 +90,13 @@ export class Agentlet { private readonly stopOperations = new Map>() private handshakeComplete = false - /** - * Unified env registry — all daemon-managed environment variables that - * are injected into spawned agent processes. Initialized from defaults, - * then overridden by process.env if present. Individual dirs are created - * lazily when resources are received via server/sendResource. - */ - private readonly envRegistry: Record = {} + private readonly bootstrapEnv: Readonly> constructor(options: AgentletOptions, logger: Logger) { - this.options = options + this.bootstrapEnv = createBootstrapEnv(Object.entries(options.bootstrapEnv ?? {})) + this.options = { ...options, bootstrapEnv: this.bootstrapEnv } this.logger = logger this.daemonId = resolveAgentletId(options.agentletId) - - // Well-known env vars with defaults — process.env overrides if set. - // Values are resolved to absolute paths against the daemon cwd so that - // spawned agents (which run in a different cwd) reference the same dir. - const defaults: Record = { - AGENTLET_REACHBACK_DIR: join('node_modules', '.cache', 'agentlet', 'reachback'), - } - for (const [key, fallback] of Object.entries(defaults)) { - this.envRegistry[key] = resolve(process.env[key] || fallback) - } } async start(): Promise { @@ -118,16 +108,10 @@ export class Agentlet { /** * Resolve `${ENV_VAR}` references in a destination path against - * the daemon's envRegistry. + * the explicit bootstrap environment. */ private resolveDestination(destination: string): string { - return destination.replace(/\$\{([^}]+)\}/g, (_match, varName) => { - const value = this.envRegistry[varName] - if (!value) { - throw new Error(`Unknown env var in destination: ${varName}`) - } - return value - }) + return interpolateBootstrapDestination(destination, this.bootstrapEnv) } /** @@ -233,7 +217,7 @@ export class Agentlet { if (!this.handshakeComplete && 'id' in msg && msg.id === 1) { if ('error' in msg && msg.error) { this.logger.error('handshake_failed', { code: msg.error.code, message: msg.error.message }) - this.shutdown('handshake_failed') + this.shutdown('handshake_failed', 1) return } if ('result' in msg) { @@ -382,6 +366,21 @@ export class Agentlet { } const autoRestart = sessionSpec.autoRestart ?? false + let agentEnv: NodeJS.ProcessEnv + try { + agentEnv = buildAgentProcessEnv( + this.options.server, + this.options.token, + this.bootstrapEnv, + sessionSpec.env, + ) + } catch (error) { + this.sendDaemonResponse(requestId, undefined, { + code: -32602, + message: error instanceof Error ? error.message : String(error), + }) + return + } if ( this.options.maxAgents && @@ -416,20 +415,11 @@ export class Agentlet { this.logger.info('spawning_agent', { command, cwd, sessionId: params.sessionId }) try { - // Inject daemon-managed env vars into the spawned agent process: - // - AGENTLET_SERVER: WS URL for reachback HTTP derivation - // - AGENTLET_TOKEN: daemon token used to authenticate reachback - // - envRegistry: all well-known dirs (AGENTLET_REACHBACK_DIR, etc.) - // Host env overrides defaults, except for the daemon-owned token. const agent = new AgentProcess({ command, cwd, - env: buildAgentProcessEnv( - this.options.server, - this.options.token, - this.envRegistry, - sessionSpec.env, - ), + env: agentEnv, + inheritEnv: false, }) agent.on('error', (err) => { @@ -822,7 +812,7 @@ export class Agentlet { this.reconnectTimer = setTimeout(() => this.connectDaemonControl(), backoff) } - private async shutdown(reason: string): Promise { + private async shutdown(reason: string, exitCode = 0): Promise { if (this.shutdownInProgress) return this.shutdownInProgress = true @@ -834,11 +824,11 @@ export class Agentlet { this.reconnectTimer = null } - await this.shutdownDaemon(reason) + await this.shutdownDaemon(reason, exitCode) this.logger.info('stopped', { reason }) } - private async shutdownDaemon(reason: string): Promise { + private async shutdownDaemon(reason: string, exitCode: number): Promise { // Stop all managed agents for (const [sessionId, managed] of this.agents) { this.logger.info('stopping_agent', { sessionId }) @@ -863,7 +853,7 @@ export class Agentlet { this.controlWs.close() } - process.exit(0) + process.exit(exitCode) } private waitForAgentExit(agent: AgentProcess, ms: number): Promise { @@ -892,17 +882,22 @@ export class Agentlet { export function buildAgentProcessEnv( server: string, token: string, - envRegistry: Readonly>, - sessionEnv?: Readonly>, -): Record { - return { - AGENTLET_SERVER: server, - ...envRegistry, - ...sessionEnv, - AGENTLET_TOKEN: token, - AGENTLET_SERVICE_SDK_URL: new URL( - './service-sdk/index.js', - import.meta.url, - ).href, - } + bootstrapEnv: Readonly>, + sessionEnv: Readonly> = {}, + inherited: NodeJS.ProcessEnv = process.env, + platform: NodeJS.Platform = process.platform, +): NodeJS.ProcessEnv { + return mergeAgentEnvironment( + { ...inherited, AGENTLET_SERVER: server }, + sessionEnv, + createBootstrapEnv(Object.entries(bootstrapEnv), platform), + { + AGENTLET_TOKEN: token, + AGENTLET_SERVICE_SDK_URL: new URL( + './service-sdk/index.js', + import.meta.url, + ).href, + }, + platform, + ) } diff --git a/external/agentlet/packages/local/src/bootstrap-env.ts b/external/agentlet/packages/local/src/bootstrap-env.ts new file mode 100644 index 000000000..cfe39ea65 --- /dev/null +++ b/external/agentlet/packages/local/src/bootstrap-env.ts @@ -0,0 +1,87 @@ +type Environment = Readonly> + +function canonicalKey(key: string, platform: NodeJS.Platform): string { + return platform === 'win32' ? key.toUpperCase() : key +} + +function validateEntry(key: string, value: unknown): asserts value is string { + if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) { + throw new Error('Invalid environment key') + } + if (typeof value !== 'string' || value.includes('\0')) { + throw new Error(`Invalid environment value for ${key}`) + } +} + +export function createBootstrapEnv( + entries: Iterable = [], + platform: NodeJS.Platform = process.platform, +): Readonly> { + const result: Record = {} + const keys = new Set() + for (const [key, value] of entries) { + validateEntry(key, value) + const canonical = canonicalKey(key, platform) + if (canonical === canonicalKey('AGENTLET_TOKEN', platform)) { + throw new Error(`Reserved environment key: ${key}`) + } + if (keys.has(canonical)) throw new Error(`Duplicate bootstrap environment key: ${key}`) + keys.add(canonical) + Object.defineProperty(result, key, { value, enumerable: true }) + } + return Object.freeze(result) +} + +export function parseBootstrapEnv( + declarations: readonly string[], + platform: NodeJS.Platform = process.platform, +): Readonly> { + return createBootstrapEnv(declarations.map(declaration => { + const separator = declaration.indexOf('=') + if (separator < 0) throw new Error('Environment injection requires KEY=VALUE') + return [declaration.slice(0, separator), declaration.slice(separator + 1)] as const + }), platform) +} + +export function mergeAgentEnvironment( + inherited: Environment, + session: Environment, + bootstrap: Readonly>, + authoritative: Readonly>, + platform: NodeJS.Platform = process.platform, +): NodeJS.ProcessEnv { + if (!session || typeof session !== 'object' || Array.isArray(session)) { + throw new Error('Invalid session environment') + } + const protectedKeys = new Set( + [...Object.keys(bootstrap), 'AGENTLET_TOKEN'].map(key => canonicalKey(key, platform)), + ) + for (const [key, value] of Object.entries(session)) { + validateEntry(key, value) + if (protectedKeys.has(canonicalKey(key, platform))) { + throw new Error(`Session cannot override protected environment key: ${key}`) + } + } + const result: NodeJS.ProcessEnv = {} + for (const environment of [inherited, session, authoritative, bootstrap]) { + for (const [key, value] of Object.entries(environment)) { + if (platform === 'win32') { + for (const existing of Object.keys(result)) { + if (canonicalKey(existing, platform) === canonicalKey(key, platform)) delete result[existing] + } + } + Object.defineProperty(result, key, { value, enumerable: true, configurable: true, writable: true }) + } + } + return result +} + +export function interpolateBootstrapDestination( + destination: string, + bootstrap: Readonly>, +): string { + return destination.replace(/\$\{([^}]+)\}/g, (_match, key: string) => { + if (!Object.hasOwn(bootstrap, key)) throw new Error(`Unknown bootstrap environment key: ${key}`) + return bootstrap[key]! + }) +} diff --git a/external/agentlet/packages/local/src/cli.ts b/external/agentlet/packages/local/src/cli.ts index eebfcf2d6..646062abe 100644 --- a/external/agentlet/packages/local/src/cli.ts +++ b/external/agentlet/packages/local/src/cli.ts @@ -1,4 +1,5 @@ import { Command } from 'commander' +import { parseBootstrapEnv } from './bootstrap-env.js' export interface AgentletOptions { server: string @@ -13,6 +14,7 @@ export interface AgentletOptions { agentletId?: string maxAgents: number + bootstrapEnv?: Readonly> } /** Result of parsing the generic `agentlet daemon` command. */ @@ -51,6 +53,12 @@ export function parseCli(argv: string[]): CliResult { .option('--log-file ', 'Path to write structured log output (JSON lines)') .option('--heartbeat ', 'WebSocket ping interval in seconds (0 to disable)', '30') .option('--allow-insecure', 'Allow ws:// (non-TLS) connections (local development only)', false) + .option( + '--env-inject ', + 'Opaque non-secret agent bootstrap value (repeatable)', + (value: string, previous: string[]) => [...previous, value], + [], + ) .action((opts) => { const token = opts.token || process.env['AGENTLET_TOKEN'] if (!token) { @@ -71,6 +79,7 @@ export function parseCli(argv: string[]): CliResult { logFile: opts.logFile, agentletId: opts.agentletId?.trim() || undefined, maxAgents: positiveSafeInteger(opts.maxAgents, '--max-agents'), + bootstrapEnv: parseBootstrapEnv(opts.envInject), }, } }) diff --git a/external/agentlet/packages/local/tests/agent-process.test.ts b/external/agentlet/packages/local/tests/agent-process.test.ts index f877b1f4c..833458cbe 100644 --- a/external/agentlet/packages/local/tests/agent-process.test.ts +++ b/external/agentlet/packages/local/tests/agent-process.test.ts @@ -31,4 +31,11 @@ describe('process transport selection', () => { shell: true, cwd: '/work', stdio: ['pipe', 'pipe', 'pipe'], })) }) + + it('does not reintroduce ambient values after the managed environment has been finalized', () => { + const env = { AGENTLET_TOKEN: 'authoritative', TOOL: 'entry' } + new AgentProcess({ command: 'agent --acp', env, inheritEnv: false }).start() + expect(spawn).toHaveBeenCalledWith('agent --acp', expect.objectContaining({ env })) + expect(vi.mocked(spawn).mock.calls[0]?.[1]?.env).toBe(env) + }) }) diff --git a/external/agentlet/packages/local/tests/agentlet.test.ts b/external/agentlet/packages/local/tests/agentlet.test.ts index ea01afee8..4fd9dcd76 100644 --- a/external/agentlet/packages/local/tests/agentlet.test.ts +++ b/external/agentlet/packages/local/tests/agentlet.test.ts @@ -101,6 +101,7 @@ describe('spawned agent environment', () => { 'cli-token', { AGENTLET_REACHBACK_DIR: '/tmp/reachback' }, { HUABU_RFS_URL: 'http://127.0.0.1:3001/api/rfs/canvas-1' }, + {}, ), ).toEqual({ AGENTLET_SERVER: 'ws://127.0.0.1:3001/api/acp/agent', @@ -113,13 +114,20 @@ describe('spawned agent environment', () => { }) }) - it('keeps the daemon token authoritative over host environment overrides', () => { + it('rejects a session token declaration without exposing its value', () => { + expect(() => + buildAgentProcessEnv('ws://daemon.test', 'daemon-token', {}, { + AGENTLET_TOKEN: 'host-secret', + }, {}), + ).toThrow('Session cannot override protected environment key: AGENTLET_TOKEN') + }) + + it('preserves ordinary session server overrides and the SDK until coordinated migration', () => { expect( buildAgentProcessEnv('ws://daemon.test', 'daemon-token', {}, { AGENTLET_SERVER: 'ws://host.test', - AGENTLET_TOKEN: 'host-token', AGENTLET_SERVICE_SDK_URL: 'file:///tmp/untrusted.js', - }), + }, {}), ).toMatchObject({ AGENTLET_SERVER: 'ws://host.test', AGENTLET_TOKEN: 'daemon-token', diff --git a/external/agentlet/packages/local/tests/bootstrap-env.test.ts b/external/agentlet/packages/local/tests/bootstrap-env.test.ts new file mode 100644 index 000000000..8d544d855 --- /dev/null +++ b/external/agentlet/packages/local/tests/bootstrap-env.test.ts @@ -0,0 +1,103 @@ +import { describe, expect, it } from 'vitest' +import { createBootstrapEnv, interpolateBootstrapDestination, parseBootstrapEnv } from '../src/bootstrap-env.js' +import { buildAgentProcessEnv } from '../src/agentlet.js' +import { parseCli } from '../src/cli.js' + +describe('opaque bootstrap environment', () => { + it('defaults to an empty frozen map', () => { + const result = createBootstrapEnv() + expect(result).toEqual({}) + expect(Object.isFrozen(result)).toBe(true) + }) + + it('copies values without trimming, interpolation or path resolution', () => { + const values = { ENTRY: ' relative path=a=b ', EMPTY: '', TEMPLATE: '${HOME}' } + const result = createBootstrapEnv(Object.entries(values)) + values.ENTRY = 'changed' + expect(result).toEqual({ ENTRY: ' relative path=a=b ', EMPTY: '', TEMPLATE: '${HOME}' }) + expect(Object.isFrozen(result)).toBe(true) + expect(parseBootstrapEnv(['ENTRY= a=b ', 'EMPTY='])).toEqual({ ENTRY: ' a=b ', EMPTY: '' }) + }) + + it('parses repeated CLI injections and keeps the generic default empty', () => { + const argv = ['node', 'agentlet', 'daemon', '--server', 'wss://example.test', '--token', 'token'] + expect(parseCli(argv).options.bootstrapEnv).toEqual({}) + expect(parseCli([...argv, '--env-inject', 'ENTRY= a=b ', '--env-inject', 'EMPTY=']).options.bootstrapEnv) + .toEqual({ ENTRY: ' a=b ', EMPTY: '' }) + }) + + it.each(['NO_EQUALS', '=secret', 'BAD-KEY=secret', '1KEY=secret', 'KEY=secret\0value', 'BAD\0KEY=secret', 'AGENTLET_TOKEN=secret'])( + 'rejects malformed or reserved declarations without logging values (%s)', declaration => { + let message = '' + try { parseBootstrapEnv([declaration]) } catch (error) { + message = error instanceof Error ? error.message : String(error) + } + expect(message).not.toBe('') + expect(message).not.toContain('secret') + }, + ) + + it('rejects duplicate keys and applies target-platform case rules', () => { + expect(() => parseBootstrapEnv(['KEY=a', 'KEY=b'], 'linux')).toThrow('Duplicate') + expect(() => parseBootstrapEnv(['KEY=a', 'key=b'], 'win32')).toThrow('Duplicate') + expect(parseBootstrapEnv(['KEY=a', 'key=b'], 'linux')).toEqual({ KEY: 'a', key: 'b' }) + expect(() => parseBootstrapEnv(['agentlet_token=secret'], 'win32')).toThrow('Reserved') + expect(parseBootstrapEnv(['agentlet_token=value'], 'linux')).toEqual({ agentlet_token: 'value' }) + }) + + it('supports portable keys that overlap object prototype names', () => { + const bootstrap = parseBootstrapEnv(['__proto__=opaque', 'constructor=entry']) + expect(Object.keys(bootstrap)).toEqual(['__proto__', 'constructor']) + expect(bootstrap.__proto__).toBe('opaque') + expect(interpolateBootstrapDestination('${__proto__}/${constructor}', bootstrap)).toBe('opaque/entry') + }) +}) + +describe('final child environment', () => { + it('preserves inherited toolchain, session context and opaque authoritative bootstrap', () => { + expect(buildAgentProcessEnv('ws://daemon', 'token', { TOOL: ' relative=a=b ' }, { + HUABU_RFS_URL: 'http://host/rfs/space', HUABU_THREAD_ID: 'thread', AGENTLET_SERVER: 'ws://session', + }, { PATH: '/tools', TOOL: 'ambient', AGENTLET_TOKEN: 'ambient-token' })).toMatchObject({ + PATH: '/tools', TOOL: ' relative=a=b ', AGENTLET_TOKEN: 'token', AGENTLET_SERVER: 'ws://session', + HUABU_RFS_URL: 'http://host/rfs/space', HUABU_THREAD_ID: 'thread', + }) + }) + + it.each(['bootstrap', 'token'])('rejects even an equal session declaration for %s', kind => { + const bootstrap = { TOOL: 'value' } + const session = kind === 'bootstrap' ? { TOOL: 'value' } : { AGENTLET_TOKEN: 'token' } + expect(() => buildAgentProcessEnv('ws://daemon', 'token', bootstrap, session, {})).toThrow('protected environment key') + }) + + it('normalizes authoritative keys at the final Windows merge without changing inherited input', () => { + const inherited = { PATH: '/tools', Tool: 'ambient', agentlet_token: 'ambient-token' } + const result = buildAgentProcessEnv('ws://daemon', 'token', { TOOL: 'entry' }, {}, inherited, 'win32') + expect(result).toMatchObject({ PATH: '/tools', TOOL: 'entry', AGENTLET_TOKEN: 'token' }) + expect(result).not.toHaveProperty('Tool') + expect(result).not.toHaveProperty('agentlet_token') + expect(inherited.Tool).toBe('ambient') + expect(() => buildAgentProcessEnv('ws://daemon', 'token', { TOOL: 'entry' }, { tool: 'entry' }, {}, 'win32')).toThrow('protected') + expect(() => buildAgentProcessEnv('ws://daemon', 'token', {}, { agentlet_token: 'token' }, {}, 'win32')).toThrow('protected') + }) + + it('preserves Unix case distinctions', () => { + expect(buildAgentProcessEnv('ws://daemon', 'token', { TOOL: 'entry' }, { tool: 'session' }, { Tool: 'ambient' }, 'linux')) + .toMatchObject({ TOOL: 'entry', tool: 'session', Tool: 'ambient' }) + }) + + it('does not inject a default reachback directory', () => { + expect(buildAgentProcessEnv('ws://daemon', 'token', {}, {}, {})).not.toHaveProperty('AGENTLET_REACHBACK_DIR') + }) + + it.each([{ BAD: 'value\0' }, { 'BAD-KEY': 'value' }])('validates session environment before spawning', session => { + expect(() => buildAgentProcessEnv('ws://daemon', 'token', {}, session, {})).toThrow('Invalid environment') + }) +}) + +describe('resource destination interpolation', () => { + it('uses only explicit bootstrap values, including empty strings', () => { + expect(interpolateBootstrapDestination('${ROOT}/${EMPTY}tool.js', { ROOT: ' relative ', EMPTY: '' })).toBe(' relative /tool.js') + expect(() => interpolateBootstrapDestination('${AGENTLET_REACHBACK_DIR}/tool.js', {})).toThrow('Unknown bootstrap') + expect(() => interpolateBootstrapDestination('${toString}/tool.js', {})).toThrow('Unknown bootstrap') + }) +}) diff --git a/external/agentlet/packages/local/tests/daemon-integration.test.ts b/external/agentlet/packages/local/tests/daemon-integration.test.ts index 958f92fe9..bd8d5e3e7 100644 --- a/external/agentlet/packages/local/tests/daemon-integration.test.ts +++ b/external/agentlet/packages/local/tests/daemon-integration.test.ts @@ -1,6 +1,6 @@ import { createServer, type Server } from 'node:http' import { arch, hostname, platform } from 'node:os' -import { mkdirSync, rmSync, writeFileSync } from 'node:fs' +import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs' import { randomUUID } from 'node:crypto' import { join } from 'node:path' import { @@ -67,7 +67,9 @@ describe('agentlet daemon integration', () => { fixtureDir = join(process.cwd(), `.agentlet-daemon-test-${randomUUID()}`) mkdirSync(fixtureDir) const mockAgentPath = join(fixtureDir, 'mock-acp-agent.cjs') + const envPath = join(fixtureDir, 'environment.json') writeFileSync(mockAgentPath, [ + `require('node:fs').writeFileSync(${JSON.stringify(envPath)}, JSON.stringify({ entry: process.env.TOOL_ENTRY, token: process.env.AGENTLET_TOKEN, rfs: process.env.HUABU_RFS_URL, thread: process.env.HUABU_THREAD_ID }))`, "const readline = require('node:readline')", 'const rl = readline.createInterface({ input: process.stdin })', "rl.on('line', (line) => {", @@ -128,11 +130,14 @@ describe('agentlet daemon integration', () => { }) await new Promise((resolve) => httpServer?.listen(0, '127.0.0.1', resolve)) const { port } = httpServer.address() as { port: number } + const bootstrapEnv = { TOOL_ENTRY: ' relative entry=a=b ', RESOURCE_DIR: fixtureDir } const daemon = new Agentlet({ server: `ws://127.0.0.1:${port}/api/bridge`, token: 'test-token', reconnectMax: 1, bufferLimit: 1000, heartbeat: 0, allowInsecure: true, logLevel: 'error', agentletId: 'machine-a', maxAgents: 1, + bootstrapEnv, }, new Logger('error')) + bootstrapEnv.TOOL_ENTRY = 'must-not-change' await daemon.start() await waitUntil(() => controlHello !== undefined) expect(controlHello).toMatchObject({ @@ -159,10 +164,28 @@ describe('agentlet daemon integration', () => { rootPath: fixtureDir, })).toMatchObject({ error: { code: -32602 } }) + for (const [id, env] of [[20, { TOOL_ENTRY: ' relative entry=a=b ' }], [21, { AGENTLET_TOKEN: 'test-token' }]] as const) { + expect(await request(id, ServerMethods.SPAWN, { + appId: 'invalid-env', sessionSpec: { command: `node ${JSON.stringify(mockAgentPath)}`, env }, + })).toMatchObject({ error: { code: -32602, message: expect.stringContaining('protected environment key') } }) + expect(existsSync(envPath)).toBe(false) + } + controlSocket?.send(JSON.stringify({ + jsonrpc: '2.0', method: ServerMethods.SEND_RESOURCE, + params: { destination: '${RESOURCE_DIR}/resource.txt', content: 'explicit resource' }, + })) + await waitUntil(() => existsSync(join(fixtureDir!, 'resource.txt'))) + expect(readFileSync(join(fixtureDir, 'resource.txt'), 'utf8')).toBe('explicit resource') + expect(await request(10, ServerMethods.SPAWN, { appId: 'thread-a', workloadType: 'Job', - sessionSpec: { command: `node ${JSON.stringify(mockAgentPath)}` }, + sessionSpec: { command: `node ${JSON.stringify(mockAgentPath)}`, env: { + HUABU_RFS_URL: 'http://host/rfs/space', HUABU_THREAD_ID: 'thread-a', + } }, })).toMatchObject({ result: { sessionId: 'native-bootstrap', pid: expect.any(Number) } }) + expect(JSON.parse(readFileSync(envPath, 'utf8'))).toEqual({ + entry: ' relative entry=a=b ', token: 'test-token', rfs: 'http://host/rfs/space', thread: 'thread-a', + }) expect(sessionSocket).toBeUndefined() await waitUntil(() => sessionHello !== undefined) expect(sessionHello).toMatchObject({ @@ -203,5 +226,34 @@ describe('agentlet daemon integration', () => { })).toMatchObject({ result: { sessionId: 'native-bootstrap', pid: expect.any(Number) } }) expect(await request(15, ServerMethods.STOP, { sessionId: 'native-bootstrap' })) .toMatchObject({ result: { stopped: true } }) + controlSocket?.send(JSON.stringify({ jsonrpc: '2.0', method: ServerMethods.SHUTDOWN })) + await waitUntil(() => (exitSpy?.mock.calls.length ?? 0) > 0) + expect(exitSpy).toHaveBeenCalledWith(0) }, 15_000) + + it('exits nonzero when the control handshake is rejected', async () => { + exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => undefined) as never) + httpServer = createServer() + gateway = new WebSocketServer({ server: httpServer }) + gateway.on('connection', socket => { + controlSocket = socket + socket.on('message', data => { + const message = JSON.parse(data.toString()) as JsonRpcMessage + if ('method' in message && message.method === AgentletMethods.HELLO) { + socket.send(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32000, message: 'Authentication rejected' } })) + } + }) + }) + await new Promise(resolve => httpServer?.listen(0, '127.0.0.1', resolve)) + const address = httpServer.address() + if (!address || typeof address === 'string') throw new Error('Missing test server address') + const daemon = new Agentlet({ + server: `ws://127.0.0.1:${address.port}/bridge`, token: 'test-token', + reconnectMax: 1, bufferLimit: 1000, heartbeat: 0, allowInsecure: true, + logLevel: 'error', agentletId: 'machine-a', maxAgents: 1, + }, new Logger('error')) + await daemon.start() + await waitUntil(() => (exitSpy?.mock.calls.length ?? 0) > 0) + expect(exitSpy).toHaveBeenCalledWith(1) + }) }) diff --git a/external/agentlet/packages/protocol/src/messages.ts b/external/agentlet/packages/protocol/src/messages.ts index 61ad54845..ca35f230c 100644 --- a/external/agentlet/packages/protocol/src/messages.ts +++ b/external/agentlet/packages/protocol/src/messages.ts @@ -263,7 +263,8 @@ export interface ListResult { /** * server/sendResource — push a file to the daemon for local storage. * The `destination` supports `${ENV_VAR}` interpolation against the - * daemon's env registry (e.g., `${AGENTLET_REACHBACK_DIR}/tool.mjs`). + * daemon's explicit bootstrap map (e.g., `${AGENTLET_REACHBACK_DIR}/tool.mjs` + * when that key was configured by the host). */ export interface SendResourceParams { /** Destination path with ${ENV_VAR} interpolation */ diff --git a/external/agentlet/spec/agent-reachback.md b/external/agentlet/spec/agent-reachback.md index 19a47f490..efc7987dc 100644 --- a/external/agentlet/spec/agent-reachback.md +++ b/external/agentlet/spec/agent-reachback.md @@ -59,16 +59,19 @@ flowchart LR ## 2. Environment Provisioning -When the daemon spawns an agent process, it injects a set of **well-known environment variables** so the agent (and the Reachback tool it invokes) can locate its tools and authenticate back to the host. Precedence is `AGENTLET_SERVER` < daemon `envRegistry` < `sessionSpec.env`, with `AGENTLET_TOKEN` always set from the daemon's authenticated launch options. +The daemon accepts repeatable `--env-inject KEY=VALUE` or an equivalent programmatic `bootstrapEnv` map. Bootstrap defaults to empty, is copied and frozen at construction, and is forwarded unchanged to every spawn and restart. Values are opaque: the CLI splits only at the first equals sign and does not trim, expand, or resolve them. Portable environment keys are required; NUL, duplicates, and bootstrap declarations of `AGENTLET_TOKEN` fail without exposing values. + +The final child environment combines ordinary inherited values and session overrides with authoritative bootstrap and daemon credentials. Any session declaration of a bootstrap key or `AGENTLET_TOKEN` fails before spawning, including equal values. Windows matching is case-insensitive and removes inherited case variants at the final merge; Unix is case-sensitive. `AGENTLET_SERVER` retains its ordinary session override behavior unless explicitly managed by bootstrap. Bootstrap does not change the daemon's own environment or sandbox running agents. | Variable | Provided by | Description | | -------- | ----------- | ----------- | -| `AGENTLET_REACHBACK_DIR` | daemon `envRegistry` | Absolute path to the directory where Reachback tool scripts are saved. Defaults to `node_modules/.cache/agentlet/reachback`; overridable via the daemon's `process.env`. Resolved to an absolute path so agents with a different `cwd` still find it. | +| `AGENTLET_REACHBACK_DIR` | explicit host bootstrap, if desired | Opaque host-defined location with no default, automatic path resolution, or ambient registry lookup. | | `AGENTLET_SERVER` | daemon `--server` | The daemon's control-channel WebSocket URL (e.g. `ws://127.0.0.1:3001/api/bridge`). Tools derive an HTTP base URL from this (`ws://`→`http://`, strip path) unless the host provides its own override. | | `AGENTLET_TOKEN` | daemon `--token` | Bearer token the tool attaches to every call back to the host. May double as user/session identity for per-token access scoping. | -| _host-specific_ | `sessionSpec.env` | Any additional variables the host app passes at spawn time (e.g. a workspace/document ID). These override defaults but cannot replace the daemon-owned `AGENTLET_TOKEN`. | +| _host-specific bootstrap_ | `--env-inject` or `bootstrapEnv` | Host-owned non-secret tool coordinates available to all spawned agents and resource interpolation. | +| _host-specific session context_ | `sessionSpec.env` | Workload context that may override ordinary inherited values, but cannot declare a bootstrap key or daemon token. | -The daemon maintains resource-directory variables in an `envRegistry` keyed by variable name. The registry is the single source of truth for `${ENV_VAR}` interpolation in resource destinations (§3). Spawned-agent environments combine the daemon's server URL and token with that registry and `sessionSpec.env`, so a token supplied through `--token` does not depend on also being present in the daemon process environment. +Explicit bootstrap is the only source of `${ENV_VAR}` interpolation in resource destinations (§3). Empty values are valid; missing keys, including inherited keys and object prototype names, produce a non-fatal `resource_save_failed` diagnostic. Hosts that used the former implicit reachback directory must now provide it explicitly. The existing bundled Service SDK URL remains daemon-owned until its host-side migration is delivered; it is not part of the generic bootstrap default. ## 3. Tool Distribution @@ -84,7 +87,7 @@ The host app pushes its Reachback tool(s) through the Gateway **when the agentle `server/sendResource { destination, content }` is sent on the control channel. The `destination` supports `${ENV_VAR}` interpolation against the daemon's -`envRegistry`, so the host references the well-known dir without knowing its +explicit bootstrap map, so the host references its configured dir without knowing its absolute path on the remote machine: ```jsonc @@ -99,6 +102,8 @@ absolute path on the remote machine: } ``` +For this example, launch the daemon with `--env-inject AGENTLET_REACHBACK_DIR=/absolute/resource/path`. The daemon does not create or resolve a default directory. + The daemon resolves the destination, creates parent directories as needed, writes the file, and logs `resource_saved`. An unknown `${ENV_VAR}` is rejected; a write failure is logged as `resource_save_failed` (non-fatal). See @@ -112,7 +117,7 @@ is injected into every spawned agent, the agent can invoke the tool by an env-relative path without any per-host configuration: ```bash -node ${AGENTLET_REACHBACK_DIR}/ [args...] +node "${AGENTLET_REACHBACK_DIR}/" [args...] ``` `server/sendResource` is **general-purpose** — it can place any @@ -121,9 +126,7 @@ primary use today. ## 4. Transport Model (CLI-first) -The Reachback Interface standardises on **distributing a CLI script** rather -than, say, registering an MCP server, because it must work uniformly across -heterogeneous agent harnesses and support long-running, streaming operations: +The Reachback Interface supports optional CLI resource distribution without requiring it. A host may also expose language-independent HTTP access and let the agent choose its own client/runtime. Providing a script does not guarantee that the agent has the runtime required to execute it. The following comparison explains why a host might choose a CLI rather than an MCP server: | Consideration | MCP | CLI script (Reachback) | | ------------- | --- | ---------------------- | @@ -154,7 +157,7 @@ To expose Reachback, a host application must: 1. **Provide a tool script** that authenticates with `AGENTLET_TOKEN`, resolves its server base URL from `AGENTLET_SERVER` (or a host-specific override), and exposes whatever commands its agents need. -2. **Push the script on connect/reconnect** via `server/sendResource` to `${AGENTLET_REACHBACK_DIR}/` from the embedding Gateway's connection callbacks. +2. **Configure a non-secret location explicitly** through `--env-inject` or `bootstrapEnv`, then optionally push the script on connect/reconnect via `server/sendResource` to `${AGENTLET_REACHBACK_DIR}/`. 3. **Serve the endpoints** the script calls, accepting `Authorization: Bearer ${AGENTLET_TOKEN}`. 4. **(Recommended) Inject usage into the agent's system prompt** at spawn time @@ -172,6 +175,7 @@ itself. | ------- | ------ | | `server/sendResource` params | [`SendResourceParams`](../packages/protocol/src/messages.ts) | | Wire contract & timing | [`protocol.md` §9 — Resource Distribution](protocol.md#resource-distribution) | -| Env registry & spawn env | [`packages/local/src/agentlet.ts`](../packages/local/src/agentlet.ts) (`envRegistry`, `resolveDestination`, `handleSendResource`) | +| Bootstrap validation, final merge & interpolation | [`packages/local/src/bootstrap-env.ts`](../packages/local/src/bootstrap-env.ts) | +| Spawn and resource transport | [`packages/local/src/agentlet.ts`](../packages/local/src/agentlet.ts) | | Host integration (connection callbacks) | Embedding Gateway implementation | | Concrete host implementation | [Huabu — `docs/architecture/agent-reachback.md`](../../../docs/architecture/agent-reachback.md) | diff --git a/external/agentlet/spec/protocol.md b/external/agentlet/spec/protocol.md index bacb7ca94..2c1afbe80 100644 --- a/external/agentlet/spec/protocol.md +++ b/external/agentlet/spec/protocol.md @@ -162,7 +162,7 @@ The native ACP `sessionId` is established by session bootstrap and is the routin - The Gateway authenticates both control and session connections before accepting hello. - Agent commands run with the daemon process's operating-system permissions. - Both compiled known-harness commands and explicit Custom commands use the target platform shell. Known commands are built only from trusted static Definition tokens and bounded options; Custom commands are trusted control-plane input. -- Resource destinations are resolved through the daemon environment registry. +- Resource destinations interpolate only the explicit frozen daemon bootstrap map. The Custom shell spawn carries a narrowly scoped `codeql[js/command-line-injection]` annotation because executing host-authorized shell code is its intended capability, including pipelines and custom launch scripts. This is not a sanitizer, an executable allow-list, a sandbox, or proof of interactive confirmation: the host must authorize commands for the target machine and must not interpolate prompts or other untrusted content into them. Known Definitions share shell execution but compile only trusted fixed tokens and bounded options. The annotation requires compatible alert-suppression analysis and alert handling; adding it alone does not guarantee dismissal in GitHub code scanning. @@ -170,7 +170,7 @@ The Custom shell spawn carries a narrowly scoped `codeql[js/command-line-injecti `server/sendResource` runs on the machine-level control channel and carries `{ destination, content }`. -The destination may reference daemon environment variables such as `${AGENTLET_REACHBACK_DIR}`. The daemon resolves the destination, creates parent directories, writes the text content, and logs success or failure. +The destination may reference explicit bootstrap values such as `${AGENTLET_REACHBACK_DIR}` when the host configured them through `--env-inject` or `bootstrapEnv`. There is no implicit directory or ambient interpolation lookup. The daemon interpolates the destination, creates parent directories, writes the text content, and logs success or a non-fatal resource failure. Hosts should send resources when a daemon connects and repeat them after reconnect. Writes are overwrite-based and idempotent. From 58f7daca17147dc46a4c4dc6e413cee3e047f95d Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 05:29:09 +0000 Subject: [PATCH 21/36] docs: document explicit Agentlet bootstrap and reachback contract Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/architecture/agent-reachback.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 5e8057f00..01c0ae35a 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -106,6 +106,10 @@ Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent envir Agentlet additionally injects its daemon-owned `AGENTLET_SERVICE_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/service-sdk`. Session or Profile environment cannot override this value. Downloaded Service Package entries use the SDK only to obtain current configuration leases; the SDK does not discover or load Package code, and provider credentials remain absent from startup environment until an entry requests them. +Agentlet also accepts a generic, default-empty `bootstrapEnv` map or repeatable `--env-inject KEY=VALUE`. It copies and freezes opaque non-secret values at construction, without interpreting host names or resolving paths. Bootstrap overrides inherited values; sessions that declare any managed key or `AGENTLET_TOKEN` fail before process launch. Windows matching is case-insensitive and removes inherited case variants in the final child environment; Unix remains case-sensitive. Ordinary session context and `AGENTLET_SERVER` overrides retain their behavior. The currently bundled SDK is still supplied until the coordinated Huabu client-runtime migration. + +There is no automatic `AGENTLET_REACHBACK_DIR` default or ambient resource registry. Hosts can opt in by explicitly declaring that key through bootstrap. `server/sendResource` remains available and interpolates only explicit bootstrap keys, reporting missing keys or write errors as non-fatal resource diagnostics. Bootstrap does not provision Node or gate Agent startup on optional tool availability. Control handshake rejection exits nonzero; normal supervised shutdown exits zero. + Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. The guide is direct-first: an external agent can discover, query, download, snapshot, upload, execute, and verify without creating another Agent. `POST /agent` remains an optional high-level interpretation and delegation path. From afe59216758053ef99d19f6d69939c5b4f6f3ede Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 06:33:50 +0000 Subject: [PATCH 22/36] refactor(agentlet): remove host-specific Service SDK Service clients and bootstrap coordinates are now host-owned. Clear generated output on build so removed SDK files cannot linger in published dist. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- external/agentlet/README.md | 3 +- external/agentlet/packages/local/package.json | 2 +- .../agentlet/packages/local/src/agentlet.ts | 4 - .../packages/local/src/service-sdk/index.ts | 89 -------------- .../packages/local/tests/agentlet.test.ts | 7 +- .../packages/local/tests/service-sdk.test.ts | 112 ------------------ external/agentlet/spec/agent-reachback.md | 2 +- 7 files changed, 5 insertions(+), 214 deletions(-) delete mode 100644 external/agentlet/packages/local/src/service-sdk/index.ts delete mode 100644 external/agentlet/packages/local/tests/service-sdk.test.ts diff --git a/external/agentlet/README.md b/external/agentlet/README.md index fbb945fb1..1e1751931 100644 --- a/external/agentlet/README.md +++ b/external/agentlet/README.md @@ -136,11 +136,10 @@ The standard environment includes: | `AGENTLET_REACHBACK_DIR` | Optional host-defined bootstrap value, with no built-in default or path interpretation. | | `AGENTLET_SERVER` | Gateway URL supplied to the daemon. | | `AGENTLET_TOKEN` | Authentication token available to host-provided reachback tools. | -| `AGENTLET_SERVICE_SDK_URL` | Daemon-owned absolute `file://` URL used by Service Package entries to lease current configuration through the ESM Service SDK published under `dist/service-sdk`. | Agentlet transports opaque resources and environment values; it does not interpret the host-specific tool protocol. -The optional Service SDK exports `leaseService(id)` and `withServiceContext(id, callback)`. It uses host-injected reachback coordinates to obtain one version-coherent runtime context containing the validated Service Manifest and current configuration without downloading Package code or persisting credentials. Downloaded Service Package entries import the SDK through `AGENTLET_SERVICE_SDK_URL`; the daemon writes that variable after workload environment values so a session cannot replace the SDK module location. +Host-specific Service clients and SDKs are not shipped or automatically configured by Agentlet. Hosts provide their own entry coordinates through generic bootstrap. ## Repository layout diff --git a/external/agentlet/packages/local/package.json b/external/agentlet/packages/local/package.json index a521a2e6c..2e7eb9747 100644 --- a/external/agentlet/packages/local/package.json +++ b/external/agentlet/packages/local/package.json @@ -11,7 +11,7 @@ "dist" ], "scripts": { - "build": "tsc", + "build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\" && tsc", "clean": "rm -rf dist", "lint": "tsc --noEmit" }, diff --git a/external/agentlet/packages/local/src/agentlet.ts b/external/agentlet/packages/local/src/agentlet.ts index cc083262c..8941e6f35 100644 --- a/external/agentlet/packages/local/src/agentlet.ts +++ b/external/agentlet/packages/local/src/agentlet.ts @@ -893,10 +893,6 @@ export function buildAgentProcessEnv( createBootstrapEnv(Object.entries(bootstrapEnv), platform), { AGENTLET_TOKEN: token, - AGENTLET_SERVICE_SDK_URL: new URL( - './service-sdk/index.js', - import.meta.url, - ).href, }, platform, ) diff --git a/external/agentlet/packages/local/src/service-sdk/index.ts b/external/agentlet/packages/local/src/service-sdk/index.ts deleted file mode 100644 index 37f2653d7..000000000 --- a/external/agentlet/packages/local/src/service-sdk/index.ts +++ /dev/null @@ -1,89 +0,0 @@ -export interface ServiceFieldOption { - value: string - label: string -} - -export interface ServiceConfigurationField { - id: string - label: string - description?: string - type: 'text' | 'secret' | 'url' | 'boolean' | 'enum' - required: boolean - options?: ServiceFieldOption[] - placeholder?: string -} - -export interface ServiceManifest { - schema: 'huabu-service/v1' - id: string - version: string - name: string - description: string - storage: { namespace: string } - package: { files: string[] } - configuration: ServiceConfigurationField[] -} - -export interface ServiceLease { - id: string - version: string - manifest: ServiceManifest - config: Record -} - -function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { - const value = process.env[name]?.trim() - if (!value) throw new Error(`Service SDK requires ${name}`) - return value -} - -async function serviceFetch(path: string, init?: RequestInit): Promise { - const baseUrl = requiredEnvironment('HUABU_RFS_URL').replace(/\/+$/, '') - const token = requiredEnvironment('AGENTLET_TOKEN') - const response = await fetch(`${baseUrl}${path}`, { - ...init, - headers: { - Authorization: `Bearer ${token}`, - ...(init?.headers ?? {}), - }, - }) - if (!response.ok) { - throw new Error(`Service request failed (${response.status})`) - } - return response -} - -export async function leaseService(serviceId: string): Promise { - if (!/^[a-z][a-z0-9-]{0,63}$/.test(serviceId)) { - throw new Error('Invalid Service id') - } - const response = await serviceFetch( - `/services/${encodeURIComponent(serviceId)}/lease`, - { method: 'POST' }, - ) - const lease = (await response.json()) as ServiceLease - const declaredFields = new Set( - lease.manifest?.configuration?.map((field) => field.id) ?? [], - ) - if ( - lease.id !== serviceId || - typeof lease.version !== 'string' || - lease.manifest?.id !== serviceId || - lease.manifest.version !== lease.version || - !Array.isArray(lease.manifest.configuration) || - !lease.config || - typeof lease.config !== 'object' || - Array.isArray(lease.config) || - Object.keys(lease.config).some((fieldId) => !declaredFields.has(fieldId)) - ) { - throw new Error('Invalid Service lease') - } - return lease -} - -export async function withServiceContext( - serviceId: string, - run: (service: ServiceLease) => Promise | T, -): Promise { - return run(await leaseService(serviceId)) -} diff --git a/external/agentlet/packages/local/tests/agentlet.test.ts b/external/agentlet/packages/local/tests/agentlet.test.ts index 4fd9dcd76..6c50df1a5 100644 --- a/external/agentlet/packages/local/tests/agentlet.test.ts +++ b/external/agentlet/packages/local/tests/agentlet.test.ts @@ -106,9 +106,6 @@ describe('spawned agent environment', () => { ).toEqual({ AGENTLET_SERVER: 'ws://127.0.0.1:3001/api/acp/agent', AGENTLET_TOKEN: 'cli-token', - AGENTLET_SERVICE_SDK_URL: expect.stringMatching( - /\/service-sdk\/index\.js$/, - ), AGENTLET_REACHBACK_DIR: '/tmp/reachback', HUABU_RFS_URL: 'http://127.0.0.1:3001/api/rfs/canvas-1', }) @@ -122,7 +119,7 @@ describe('spawned agent environment', () => { ).toThrow('Session cannot override protected environment key: AGENTLET_TOKEN') }) - it('preserves ordinary session server overrides and the SDK until coordinated migration', () => { + it('preserves ordinary session overrides without any host-specific SDK injection', () => { expect( buildAgentProcessEnv('ws://daemon.test', 'daemon-token', {}, { AGENTLET_SERVER: 'ws://host.test', @@ -131,7 +128,7 @@ describe('spawned agent environment', () => { ).toMatchObject({ AGENTLET_SERVER: 'ws://host.test', AGENTLET_TOKEN: 'daemon-token', - AGENTLET_SERVICE_SDK_URL: expect.not.stringContaining('untrusted'), + AGENTLET_SERVICE_SDK_URL: 'file:///tmp/untrusted.js', }) }) }) diff --git a/external/agentlet/packages/local/tests/service-sdk.test.ts b/external/agentlet/packages/local/tests/service-sdk.test.ts deleted file mode 100644 index 10225a82d..000000000 --- a/external/agentlet/packages/local/tests/service-sdk.test.ts +++ /dev/null @@ -1,112 +0,0 @@ -import { afterEach, describe, expect, it, vi } from 'vitest' - -import { - leaseService, - withServiceContext, -} from '../src/service-sdk/index.js' - -const manifest = { - schema: 'huabu-service/v1', - id: 'example', - version: '1.0.0', - name: 'Example', - description: 'Example Service', - storage: { namespace: 'integration.example' }, - package: { files: ['SKILL.md', 'entry.mjs'] }, - configuration: [ - { - id: 'quality', - label: 'Quality', - type: 'enum', - required: true, - options: [{ value: 'high', label: 'high' }], - }, - { - id: 'apiKey', - label: 'API key', - type: 'secret', - required: true, - }, - ], -} as const - -afterEach(() => { - vi.unstubAllGlobals() - delete process.env.HUABU_RFS_URL - delete process.env.AGENTLET_TOKEN -}) - -describe('Service SDK', () => { - it('leases config without loading package code', async () => { - process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' - process.env.AGENTLET_TOKEN = 'agentlet-token' - const fetchMock = vi - .fn() - .mockResolvedValueOnce( - new Response( - JSON.stringify({ - id: 'example', - version: '1.0.0', - manifest, - config: { apiKey: 'provider-secret' }, - }), - { status: 200 }, - ), - ) - vi.stubGlobal('fetch', fetchMock) - - const lease = await leaseService('example') - - expect(lease.config).toEqual({ apiKey: 'provider-secret' }) - expect(lease.manifest.configuration[0]?.id).toBe('quality') - expect(fetchMock).toHaveBeenCalledTimes(1) - expect(fetchMock).toHaveBeenNthCalledWith( - 1, - 'https://huabu.example/api/rfs/canvas-1/services/example/lease', - expect.objectContaining({ - method: 'POST', - headers: { Authorization: 'Bearer agentlet-token' }, - }), - ) - }) - - it('provides config and lease metadata to a scoped callback', async () => { - process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' - process.env.AGENTLET_TOKEN = 'agentlet-token' - vi.stubGlobal( - 'fetch', - vi.fn().mockResolvedValue( - new Response( - JSON.stringify({ - id: 'example', - version: '1.0.0', - manifest, - config: { apiKey: 'provider-secret' }, - }), - ), - ), - ) - - await expect( - withServiceContext('example', ({ config, manifest: serviceManifest }) => ({ - configured: Boolean(config.apiKey), - name: serviceManifest.name, - })), - ).resolves.toEqual({ configured: true, name: 'Example' }) - }) - - it('does not include response bodies in provider-facing errors', async () => { - process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1' - process.env.AGENTLET_TOKEN = 'agentlet-token' - vi.stubGlobal( - 'fetch', - vi.fn().mockResolvedValue( - new Response('provider-secret', { status: 409 }), - ), - ) - - await expect(leaseService('example')).rejects.toThrow( - 'Service request failed (409)', - ) - }) -}) diff --git a/external/agentlet/spec/agent-reachback.md b/external/agentlet/spec/agent-reachback.md index efc7987dc..617ec6d5e 100644 --- a/external/agentlet/spec/agent-reachback.md +++ b/external/agentlet/spec/agent-reachback.md @@ -71,7 +71,7 @@ The final child environment combines ordinary inherited values and session overr | _host-specific bootstrap_ | `--env-inject` or `bootstrapEnv` | Host-owned non-secret tool coordinates available to all spawned agents and resource interpolation. | | _host-specific session context_ | `sessionSpec.env` | Workload context that may override ordinary inherited values, but cannot declare a bootstrap key or daemon token. | -Explicit bootstrap is the only source of `${ENV_VAR}` interpolation in resource destinations (§3). Empty values are valid; missing keys, including inherited keys and object prototype names, produce a non-fatal `resource_save_failed` diagnostic. Hosts that used the former implicit reachback directory must now provide it explicitly. The existing bundled Service SDK URL remains daemon-owned until its host-side migration is delivered; it is not part of the generic bootstrap default. +Explicit bootstrap is the only source of `${ENV_VAR}` interpolation in resource destinations (§3). Empty values are valid; missing keys, including inherited keys and object prototype names, produce a non-fatal `resource_save_failed` diagnostic. Hosts that used the former implicit reachback directory must now provide it explicitly. Agentlet supplies no host-specific SDK or SDK location; these belong to host bootstrap. ## 3. Tool Distribution From d3c8e3f7ab3edc286f99aad0e125a2da1649a9aa Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 06:33:50 +0000 Subject: [PATCH 23/36] feat(agentlet-host): forward opaque host bootstrap to embedded daemon Keep supervisor lifecycle ownership and pass credentials only in child env, never argv. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/daemon-supervisor.test.ts | 74 ++++++++++++++++++- .../agentlet-host/src/daemon-supervisor.ts | 30 +++++--- .../packages/agentlet-host/src/index.ts | 3 + 3 files changed, 94 insertions(+), 13 deletions(-) diff --git a/external/agenetes/packages/agentlet-host/src/daemon-supervisor.test.ts b/external/agenetes/packages/agentlet-host/src/daemon-supervisor.test.ts index b2c18e5a7..b9b3072f8 100644 --- a/external/agenetes/packages/agentlet-host/src/daemon-supervisor.test.ts +++ b/external/agenetes/packages/agentlet-host/src/daemon-supervisor.test.ts @@ -1,6 +1,22 @@ -import { describe, expect, it } from 'vitest'; +import { + mkdtempSync, + existsSync, + readFileSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; -import { filterHostNamespacedEnv } from './daemon-supervisor.js'; +import Fastify from 'fastify'; +import { describe, expect, it, vi } from 'vitest'; + +import { getDaemonAuth, _resetDaemonAuthForTests } from './daemon-auth.js'; +import { + filterHostNamespacedEnv, + getDaemonSupervisor, + _resetDaemonSupervisorForTests, +} from './daemon-supervisor.js'; describe('filterHostNamespacedEnv', () => { const base = { @@ -16,6 +32,60 @@ describe('filterHostNamespacedEnv', () => { expect(out).toEqual({ PATH: '/usr/bin', HOME: '/home/agent' }); }); + describe('embedded launch bootstrap', () => { + it('forks with immutable opaque host bootstrap and keeps the credential out of argv', async () => { + const directory = mkdtempSync(join(tmpdir(), 'agenetes-supervisor-')); + const entry = join(directory, 'daemon.cjs'); + const result = join(directory, 'launch.json'); + writeFileSync( + entry, + `require('node:fs').writeFileSync(${JSON.stringify(result)}, JSON.stringify({ argv: process.argv.slice(2), token: process.env.AGENTLET_TOKEN, secret: process.env.HUABU_SECRET_KEY }));`, + ); + const app = Fastify(); + _resetDaemonSupervisorForTests(); + _resetDaemonAuthForTests(); + getDaemonAuth().setDaemonToken('host-token'); + vi.stubEnv('HUABU_SECRET_KEY', 'must-not-inherit'); + vi.stubEnv('AGENTLET_TOKEN', 'wrong-token'); + const bootstrapEnv = { HOST_ENTRY: ' opaque entry=a=b ' }; + try { + getDaemonSupervisor().attach(app, { + daemonEntryPath: entry, + dataDir: directory, + bootstrapEnv, + hostEnvPrefix: 'HUABU_', + hostEnvAllowlist: [], + }); + bootstrapEnv.HOST_ENTRY = 'changed'; + await app.listen({ port: 0, host: '127.0.0.1' }); + const deadline = Date.now() + 5000; + while (!existsSync(result)) { + if (Date.now() >= deadline) + throw new Error('Supervisor child did not start'); + await new Promise((resolve) => setTimeout(resolve, 10)); + } + const launch = JSON.parse(readFileSync(result, 'utf8')); + expect(launch.token).toBe('host-token'); + expect(launch.secret).toBeUndefined(); + expect(launch.argv).toContain('HOST_ENTRY= opaque entry=a=b '); + expect(launch.argv).not.toContain('--token'); + expect(launch.argv).not.toContain('host-token'); + const address = app.server.address(); + if (!address || typeof address === 'string') + throw new Error('Missing bound test port'); + expect(launch.argv).toContain( + `ws://127.0.0.1:${address.port}/api/acp/agent`, + ); + } finally { + await app.close(); + _resetDaemonSupervisorForTests(); + _resetDaemonAuthForTests(); + vi.unstubAllEnvs(); + rmSync(directory, { recursive: true, force: true }); + } + }); + }); + it('keeps only allow-listed host-namespaced vars', () => { const out = filterHostNamespacedEnv(base, 'HUABU_', ['HUABU_RFS_URL']); expect(out).toEqual({ diff --git a/external/agenetes/packages/agentlet-host/src/daemon-supervisor.ts b/external/agenetes/packages/agentlet-host/src/daemon-supervisor.ts index 6dc6e200e..f51d645dd 100644 --- a/external/agenetes/packages/agentlet-host/src/daemon-supervisor.ts +++ b/external/agenetes/packages/agentlet-host/src/daemon-supervisor.ts @@ -14,7 +14,7 @@ * token from {@link getDaemonAuth} and `child_process.fork` the * agentlet daemon entry (an absolute path injected by the host) * with `daemon --server ws://127.0.0.1:/api/acp/agent - * --token --allow-insecure`. + * --allow-insecure`, with the credential in child `AGENTLET_TOKEN`. * 2. On clean exit (code 0, no shutdown signal) we treat it as the * daemon following our own shutdown request and stay offline. * 3. On unexpected exit (non-zero code OR signal OR crash) we @@ -226,6 +226,7 @@ export interface AttachOptions { * passes a ready absolute path — this package never resolves it. */ daemonEntryPath: string; + bootstrapEnv?: Readonly>; /** Absolute directory for host-owned persistent state. */ dataDir: string; /** Resolve the host-owned process limit each time the daemon starts. */ @@ -291,6 +292,7 @@ class DaemonSupervisor { * knowledge (dev vs bundled paths); this package never resolves it. */ private daemonEntryPath = ''; + private bootstrapEnv: Readonly> = {}; /** * Absolute directory for host-owned persistent state, injected at * {@link attach} time. Used only for legacy-ticket cleanup here. @@ -308,6 +310,7 @@ class DaemonSupervisor { if (this.app) return; this.app = app; this.daemonEntryPath = opts.daemonEntryPath; + this.bootstrapEnv = Object.freeze({ ...opts.bootstrapEnv }); this.dataDir = opts.dataDir; this.getMaxAgents = opts.getMaxAgents; this.hostEnvPrefix = opts.hostEnvPrefix; @@ -444,8 +447,10 @@ class DaemonSupervisor { 'daemon', '--server', serverUrl, - '--token', - token, + ...Object.entries(this.bootstrapEnv).flatMap(([key, value]) => [ + '--env-inject', + `${key}=${value}`, + ]), ...(maxAgents === undefined ? [] : ['--max-agents', String(maxAgents)]), '--allow-insecure', ]; @@ -453,6 +458,16 @@ class DaemonSupervisor { this.state.starting = true; this.state.nextRestartAt = null; + const childEnv = filterHostNamespacedEnv( + process.env, + this.hostEnvPrefix, + this.hostEnvAllowlist, + ); + for (const key of Object.keys(childEnv)) { + const normalized = process.platform === 'win32' ? key.toUpperCase() : key; + if (normalized === 'AGENTLET_TOKEN') delete childEnv[key]; + } + childEnv.AGENTLET_TOKEN = token; let child: ChildProcess; try { child = fork(entry, args, { @@ -467,14 +482,7 @@ class DaemonSupervisor { // secrets and config never reach the daemon or the agents it // spawns; the daemon receives its coordinates via CLI args and // agents via explicit spawn `env` injection. - env: { - ...filterHostNamespacedEnv( - process.env, - this.hostEnvPrefix, - this.hostEnvAllowlist, - ), - AGENTLET_TOKEN: token, - }, + env: childEnv, }); } catch (err) { const message = err instanceof Error ? err.message : String(err); diff --git a/external/agenetes/packages/agentlet-host/src/index.ts b/external/agenetes/packages/agentlet-host/src/index.ts index ac27e0371..dd930baa9 100644 --- a/external/agenetes/packages/agentlet-host/src/index.ts +++ b/external/agenetes/packages/agentlet-host/src/index.ts @@ -91,6 +91,8 @@ export interface MountAgenetesOptions { * owns this knowledge; this package never resolves paths. */ daemonEntryPath: string; + /** Opaque, non-secret bootstrap values forwarded through Agentlet's generic CLI. */ + bootstrapEnv?: Readonly>; /** Resolve the host-owned process limit on each supervised daemon start. */ getMaxAgents?: () => number; /** @@ -142,6 +144,7 @@ export function mountAgenetes( getDaemonSupervisor().attach(app, { daemonEntryPath: opts.daemonEntryPath, + bootstrapEnv: opts.bootstrapEnv, dataDir: opts.dataDir, getMaxAgents: opts.getMaxAgents, hostEnvPrefix: opts.hostEnvPrefix, From 0ec97f8c09b97c2bd6ab5d8949e67a447a886f28 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 06:33:50 +0000 Subject: [PATCH 24/36] feat: migrate Service SDK to Huabu client runtime and source daemon Coordinate canonical SDK env, source and embedded launch, shared origin/schema validation, all Server build and Desktop resource layouts, and remove automatic PATH installation. Preserve HTTP access without provisioning Agent Node. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/desktop/electron-builder.yml | 6 + apps/server/package.json | 5 +- apps/server/src/app.ts | 11 +- apps/server/src/bundle.test.ts | 64 ++++ .../src/modules/agent/acp/daemon-entry.ts | 44 +-- apps/server/src/modules/agent/acp/index.ts | 2 +- .../src/modules/remote_fs/rfs.route.test.ts | 2 +- .../src/modules/security/public-origin.ts | 47 +-- .../src/prompt/external-agent/access-huabu.md | 8 +- apps/server/src/services/image-gen/SKILL.md | 4 +- apps/server/src/services/image-gen/entry.mjs | 4 +- .../src/services/image-gen/entry.test.ts | 18 +- apps/server/src/services/web-search/SKILL.md | 2 +- apps/server/src/services/web-search/entry.mjs | 4 +- .../src/services/web-search/entry.test.ts | 17 +- apps/server/tsup.config.ts | 20 +- docs/architecture/agent-reachback.md | 16 +- docs/architecture/service-packages.md | 14 +- docs/proposals/service-packages.md | 2 + eslint.config.mjs | 2 + package.json | 11 +- packages/client-runtime/package.json | 30 ++ packages/client-runtime/src/bootstrap.ts | 73 ++++ packages/client-runtime/src/daemon.ts | 239 ++++++++++++++ packages/client-runtime/src/public-origin.ts | 45 +++ packages/client-runtime/src/service-sdk.ts | 71 ++++ packages/client-runtime/tests/daemon.test.ts | 311 ++++++++++++++++++ .../client-runtime/tests/service-sdk.test.ts | 152 +++++++++ packages/client-runtime/tsconfig.json | 9 + packages/client-runtime/tsup.config.ts | 17 + packages/shared/package.json | 4 + pnpm-lock.yaml | 25 ++ 32 files changed, 1167 insertions(+), 112 deletions(-) create mode 100644 packages/client-runtime/package.json create mode 100644 packages/client-runtime/src/bootstrap.ts create mode 100644 packages/client-runtime/src/daemon.ts create mode 100644 packages/client-runtime/src/public-origin.ts create mode 100644 packages/client-runtime/src/service-sdk.ts create mode 100644 packages/client-runtime/tests/daemon.test.ts create mode 100644 packages/client-runtime/tests/service-sdk.test.ts create mode 100644 packages/client-runtime/tsconfig.json create mode 100644 packages/client-runtime/tsup.config.ts diff --git a/apps/desktop/electron-builder.yml b/apps/desktop/electron-builder.yml index 131d66cdf..c387a13c8 100644 --- a/apps/desktop/electron-builder.yml +++ b/apps/desktop/electron-builder.yml @@ -83,6 +83,12 @@ extraResources: # files bloat the installer for no benefit. - '**/*.js' - '**/*.js.map' + - 'package.json' + - from: ../server/dist-bundle/client-runtime + to: server/client-runtime + filter: + - '**/*.js' + - 'package.json' - from: ../web/dist to: web filter: diff --git a/apps/server/package.json b/apps/server/package.json index 2ad9524a3..db58904de 100644 --- a/apps/server/package.json +++ b/apps/server/package.json @@ -4,10 +4,12 @@ "type": "module", "scripts": { "dev": "tsx watch src/server.ts", + "predev": "pnpm --filter @huabu/client-runtime build", "lint": "eslint .", "format": "prettier --write .", "build": "tsc -p tsconfig.json", - "prebundle": "node -e \"require('node:fs').rmSync('dist-bundle', { recursive: true, force: true })\"", + "prebuild": "pnpm --filter @huabu/client-runtime build", + "prebundle": "pnpm --filter @huabu/client-runtime build && node -e \"require('node:fs').rmSync('dist-bundle', { recursive: true, force: true })\"", "bundle": "tsup", "media:prepare": "node scripts/prepare-video-media.mjs", "typecheck": "tsc -p tsconfig.json --noEmit", @@ -40,6 +42,7 @@ "@fastify/rate-limit": "^11.2.0", "@fastify/static": "^8.0.2", "@huabu/shared": "workspace:*", + "@huabu/client-runtime": "workspace:*", "@mozilla/readability": "^0.6.0", "@opendocsg/pdf2md": "^0.2.5", "@resvg/resvg-wasm": "^2.6.2", diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index a819fb770..f690e667c 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -27,7 +27,7 @@ import { getAgentProfileRegistry, installAcpProfileCachePort, mountAgenetes, - resolveDaemonEntry, + resolveDaemonRuntime, } from './modules/agent/acp/index.js'; import { initializeAgentDefaults } from './modules/agent/agent-defaults.js'; import agentDefaultsRoutes from './modules/agent/agent-defaults.route.js'; @@ -299,10 +299,17 @@ try { app.log.warn({ err }, '[acp] could not remove legacy acp-config.json'); } } +const daemonRuntime = resolveDaemonRuntime(); +if (!daemonRuntime.artifacts.serviceSdkEntry) { + app.log.warn( + '[acp] Service SDK artifact missing; direct HTTP remains available, rebuild client-runtime to use JS Service entries', + ); +} const agentletGateway = mountAgenetes(app, { connectionToken: getConnectionToken(), dataDir: getDataDir(), - daemonEntryPath: resolveDaemonEntry() ?? '', + daemonEntryPath: daemonRuntime.artifacts.daemonEntry ?? '', + bootstrapEnv: daemonRuntime.bootstrapEnv, getMaxAgents: () => getExternalAgentRuntimeConfig().maxAgents, // Host-namespaced env isolation: the agentlet daemon and every external // agent it spawns are host-agnostic and must receive their Huabu diff --git a/apps/server/src/bundle.test.ts b/apps/server/src/bundle.test.ts index fc44c4d93..b3b8dabaf 100644 --- a/apps/server/src/bundle.test.ts +++ b/apps/server/src/bundle.test.ts @@ -5,10 +5,12 @@ import { execFileSync } from 'node:child_process'; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; import { tmpdir } from 'node:os'; import path from 'node:path'; +import { pathToFileURL } from 'node:url'; import { build } from 'tsup'; import { describe, expect, it } from 'vitest'; +import clientRuntimeConfig from '../../../packages/client-runtime/tsup.config.js'; import bundleConfig from '../tsup.config.js'; const configured = @@ -16,6 +18,68 @@ const configured = const configurations = Array.isArray(configured) ? configured : [configured]; describe('server bundle runtime', () => { + it('loads real Agentlet and client-runtime artifacts outside the workspace without node_modules', async () => { + const directory = mkdtempSync(path.join(tmpdir(), 'huabu-real-runtime-')); + try { + writeFileSync(path.join(directory, 'package.json'), '{"type":"module"}'); + await build({ + ...configurations[1], + config: false, + entry: { + index: path.resolve( + '../../external/agentlet/packages/local/src/index.ts', + ), + }, + outDir: path.join(directory, 'agentlet'), + onSuccess: undefined, + silent: true, + }); + const runtimeOptions = + typeof clientRuntimeConfig === 'function' + ? await clientRuntimeConfig({}) + : clientRuntimeConfig; + if (Array.isArray(runtimeOptions)) + throw new Error('Expected one runtime build config'); + await build({ + ...runtimeOptions, + config: false, + entry: { + 'service-sdk': path.resolve( + '../../packages/client-runtime/src/service-sdk.ts', + ), + daemon: path.resolve('../../packages/client-runtime/src/daemon.ts'), + }, + outDir: path.join(directory, 'client-runtime'), + silent: true, + }); + const daemonHelp = execFileSync( + process.execPath, + [path.join(directory, 'agentlet/index.js'), 'daemon', '--help'], + { encoding: 'utf8' }, + ); + expect(daemonHelp).toContain('--env-inject'); + const hostHelp = execFileSync( + process.execPath, + [path.join(directory, 'client-runtime/daemon.js'), '--help'], + { encoding: 'utf8' }, + ); + expect(hostHelp).toContain('pnpm start:daemon'); + const sdkProbe = execFileSync( + process.execPath, + [ + '--input-type=module', + '-e', + 'const sdk = await import(process.argv[1]); console.log(typeof sdk.leaseService, typeof sdk.withServiceContext)', + pathToFileURL(path.join(directory, 'client-runtime/service-sdk.js')) + .href, + ], + { encoding: 'utf8' }, + ); + expect(sdkProbe.trim()).toBe('function function'); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }); it.each(configurations)( 'loads prefix-only Node built-ins with the $outDir configuration', async (configuration) => { diff --git a/apps/server/src/modules/agent/acp/daemon-entry.ts b/apps/server/src/modules/agent/acp/daemon-entry.ts index 42942eb61..0d8032099 100644 --- a/apps/server/src/modules/agent/acp/daemon-entry.ts +++ b/apps/server/src/modules/agent/acp/daemon-entry.ts @@ -1,10 +1,13 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { existsSync } from 'node:fs'; import { dirname, resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; +import { + buildHuabuBootstrapEnv, + resolveRuntimeArtifacts, +} from '@huabu/client-runtime'; /** * Resolve the absolute path to the agentlet daemon entry script. * @@ -26,36 +29,15 @@ import { fileURLToPath } from 'node:url'; * The first existing path wins. */ export function resolveDaemonEntry(): string | null { - const env = process.env.HUABU_AGENTLET_DAEMON_PATH; - if (env && existsSync(env)) return env; + return resolveDaemonRuntime().artifacts.daemonEntry; +} - // import.meta.url resolves to this source file in dev (tsx) and to - // the bundled server.js in production (every module collapses into - // the same file under tsup --bundle). Two candidates handle both. +export function resolveDaemonRuntime() { const here = dirname(fileURLToPath(import.meta.url)); - - // Production: dist-bundle/server.js → dist-bundle/agentlet/index.js - const bundled = resolve(here, 'agentlet', 'index.js'); - if (existsSync(bundled)) return bundled; - - // Dev: apps/server/src/modules/agent/acp/daemon-entry.ts - // → external/agentlet/packages/local/dist/index.js - const dev = resolve( - here, - '..', - '..', - '..', - '..', - '..', - '..', - 'external', - 'agentlet', - 'packages', - 'local', - 'dist', - 'index.js', - ); - if (existsSync(dev)) return dev; - - return null; + const artifacts = resolveRuntimeArtifacts({ + daemonOverride: process.env.HUABU_AGENTLET_DAEMON_PATH, + bundleDir: here, + repoRoot: resolve(here, '../../../../../..'), + }); + return { artifacts, bootstrapEnv: buildHuabuBootstrapEnv(artifacts) }; } diff --git a/apps/server/src/modules/agent/acp/index.ts b/apps/server/src/modules/agent/acp/index.ts index e2d0430e9..9010e2111 100644 --- a/apps/server/src/modules/agent/acp/index.ts +++ b/apps/server/src/modules/agent/acp/index.ts @@ -38,7 +38,7 @@ export type { TranslatorLogger } from '@agenetes/acp-driver'; export { getDaemonAuth } from '@agenetes/agentlet-host'; export { getDaemonSupervisor, getDaemonStatus } from '@agenetes/agentlet-host'; -export { resolveDaemonEntry } from './daemon-entry.js'; +export { resolveDaemonEntry, resolveDaemonRuntime } from './daemon-entry.js'; export { installAcpProfileCachePort } from './profile-cache-port.js'; export { ensureAgentForThread, diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index f620fe45c..de1f97eda 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -236,7 +236,7 @@ describe('GET /api/rfs/:canvasId/skill', () => { ); } expect(res.body).toContain('/capabilities/commands/$COMMAND'); - expect(res.body).toContain('AGENTLET_SERVICE_SDK_URL'); + expect(res.body).toContain('HUABU_SERVICE_SDK_URL'); expect(res.body).toContain('/services'); expect(res.body).toContain('$HUABU_RFS_URL/skill/tasks'); expect(res.body).toContain('**parent-local**'); diff --git a/apps/server/src/modules/security/public-origin.ts b/apps/server/src/modules/security/public-origin.ts index 3b299490c..a665ebf6c 100644 --- a/apps/server/src/modules/security/public-origin.ts +++ b/apps/server/src/modules/security/public-origin.ts @@ -1,45 +1,8 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -export class InvalidPublicOriginError extends Error {} - -export function normalizePublicOrigin(rawValue: string): string { - let url: URL; - try { - url = new URL(rawValue.trim()); - } catch { - throw new InvalidPublicOriginError( - 'HUABU_PUBLIC_ORIGIN must be an absolute HTTP(S) origin', - ); - } - - if (url.protocol !== 'http:' && url.protocol !== 'https:') { - throw new InvalidPublicOriginError( - 'HUABU_PUBLIC_ORIGIN must use HTTP or HTTPS', - ); - } - if (url.username || url.password) { - throw new InvalidPublicOriginError( - 'HUABU_PUBLIC_ORIGIN must not include credentials', - ); - } - if (url.search || url.hash) { - throw new InvalidPublicOriginError( - 'HUABU_PUBLIC_ORIGIN must not include a query or fragment', - ); - } - if (url.pathname !== '/') { - throw new InvalidPublicOriginError( - 'HUABU_PUBLIC_ORIGIN must be an origin without a path prefix', - ); - } - - return url.origin; -} - -export function resolveConfiguredPublicOrigin( - env: NodeJS.ProcessEnv = process.env, -): string | undefined { - const rawValue = env.HUABU_PUBLIC_ORIGIN?.trim(); - return rawValue ? normalizePublicOrigin(rawValue) : undefined; -} +export { + InvalidPublicOriginError, + normalizePublicOrigin, + resolveConfiguredPublicOrigin, +} from '@huabu/client-runtime'; diff --git a/apps/server/src/prompt/external-agent/access-huabu.md b/apps/server/src/prompt/external-agent/access-huabu.md index c2818b3c2..e07a37a4b 100644 --- a/apps/server/src/prompt/external-agent/access-huabu.md +++ b/apps/server/src/prompt/external-agent/access-huabu.md @@ -6,7 +6,7 @@ These environment variables are already set: - `HUABU_RFS_URL` — the base URL for this Space, with no trailing slash. - `AGENTLET_TOKEN` — the RFS bearer credential. -- `AGENTLET_SERVICE_SDK_URL` — the daemon-owned `file://` URL used internally by downloaded Service Package entries to lease current configuration. +- `HUABU_SERVICE_SDK_URL` — the Huabu-owned `file://` URL used by optional Node Service entries to lease current configuration. Huabu provides the entry, not Node; choose a compatible Node from your own environment. - `HUABU_THREAD_ID` — your conversation ID. Pass it on `execute` (see §6) to attribute your edits. Prefer deterministic direct operations: @@ -307,9 +307,11 @@ cd image-gen Every archive contains one top-level directory named after the Service, so extracting `image-gen.zip` creates `image-gen/` rather than placing files directly in the current directory. `service.yaml` and every file declared by `package.files` are included; undeclared development files are not. -Read the extracted `SKILL.md`, then run `node entry.mjs --help` before invoking the optional entry. Runtime help uses the leased Manifest and configuration to show current choices and configured defaults that may not be visible from the source alone. The entry obtains that coherent Service context on demand through `AGENTLET_SERVICE_SDK_URL`; you normally do not need to import or call the SDK yourself. An entry is a modifiable starting point rather than a complete provider SDK: when the task needs another provider endpoint, follow the official documentation linked by the Skill and modify only your local Package copy. +With compatible Node available, read the extracted `SKILL.md`, then run `node entry.mjs --help` before invoking the optional entry. Runtime help uses the leased Manifest and configuration to show current choices and configured defaults that may not be visible from the source alone. The entry obtains that coherent Service context on demand through `HUABU_SERVICE_SDK_URL`; you normally do not need to import or call the SDK yourself. An entry is a modifiable starting point rather than a complete provider SDK: when the task needs another provider endpoint, follow the official documentation linked by the Skill and modify only your local Package copy. Old downloaded entries that use `AGENTLET_SERVICE_SDK_URL` must be refreshed; there is no legacy alias. -Never print, persist, or forward leased credentials. A Service Package without `SKILL.md` is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. +Without Node, JS entries cannot run, but Service leases remain language-independent. Use your own HTTP client in a business subprocess to `POST "$HUABU_RFS_URL/services//lease"` with the normal bearer authentication, consume the coherent `manifest` and `config` response in memory, and call only the intended provider according to its documentation. Do not print the lease into tool output, save it to disk, put credentials in argv, or export them to a global shell environment. + +Never print or persist leased credentials or send them to unrelated recipients; only the intended provider receives the credential necessary for the operation. A Service Package without `SKILL.md` is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. ## Advanced workflows diff --git a/apps/server/src/services/image-gen/SKILL.md b/apps/server/src/services/image-gen/SKILL.md index 389cc4a54..e6ceb0513 100644 --- a/apps/server/src/services/image-gen/SKILL.md +++ b/apps/server/src/services/image-gen/SKILL.md @@ -2,8 +2,8 @@ Use this Service when the user asks you to generate an image through their configured Azure OpenAI image deployment. -`entry.mjs` is an executable starting point for basic prompt-to-image generation, not a complete provider SDK. Run `node entry.mjs --help` first to read the runtime options, current configured defaults, and Manifest-defined choices. Then run `node entry.mjs --prompt "" --quality --output `, or use `--prompt-file ` for a file-backed prompt. It obtains the current Manifest and configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credentials. +`entry.mjs` is an executable starting point for basic prompt-to-image generation, not a complete provider SDK. With a compatible Node available in your environment, run `node entry.mjs --help` first to read the runtime options, current configured defaults, and Manifest-defined choices. Then run `node entry.mjs --prompt "" --quality --output `, or use `--prompt-file ` for a file-backed prompt. It obtains the current Manifest and configuration through the Huabu Service SDK; never print or persist the supplied credentials, and send them only to the intended provider. -When the task needs image editing or another provider feature that the entry does not implement, read the [Azure OpenAI image generation documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/dall-e?tabs=command-line%2Ckeyless%2Ctypescript-keyless&pivots=programming-language-typescript), modify the local Package copy, and keep configuration retrieval through `AGENTLET_SERVICE_SDK_URL`. +When the task needs image editing or another provider feature that the entry does not implement, read the [Azure OpenAI image generation documentation](https://learn.microsoft.com/en-us/azure/foundry/openai/how-to/dall-e?tabs=command-line%2Ckeyless%2Ctypescript-keyless&pivots=programming-language-typescript), modify the local Package copy, and keep configuration retrieval through `HUABU_SERVICE_SDK_URL`. The daemon does not provide Node; without it, use the authenticated HTTP lease described by the root Space guide and your own HTTP client rather than invoking this JS entry. The entry writes the generated image to the requested local path. Upload it through the existing Huabu RFS artifact workflow only when the user's task requires durable Space content. diff --git a/apps/server/src/services/image-gen/entry.mjs b/apps/server/src/services/image-gen/entry.mjs index 35d7d77c6..4df98f144 100644 --- a/apps/server/src/services/image-gen/entry.mjs +++ b/apps/server/src/services/image-gen/entry.mjs @@ -136,8 +136,8 @@ async function imageBytes(result) { export async function main(argv = process.argv.slice(2)) { const options = parseCliArgs(argv); - const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; - if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); + const sdkUrl = process.env.HUABU_SERVICE_SDK_URL; + if (!sdkUrl) throw new Error('HUABU_SERVICE_SDK_URL is unavailable'); const { withServiceContext } = await import(sdkUrl); await withServiceContext('image-gen', async ({ manifest, config }) => { const quality = qualityContext(manifest, config); diff --git a/apps/server/src/services/image-gen/entry.test.ts b/apps/server/src/services/image-gen/entry.test.ts index e9ea98508..9dac22a70 100644 --- a/apps/server/src/services/image-gen/entry.test.ts +++ b/apps/server/src/services/image-gen/entry.test.ts @@ -22,10 +22,22 @@ async function loadEntry() { afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); - delete process.env.AGENTLET_SERVICE_SDK_URL; + delete process.env.HUABU_SERVICE_SDK_URL; }); describe('Image Service entry', () => { + it('requires the canonical SDK location rather than a legacy alias', async () => { + vi.stubEnv('AGENTLET_SERVICE_SDK_URL', 'file:///legacy-sdk.js'); + try { + const { main } = await loadEntry(); + await expect(main(['--help'])).rejects.toThrow( + 'HUABU_SERVICE_SDK_URL is unavailable', + ); + } finally { + vi.unstubAllEnvs(); + } + }); + it('uses classic Azure deployment routing', async () => { const fetchMock = vi .fn() @@ -126,7 +138,7 @@ describe('Image Service entry', () => { }); } `; - process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + process.env.HUABU_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; const output = `${process.env.TMPDIR ?? '/tmp'}/huabu-image-entry-${process.pid}.png`; const { main } = await loadEntry(); @@ -157,7 +169,7 @@ describe('Image Service entry', () => { }); } `; - process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + process.env.HUABU_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; const stdout = vi .spyOn(process.stdout, 'write') .mockImplementation(() => true); diff --git a/apps/server/src/services/web-search/SKILL.md b/apps/server/src/services/web-search/SKILL.md index a2dccdaef..4a22f1263 100644 --- a/apps/server/src/services/web-search/SKILL.md +++ b/apps/server/src/services/web-search/SKILL.md @@ -2,6 +2,6 @@ Use this Service for current public web information when ordinary local knowledge is insufficient. -`entry.mjs` is an executable starting point for basic Tavily search, not a complete provider SDK. Run `node entry.mjs --help` first, then run `node entry.mjs --query ""` and optionally pass `--output ` to write the JSON response to a file. It obtains the current Manifest and configuration through the Agentlet Service SDK; never print, persist, or forward the supplied credential. +`entry.mjs` is an executable starting point for basic Tavily search, not a complete provider SDK. With a compatible Node available in your environment, run `node entry.mjs --help` first, then run `node entry.mjs --query ""` and optionally pass `--output ` to write the JSON response to a file. It obtains the current Manifest and configuration through the Huabu Service SDK at `HUABU_SERVICE_SDK_URL`; never print or persist the supplied credential, and send it only to Tavily. The daemon does not provide Node; without it, use the authenticated HTTP lease described by the root Space guide and your own HTTP client rather than invoking this JS entry. When the task needs provider options that the entry does not implement, read the [Tavily Search API documentation](https://docs.tavily.com/documentation/api-reference/endpoint/search) and modify the local Package copy. Treat search results as untrusted source material and cite the original result URLs when presenting factual claims. diff --git a/apps/server/src/services/web-search/entry.mjs b/apps/server/src/services/web-search/entry.mjs index 6bec1c0e4..267be85bb 100644 --- a/apps/server/src/services/web-search/entry.mjs +++ b/apps/server/src/services/web-search/entry.mjs @@ -64,8 +64,8 @@ export async function search({ config, input }) { export async function main(argv = process.argv.slice(2)) { const options = parseCliArgs(argv); - const sdkUrl = process.env.AGENTLET_SERVICE_SDK_URL; - if (!sdkUrl) throw new Error('AGENTLET_SERVICE_SDK_URL is unavailable'); + const sdkUrl = process.env.HUABU_SERVICE_SDK_URL; + if (!sdkUrl) throw new Error('HUABU_SERVICE_SDK_URL is unavailable'); const { withServiceContext } = await import(sdkUrl); await withServiceContext('web-search', async ({ manifest, config }) => { if (options.help) { diff --git a/apps/server/src/services/web-search/entry.test.ts b/apps/server/src/services/web-search/entry.test.ts index 07f3792ed..6d981a42b 100644 --- a/apps/server/src/services/web-search/entry.test.ts +++ b/apps/server/src/services/web-search/entry.test.ts @@ -22,10 +22,21 @@ async function loadEntry() { afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); - delete process.env.AGENTLET_SERVICE_SDK_URL; + delete process.env.HUABU_SERVICE_SDK_URL; }); describe('Web Search Service entry', () => { + it('requires the canonical SDK location rather than a legacy alias', async () => { + vi.stubEnv('AGENTLET_SERVICE_SDK_URL', 'file:///legacy-sdk.js'); + try { + const { main } = await loadEntry(); + await expect(main(['--help'])).rejects.toThrow( + 'HUABU_SERVICE_SDK_URL is unavailable', + ); + } finally { + vi.unstubAllEnvs(); + } + }); it('sends the configured Tavily key and normalized query', async () => { const fetchMock = vi .fn() @@ -84,7 +95,7 @@ describe('Web Search Service entry', () => { }); } `; - process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + process.env.HUABU_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; const output = `${process.env.TMPDIR ?? '/tmp'}/huabu-web-search-entry-${process.pid}.json`; const { main } = await loadEntry(); @@ -105,7 +116,7 @@ describe('Web Search Service entry', () => { }); } `; - process.env.AGENTLET_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; + process.env.HUABU_SERVICE_SDK_URL = `data:text/javascript;base64,${Buffer.from(sdkSource).toString('base64')}`; const stdout = vi .spyOn(process.stdout, 'write') .mockImplementation(() => true); diff --git a/apps/server/tsup.config.ts b/apps/server/tsup.config.ts index 4834e599d..6e509e92a 100644 --- a/apps/server/tsup.config.ts +++ b/apps/server/tsup.config.ts @@ -1,7 +1,7 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { cpSync } from 'node:fs'; +import { cpSync, writeFileSync } from 'node:fs'; import { createRequire } from 'node:module'; import path from 'node:path'; @@ -84,6 +84,15 @@ export default defineConfig([ const servicesDst = path.resolve('dist-bundle/services'); cpSync(servicesSrc, servicesDst, { recursive: true }); console.log(`[tsup] copied Service packages -> ${servicesDst}`); + cpSync( + path.resolve('../../packages/client-runtime/dist'), + path.resolve('dist-bundle/client-runtime'), + { recursive: true }, + ); + writeFileSync( + path.resolve('dist-bundle/client-runtime/package.json'), + '{"type":"module"}\n', + ); // @resvg/resvg-wasm — copied next to server.js so the // snapshot_nodes tool's bundle-layout fallback finds it via // bundled server module's file URL. @@ -112,9 +121,6 @@ export default defineConfig([ index: path.resolve( '../../external/agentlet/packages/local/src/index.ts', ), - 'service-sdk/index': path.resolve( - '../../external/agentlet/packages/local/src/service-sdk/index.ts', - ), }, format: ['esm'], outDir: 'dist-bundle/agentlet', @@ -129,5 +135,11 @@ export default defineConfig([ esbuildOptions(options) { options.platform = 'node'; }, + async onSuccess() { + writeFileSync( + path.resolve('dist-bundle/agentlet/package.json'), + '{"type":"module"}\n', + ); + }, }, ]); diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index 01c0ae35a..fd6ffe41c 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -104,12 +104,20 @@ Parent lineage is best effort. The route resolves `parentThreadId` or `X-Huabu-H Huabu injects `HUABU_RFS_URL` and `AGENTLET_TOKEN` into the external agent environment. `HUABU_RFS_URL` is derived from the deployment-owned root `HUABU_PUBLIC_ORIGIN` plus `/api/rfs/`; a loopback deployment with no configured public origin uses its actual bound port as the explicit local fallback. Network binds require a non-loopback public origin before the Server listens, so a remote Agentlet never receives a success-shaped Server-local loopback URL. Every external-agent Deployment persists the bootstrap as its initial preamble, including Deployments first created by mode, model, or configuration control requests; startup repair backfills older undelivered records that omitted it. The preamble owns the authentication contract and curl header setup because every external Agent needs them before loading any Skill. The public basic guide is loaded without credentials from `GET /skill`; repeating that request with authentication adds the current root override and live Space Skill Frames. Advanced layout, Task, recursive-Agent, and Interactive View procedures are loaded on demand from authenticated `GET /skill/layout`, `/skill/tasks`, `/skill/agents`, and `/skill/interactive-views`. -Agentlet additionally injects its daemon-owned `AGENTLET_SERVICE_SDK_URL`, an absolute `file://` URL for the SDK shipped in Agentlet's `dist/service-sdk`. Session or Profile environment cannot override this value. Downloaded Service Package entries use the SDK only to obtain current configuration leases; the SDK does not discover or load Package code, and provider credentials remain absent from startup environment until an entry requests them. +Huabu injects `HUABU_SERVICE_SDK_URL`, an absolute `file://` URL for its own SDK in `packages/client-runtime/dist/service-sdk.js` or the installed `client-runtime/service-sdk.js`. Generic Agentlet protects this explicit bootstrap key against session overrides but ships no SDK itself. No old `AGENTLET_SERVICE_SDK_URL` alias or fallback exists; refresh old downloaded entries and restart Agents. Entries obtain only current configuration leases, not Package code, and provider credentials remain absent from startup environment until requested. -Agentlet also accepts a generic, default-empty `bootstrapEnv` map or repeatable `--env-inject KEY=VALUE`. It copies and freezes opaque non-secret values at construction, without interpreting host names or resolving paths. Bootstrap overrides inherited values; sessions that declare any managed key or `AGENTLET_TOKEN` fail before process launch. Windows matching is case-insensitive and removes inherited case variants in the final child environment; Unix remains case-sensitive. Ordinary session context and `AGENTLET_SERVER` overrides retain their behavior. The currently bundled SDK is still supplied until the coordinated Huabu client-runtime migration. +Agentlet accepts a generic, default-empty `bootstrapEnv` map or repeatable `--env-inject KEY=VALUE`. It copies and freezes opaque non-secret values at construction, without interpreting host names or resolving paths. Bootstrap overrides inherited values; sessions that declare any managed key or `AGENTLET_TOKEN` fail before process launch. Windows matching is case-insensitive and removes inherited case variants in the final child environment; Unix remains case-sensitive. Ordinary session context and `AGENTLET_SERVER` overrides retain their behavior. There is no automatic `AGENTLET_REACHBACK_DIR` default or ambient resource registry. Hosts can opt in by explicitly declaring that key through bootstrap. `server/sendResource` remains available and interpolates only explicit bootstrap keys, reporting missing keys or write errors as non-fatal resource diagnostics. Bootstrap does not provision Node or gate Agent startup on optional tool availability. Control handshake rejection exits nonzero; normal supervised shutdown exits zero. +### Source and embedded launch + +From a prepared Huabu source checkout, use `pnpm start:daemon` with `HUABU_PUBLIC_ORIGIN` and `HUABU_CONNECTION_TOKEN` in the process environment, the optional root `.env`, or an explicit `--env-file `. Default-file connection fields are overridden by process env; an explicit file must exist and is the sole connection source. Dotenv is parsed as data, rejecting duplicate keys and malformed assignments; only the two connection fields are consumed. HTTPS derives WSS `/api/acp/agent`; HTTP derives WS plus `--allow-insecure` and an explicit plaintext warning. The launcher uses structured argv, strips the Huabu deployment namespace from the child environment, passes the token only as `AGENTLET_TOKEN`, forwards signals, and propagates child exit without a second restart loop. + +The embedded path does not invoke `huabu-daemon`, pnpm, or repo env files. Server resolves the same client artifacts/bootstrap and supplies them to the existing generic supervisor, which directly forks Agentlet with the bound loopback endpoint and authoritative child credential. Desktop keeps its existing Electron Server/Agentlet process chain and does not expose an Electron Node-mode executable to Agents. Agent tool runtime choice remains independent of daemon startup. SDK/RFS coordinates are supplied only for actual local artifacts; missing optional tools do not gate embedded Agentlet or HTTP access. The RFS implementation is delivered independently of SDK migration. + +Installation retains required builds but no longer modifies user shell rc or PATH. Previously installed PATH entries are left untouched. + Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. The guide is direct-first: an external agent can discover, query, download, snapshot, upload, execute, and verify without creating another Agent. `POST /agent` remains an optional high-level interpretation and delegation path. @@ -130,9 +138,9 @@ An external agent runs as an untrusted third-party CLI. It must receive its Huab 1. **Namespace strip at the transport boundary.** When the server forks the embedded agentlet daemon, the entire `HUABU_` namespace is stripped from the inherited environment (`mountAgenetes({ hostEnvPrefix: 'HUABU_', hostEnvAllowlist: [] })`). The daemon needs none of it, so its allowlist is empty; because every agent is spawned by that daemon, the agents inherit an already-clean environment. Non-namespaced OS/toolchain variables (`PATH`, `HOME`, `TMPDIR`, …) always pass through so the agent CLI still runs. The mechanism (`filterHostNamespacedEnv`) is host-agnostic — the prefix and allowlist are Huabu policy passed in by `apps/server`. -2. **Explicit reachback injection.** The only `HUABU_*` values an agent legitimately sees are re-added per-spawn by `buildReachbackEnv()`: `HUABU_RFS_URL` and `HUABU_THREAD_ID`. Anything an agent should see in future must be added to that injection point — inheritance is not a supported channel. +2. **Explicit reachback injection.** Per-session `buildReachbackEnv()` supplies `HUABU_RFS_URL` and `HUABU_THREAD_ID`; the host-owned launcher bootstrap supplies SDK and available RFS entry coordinates. Inheritance is not a supported channel for Huabu configuration. -**Consequence for adding env vars:** a new `HUABU_*` variable is denied to agents by default. To expose one, add it to `buildReachbackEnv()` (for agents) or to `hostEnvAllowlist` (for the daemon). A host secret such as `HUABU_SECRET_KEY` must never be added to either; it is additionally scrubbed from `process.env` after `initializeSecretStore()` consumes it (see [`credential-storage.md`](./credential-storage.md)). This isolation only covers the `HUABU_` namespace — non-namespaced secrets a deployment exports into the server's own environment (e.g. provider API keys) are not filtered and should not be relied upon as agent-invisible. +**Consequence for adding env vars:** a new `HUABU_*` variable is denied to agents by default. To expose session context, add it to `buildReachbackEnv()`; device-local non-secret tools use explicit host bootstrap. A host secret such as `HUABU_SECRET_KEY` must never be added to either; it is additionally scrubbed from `process.env` after `initializeSecretStore()` consumes it (see [`credential-storage.md`](./credential-storage.md)). This isolation only covers the `HUABU_` namespace — non-namespaced secrets a deployment exports into the server's own environment (e.g. provider API keys) are not filtered and should not be relied upon as agent-invisible. ## Code entry points diff --git a/docs/architecture/service-packages.md b/docs/architecture/service-packages.md index 6c36b7b4f..de04072e2 100644 --- a/docs/architecture/service-packages.md +++ b/docs/architecture/service-packages.md @@ -48,7 +48,7 @@ Internal Agent tools keep their high-level Huabu integrations. `generate_image` Product pipelines also retain reviewed Server adapters. The YouTube loader and Ink OCR request path resolve their registered Service configuration but do not import Package entries. -External Agent Packages provide a real `SKILL.md` and may provide an `entry.mjs` that imports `AGENTLET_SERVICE_SDK_URL`, leases one coherent runtime context containing the current Manifest and configuration, and implements only a useful baseline provider workflow. Every executable entry supports `-h` and `--help`; an Agent runs help before invocation because runtime Manifest constraints and configured defaults may not be derivable from the source alone. Entries define their own CLI mapping, use Manifest enum options as the authoritative choices, use explicitly mapped configuration fields as defaults, and let an explicit operation argument override only those defaults. The entry is not a complete provider SDK: the Skill links official provider documentation, and an Agent may modify its downloaded local copy for additional endpoints. The bundled Image and Tavily Packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore publish neither placeholder file. +External Agent Packages provide a real `SKILL.md` and may provide an `entry.mjs` that imports `HUABU_SERVICE_SDK_URL`, leases one coherent runtime context containing the current Manifest and configuration, and implements only a useful baseline provider workflow. Every executable entry supports `-h` and `--help`; an Agent runs help before invocation because runtime Manifest constraints and configured defaults may not be derivable from the source alone. Entries define their own CLI mapping, use Manifest enum options as the authoritative choices, use explicitly mapped configuration fields as defaults, and let an explicit operation argument override only those defaults. The entry is not a complete provider SDK: the Skill links official provider documentation, and an Agent may modify its downloaded local copy for additional endpoints. The bundled Image and Tavily Packages are Agent-facing. YouTube Transcripts and Ink OCR are not Agent-facing and therefore publish neither placeholder file. ## Owner Settings API @@ -78,17 +78,17 @@ Manifest and Skill responses contain no credentials. Lease requires the normal a Package download streams a ZIP on demand from the validated Package record without a temporary file or ZIP cache. The archive contains one `/` root directory, `service.yaml`, and exactly the files declared by `package.files`; undeclared tests and development files are excluded. The response uses the Package content hash as its ETag. Phase 1 resolves records from bundled directories; a future validated custom-Service installation can expose the same immutable root, exact file list, and hash without changing the route. -## Agentlet SDK +## Huabu client SDK -Agentlet publishes `dist/service-sdk/index.js`. The daemon computes its absolute `file://` URL relative to its own `import.meta.url` and injects it as the authoritative `AGENTLET_SERVICE_SDK_URL` after workload environment values, so a Profile or session cannot replace it. +`packages/client-runtime` publishes the self-contained `dist/service-sdk.js`. Remote `huabu-daemon` and the embedded Server resolve the device-local artifact through the same resolver/bootstrap builder and inject its absolute `file://` URL as `HUABU_SERVICE_SDK_URL`. Generic Agentlet forwards and protects that opaque bootstrap key without owning SDK code. No old SDK alias or fallback is provided; previously downloaded entries must be refreshed and Agents restarted to obtain the new bootstrap. Node is selected by the Agent, not supplied or checked by the daemon. Without Node, the existing authenticated HTTP lease is still available to any HTTP-capable business process. -`leaseService(id)` obtains a fresh `{ id, version, manifest, config }` context without downloading or loading Package code. `withServiceContext(id, callback)` is the scoped convenience wrapper used by `entry.mjs`. The SDK verifies that the leased Manifest identity and version match the enclosing context, reports bounded status-only request failures, and does not include response bodies that could contain credentials. +`leaseService(id)` obtains a fresh `{ id, version, manifest, config }` context without downloading or loading Package code. `withServiceContext(id, callback)` is the scoped convenience wrapper used by `entry.mjs`. The SDK validates the canonical shared `serviceLeaseSchema`, including identity/version coherence and declared config fields, reports bounded status-only request failures, and does not include malformed JSON or response bodies that could contain credentials. The SDK reduces accidental persistence but is not a sandbox. A trusted External Agent and loaded client share the Agent process's filesystem, network, RFS bearer, and provider credentials. Static provider credentials cannot be revoked after disclosure except by provider-side rotation. ## Build and packaging -Server development reads Packages from `apps/server/src/services`. The Server bundle copies that directory to `dist-bundle/services`, while RFS distribution still selects only Manifest-declared files. The bundled Agentlet build emits both `agentlet/index.js` and `agentlet/service-sdk/index.js`; the published Agentlet npm package already includes its complete `dist` tree. +Server development reads Packages from `apps/server/src/services`. The Server bundle copies that directory to `dist-bundle/services`, while RFS distribution still selects only Manifest-declared files. Agentlet is bundled separately as `agentlet/index.js` with no SDK. The self-contained client runtime is copied into `dist-bundle/client-runtime`; Desktop resources include its JS files and explicit ESM `package.json`. Server build/bundle and development startup build the runtime. `pnpm start:daemon` builds Agentlet and the runtime before running the source launcher, without global PATH installation. ## Code entry points @@ -100,4 +100,6 @@ Server development reads Packages from `apps/server/src/services`. The Server bu | `apps/server/src/modules/services/services.route.ts` | Owner Generic Settings API | | `apps/server/src/modules/remote_fs/rfs.route.ts` | Authenticated Service discovery, files, and lease | | `apps/web/src/components/Settings/sections/ServicesSettings.tsx` | Manifest-driven Services UI | -| `external/agentlet/packages/local/src/service-sdk/index.ts` | External Agent SDK | +| `packages/client-runtime/src/service-sdk.ts` | Canonical lease-only External Agent SDK | +| `packages/client-runtime/src/bootstrap.ts` | Shared device-local artifacts and host bootstrap | +| `packages/client-runtime/src/daemon.ts` | Source-checkout launcher and connection env inputs | diff --git a/docs/proposals/service-packages.md b/docs/proposals/service-packages.md index 2b7b7a7db..390d2b1cd 100644 --- a/docs/proposals/service-packages.md +++ b/docs/proposals/service-packages.md @@ -4,6 +4,8 @@ Status: Accepted Last updated: 2026-10-10 +The SDK ownership recorded in this design has been superseded by #292: the implemented SDK lives in `packages/client-runtime` and uses `HUABU_SERVICE_SDK_URL`, with no legacy alias. See [current Service architecture](../architecture/service-packages.md); the original Agentlet SDK references below preserve design history rather than the current bootstrap contract. + ## 摘要 本 Proposal 定义统一的 Service Package，用一个受严格校验的 YAML Manifest 描述配置字段、存储 namespace 与精确发布文件，同时让 Internal Agent Tool、External Agent 与产品 Pipeline 保留适合各自信任边界的执行路径。 diff --git a/eslint.config.mjs b/eslint.config.mjs index b9dbe359e..fb195694b 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -67,6 +67,7 @@ export default typescriptEslint.config( './apps/docs/tsconfig.json', './apps/docs/tsconfig.node.json', './packages/shared/tsconfig.json', + './packages/client-runtime/tsconfig.json', './external/agenetes/packages/protocol/tsconfig.json', './external/agenetes/packages/runtime/tsconfig.json', ], @@ -83,6 +84,7 @@ export default typescriptEslint.config( './apps/web/tsconfig.json', './apps/docs/tsconfig.json', './packages/shared/tsconfig.json', + './packages/client-runtime/tsconfig.json', './external/agenetes/packages/protocol/tsconfig.json', './external/agenetes/packages/runtime/tsconfig.json', ], diff --git a/package.json b/package.json index 182f73f28..c2ad2c8fd 100644 --- a/package.json +++ b/package.json @@ -2,17 +2,20 @@ "name": "huabu", "private": true, "scripts": { - "predev": "pnpm run build:agentlet && pnpm run build:agenetes", + "predev": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm run build:client-runtime", "dev": "node scripts/dev.mjs", "dev:server": "pnpm --filter @huabu/server dev", "dev:web": "pnpm --filter @huabu/web dev", "dev:shared": "pnpm --filter @huabu/shared dev", - "predev:desktop": "pnpm run build:agentlet && pnpm run build:agenetes", + "predev:desktop": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm run build:client-runtime", "dev:desktop": "node scripts/dev-desktop.mjs", "start:web": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm --filter @huabu/shared build && pnpm --filter @huabu/server bundle && pnpm --filter @huabu/web build && node scripts/start-web.mjs", "start:desktop": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm --filter @huabu/shared build && pnpm --filter @huabu/server bundle && pnpm --filter @huabu/web build && pnpm --filter @huabu/desktop dev", "build": "pnpm -r --if-present run build", "build:agentlet": "pnpm --filter @agentlet/protocol --filter agentlet run build", + "build:client-runtime": "pnpm --filter @huabu/client-runtime build", + "prestart:daemon": "pnpm run build:agentlet && pnpm run build:client-runtime", + "start:daemon": "node packages/client-runtime/dist/daemon.js", "build:agenetes": "pnpm --filter @agenetes/protocol --filter @agenetes/runtime --filter @agenetes/agent-profile --filter @agenetes/agentlet-gateway --filter @agenetes/agentlet-host --filter @agenetes/acp-driver --filter @agenetes/pi-driver --filter @agenetes/agenetes run build", "build:desktop": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm --filter @huabu/shared build && pnpm --filter @huabu/server bundle && pnpm --filter @huabu/web build && pnpm --filter @huabu/desktop dist", "build:desktop:mac": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm --filter @huabu/shared build && pnpm --filter @huabu/server bundle && pnpm --filter @huabu/web build && pnpm --filter @huabu/desktop dist:mac", @@ -33,12 +36,12 @@ "lint:fix": "eslint . --fix", "format": "prettier --write .", "format:check": "prettier --check .", - "pretypecheck": "pnpm run build:agentlet && pnpm run build:agenetes", + "pretypecheck": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm run build:client-runtime", "typecheck": "pnpm -r --parallel typecheck", "hooks:install": "node scripts/install-git-hooks.mjs", "hooks:uninstall": "node scripts/uninstall-git-hooks.mjs", "clean": "node scripts/clean.mjs", - "postinstall": "pnpm run build:agentlet && pnpm run build:agenetes && node scripts/install-agentlet-to-path.mjs", + "postinstall": "pnpm run build:agentlet && pnpm run build:agenetes && pnpm run build:client-runtime", "test:storage-backends": "pnpm --filter @huabu/server test:storage" }, "engines": { diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json new file mode 100644 index 000000000..57442e727 --- /dev/null +++ b/packages/client-runtime/package.json @@ -0,0 +1,30 @@ +{ + "name": "@huabu/client-runtime", + "private": true, + "type": "module", + "exports": { + ".": { + "types": "./src/bootstrap.ts", + "import": "./dist/bootstrap.js" + }, + "./service-sdk": { + "types": "./src/service-sdk.ts", + "import": "./dist/service-sdk.js" + } + }, + "scripts": { + "build": "tsup", + "typecheck": "tsc --noEmit", + "test": "vitest run" + }, + "dependencies": { + "@huabu/shared": "workspace:*", + "dotenv": "^17.2.3" + }, + "devDependencies": { + "@types/node": "^24.13.3", + "tsup": "^8.5.1", + "typescript": "^6.0.3", + "vitest": "^4.1.11" + } +} diff --git a/packages/client-runtime/src/bootstrap.ts b/packages/client-runtime/src/bootstrap.ts new file mode 100644 index 000000000..cf80cdc0d --- /dev/null +++ b/packages/client-runtime/src/bootstrap.ts @@ -0,0 +1,73 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { existsSync } from 'node:fs'; +import { isAbsolute, resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; + +export { + normalizePublicOrigin, + resolveConfiguredPublicOrigin, + InvalidPublicOriginError, +} from './public-origin.js'; + +export interface RuntimeArtifacts { + daemonEntry: string | null; + serviceSdkEntry: string | null; + rfsEntry: string | null; +} + +export function resolveRuntimeArtifacts(options: { + repoRoot?: string; + bundleDir?: string; + daemonOverride?: string; +}): RuntimeArtifacts { + const firstExisting = (paths: (string | undefined)[]): string | null => + paths.find((path): path is string => + Boolean(path && isAbsolute(path) && existsSync(path)), + ) ?? null; + const { repoRoot, bundleDir } = options; + return { + daemonEntry: firstExisting([ + options.daemonOverride, + bundleDir && resolve(bundleDir, 'agentlet/index.js'), + repoRoot && + resolve(repoRoot, 'external/agentlet/packages/local/dist/index.js'), + ]), + serviceSdkEntry: firstExisting([ + bundleDir && resolve(bundleDir, 'client-runtime/service-sdk.js'), + repoRoot && + resolve(repoRoot, 'packages/client-runtime/dist/service-sdk.js'), + ]), + rfsEntry: firstExisting([ + bundleDir && resolve(bundleDir, 'client-runtime/rfs.js'), + repoRoot && resolve(repoRoot, 'packages/client-runtime/dist/rfs.js'), + ]), + }; +} + +export function buildHuabuBootstrapEnv( + artifacts: RuntimeArtifacts, +): Readonly> { + const env: Record = {}; + if (artifacts.serviceSdkEntry) + env.HUABU_SERVICE_SDK_URL = pathToFileURL(artifacts.serviceSdkEntry).href; + if (artifacts.rfsEntry) env.HUABU_RFS_ENTRY = artifacts.rfsEntry; + return Object.freeze(env); +} + +export function buildDaemonChildEnv( + inherited: NodeJS.ProcessEnv, + token: string, + platform: NodeJS.Platform = process.platform, +): NodeJS.ProcessEnv { + const env: NodeJS.ProcessEnv = {}; + for (const [key, value] of Object.entries(inherited)) { + const normalized = platform === 'win32' ? key.toUpperCase() : key; + if (normalized.startsWith('HUABU_') || normalized === 'AGENTLET_TOKEN') + continue; + env[key] = value; + } + env.AGENTLET_TOKEN = token; + return env; +} diff --git a/packages/client-runtime/src/daemon.ts b/packages/client-runtime/src/daemon.ts new file mode 100644 index 000000000..8d15fc2f8 --- /dev/null +++ b/packages/client-runtime/src/daemon.ts @@ -0,0 +1,239 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { spawn } from 'node:child_process'; +import { readFileSync } from 'node:fs'; +import { constants } from 'node:os'; +import { resolve } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; +import { parseArgs } from 'node:util'; + +import { parse } from 'dotenv'; + +import { + buildDaemonChildEnv, + buildHuabuBootstrapEnv, + resolveRuntimeArtifacts, +} from './bootstrap.js'; +import { normalizePublicOrigin } from './public-origin.js'; + +const CONNECTION_KEYS = new Set([ + 'HUABU_PUBLIC_ORIGIN', + 'HUABU_CONNECTION_TOKEN', +]); + +export function parseConnectionEnvFile( + text: string, + platform: NodeJS.Platform = process.platform, +): Record { + if (text.includes('\0')) throw new Error('Environment file contains NUL'); + const result: Record = {}; + const seen = new Set(); + const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/); + for (let index = 0; index < lines.length; index++) { + let statement = lines[index] ?? ''; + if (!statement.trim() || statement.trimStart().startsWith('#')) continue; + const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec( + statement, + ); + if (!match) + throw new Error(`Invalid environment assignment at line ${index + 1}`); + const key = match[1]; + const value = match[2] ?? ''; + if (!key) throw new Error('Invalid environment key'); + const canonical = platform === 'win32' ? key.toUpperCase() : key; + if (seen.has(canonical)) + throw new Error(`Duplicate environment key: ${key}`); + seen.add(canonical); + const quote = value[0]; + if (quote === '"' || quote === "'" || quote === '`') { + let quoted = value; + let closing = -1; + while (closing < 0) { + for (let offset = 1; offset < quoted.length; offset++) { + if (quoted[offset] !== quote) continue; + let slashes = 0; + for ( + let before = offset - 1; + before >= 0 && quoted[before] === '\\'; + before-- + ) + slashes++; + if (slashes % 2 === 0) { + closing = offset; + break; + } + } + if (closing < 0) { + index++; + if (index >= lines.length) + throw new Error(`Unclosed environment value for ${key}`); + quoted += `\n${lines[index]}`; + statement += `\n${lines[index]}`; + } + } + const trailing = quoted.slice(closing + 1).trim(); + if (trailing && !trailing.startsWith('#')) + throw new Error(`Invalid environment value for ${key}`); + } + const parsed = parse(statement); + if (!Object.hasOwn(parsed, key)) + throw new Error(`Invalid environment value for ${key}`); + if (CONNECTION_KEYS.has(canonical)) { + result[canonical] = parsed[key] ?? ''; + } + } + return result; +} + +export function readConnectionConfig(options: { + repoRoot: string; + envFile?: string; + inherited?: NodeJS.ProcessEnv; + platform?: NodeJS.Platform; +}): { origin: string; token: string } { + const platform = options.platform ?? process.platform; + if (options.envFile !== undefined && !options.envFile.trim()) + throw new Error('--env-file requires a non-empty path'); + const path = options.envFile + ? resolve(options.envFile) + : resolve(options.repoRoot, '.env'); + let fileEnv: Record = {}; + try { + fileEnv = parseConnectionEnvFile(readFileSync(path, 'utf8'), platform); + } catch (error) { + if ( + !( + error instanceof Error && + 'code' in error && + error.code === 'ENOENT' && + !options.envFile + ) + ) + throw error; + } + const inherited: Record = {}; + if (!options.envFile) { + for (const [key, value] of Object.entries( + options.inherited ?? process.env, + )) { + const canonical = platform === 'win32' ? key.toUpperCase() : key; + if (!CONNECTION_KEYS.has(canonical)) continue; + if (Object.hasOwn(inherited, canonical)) + throw new Error(`Duplicate environment key: ${canonical}`); + inherited[canonical] = value; + } + } + const connection = { ...fileEnv, ...inherited }; + const token = connection.HUABU_CONNECTION_TOKEN; + const origin = connection.HUABU_PUBLIC_ORIGIN; + if (!origin?.trim()) + throw new Error('huabu-daemon requires HUABU_PUBLIC_ORIGIN'); + if (!token?.trim()) + throw new Error('huabu-daemon requires HUABU_CONNECTION_TOKEN'); + return { origin: normalizePublicOrigin(origin), token }; +} + +export function parseDaemonArgs(argv: string[]) { + return parseArgs({ + args: argv[0] === '--' ? argv.slice(1) : argv, + options: { + help: { type: 'boolean', short: 'h' }, + 'env-file': { type: 'string' }, + 'max-agents': { type: 'string' }, + 'agentlet-id': { type: 'string' }, + 'reconnect-max': { type: 'string' }, + 'buffer-limit': { type: 'string' }, + heartbeat: { type: 'string' }, + 'log-level': { type: 'string' }, + 'log-file': { type: 'string' }, + }, + allowPositionals: false, + strict: true, + }).values; +} + +export async function runDaemon( + argv = process.argv.slice(2), + repoRoot = fileURLToPath(new URL('../../../', import.meta.url)), +): Promise { + const options = parseDaemonArgs(argv); + if (options.help) { + process.stdout.write( + 'Usage: pnpm start:daemon [--env-file ] [Agentlet operational options]\nConnection: HUABU_PUBLIC_ORIGIN and HUABU_CONNECTION_TOKEN, via process env or dotenv.\nOptions: --max-agents, --agentlet-id, --reconnect-max, --buffer-limit, --heartbeat, --log-level, --log-file.\n', + ); + return 0; + } + const { origin, token } = readConnectionConfig({ + repoRoot, + envFile: options['env-file'], + }); + const server = new URL('/api/acp/agent', origin); + const insecure = server.protocol === 'http:'; + server.protocol = insecure ? 'ws:' : 'wss:'; + const artifacts = resolveRuntimeArtifacts({ repoRoot }); + if (!artifacts.daemonEntry || !artifacts.serviceSdkEntry) + throw new Error( + 'Missing built Agentlet/client-runtime artifacts; run pnpm start:daemon from a prepared checkout', + ); + const bootstrap = buildHuabuBootstrapEnv(artifacts); + const args = [ + 'daemon', + '--server', + server.href, + ...(insecure ? ['--allow-insecure'] : []), + ...Object.entries(bootstrap).flatMap(([key, value]) => [ + '--env-inject', + `${key}=${value}`, + ]), + ]; + for (const [key, value] of Object.entries(options)) { + if (key === 'env-file' || key === 'help' || typeof value !== 'string') + continue; + args.push(`--${key}`, value); + } + if (insecure) + process.stderr.write( + 'Warning: HTTP/WS sends the connection credential without TLS.\n', + ); + const child = spawn(process.execPath, [artifacts.daemonEntry, ...args], { + env: buildDaemonChildEnv(process.env, token), + stdio: 'inherit', + shell: false, + }); + const interrupt = () => { + child.kill('SIGINT'); + }; + const terminate = () => { + child.kill('SIGTERM'); + }; + process.on('SIGINT', interrupt); + process.on('SIGTERM', terminate); + try { + return await new Promise((complete, reject) => { + child.once('error', reject); + child.once('exit', (code, signal) => + complete(signal ? 128 + constants.signals[signal] : (code ?? 1)), + ); + }); + } finally { + process.removeListener('SIGINT', interrupt); + process.removeListener('SIGTERM', terminate); + } +} + +if ( + process.argv[1] && + pathToFileURL(resolve(process.argv[1])).href === import.meta.url +) { + runDaemon() + .then((code) => { + process.exitCode = code; + }) + .catch((error) => { + process.stderr.write( + `${error instanceof Error ? error.message : String(error)}\n`, + ); + process.exitCode = 1; + }); +} diff --git a/packages/client-runtime/src/public-origin.ts b/packages/client-runtime/src/public-origin.ts new file mode 100644 index 000000000..3b299490c --- /dev/null +++ b/packages/client-runtime/src/public-origin.ts @@ -0,0 +1,45 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +export class InvalidPublicOriginError extends Error {} + +export function normalizePublicOrigin(rawValue: string): string { + let url: URL; + try { + url = new URL(rawValue.trim()); + } catch { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must be an absolute HTTP(S) origin', + ); + } + + if (url.protocol !== 'http:' && url.protocol !== 'https:') { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must use HTTP or HTTPS', + ); + } + if (url.username || url.password) { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must not include credentials', + ); + } + if (url.search || url.hash) { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must not include a query or fragment', + ); + } + if (url.pathname !== '/') { + throw new InvalidPublicOriginError( + 'HUABU_PUBLIC_ORIGIN must be an origin without a path prefix', + ); + } + + return url.origin; +} + +export function resolveConfiguredPublicOrigin( + env: NodeJS.ProcessEnv = process.env, +): string | undefined { + const rawValue = env.HUABU_PUBLIC_ORIGIN?.trim(); + return rawValue ? normalizePublicOrigin(rawValue) : undefined; +} diff --git a/packages/client-runtime/src/service-sdk.ts b/packages/client-runtime/src/service-sdk.ts new file mode 100644 index 000000000..e1bc582f8 --- /dev/null +++ b/packages/client-runtime/src/service-sdk.ts @@ -0,0 +1,71 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { serviceLeaseSchema } from '@huabu/shared/service-package'; + +import type { + ServiceConfigurationField, + ServiceLease, +} from '@huabu/shared/service-package'; +export type { + ServiceConfigurationField, + ServiceManifest, + ServiceLease, +} from '@huabu/shared/service-package'; +export type ServiceFieldOption = NonNullable< + ServiceConfigurationField['options'] +>[number]; + +function requiredEnvironment(name: 'HUABU_RFS_URL' | 'AGENTLET_TOKEN'): string { + const value = process.env[name]?.trim(); + if (!value) throw new Error(`Service SDK requires ${name}`); + return value; +} + +async function serviceFetch( + path: string, + init?: RequestInit, +): Promise { + const baseUrl = requiredEnvironment('HUABU_RFS_URL').replace(/\/+$/, ''); + const token = requiredEnvironment('AGENTLET_TOKEN'); + const response = await fetch(`${baseUrl}${path}`, { + ...init, + headers: { + Authorization: `Bearer ${token}`, + ...(init?.headers ?? {}), + }, + }); + if (!response.ok) { + throw new Error(`Service request failed (${response.status})`); + } + return response; +} + +export async function leaseService(serviceId: string): Promise { + if (!/^[a-z][a-z0-9-]{0,63}$/.test(serviceId)) { + throw new Error('Invalid Service id'); + } + const response = await serviceFetch( + `/services/${encodeURIComponent(serviceId)}/lease`, + { method: 'POST' }, + ); + let body: unknown; + try { + body = await response.json(); + } catch (error) { + if (error instanceof SyntaxError) throw new Error('Invalid Service lease'); + throw error; + } + const lease = serviceLeaseSchema.safeParse(body); + if (!lease.success || lease.data.id !== serviceId) { + throw new Error('Invalid Service lease'); + } + return lease.data; +} + +export async function withServiceContext( + serviceId: string, + run: (service: ServiceLease) => Promise | T, +): Promise { + return run(await leaseService(serviceId)); +} diff --git a/packages/client-runtime/tests/daemon.test.ts b/packages/client-runtime/tests/daemon.test.ts new file mode 100644 index 000000000..9d2c229e7 --- /dev/null +++ b/packages/client-runtime/tests/daemon.test.ts @@ -0,0 +1,311 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { + existsSync, + mkdtempSync, + mkdirSync, + readFileSync, + rmSync, + writeFileSync, +} from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { pathToFileURL } from 'node:url'; + +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { + buildDaemonChildEnv, + buildHuabuBootstrapEnv, + resolveRuntimeArtifacts, +} from '../src/bootstrap.js'; +import { + parseConnectionEnvFile, + parseDaemonArgs, + readConnectionConfig, + runDaemon, +} from '../src/daemon.js'; + +const directories: string[] = []; +afterEach(() => { + vi.unstubAllEnvs(); + for (const directory of directories.splice(0)) + rmSync(directory, { recursive: true, force: true }); +}); +function root() { + const directory = mkdtempSync(join(tmpdir(), 'huabu-runtime spaced-')); + directories.push(directory); + return directory; +} + +describe('connection configuration', () => { + it('accepts direct env without a file and normalizes the canonical origin', () => { + expect( + readConnectionConfig({ + repoRoot: root(), + inherited: { + HUABU_PUBLIC_ORIGIN: 'https://example.test/', + HUABU_CONNECTION_TOKEN: 'token', + }, + }), + ).toEqual({ origin: 'https://example.test', token: 'token' }); + }); + + it('uses shell overrides for default dotenv but isolates an explicit file', () => { + const repoRoot = root(); + const file = join(repoRoot, '.env'); + writeFileSync( + file, + 'HUABU_PUBLIC_ORIGIN=https://file.test\nHUABU_CONNECTION_TOKEN=file-token\n', + ); + const inherited = { + HUABU_PUBLIC_ORIGIN: 'https://shell.test', + HUABU_CONNECTION_TOKEN: 'shell-token', + }; + expect(readConnectionConfig({ repoRoot, inherited })).toEqual({ + origin: 'https://shell.test', + token: 'shell-token', + }); + expect( + readConnectionConfig({ repoRoot, inherited, envFile: file }), + ).toEqual({ origin: 'https://file.test', token: 'file-token' }); + writeFileSync(file, 'HUABU_PUBLIC_ORIGIN=https://file.test\n'); + expect(() => + readConnectionConfig({ repoRoot, inherited, envFile: file }), + ).toThrow('HUABU_CONNECTION_TOKEN'); + expect(() => + readConnectionConfig({ + repoRoot, + inherited, + envFile: join(repoRoot, 'missing'), + }), + ).toThrow('ENOENT'); + expect(() => + readConnectionConfig({ repoRoot, inherited, envFile: '' }), + ).toThrow('--env-file requires'); + }); + + it('parses dotenv as data, filters unrelated fields and preserves opaque credential values', () => { + expect( + parseConnectionEnvFile( + '# comment\nexport HUABU_PUBLIC_ORIGIN="https://example.test/" # origin\nHUABU_CONNECTION_TOKEN="a=b ${HOME}"\nOTHER=`line\nmore`\n', + ), + ).toEqual({ + HUABU_PUBLIC_ORIGIN: 'https://example.test/', + HUABU_CONNECTION_TOKEN: 'a=b ${HOME}', + }); + }); + + it.each([ + 'HUABU_CONNECTION_TOKEN=secret\nHUABU_CONNECTION_TOKEN=other', + 'HUABU_CONNECTION_TOKEN="secret', + 'HUABU_CONNECTION_TOKEN="secret"extra', + 'malformed secret', + 'HUABU_CONNECTION_TOKEN=secret\0', + ])('rejects malformed files without exposing credential values', (text) => { + expect(() => parseConnectionEnvFile(text)).toThrow(); + try { + parseConnectionEnvFile(text); + } catch (error) { + expect(String(error)).not.toContain('secret'); + } + }); + + it('rejects Windows case collisions in files and inherited connection input', () => { + expect(() => + parseConnectionEnvFile( + 'HUABU_CONNECTION_TOKEN=a\nhuabu_connection_token=b', + 'win32', + ), + ).toThrow('Duplicate'); + expect(() => + readConnectionConfig({ + repoRoot: root(), + platform: 'win32', + inherited: { + HUABU_PUBLIC_ORIGIN: 'https://host.test', + HUABU_CONNECTION_TOKEN: 'a', + huabu_connection_token: 'b', + }, + }), + ).toThrow('Duplicate'); + }); + + it.each([ + 'https://host.test/path', + 'https://user:password@host.test', + 'wss://host.test', + 'https://host.test?query', + 'https://host.test#fragment', + ])('rejects non-origin configuration %s', (origin) => { + expect(() => + readConnectionConfig({ + repoRoot: root(), + inherited: { + HUABU_PUBLIC_ORIGIN: origin, + HUABU_CONNECTION_TOKEN: 'token', + }, + }), + ).toThrow('HUABU_PUBLIC_ORIGIN'); + }); + + it.each(['--server', '--token', '--env-inject', '--allow-insecure'])( + 'does not permit protected launch override %s', + (option) => { + expect(() => parseDaemonArgs([option, 'value'])).toThrow(); + }, + ); +}); + +describe('device-local runtime bootstrap', () => { + it('forwards termination to its actual child and removes signal listeners', async () => { + const repoRoot = root(); + mkdirSync(join(repoRoot, 'packages/client-runtime/dist'), { + recursive: true, + }); + mkdirSync(join(repoRoot, 'external/agentlet/packages/local/dist'), { + recursive: true, + }); + writeFileSync( + join(repoRoot, 'packages/client-runtime/dist/service-sdk.js'), + 'export {};', + ); + const ready = join(repoRoot, 'ready'); + writeFileSync( + join(repoRoot, 'external/agentlet/packages/local/dist/index.js'), + `process.on('SIGTERM', () => process.exit(9)); require('node:fs').writeFileSync(${JSON.stringify(ready)}, 'ready'); setTimeout(() => process.exit(66), 5000);`, + ); + vi.stubEnv('HUABU_PUBLIC_ORIGIN', 'https://host.test'); + vi.stubEnv('HUABU_CONNECTION_TOKEN', 'token'); + const initial = process.listeners('SIGTERM'); + const running = runDaemon([], repoRoot); + const handler = process + .listeners('SIGTERM') + .find((listener) => !initial.includes(listener)); + if (!handler) throw new Error('Missing source launcher signal handler'); + try { + const deadline = Date.now() + 3000; + while (!existsSync(ready)) { + if (Date.now() >= deadline) + throw new Error('Source launcher child did not start'); + await new Promise((resolve) => setTimeout(resolve, 10)); + } + handler('SIGTERM'); + expect(await running).toBe(9); + expect(process.listeners('SIGTERM')).toEqual(initial); + } finally { + handler('SIGTERM'); + await running; + } + }); + it('only advertises actual artifacts and never provides Node coordinates', () => { + const repoRoot = root(); + mkdirSync(join(repoRoot, 'packages/client-runtime/dist'), { + recursive: true, + }); + const sdk = join(repoRoot, 'packages/client-runtime/dist/service-sdk.js'); + writeFileSync(sdk, 'export {};'); + const artifacts = resolveRuntimeArtifacts({ repoRoot }); + expect(artifacts).toEqual({ + daemonEntry: null, + serviceSdkEntry: sdk, + rfsEntry: null, + }); + const env = buildHuabuBootstrapEnv(artifacts); + expect(env).toEqual({ HUABU_SERVICE_SDK_URL: pathToFileURL(sdk).href }); + expect(Object.isFrozen(env)).toBe(true); + expect( + buildHuabuBootstrapEnv({ + daemonEntry: null, + serviceSdkEntry: null, + rfsEntry: null, + }), + ).toEqual({}); + }); + + it('prefers self-contained bundle layout and supports explicit daemon overrides', () => { + const bundleDir = root(); + mkdirSync(join(bundleDir, 'agentlet')); + mkdirSync(join(bundleDir, 'client-runtime')); + for (const file of [ + 'agentlet/index.js', + 'client-runtime/service-sdk.js', + 'client-runtime/rfs.js', + ]) + writeFileSync(join(bundleDir, file), 'export {};'); + const artifacts = resolveRuntimeArtifacts({ bundleDir }); + expect(buildHuabuBootstrapEnv(artifacts)).toEqual({ + HUABU_SERVICE_SDK_URL: pathToFileURL( + join(bundleDir, 'client-runtime/service-sdk.js'), + ).href, + HUABU_RFS_ENTRY: join(bundleDir, 'client-runtime/rfs.js'), + }); + const override = join(bundleDir, 'override.js'); + writeFileSync(override, 'export {};'); + expect( + resolveRuntimeArtifacts({ bundleDir, daemonOverride: override }) + .daemonEntry, + ).toBe(override); + }); + + it('filters deployment namespace and authoritative token variants before child launch', () => { + const inherited = { + PATH: '/tools', + HUABU_SECRET_KEY: 'secret', + huabu_connection_token: 'secret', + Agentlet_Token: 'old', + }; + expect(buildDaemonChildEnv(inherited, 'new', 'win32')).toEqual({ + PATH: '/tools', + AGENTLET_TOKEN: 'new', + }); + expect(inherited.Agentlet_Token).toBe('old'); + }); + + it.each([ + ['https://host.test', 'wss://host.test/api/acp/agent', false], + ['http://host.test:1234', 'ws://host.test:1234/api/acp/agent', true], + ])( + 'launches an actual child for %s with token only in env and propagates exit', + async (origin, endpoint, insecure) => { + const repoRoot = root(); + mkdirSync(join(repoRoot, 'packages/client-runtime/dist'), { + recursive: true, + }); + mkdirSync(join(repoRoot, 'external/agentlet/packages/local/dist'), { + recursive: true, + }); + writeFileSync( + join(repoRoot, 'packages/client-runtime/dist/service-sdk.js'), + 'export {};', + ); + const output = join(repoRoot, 'child.json'); + writeFileSync( + join(repoRoot, 'external/agentlet/packages/local/dist/index.js'), + `require('node:fs').writeFileSync(${JSON.stringify(output)}, JSON.stringify({argv:process.argv.slice(2),token:process.env.AGENTLET_TOKEN,secret:process.env.HUABU_SECRET_KEY})); process.exit(7);`, + ); + const envFile = join(repoRoot, 'connection.env'); + writeFileSync( + envFile, + `HUABU_PUBLIC_ORIGIN=${origin}\nHUABU_CONNECTION_TOKEN=child-secret\n`, + ); + vi.stubEnv('HUABU_SECRET_KEY', 'must-not-inherit'); + expect( + await runDaemon( + ['--', '--env-file', envFile, '--max-agents', '4'], + repoRoot, + ), + ).toBe(7); + const result = JSON.parse(readFileSync(output, 'utf8')); + expect(result.token).toBe('child-secret'); + expect(result.secret).toBeUndefined(); + expect(result.argv.slice(0, 3)).toEqual(['daemon', '--server', endpoint]); + expect(result.argv.includes('--allow-insecure')).toBe(insecure); + expect(result.argv).not.toContain('child-secret'); + expect(result.argv).not.toContain('--token'); + expect(result.argv).not.toContain('HUABU_NODE_EXECUTABLE'); + expect(result.argv.slice(-2)).toEqual(['--max-agents', '4']); + }, + ); +}); diff --git a/packages/client-runtime/tests/service-sdk.test.ts b/packages/client-runtime/tests/service-sdk.test.ts new file mode 100644 index 000000000..76c7e54d2 --- /dev/null +++ b/packages/client-runtime/tests/service-sdk.test.ts @@ -0,0 +1,152 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; + +import { leaseService, withServiceContext } from '../src/service-sdk.js'; + +const manifest = { + schema: 'huabu-service/v1', + id: 'example', + version: '1.0.0', + name: 'Example', + description: 'Example Service', + storage: { namespace: 'integration.example' }, + package: { files: ['SKILL.md', 'entry.mjs'] }, + configuration: [ + { + id: 'quality', + label: 'Quality', + type: 'enum', + required: true, + options: [{ value: 'high', label: 'high' }], + }, + { + id: 'apiKey', + label: 'API key', + type: 'secret', + required: true, + }, + ], +} as const; + +afterEach(() => { + vi.unstubAllGlobals(); + delete process.env.HUABU_RFS_URL; + delete process.env.AGENTLET_TOKEN; +}); + +describe('Service SDK', () => { + it.each([ + { id: 'other', version: '1.0.0', manifest, config: {} }, + { id: 'example', version: '2.0.0', manifest, config: {} }, + { + id: 'example', + version: '1.0.0', + manifest, + config: { undeclared: 'secret' }, + }, + { + id: 'example', + version: '1.0.0', + manifest: { ...manifest, configuration: null }, + config: {}, + }, + ])( + 'rejects incoherent or undeclared configuration without leaking response fields', + async (body) => { + process.env.HUABU_RFS_URL = 'https://huabu.example/rfs/c1'; + process.env.AGENTLET_TOKEN = 'token'; + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue(new Response(JSON.stringify(body))), + ); + await expect(leaseService('example')).rejects.toThrow( + 'Invalid Service lease', + ); + }, + ); + + it('does not leak malformed JSON in response parse diagnostics', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/rfs/c1'; + process.env.AGENTLET_TOKEN = 'token'; + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue(new Response('{"secret":"provider-secret"')), + ); + await expect(leaseService('example')).rejects.toThrow( + 'Invalid Service lease', + ); + }); + + it('leases config without loading package code', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1'; + process.env.AGENTLET_TOKEN = 'agentlet-token'; + const fetchMock = vi.fn().mockResolvedValueOnce( + new Response( + JSON.stringify({ + id: 'example', + version: '1.0.0', + manifest, + config: { apiKey: 'provider-secret' }, + }), + { status: 200 }, + ), + ); + vi.stubGlobal('fetch', fetchMock); + + const lease = await leaseService('example'); + + expect(lease.config).toEqual({ apiKey: 'provider-secret' }); + expect(lease.manifest.configuration[0]?.id).toBe('quality'); + expect(fetchMock).toHaveBeenCalledTimes(1); + expect(fetchMock).toHaveBeenNthCalledWith( + 1, + 'https://huabu.example/api/rfs/canvas-1/services/example/lease', + expect.objectContaining({ + method: 'POST', + headers: { Authorization: 'Bearer agentlet-token' }, + }), + ); + }); + + it('provides config and lease metadata to a scoped callback', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1'; + process.env.AGENTLET_TOKEN = 'agentlet-token'; + vi.stubGlobal( + 'fetch', + vi.fn().mockResolvedValue( + new Response( + JSON.stringify({ + id: 'example', + version: '1.0.0', + manifest, + config: { apiKey: 'provider-secret' }, + }), + ), + ), + ); + + await expect( + withServiceContext( + 'example', + ({ config, manifest: serviceManifest }) => ({ + configured: Boolean(config.apiKey), + name: serviceManifest.name, + }), + ), + ).resolves.toEqual({ configured: true, name: 'Example' }); + }); + + it('does not include response bodies in provider-facing errors', async () => { + process.env.HUABU_RFS_URL = 'https://huabu.example/api/rfs/canvas-1'; + process.env.AGENTLET_TOKEN = 'agentlet-token'; + vi.stubGlobal( + 'fetch', + vi + .fn() + .mockResolvedValue(new Response('provider-secret', { status: 409 })), + ); + + await expect(leaseService('example')).rejects.toThrow( + 'Service request failed (409)', + ); + }); +}); diff --git a/packages/client-runtime/tsconfig.json b/packages/client-runtime/tsconfig.json new file mode 100644 index 000000000..e82fcc777 --- /dev/null +++ b/packages/client-runtime/tsconfig.json @@ -0,0 +1,9 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext" + }, + "include": ["src", "tests", "tsup.config.ts"] +} diff --git a/packages/client-runtime/tsup.config.ts b/packages/client-runtime/tsup.config.ts new file mode 100644 index 000000000..1d273666a --- /dev/null +++ b/packages/client-runtime/tsup.config.ts @@ -0,0 +1,17 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { defineConfig } from 'tsup'; + +export default defineConfig({ + entry: ['src/bootstrap.ts', 'src/daemon.ts', 'src/service-sdk.ts'], + format: ['esm'], + target: 'node24', + noExternal: [/.*/], + splitting: false, + clean: true, + removeNodeProtocol: false, + banner: { + js: "import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);", + }, +}); diff --git a/packages/shared/package.json b/packages/shared/package.json index 825cd044e..df36d573c 100644 --- a/packages/shared/package.json +++ b/packages/shared/package.json @@ -6,6 +6,10 @@ "main": "./src/index.ts", "types": "./src/index.ts", "exports": { + "./service-package": { + "types": "./src/types/api/service-package.ts", + "import": "./src/types/api/service-package.ts" + }, ".": { "types": "./src/index.ts", "import": "./src/index.ts" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9b2cd9f6c..e0c9fb7a1 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -211,6 +211,9 @@ importers: '@fastify/static': specifier: ^8.0.2 version: 8.3.0 + '@huabu/client-runtime': + specifier: workspace:* + version: link:../../packages/client-runtime '@huabu/shared': specifier: workspace:* version: link:../../packages/shared @@ -685,6 +688,28 @@ importers: specifier: ^5.9.0 version: 5.9.3 + packages/client-runtime: + dependencies: + '@huabu/shared': + specifier: workspace:* + version: link:../shared + dotenv: + specifier: ^17.2.3 + version: 17.4.2 + devDependencies: + '@types/node': + specifier: ^24.13.3 + version: 24.13.3 + tsup: + specifier: ^8.5.1 + version: 8.5.1(jiti@2.7.0)(postcss@8.5.25)(tsx@4.22.4)(typescript@6.0.3)(yaml@2.9.0) + typescript: + specifier: ^6.0.3 + version: 6.0.3 + vitest: + specifier: ^4.1.11 + version: 4.1.11(@opentelemetry/api@1.9.0)(@types/node@24.13.3)(happy-dom@20.11.1)(vite@7.3.5(@types/node@24.13.3)(jiti@2.7.0)(lightningcss@1.32.0)(tsx@4.22.4)(yaml@2.9.0)) + packages/shared: dependencies: '@agenetes/protocol': From 62a5d59db77ec9f331334dec3e0e3f75022b4ee9 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 06:45:03 +0000 Subject: [PATCH 25/36] feat: add optional raw RFS client and private Service lease guide Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- apps/server/src/bundle.test.ts | 11 + .../src/modules/remote_fs/rfs.route.test.ts | 9 + apps/server/src/modules/remote_fs/skill.ts | 1 + .../src/prompt/external-agent/access-huabu.md | 6 +- .../prompt/external-agent/service-config.md | 13 + docs/architecture/agent-reachback.md | 10 +- packages/client-runtime/src/rfs.ts | 394 ++++++++++++++++ packages/client-runtime/tests/rfs.test.ts | 425 ++++++++++++++++++ packages/client-runtime/tsup.config.ts | 7 +- 9 files changed, 873 insertions(+), 3 deletions(-) create mode 100644 apps/server/src/prompt/external-agent/service-config.md create mode 100644 packages/client-runtime/src/rfs.ts create mode 100644 packages/client-runtime/tests/rfs.test.ts diff --git a/apps/server/src/bundle.test.ts b/apps/server/src/bundle.test.ts index b3b8dabaf..fd84f1840 100644 --- a/apps/server/src/bundle.test.ts +++ b/apps/server/src/bundle.test.ts @@ -48,6 +48,7 @@ describe('server bundle runtime', () => { '../../packages/client-runtime/src/service-sdk.ts', ), daemon: path.resolve('../../packages/client-runtime/src/daemon.ts'), + rfs: path.resolve('../../packages/client-runtime/src/rfs.ts'), }, outDir: path.join(directory, 'client-runtime'), silent: true, @@ -64,6 +65,16 @@ describe('server bundle runtime', () => { { encoding: 'utf8' }, ); expect(hostHelp).toContain('pnpm start:daemon'); + const rfsHelp = execFileSync( + process.execPath, + [path.join(directory, 'client-runtime/rfs.js'), '--help'], + { + encoding: 'utf8', + env: { ...process.env, HUABU_RFS_URL: '', AGENTLET_TOKEN: '' }, + stdio: ['ignore', 'pipe', 'pipe'], + }, + ); + expect(rfsHelp).toContain('Response bodies and SSE are raw'); const sdkProbe = execFileSync( process.execPath, [ diff --git a/apps/server/src/modules/remote_fs/rfs.route.test.ts b/apps/server/src/modules/remote_fs/rfs.route.test.ts index de1f97eda..da3a9d63c 100644 --- a/apps/server/src/modules/remote_fs/rfs.route.test.ts +++ b/apps/server/src/modules/remote_fs/rfs.route.test.ts @@ -363,6 +363,10 @@ describe('GET /api/rfs/:canvasId/skill', () => { method: 'GET', url: '/rfs/c1/skill/interactive-views', }); + const serviceConfig = await app.inject({ + method: 'GET', + url: '/rfs/c1/skill/service-config', + }); const unknown = await app.inject({ method: 'GET', url: '/rfs/c1/skill/not-a-skill', @@ -377,6 +381,11 @@ describe('GET /api/rfs/:canvasId/skill', () => { expect(tasks.body).toContain('# Durable Tasks and Runs'); expect(agents.body).toContain('# Creating and Prompting Agents'); expect(interactiveViews.body).toContain('# Building Interactive Views'); + expect(serviceConfig.statusCode).toBe(200); + expect(serviceConfig.body).toContain( + '# Using Service configuration in your own process', + ); + expect(serviceConfig.body).toContain('withServiceContext'); expect(interactiveViews.body).toContain('huabu.view.connect'); expect(unknown.statusCode).toBe(404); expect(unknown.json()).toMatchObject({ code: 'skill_not_found' }); diff --git a/apps/server/src/modules/remote_fs/skill.ts b/apps/server/src/modules/remote_fs/skill.ts index e77af7159..b2753dc0b 100644 --- a/apps/server/src/modules/remote_fs/skill.ts +++ b/apps/server/src/modules/remote_fs/skill.ts @@ -25,6 +25,7 @@ const FOCUSED_SKILL_TEMPLATES = { tasks: 'external-agent/tasks.md', agents: 'external-agent/agents.md', 'interactive-views': 'external-agent/interactive-views.md', + 'service-config': 'external-agent/service-config.md', } as const; export type RfsFocusedSkillId = keyof typeof FOCUSED_SKILL_TEMPLATES; diff --git a/apps/server/src/prompt/external-agent/access-huabu.md b/apps/server/src/prompt/external-agent/access-huabu.md index e07a37a4b..54ecde0bb 100644 --- a/apps/server/src/prompt/external-agent/access-huabu.md +++ b/apps/server/src/prompt/external-agent/access-huabu.md @@ -8,6 +8,9 @@ These environment variables are already set: - `AGENTLET_TOKEN` — the RFS bearer credential. - `HUABU_SERVICE_SDK_URL` — the Huabu-owned `file://` URL used by optional Node Service entries to lease current configuration. Huabu provides the entry, not Node; choose a compatible Node from your own environment. - `HUABU_THREAD_ID` — your conversation ID. Pass it on `execute` (see §6) to attribute your edits. +- `HUABU_RFS_ENTRY` — when present, the optional local RFS JS entry. Huabu does not provide a Node executable or require this client for HTTP access. + +If you have compatible Node, `node "$HUABU_RFS_ENTRY" --help` (PowerShell: `node "$env:HUABU_RFS_ENTRY" --help`) combines local usage with the live Server contract. It supports `get-skill`, `query`, `execute`, `download`, `upload`, and raw streaming `agent` operations. `query --help TYPE` and `execute --help TYPE` load only the requested capability detail. A missing runtime or entry is a reason to choose native HTTP before issuing a request, not to repeat a possibly delivered mutation: after transport failure, inspect state before any resend. Exit 0 means successful HTTP delivery/normal EOF; always inspect command outcomes, conflicts, and Agent SSE events yourself. Ctrl+C closes local delivery, not remote work. Prefer deterministic direct operations: @@ -309,7 +312,7 @@ Every archive contains one top-level directory named after the Service, so extra With compatible Node available, read the extracted `SKILL.md`, then run `node entry.mjs --help` before invoking the optional entry. Runtime help uses the leased Manifest and configuration to show current choices and configured defaults that may not be visible from the source alone. The entry obtains that coherent Service context on demand through `HUABU_SERVICE_SDK_URL`; you normally do not need to import or call the SDK yourself. An entry is a modifiable starting point rather than a complete provider SDK: when the task needs another provider endpoint, follow the official documentation linked by the Skill and modify only your local Package copy. Old downloaded entries that use `AGENTLET_SERVICE_SDK_URL` must be refreshed; there is no legacy alias. -Without Node, JS entries cannot run, but Service leases remain language-independent. Use your own HTTP client in a business subprocess to `POST "$HUABU_RFS_URL/services//lease"` with the normal bearer authentication, consume the coherent `manifest` and `config` response in memory, and call only the intended provider according to its documentation. Do not print the lease into tool output, save it to disk, put credentials in argv, or export them to a global shell environment. +Without Node, JS entries cannot run, but Service leases remain language-independent. When using your own business process instead of a bundled entry, load authenticated `GET skill/service-config` for the in-memory lease/provider workflow. Never print or persist leased credentials or send them to unrelated recipients; only the intended provider receives the credential necessary for the operation. A Service Package without `SKILL.md` is intentionally unavailable for direct External Agent use; do not construct provider calls from its Settings manifest. @@ -321,6 +324,7 @@ Load these authenticated guides only when the request needs them: - `GET skill/tasks` — durable long-horizon Tasks and Runs. - `GET skill/agents` — available Profiles, Agent creation, launch configuration, continued conversations, and recursive delegation. - `GET skill/interactive-views` — durable sandboxed HTML Views with Host-owned state, data, navigation, and Agent actions. +- `GET skill/service-config` — fresh Service configuration leases consumed privately by your own business subprocess, including non-Node HTTP clients. ```bash curl -fsS -H "$AUTH" "$HUABU_RFS_URL/skill/tasks" diff --git a/apps/server/src/prompt/external-agent/service-config.md b/apps/server/src/prompt/external-agent/service-config.md new file mode 100644 index 000000000..18b726015 --- /dev/null +++ b/apps/server/src/prompt/external-agent/service-config.md @@ -0,0 +1,13 @@ +# Using Service configuration in your own process + +Use this guide when the bundled Service entry cannot perform the provider operation you need, or when you have no compatible Node runtime. This is a configuration lease workflow, not a generic provider runner or proxy. + +1. Discover configured Services with authenticated `GET $HUABU_RFS_URL/services`. Select only an Agent-facing Service that has a `skill` link. Read its `GET /services//skill` and credential-free `GET /services//manifest`; use the provider documentation linked by that Skill. +2. Write a business subprocess in your available language. Inside that process, send authenticated `POST /services//lease`, using `AGENTLET_TOKEN` from its inherited environment, without putting that token in argv. Reject non-2xx HTTP responses and invalid/incoherent lease data explicitly. A successful lease contains `id`, `version`, `manifest`, and `config`; use that one coherent response for the operation, not a separately cached Manifest. +3. Consume the lease in memory and authenticate only to the intended provider. Construct the documented provider request for your business operation; do not forward the Huabu bearer credential to the provider. Respect the Service's declared configuration keys and provider endpoint rather than inventing a universal environment mapping. +4. Emit only the business result (for example artifact bytes or a bounded result description). Do not dump the lease, provider request headers, or credentials into tool output, logs, files, argv, or a global shell environment. Sanitize provider diagnostics that could echo credentials. Do not send credentials to unrelated recipients. +5. Obtain a fresh lease for a new operation when current configuration matters. A lease is a point-in-time snapshot, not a subscription or a retry/idempotency guarantee. After an ambiguous provider mutation failure, inspect provider state before deciding whether another operation is safe. + +With compatible Node, the Huabu-owned SDK can perform step 2: `const { withServiceContext } = await import(process.env.HUABU_SERVICE_SDK_URL);` followed by `await withServiceContext('', async lease => { /* business operation */ });`. The callback receives the coherent lease and returns your business result. Huabu provides the SDK coordinate, not a Node executable. Never import the obsolete `AGENTLET_SERVICE_SDK_URL` or silently substitute stale configuration when a lease fails. + +Without Node, use your own HTTP library within the business process. Do not use a shell command that prints `POST /services//lease` into the agent transcript as an intermediate step. The optional RFS CLI deliberately has no provider execution or credential-export command; these are still the existing language-independent HTTP APIs. diff --git a/docs/architecture/agent-reachback.md b/docs/architecture/agent-reachback.md index fd6ffe41c..e2cc33ab1 100644 --- a/docs/architecture/agent-reachback.md +++ b/docs/architecture/agent-reachback.md @@ -25,7 +25,7 @@ All endpoints are mounted under `/api/rfs/:canvasId`; `HUABU_RFS_URL` already co | Endpoint | Responsibility | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `GET /skill` | Return the public bundled root guide; authenticated requests resolve the current root guide and append live Skill Frames. | -| `GET /skill/:skillId` | Return an authenticated advanced guide: `layout`, `tasks`, or `agents`. | +| `GET /skill/:skillId` | Return an authenticated advanced guide: `layout`, `tasks`, `agents`, `interactive-views`, or `service-config`. | | `GET /download/` | Stream a known node, artifact, or staged-upload file. | | `POST /upload/` | Stage bytes in the canvas `.upload/` directory without creating a node. | | `DELETE /upload/` | Remove one exact staged upload. | @@ -118,6 +118,14 @@ The embedded path does not invoke `huabu-daemon`, pnpm, or repo env files. Serve Installation retains required builds but no longer modifies user shell rc or PATH. Previously installed PATH entries are left untouched. +### Optional RFS client + +`packages/client-runtime/dist/rfs.js` is a self-contained optional Node entry, advertised as `HUABU_RFS_ENTRY` only when present. Run it with an Agent-selected compatible Node; Huabu neither injects a Node executable nor gates Agent startup on the client. The commands are `get-skill`, `query`, `execute`, `download`, `upload`, and `agent profiles|create|prompt`. JSON/text sources are mutually exclusive and forwarded unchanged; file `-` means stdin. `agent create --no-start` requires a JSON source and only sets the existing create-only header, leaving body validation to the Server. `execute` and `agent create` add safe `HUABU_THREAD_ID` correlation, warning if absent. Uploads stream raw bytes; logical path segments are encoded once. + +Responses, including incremental Agent SSE and business failures, reach stdout unchanged. Exit zero means successful HTTP transport/normal EOF, not command acceptance or Agent business success. HTTP/local/I/O/network/TLS/detectable transport errors fail; HTTP error bodies still go to stdout. A file download is written to a sibling temporary file and renamed only after complete success; `304` preserves the target. `--dump-header` records semantic status and Fetch-normalized headers, not wire-identical traffic. The client never follows redirects, retries mutations, reconnects SSE, or cancels remote work on Ctrl+C. Ambiguous mutation failure explicitly warns to inspect state before another request. + +Help retains local usage and attempts a bounded live contract request. Query/execute help uses `/capabilities`, or `/capabilities/queries/:type` and `/capabilities/commands/:type` for one specified operation; Agent help uses `/skill/agents`. An unavailable live contract is marked on stderr and help still exits zero. There is no private schema registry or offline cache presented as current. The focused authenticated `/skill/service-config` guide covers the existing lease API for an Agent's own business process without adding a provider runner or exporting credentials. + Skills explain when and how to compose workflows, but they do not duplicate the wire protocol. `GET /capabilities` and its per-operation endpoints remain the canonical, schema-derived source for current query and command fields, limits, and semantics. The guide is direct-first: an external agent can discover, query, download, snapshot, upload, execute, and verify without creating another Agent. `POST /agent` remains an optional high-level interpretation and delegation path. diff --git a/packages/client-runtime/src/rfs.ts b/packages/client-runtime/src/rfs.ts new file mode 100644 index 000000000..e3c068b00 --- /dev/null +++ b/packages/client-runtime/src/rfs.ts @@ -0,0 +1,394 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { once } from 'node:events'; +import { createReadStream, createWriteStream } from 'node:fs'; +import { mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises'; +import { dirname, join, resolve } from 'node:path'; +import { Readable } from 'node:stream'; +import { pipeline } from 'node:stream/promises'; +import { pathToFileURL } from 'node:url'; +import { parseArgs } from 'node:util'; + +import type { Writable } from 'node:stream'; + +const usage = `Huabu RFS (optional Node client) + get-skill [skillId] + query --json STRING | --json-file PATH|- + execute --json STRING | --json-file PATH|- + download LOGICAL_PATH [--output PATH] [--dump-header PATH] [--if-none-match ETAG] + upload NAME --file PATH|- + agent profiles + agent create [--no-start] INPUT + agent prompt THREAD_ID INPUT +INPUT: exactly one of --text STRING, --json STRING, --text-file PATH|-, --json-file PATH|- +Use --help; query/execute --help TYPE loads that operation's current contract. +Required environment: HUABU_RFS_URL, AGENTLET_TOKEN. +execute/agent create correlate HUABU_THREAD_ID when set. +Response bodies and SSE are raw; exit 0 means HTTP success/normal EOF, not business success. +No redirects, retries, reconnects or remote cancellation. Inspect business results yourself. +`; + +const options = { + help: { type: 'boolean', short: 'h' }, + json: { type: 'string' }, + 'json-file': { type: 'string' }, + text: { type: 'string' }, + 'text-file': { type: 'string' }, + file: { type: 'string' }, + output: { type: 'string' }, + 'dump-header': { type: 'string' }, + 'if-none-match': { type: 'string' }, + 'no-start': { type: 'boolean' }, +} as const; +type Values = ReturnType['values']; +function parseCli(args: string[]) { + return parseArgs({ args, options, allowPositionals: true, strict: true }); +} + +function segment(value: string | undefined): string { + if (!value || value === '.' || value === '..' || /[\\/\0]/.test(value)) + throw new Error( + 'Expected one nonempty logical path segment, not a URL or traversal', + ); + return encodeURIComponent(value); +} +function header(value: string, name: string): string { + if (!value || /[^\x20-\x7e\x80-\xff]/.test(value)) + throw new Error(`${name} is not a safe HTTP header value`); + return value; +} +function connection(env: NodeJS.ProcessEnv) { + if (!env.HUABU_RFS_URL || !env.AGENTLET_TOKEN) + throw new Error('HUABU_RFS_URL and AGENTLET_TOKEN are required'); + let url: URL; + try { + url = new URL(env.HUABU_RFS_URL); + } catch { + throw new Error('HUABU_RFS_URL must be an HTTP(S) base URL'); + } + if ( + !['http:', 'https:'].includes(url.protocol) || + url.username || + url.password || + url.search || + url.hash + ) + throw new Error( + 'HUABU_RFS_URL must be an HTTP(S) base URL without credentials, query or fragment', + ); + return { + base: url.href.replace(/\/+$/, ''), + headers: { + Authorization: header(`Bearer ${env.AGENTLET_TOKEN}`, 'AGENTLET_TOKEN'), + }, + }; +} +function allow(values: Values, permitted: string[]) { + for (const name of Object.keys(values)) + if (name !== 'help' && !permitted.includes(name)) + throw new Error(`Unsupported option --${name} for this command`); +} +async function input(values: Values, stdin: Readable, jsonOnly: boolean) { + const names = ['json', 'json-file', 'text', 'text-file'] as const; + const selected = names.filter((name) => values[name] !== undefined); + const [name] = selected; + if (selected.length !== 1 || name === undefined) + throw new Error( + 'Provide exactly one input: --json, --json-file, --text or --text-file', + ); + if (jsonOnly && !name.startsWith('json')) + throw new Error('This command requires a JSON input source'); + const value = values[name]; + if (value === undefined) throw new Error('Input source is missing'); + const bytes = name.endsWith('-file') + ? value === '-' + ? await collect(stdin) + : await readFile(value) + : Buffer.from(value); + return { + bytes, + contentType: name.startsWith('json') ? 'application/json' : 'text/plain', + }; +} +async function collect(stream: Readable): Promise { + const chunks: Buffer[] = []; + for await (const chunk of stream) + chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); + return Buffer.concat(chunks); +} +async function deliver( + response: Response, + destination: Writable, + end: boolean, +) { + async function* bytes() { + if (!response.body) return; + const reader = response.body.getReader(); + try { + while (true) { + const result = await reader.read(); + if (result.done) return; + yield result.value; + } + } finally { + try { + await reader.cancel(); + } finally { + reader.releaseLock(); + } + } + } + await pipeline(Readable.from(bytes()), destination, { end }); +} +function streamBody(source: Readable): ReadableStream { + const iterator = source[Symbol.asyncIterator](); + return new ReadableStream({ + async pull(controller) { + const result = await iterator.next(); + if (result.done) controller.close(); + else if (typeof result.value === 'string') + controller.enqueue(new Uint8Array(Buffer.from(result.value))); + else if (result.value instanceof Uint8Array) + controller.enqueue(new Uint8Array(result.value)); + else throw new Error('Upload input must contain bytes'); + }, + async cancel() { + source.destroy(); + await iterator.return?.(); + }, + }); +} + +export interface RfsIO { + env?: NodeJS.ProcessEnv; + stdin?: Readable; + stdout?: Writable; + stderr?: Writable; + signal?: AbortSignal; + helpTimeoutMs?: number; +} + +export async function runRfs(args: string[], io: RfsIO = {}): Promise { + const env = io.env ?? process.env; + const stdin = io.stdin ?? process.stdin; + const stdout = io.stdout ?? process.stdout; + const stderr = io.stderr ?? process.stderr; + const controller = new AbortController(); + const signal = io.signal + ? AbortSignal.any([io.signal, controller.signal]) + : controller.signal; + let mutation = false; + let sent = false; + let uploadStream: Readable | undefined; + let temporary: string | undefined; + const diagnostic = (message: string) => + stderr.write(`huabu-rfs: ${message}\n`); + try { + const { values, positionals } = parseCli(args); + const [command, ...rest] = positionals; + const commands = [ + 'get-skill', + 'query', + 'execute', + 'download', + 'upload', + 'agent', + ]; + if (command && !commands.includes(command)) + throw new Error(`Unknown command ${command}`); + if (!command || values.help) { + stdout.write(usage); + let path = '/skill'; + if (command === 'query' || command === 'execute') { + if (rest.length > 1) + throw new Error('Help accepts at most one operation type'); + path = rest[0] + ? `/capabilities/${command === 'query' ? 'queries' : 'commands'}/${segment(rest[0])}` + : '/capabilities'; + } else if (command === 'agent') path = '/skill/agents'; + try { + const config = connection(env); + const response = await fetch(`${config.base}${path}`, { + headers: config.headers, + redirect: 'manual', + signal: AbortSignal.any([ + signal, + AbortSignal.timeout(io.helpTimeoutMs ?? 3000), + ]), + }); + if (!response.ok) throw new Error(`HTTP ${response.status}`); + const contract = await response.text(); + stdout.write(`\nLive Server contract - GET ${path}\n${contract}\n`); + } catch (error) { + diagnostic( + `Live Server contract unavailable: ${error instanceof Error ? error.message : String(error)}. Local usage only.`, + ); + } + return 0; + } + const config = connection(env); + const headers: Record = { ...config.headers }; + let path: string; + let method = 'GET'; + let body: RequestInit['body']; + let duplex: 'half' | undefined; + if (command === 'get-skill') { + allow(values, []); + if (rest.length > 1) + throw new Error('get-skill accepts at most one skill ID'); + path = rest[0] ? `/skill/${segment(rest[0])}` : '/skill'; + } else if (command === 'query' || command === 'execute') { + allow(values, ['json', 'json-file']); + if (rest.length) + throw new Error(`${command} takes no positional arguments`); + const source = await input(values, stdin, true); + body = new Uint8Array(source.bytes); + headers['Content-Type'] = source.contentType; + path = `/${command}`; + method = 'POST'; + mutation = command === 'execute'; + } else if (command === 'download') { + allow(values, ['output', 'dump-header', 'if-none-match']); + const [logicalPath] = rest; + if (rest.length !== 1 || logicalPath === undefined) + throw new Error('download requires one logical path'); + path = `/download/${logicalPath.split('/').map(segment).join('/')}`; + if (values['if-none-match'] !== undefined) + headers['If-None-Match'] = header( + values['if-none-match'], + '--if-none-match', + ); + if (values.output === '' || values['dump-header'] === '') + throw new Error('Output paths must be nonempty'); + if ( + values.output && + values['dump-header'] && + resolve(values.output) === resolve(values['dump-header']) + ) + throw new Error('--output and --dump-header must use different paths'); + } else if (command === 'upload') { + allow(values, ['file']); + if (rest.length !== 1 || values.file === undefined || values.file === '') + throw new Error('upload requires one name and --file PATH|-'); + path = `/upload/${segment(rest[0])}`; + uploadStream = + values.file === '-' ? stdin : createReadStream(values.file); + if (values.file !== '-') await once(uploadStream, 'open'); + body = streamBody(uploadStream); + duplex = 'half'; + headers['Content-Type'] = 'application/octet-stream'; + method = 'POST'; + mutation = true; + } else { + const [operation, threadId] = rest; + if (operation === 'profiles') { + allow(values, []); + if (rest.length !== 1) + throw new Error('agent profiles takes no further arguments'); + path = '/agent/profiles'; + } else if (operation === 'create' || operation === 'prompt') { + allow(values, [ + 'json', + 'json-file', + 'text', + 'text-file', + ...(operation === 'create' ? ['no-start'] : []), + ]); + if (rest.length !== (operation === 'create' ? 1 : 2)) + throw new Error( + 'agent create takes no thread ID; agent prompt requires one', + ); + const source = await input(values, stdin, values['no-start'] === true); + body = new Uint8Array(source.bytes); + headers['Content-Type'] = source.contentType; + if (values['no-start']) headers['X-Huabu-Agent-Start'] = 'false'; + path = + operation === 'create' + ? '/agent' + : `/agent/${segment(threadId)}/prompt`; + method = 'POST'; + mutation = true; + } else throw new Error('agent requires profiles, create or prompt'); + } + if ( + command === 'execute' || + (command === 'agent' && rest[0] === 'create') + ) { + if (env.HUABU_THREAD_ID !== undefined) + headers['X-Huabu-Host-Thread-Id'] = header( + env.HUABU_THREAD_ID, + 'HUABU_THREAD_ID', + ); + else + diagnostic( + 'HUABU_THREAD_ID is absent; proceeding without host-thread correlation.', + ); + } + sent = true; + const init: RequestInit & { duplex?: 'half' } = { + method, + headers, + body, + duplex, + redirect: 'manual', + signal, + }; + const response = await fetch(`${config.base}${path}`, init); + if (command === 'download' && values['dump-header']) { + const lines = [ + `HTTP ${response.status} ${response.statusText}`, + ...Array.from(response.headers, ([key, value]) => `${key}: ${value}`), + '', + '', + ]; + await writeFile(values['dump-header'], lines.join('\r\n')); + } + if (command === 'download' && response.status === 304) return 0; + if (response.ok && command === 'download' && values.output) { + const target = resolve(values.output); + temporary = await mkdtemp(join(dirname(target), '.huabu-rfs-')); + await deliver( + response, + createWriteStream(join(temporary, 'body'), { flags: 'wx' }), + true, + ); + await rename(join(temporary, 'body'), target); + } else await deliver(response, stdout, false); + if (!response.ok) + diagnostic(`HTTP ${response.status}; response body is on stdout.`); + return response.ok ? 0 : 1; + } catch (error) { + controller.abort(); + diagnostic( + signal.aborted && io.signal?.aborted + ? 'Local delivery interrupted; this does not cancel remote work.' + : error instanceof Error + ? error.message + : String(error), + ); + if (mutation && sent) + diagnostic( + 'Remote outcome may be unknown. Inspect state before any further mutation; do not blindly resend.', + ); + return io.signal?.aborted ? 130 : 1; + } finally { + if (uploadStream && uploadStream !== stdin) uploadStream.destroy(); + if (temporary) await rm(temporary, { recursive: true, force: true }); + } +} + +if ( + process.argv[1] && + pathToFileURL(resolve(process.argv[1])).href === import.meta.url +) { + const controller = new AbortController(); + const interrupt = () => controller.abort(); + process.once('SIGINT', interrupt); + process.once('SIGTERM', interrupt); + process.exitCode = await runRfs(process.argv.slice(2), { + signal: controller.signal, + }); + process.removeListener('SIGINT', interrupt); + process.removeListener('SIGTERM', interrupt); +} diff --git a/packages/client-runtime/tests/rfs.test.ts b/packages/client-runtime/tests/rfs.test.ts new file mode 100644 index 000000000..dd0cda154 --- /dev/null +++ b/packages/client-runtime/tests/rfs.test.ts @@ -0,0 +1,425 @@ +// Copyright (c) Microsoft Corporation. +// Licensed under the MIT license. + +import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'; +import { + createServer, + type IncomingMessage, + type ServerResponse, +} from 'node:http'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { Readable, Writable } from 'node:stream'; + +import { afterEach, describe, expect, it } from 'vitest'; + +import { runRfs } from '../src/rfs.js'; + +const cleanup: (() => Promise)[] = []; +afterEach(async () => { + for (const action of cleanup.splice(0).reverse()) await action(); +}); +async function server( + handler: (request: IncomingMessage, response: ServerResponse) => void, +) { + const app = createServer(handler); + await new Promise((resolve) => app.listen(0, '127.0.0.1', resolve)); + cleanup.push(async () => { + app.closeAllConnections(); + await new Promise((resolve, reject) => + app.close((error) => (error ? reject(error) : resolve())), + ); + }); + const address = app.address(); + if (!address || typeof address === 'string') + throw new Error('Expected bound port'); + return { + HUABU_RFS_URL: `http://127.0.0.1:${address.port}/rfs/space`, + AGENTLET_TOKEN: 'private-token', + HUABU_THREAD_ID: 'host-thread', + }; +} +async function directory() { + const path = await mkdtemp(join(tmpdir(), 'huabu-rfs-test-')); + cleanup.push(() => rm(path, { recursive: true, force: true })); + return path; +} +function output(onChunk?: (chunk: Buffer) => void) { + const chunks: Buffer[] = []; + const stream = new Writable({ + write(chunk, _encoding, callback) { + chunks.push(Buffer.from(chunk)); + onChunk?.(chunk); + callback(); + }, + }); + return { + stream, + bytes: () => Buffer.concat(chunks), + text: () => Buffer.concat(chunks).toString(), + }; +} +async function bytes(request: IncomingMessage) { + const chunks: Buffer[] = []; + for await (const chunk of request) chunks.push(chunk); + return Buffer.concat(chunks); +} +async function call( + args: string[], + env: NodeJS.ProcessEnv, + stdin: Buffer = Buffer.alloc(0), + extra: Parameters[1] = {}, +) { + const stdout = output(); + const stderr = output(); + const code = await runRfs(args, { + env, + stdout: stdout.stream, + stderr: stderr.stream, + stdin: Readable.from([stdin]), + ...extra, + }); + return { code, stdout: stdout.bytes(), stderr: stderr.text() }; +} + +describe('optional raw RFS client', () => { + it.each(['query', 'execute'])( + 'forwards %s JSON bytes and unknown result fields without interpreting business outcomes', + async (command) => { + const original = ' \n{"type":"FUTURE","unknown":true}\n'; + const reply = + '{"results":[{"applied":false,"reason":"conflict"}],"future":[1,2]}'; + const env = await server((request, response) => { + expect(request.url).toBe(`/rfs/space/${command}`); + expect(request.headers.authorization).toBe('Bearer private-token'); + expect(request.headers['x-huabu-host-thread-id']).toBe( + command === 'execute' ? 'host-thread' : undefined, + ); + void bytes(request).then((body) => { + expect(body.toString()).toBe(original); + response.end(reply); + }); + }); + const result = await call( + [command, '--json-file', '-'], + env, + Buffer.from(original), + ); + expect(result.code).toBe(0); + expect(result.stdout.toString()).toBe(reply); + }, + ); + + it.each([ + ['query', '--json', '{}', '--json-file', '-'], + ['query', '--text', 'x'], + ['query', '--output', 'x', '--json', '{}'], + ['execute'], + ['agent', 'create', '--text', 'x', '--no-start'], + ['agent', 'create', 'extra', '--json', '{}'], + ['agent', 'prompt', '--text', 'x'], + ['agent', 'prompt', 't', '--text', 'x', '--no-start'], + ['agent', 'profiles', '--json', '{}'], + ['download', '../file'], + ['download', 'nodes//file'], + ['upload', 'a/b', '--file', '-'], + ['upload', 'a'], + ['capabilities'], + ])('rejects invalid input locally: %j', async (...args) => { + let count = 0; + const env = await server((_request, response) => { + count++; + response.end(); + }); + const result = await call(args, env); + expect(result.code).toBe(1); + expect(result.stderr).not.toBe(''); + expect(count).toBe(0); + }); + + it.each(['json', 'text', 'json-file', 'text-file'])( + 'forwards Agent %s input unchanged', + async (source) => { + const content = source.startsWith('json') + ? ' \n{"prompt":"x","future":42}\n' + : 'hello\r\nworld\n'; + const env = await server((request, response) => { + expect(request.url).toBe('/rfs/space/agent'); + expect(request.headers['content-type']).toBe( + source.startsWith('json') ? 'application/json' : 'text/plain', + ); + expect(request.headers['x-huabu-host-thread-id']).toBe('host-thread'); + void bytes(request).then((body) => { + expect(body.toString()).toBe(content); + response.end( + 'event: error\ndata: {"message":"business failure"}\n\n', + ); + }); + }); + const result = await call( + [ + 'agent', + 'create', + `--${source}`, + source.endsWith('file') ? '-' : content, + ], + env, + Buffer.from(content), + ); + expect(result.code).toBe(0); + expect(result.stdout.toString()).toContain('event: error'); + }, + ); + + it('uses JSON create-only header without rewriting body and reads actual files', async () => { + const file = join(await directory(), 'body.json'); + const original = '{"future":1,"prompt":"Server should validate this"}\n'; + await writeFile(file, original); + const env = await server((request, response) => { + expect(request.headers['x-huabu-agent-start']).toBe('false'); + void bytes(request).then((body) => { + expect(body.toString()).toBe(original); + response.end('{"nodeId":"n"}'); + }); + }); + expect( + (await call(['agent', 'create', '--no-start', '--json-file', file], env)) + .code, + ).toBe(0); + }); + + it('streams raw SSE before EOF and does not require done/end events', async () => { + let first!: () => void; + const observed = new Promise((resolve) => { + first = resolve; + }); + let finish!: () => void; + const env = await server((request, response) => { + expect(request.url).toBe('/rfs/space/agent/a%20b%252F/prompt'); + expect(request.headers['x-huabu-host-thread-id']).toBeUndefined(); + response.setHeader('content-type', 'text/event-stream'); + response.write(': heartbeat\n\nevent: custom\ndata: {"unknown":1}\n\n'); + finish = () => response.end('data: last\n\n'); + }); + const stdout = output(() => first()); + let settled = false; + const promise = runRfs(['agent', 'prompt', 'a b%2F', '--text', 'hello'], { + env, + stdout: stdout.stream, + stderr: output().stream, + }).then((code) => { + settled = true; + return code; + }); + await observed; + expect(settled).toBe(false); + expect(stdout.text()).toBe( + ': heartbeat\n\nevent: custom\ndata: {"unknown":1}\n\n', + ); + finish(); + expect(await promise).toBe(0); + expect(stdout.text()).toContain('data: last'); + }); + + it('streams binary file/stdin uploads with exactly-once encoding', async () => { + const payload = Buffer.from([0, 255, 10, 13, 128, 42]); + const file = join(await directory(), 'upload.bin'); + await writeFile(file, payload); + const env = await server((request, response) => { + expect(request.url).toBe('/rfs/space/upload/a%20%2520.bin'); + void bytes(request).then((body) => { + expect(body).toEqual(payload); + response.end('{"unknown":"untouched"}'); + }); + }); + for (const source of [file, '-']) { + const result = await call( + ['upload', 'a %20.bin', '--file', source], + env, + payload, + ); + expect(result.code).toBe(0); + expect(result.stdout.toString()).toBe('{"unknown":"untouched"}'); + } + }); + + it('replaces only a complete download, dumps metadata, and preserves cached target on 304', async () => { + const folder = await directory(); + const target = join(folder, 'body'); + const headers = join(folder, 'headers'); + await writeFile(target, 'old'); + const env = await server((request, response) => { + expect(request.url).toBe('/rfs/space/download/nodes/a%20%2520.md'); + response.setHeader('etag', '"revision"'); + response.setHeader('x-huabu-node-id', 'node-1'); + if (request.headers['if-none-match']) { + response.writeHead(304); + response.end(); + } else response.end(Buffer.from([0, 255, 10])); + }); + const args = [ + 'download', + 'nodes/a %20.md', + '--output', + target, + '--dump-header', + headers, + ]; + expect((await call(args, env)).code).toBe(0); + expect(await readFile(target)).toEqual(Buffer.from([0, 255, 10])); + expect(await readFile(headers, 'utf8')).toContain('etag: "revision"'); + expect(await readFile(headers, 'utf8')).toContain( + 'x-huabu-node-id: node-1', + ); + expect( + (await call([...args, '--if-none-match', '"revision"'], env)).code, + ).toBe(0); + expect(await readFile(target)).toEqual(Buffer.from([0, 255, 10])); + expect(await readFile(headers, 'utf8')).toContain('HTTP 304'); + expect(await readdir(folder)).toEqual(['body', 'headers']); + }); + + it('preserves target on truncated transport and reports error bodies only on stdout', async () => { + const folder = await directory(); + const target = join(folder, 'body'); + await writeFile(target, 'old'); + let partial = true; + const env = await server((_request, response) => { + if (partial) { + response.setHeader('content-length', '100'); + response.write('partial'); + setTimeout(() => response.destroy(), 10); + } else { + response.writeHead(403); + response.end('raw HTTP error'); + } + }); + const args = ['download', 'nodes/a', '--output', target]; + expect((await call(args, env)).code).toBe(1); + expect(await readFile(target, 'utf8')).toBe('old'); + partial = false; + const result = await call(args, env); + expect(result.code).toBe(1); + expect(result.stdout.toString()).toBe('raw HTTP error'); + expect(await readFile(target, 'utf8')).toBe('old'); + expect(await readdir(folder)).toEqual(['body']); + }); + + it('does not follow redirects or forward credentials to another server', async () => { + let redirected = 0; + const target = await server((_request, response) => { + redirected++; + response.end('bad'); + }); + const env = await server((_request, response) => { + response.writeHead(302, { location: target.HUABU_RFS_URL }); + response.end('redirect body'); + }); + const result = await call(['get-skill'], env); + expect(result.code).toBe(1); + expect(result.stdout.toString()).toBe('redirect body'); + expect(redirected).toBe(0); + }); + + it.each([ + [['query', '--help'], '/capabilities'], + [['query', '--help', 'QUERY'], '/capabilities/queries/QUERY'], + [['execute', '--help', 'CMD'], '/capabilities/commands/CMD'], + [['agent', '--help'], '/skill/agents'], + ])('combines local/live help at the exact endpoint', async (args, path) => { + const env = await server((request, response) => { + expect(request.url).toBe(`/rfs/space${path}`); + response.end('live contract'); + }); + const result = await call(args, env); + expect(result.code).toBe(0); + expect(result.stdout.toString()).toContain('Huabu RFS'); + expect(result.stdout.toString()).toContain(`GET ${path}\nlive contract`); + }); + + it('marks absent/auth-failed/timed-out live help without changing help exit status', async () => { + let stall = false; + const env = await server((_request, response) => { + if (!stall) { + response.writeHead(401); + response.end('denied'); + } + }); + for (const current of [{}, env]) { + const result = await call(['--help'], current); + expect(result.code).toBe(0); + expect(result.stderr).toContain('Live Server contract unavailable'); + expect(result.stdout.toString()).not.toContain('denied'); + } + stall = true; + const result = await call(['--help'], env, Buffer.alloc(0), { + helpTimeoutMs: 20, + }); + expect(result.code).toBe(0); + expect(result.stderr).toContain('Live Server contract unavailable'); + }); + + it('rejects unsafe header/env and missing input files before issuing requests', async () => { + let count = 0; + const env = await server((_request, response) => { + count++; + response.end(); + }); + for (const changed of [ + { ...env, HUABU_THREAD_ID: 'unsafe\r\nheader' }, + { ...env, AGENTLET_TOKEN: 'private\nsecret' }, + { ...env, HUABU_RFS_URL: 'ftp://example.test' }, + ]) + expect((await call(['execute', '--json', '{}'], changed)).code).toBe(1); + expect( + ( + await call( + ['upload', 'x', '--file', '/nonexistent-huabu-rfs-file'], + env, + ) + ).code, + ).toBe(1); + expect(count).toBe(0); + }); + + it('warns for absent correlation but continues, and reports ambiguous network mutations', async () => { + const env = await server((_request, response) => { + response.end('okay'); + }); + delete (env as NodeJS.ProcessEnv).HUABU_THREAD_ID; + const result = await call(['execute', '--json', '{}'], env); + expect(result.code).toBe(0); + expect(result.stderr).toContain('proceeding without host-thread'); + const dropped = await server((request) => { + request.socket.destroy(); + }); + const unknown = await call(['execute', '--json', '{}'], dropped); + expect(unknown.code).toBe(1); + expect(unknown.stderr).toContain('Remote outcome may be unknown'); + expect(unknown.stderr).not.toContain('private-token'); + }); + + it('aborts local SSE delivery without pretending to cancel remote work', async () => { + let first!: () => void; + const observed = new Promise((resolve) => { + first = resolve; + }); + const env = await server((_request, response) => { + response.write(': running\n\n'); + }); + const controller = new AbortController(); + const stdout = output(() => first()); + const stderr = output(); + const pending = runRfs(['agent', 'prompt', 't', '--text', 'hello'], { + env, + stdout: stdout.stream, + stderr: stderr.stream, + signal: controller.signal, + }); + await observed; + controller.abort(); + expect(await pending).toBe(130); + expect(stderr.text()).toContain('does not cancel remote work'); + expect(stderr.text()).toContain('Remote outcome may be unknown'); + }); +}); diff --git a/packages/client-runtime/tsup.config.ts b/packages/client-runtime/tsup.config.ts index 1d273666a..21968a8a9 100644 --- a/packages/client-runtime/tsup.config.ts +++ b/packages/client-runtime/tsup.config.ts @@ -4,7 +4,12 @@ import { defineConfig } from 'tsup'; export default defineConfig({ - entry: ['src/bootstrap.ts', 'src/daemon.ts', 'src/service-sdk.ts'], + entry: [ + 'src/bootstrap.ts', + 'src/daemon.ts', + 'src/service-sdk.ts', + 'src/rfs.ts', + ], format: ['esm'], target: 'node24', noExternal: [/.*/], From bada32c84baa35ead927d741dc8bd32accc9e1a5 Mon Sep 17 00:00:00 2001 From: Yuqing Yang Date: Mon, 12 Oct 2026 07:07:16 +0000 Subject: [PATCH 26/36] feat: replace token settings with scoped source-daemon onboarding Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .env.example | 10 +- apps/server/src/app.ts | 4 +- apps/server/src/bundle.test.ts | 68 +++- apps/server/src/connection-token.test.ts | 307 +++++++++++------- apps/server/src/connection-token.ts | 142 ++++---- .../agent/acp/connection-token.route.test.ts | 181 +++++------ .../agent/acp/connection-token.route.ts | 46 +-- .../prompt/external-agent/service-config.md | 2 +- .../src/security/environment-secret-store.ts | 3 - apps/server/src/security/secret-ids.ts | 1 + apps/web/src/api/_routes.ts | 1 - apps/web/src/api/acp.ts | 32 +- .../ExternalAgentRuntimeSettings.test.tsx | 251 +++++++------- .../sections/ExternalAgentRuntimeSettings.tsx | 228 +++++-------- apps/web/src/i18n/resources/en/common.json | 26 +- apps/web/src/i18n/resources/zh-CN/common.json | 26 +- apps/web/src/utils/io/clipboard.ts | 11 +- bin/start-agentlet-daemon | 168 +--------- docs/architecture/agent-profiles.md | 2 +- docs/architecture/agent-reachback.md | 8 +- docs/architecture/api-design.md | 4 + docs/architecture/credential-storage.md | 4 +- docs/architecture/deployment-security.md | 2 +- docs/architecture/web-architecture.md | 2 +- packages/client-runtime/src/daemon.ts | 2 +- packages/client-runtime/src/rfs.ts | 36 +- packages/client-runtime/tests/rfs.test.ts | 41 ++- packages/shared/src/types/api/acp.ts | 34 +- scripts/install-agentlet-to-path.mjs | 3 +- 29 files changed, 755 insertions(+), 890 deletions(-) diff --git a/.env.example b/.env.example index e8e21fcb9..6e4aaf971 100644 --- a/.env.example +++ b/.env.example @@ -51,8 +51,14 @@ # HUABU_DEBUG_PROMPT=true # ── External ACP agents (Copilot, Claude Code, …) ── -# Pairing itself is done in the Settings popover → "External Agents"; -# codes are ephemeral and never written to disk (no env override). +# Settings > Agent > External Agent runtime > How to connect copies a +# source-daemon command or private connection env file. Run it from a +# compatible Huabu checkout after pnpm install; startup builds itself. +# Server credentials are fixed for the process lifetime: a nonempty value +# here, or a random per-boot fallback. Set this for stable remote connections. +# Old Settings token overrides are ignored but retained, not migrated/deleted. +# Generate a stable token: node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))" +# HUABU_CONNECTION_TOKEN= # ── Network exposure ── # By default the server binds to 127.0.0.1 only, so a fresh install is # never silently exposed to the LAN. Set HUABU_BIND_HOST=0.0.0.0 (or a diff --git a/apps/server/src/app.ts b/apps/server/src/app.ts index f690e667c..63a12338b 100644 --- a/apps/server/src/app.ts +++ b/apps/server/src/app.ts @@ -275,8 +275,8 @@ app.register(rfsRoutes, { prefix: '/api/rfs' }); // It mounts the stateless Gateway, forks & supervises the agentlet daemon, // and authenticates connections against the host-injected connection token. // The daemon owns the agent worker pool; the server tells it which agent CLI -// to spawn (per user profile). The connection token never crosses the HTTP -// boundary — it lives only in-process and on the loopback WS. +// to spawn (per user profile). The token is revealed only by the explicit +// owner-only no-store copy action and is never part of ordinary read models. // // L1 owns all deployment-layout knowledge and injects it downward: // the global connection token, the data directory, and the resolved diff --git a/apps/server/src/bundle.test.ts b/apps/server/src/bundle.test.ts index fd84f1840..6511aa59f 100644 --- a/apps/server/src/bundle.test.ts +++ b/apps/server/src/bundle.test.ts @@ -1,8 +1,10 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { execFileSync } from 'node:child_process'; +import { execFileSync, spawn } from 'node:child_process'; +import { once } from 'node:events'; import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { createServer } from 'node:http'; import { tmpdir } from 'node:os'; import path from 'node:path'; import { pathToFileURL } from 'node:url'; @@ -10,6 +12,10 @@ import { pathToFileURL } from 'node:url'; import { build } from 'tsup'; import { describe, expect, it } from 'vitest'; +import { + buildHuabuBootstrapEnv, + resolveRuntimeArtifacts, +} from '../../../packages/client-runtime/src/bootstrap.js'; import clientRuntimeConfig from '../../../packages/client-runtime/tsup.config.js'; import bundleConfig from '../tsup.config.js'; @@ -75,6 +81,66 @@ describe('server bundle runtime', () => { }, ); expect(rfsHelp).toContain('Response bodies and SSE are raw'); + const bootstrap = buildHuabuBootstrapEnv( + resolveRuntimeArtifacts({ bundleDir: directory }), + ); + const rfsEntry = bootstrap.HUABU_RFS_ENTRY; + if (!rfsEntry) throw new Error('Expected built RFS entry'); + expect(rfsEntry).toBe(path.join(directory, 'client-runtime/rfs.js')); + expect(bootstrap.HUABU_SERVICE_SDK_URL).toBe( + pathToFileURL(path.join(directory, 'client-runtime/service-sdk.js')) + .href, + ); + const original = ' {"type":"FUTURE","unknown":true}\n'; + const mockServer = createServer((request, response) => { + let body = ''; + request.on('data', (chunk) => { + body += chunk; + }); + request.on('end', () => { + expect(request.url).toBe('/rfs/space/query'); + expect(request.headers.authorization).toBe('Bearer mock-token'); + expect(body).toBe(original); + response.end('{"business":false,"future":1}\n'); + }); + }); + await new Promise((resolve) => + mockServer.listen(0, '127.0.0.1', resolve), + ); + try { + const address = mockServer.address(); + if (!address || typeof address === 'string') + throw new Error('Expected test port'); + const child = spawn( + process.execPath, + [rfsEntry, 'query', '--json-file', '-'], + { + env: { + HUABU_RFS_URL: `http://127.0.0.1:${address.port}/rfs/space`, + AGENTLET_TOKEN: 'mock-token', + }, + stdio: ['pipe', 'pipe', 'pipe'], + }, + ); + let stdout = ''; + let stderr = ''; + child.stdout.on('data', (chunk) => { + stdout += chunk; + }); + child.stderr.on('data', (chunk) => { + stderr += chunk; + }); + child.stdin.end(original); + const [code] = await once(child, 'close'); + expect(code).toBe(0); + expect(stdout).toBe('{"business":false,"future":1}\n'); + expect(stderr).toBe(''); + } finally { + mockServer.closeAllConnections(); + await new Promise((resolve, reject) => + mockServer.close((error) => (error ? reject(error) : resolve())), + ); + } const sdkProbe = execFileSync( process.execPath, [ diff --git a/apps/server/src/connection-token.test.ts b/apps/server/src/connection-token.test.ts index 708e54674..931072130 100644 --- a/apps/server/src/connection-token.test.ts +++ b/apps/server/src/connection-token.test.ts @@ -1,31 +1,39 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. +import { execFileSync } from 'node:child_process'; +import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { + _resetConnectionTokenForTests, + buildAgentletConnectionCommand, + getConnectionToken, + initializeConnectionToken, +} from './connection-token.js'; +import { + parseConnectionEnvFile, + readConnectionConfig, +} from '../../../packages/client-runtime/src/daemon.js'; + const mocks = vi.hoisted(() => ({ - persisted: null as string | null, - writable: true, + persisted: 'historical-stored-token', + getPersistedSecret: vi.fn(), setSecret: vi.fn(), setDaemonToken: vi.fn(), restart: vi.fn(), disconnect: vi.fn(), - maxAgents: 7, })); - vi.mock('./security/secret-store.js', () => ({ - getPersistedSecret: () => mocks.persisted, - isSecretStoreWritable: () => mocks.writable, + getPersistedSecret: mocks.getPersistedSecret, setSecret: mocks.setSecret, })); - vi.mock('./modules/agent/acp/runtime-config.js', () => ({ - getExternalAgentRuntimeConfig: () => ({ - idleTimeoutSecs: 600, - maxAgents: mocks.maxAgents, - }), + getExternalAgentRuntimeConfig: () => ({ idleTimeoutSecs: 600, maxAgents: 7 }), })); - vi.mock('@agenetes/agentlet-host', () => ({ getDaemonAuth: () => ({ setDaemonToken: mocks.setDaemonToken }), getDaemonSupervisor: () => ({ restart: mocks.restart }), @@ -34,130 +42,201 @@ vi.mock('@agenetes/agentlet-host', () => ({ }), })); -import { - _resetConnectionTokenForTests, - buildAgentletConnectionCommand, - getConnectionToken, - initializeConnectionToken, - setConnectionToken, -} from './connection-token.js'; - beforeEach(() => { _resetConnectionTokenForTests(); - mocks.persisted = null; - mocks.writable = true; - mocks.setSecret.mockResolvedValue(undefined); vi.clearAllMocks(); - delete process.env.HUABU_CONNECTION_TOKEN; - delete process.env.HUABU_PUBLIC_ORIGIN; + mocks.getPersistedSecret.mockReturnValue(mocks.persisted); + vi.stubEnv('HUABU_CONNECTION_TOKEN', ''); + vi.stubEnv('HUABU_PUBLIC_ORIGIN', ''); }); +afterEach(() => vi.unstubAllEnvs()); -afterEach(() => { - delete process.env.HUABU_CONNECTION_TOKEN; - delete process.env.HUABU_PUBLIC_ORIGIN; -}); - -describe('connection token resolution', () => { - it('prefers persisted, environment, then one generated fallback', () => { - mocks.persisted = 'stored-token'; - expect(initializeConnectionToken()).toEqual({ - source: 'stored', - writable: true, - }); - expect(getConnectionToken()).toBe('stored-token'); +const request = { + origin: 'https://huabu.example.com', + shell: 'posix' as const, + format: 'command' as const, +}; - _resetConnectionTokenForTests(); - mocks.persisted = null; - process.env.HUABU_CONNECTION_TOKEN = 'environment-token'; - expect(initializeConnectionToken().source).toBe('environment'); +describe('immutable connection token', () => { + it('ignores but does not delete historical persisted overrides', () => { + vi.stubEnv('HUABU_CONNECTION_TOKEN', 'environment-token'); + initializeConnectionToken(); expect(getConnectionToken()).toBe('environment-token'); - - _resetConnectionTokenForTests(); - delete process.env.HUABU_CONNECTION_TOKEN; - expect(initializeConnectionToken().source).toBe('generated'); - const generated = getConnectionToken(); - expect(generated).toMatch(/^[0-9a-f]{64}$/); - expect(getConnectionToken()).toBe(generated); + expect(mocks.setDaemonToken).toHaveBeenCalledWith('environment-token'); + expect(mocks.getPersistedSecret).not.toHaveBeenCalled(); + expect(mocks.setSecret).not.toHaveBeenCalled(); + expect(mocks.persisted).toBe('historical-stored-token'); }); - - it('persists before switching auth and restarting connected agentlets', async () => { + it('generates one random token per boot and never switches after first use', () => { + const token = getConnectionToken(); + expect(token).toMatch(/^[0-9a-f]{64}$/); + vi.stubEnv('HUABU_CONNECTION_TOKEN', 'later-change'); initializeConnectionToken(); - await setConnectionToken('new-token'); - - expect(mocks.setSecret).toHaveBeenCalledWith( - 'integration:agentlet:connection-token', - 'new-token', - ); - expect(mocks.setDaemonToken).toHaveBeenLastCalledWith('new-token'); - expect(mocks.disconnect).toHaveBeenCalledWith('connection_token_changed'); - expect(mocks.restart).toHaveBeenCalledOnce(); - expect(getConnectionToken()).toBe('new-token'); - }); - - it('keeps the active token when persistence fails', async () => { - process.env.HUABU_CONNECTION_TOKEN = 'old-token'; initializeConnectionToken(); - mocks.setSecret.mockRejectedValueOnce(new Error('write failed')); - - await expect(setConnectionToken('new-token')).rejects.toThrow( - 'write failed', - ); - expect(getConnectionToken()).toBe('old-token'); - expect(mocks.disconnect).not.toHaveBeenCalled(); + expect(getConnectionToken()).toBe(token); + expect(mocks.setDaemonToken).toHaveBeenLastCalledWith(token); expect(mocks.restart).not.toHaveBeenCalled(); + expect(mocks.disconnect).not.toHaveBeenCalled(); + _resetConnectionTokenForTests(); + vi.stubEnv('HUABU_CONNECTION_TOKEN', ' '); + expect(getConnectionToken()).not.toBe(token); }); - - it('clears to the environment fallback', async () => { - mocks.persisted = 'stored-token'; - process.env.HUABU_CONNECTION_TOKEN = 'environment-token'; + it('keeps a captured env token when env changes, and normalizes surrounding whitespace consistently with the source daemon', () => { + vi.stubEnv('HUABU_CONNECTION_TOKEN', ' environment-token '); + expect(getConnectionToken()).toBe('environment-token'); + expect( + readConnectionConfig({ + repoRoot: '/nonexistent-huabu-checkout', + inherited: { + HUABU_PUBLIC_ORIGIN: request.origin, + HUABU_CONNECTION_TOKEN: ' environment-token ', + }, + }).token, + ).toBe(getConnectionToken()); + vi.stubEnv('HUABU_CONNECTION_TOKEN', 'changed'); initializeConnectionToken(); - - await setConnectionToken(null); - expect(getConnectionToken()).toBe('environment-token'); - expect(mocks.setDaemonToken).toHaveBeenLastCalledWith('environment-token'); }); }); -describe('Agentlet connection command', () => { - it('derives secure and insecure endpoints and reports warnings', () => { - process.env.HUABU_CONNECTION_TOKEN = "token'quoted"; - initializeConnectionToken(); - - expect(buildAgentletConnectionCommand('https://huabu.example.com')).toEqual( - { - command: - "agentlet daemon --server 'wss://huabu.example.com/api/acp/agent' --max-agents 7 --token 'token'\"'\"'quoted'", - warnings: [], - }, - ); - expect(buildAgentletConnectionCommand('http://localhost:3001')).toEqual({ - command: - "agentlet daemon --server 'ws://localhost:3001/api/acp/agent' --max-agents 7 --token 'token'\"'\"'quoted' --allow-insecure", - warnings: ['loopback', 'insecure'], +describe('source-daemon copy text', () => { + it.skipIf(process.platform === 'win32')( + 'uses invocation-scoped env without token argv, and preserves metacharacters in a real POSIX shell', + () => { + const token = 'quote\'"$HOME \\n `tick` # literal'; + vi.stubEnv('HUABU_CONNECTION_TOKEN', token); + const result = buildAgentletConnectionCommand(request); + expect(result.source).toBe('environment'); + expect(result.warnings).toEqual([]); + expect(result.content).toContain('pnpm start:daemon --max-agents 7'); + expect(result.content).not.toContain('--token'); + const folder = mkdtempSync(join(tmpdir(), 'huabu-command-')); + try { + writeFileSync( + join(folder, 'pnpm'), + `#!${process.execPath} +console.log(JSON.stringify({origin: process.env.HUABU_PUBLIC_ORIGIN, token: process.env.HUABU_CONNECTION_TOKEN, args: process.argv.slice(2)})); +`, + { mode: 0o700 }, + ); + const resultText = execFileSync( + 'sh', + [ + '-c', + `${result.content}\n"${process.execPath}" -e 'console.log(JSON.stringify({origin:process.env.HUABU_PUBLIC_ORIGIN,token:process.env.HUABU_CONNECTION_TOKEN}))'`, + ], + { + encoding: 'utf8', + env: { + ...process.env, + PATH: `${folder}:${process.env.PATH}`, + HUABU_PUBLIC_ORIGIN: 'before-origin', + HUABU_CONNECTION_TOKEN: 'before-token', + }, + }, + ); + const [child, parent] = resultText + .trim() + .split('\n') + .map((line) => JSON.parse(line)); + expect(child).toEqual({ + origin: request.origin, + token, + args: ['start:daemon', '--max-agents', '7'], + }); + expect(parent).toEqual({ + origin: 'before-origin', + token: 'before-token', + }); + } finally { + rmSync(folder, { recursive: true, force: true }); + } + }, + ); + it('quotes PowerShell literally and restores both previous process env values in finally', () => { + vi.stubEnv('HUABU_CONNECTION_TOKEN', "token'$HOME`quoted"); + const result = buildAgentletConnectionCommand({ + ...request, + shell: 'powershell', }); + expect(result.content).toContain( + "$env:HUABU_CONNECTION_TOKEN = 'token''$HOME`quoted'", + ); + expect(result.content).toContain('} finally {'); + expect(result.content).toContain( + "SetEnvironmentVariable('HUABU_PUBLIC_ORIGIN', $huabuPreviousOrigin, 'Process')", + ); + expect(result.content).toContain( + "SetEnvironmentVariable('HUABU_CONNECTION_TOKEN', $huabuPreviousToken, 'Process')", + ); + expect(result.content).not.toContain('--token'); }); - - it('rejects origins with paths or unsupported protocols', () => { + it.each([ + 'simple', + "single'quote", + 'both\'"quotes # with \\n data', + 'with`backtick', + 'all\'"`quotes', + ])( + 'round-trips private env files through the real daemon parser: %s', + (token) => { + vi.stubEnv('HUABU_CONNECTION_TOKEN', token); + const result = buildAgentletConnectionCommand({ + ...request, + format: 'env-file', + }); + expect(parseConnectionEnvFile(result.content)).toEqual({ + HUABU_PUBLIC_ORIGIN: request.origin, + HUABU_CONNECTION_TOKEN: token, + }); + expect(result.content).not.toContain('--max-agents'); + }, + ); + it('rejects an unrepresentable env file explicitly without blocking the command format', () => { + vi.stubEnv('HUABU_CONNECTION_TOKEN', 'all\'"`quotes # with comment'); expect(() => - buildAgentletConnectionCommand('https://example.com/path'), - ).toThrow('Origin must be an HTTP(S) origin without a path'); - expect(() => buildAgentletConnectionCommand('file:///tmp/huabu')).toThrow( - 'Origin must be an HTTP(S) origin without a path', + buildAgentletConnectionCommand({ ...request, format: 'env-file' }), + ).toThrow('use Copy connection command instead'); + expect(buildAgentletConnectionCommand(request).content).toContain( + 'pnpm start:daemon', ); }); - - it('uses the configured public origin instead of the browser origin', () => { - process.env.HUABU_CONNECTION_TOKEN = 'token'; - process.env.HUABU_PUBLIC_ORIGIN = 'https://public.huabu.example:8443/'; - initializeConnectionToken(); - - expect( - buildAgentletConnectionCommand('http://localhost:5173'), - ).toMatchObject({ - command: - "agentlet daemon --server 'wss://public.huabu.example:8443/api/acp/agent' --max-agents 7 --token 'token'", - warnings: [], + it('reports HTTP/loopback warnings and generated-token source', () => { + const result = buildAgentletConnectionCommand({ + ...request, + origin: 'http://localhost:3001', }); + expect(result.warnings).toEqual(['loopback', 'insecure']); + expect(result.source).toBe('generated'); + expect(result.content).toContain( + "HUABU_PUBLIC_ORIGIN='http://localhost:3001'", + ); + }); + it('uses the configured public origin rather than the local browser origin', () => { + vi.stubEnv('HUABU_PUBLIC_ORIGIN', 'https://public.huabu.example:8443/'); + const result = buildAgentletConnectionCommand({ + ...request, + origin: 'http://localhost:5173', + }); + expect(result.content).toContain( + "HUABU_PUBLIC_ORIGIN='https://public.huabu.example:8443'", + ); + expect(result.warnings).toEqual([]); + expect(() => + buildAgentletConnectionCommand({ + ...request, + origin: 'file:///tmp/huabu', + }), + ).toThrow('Origin must be an HTTP(S) origin without a path'); + }); + it.each([ + 'https://example.com/path', + 'file:///tmp/huabu', + 'https://user:secret@example.com', + 'https://example.com/?x=1', + ])('rejects invalid root origins: %s', (origin) => { + expect(() => + buildAgentletConnectionCommand({ ...request, origin }), + ).toThrow('Origin must be an HTTP(S) origin without a path'); }); }); diff --git a/apps/server/src/connection-token.ts b/apps/server/src/connection-token.ts index ebe8758a4..52e3d1b90 100644 --- a/apps/server/src/connection-token.ts +++ b/apps/server/src/connection-token.ts @@ -3,27 +3,18 @@ import { randomBytes } from 'node:crypto'; -import { - getAgentletGateway, - getDaemonAuth, - getDaemonSupervisor, -} from '@agenetes/agentlet-host'; +import { getDaemonAuth } from '@agenetes/agentlet-host'; +import { parse } from 'dotenv'; import { getExternalAgentRuntimeConfig } from './modules/agent/acp/runtime-config.js'; import { normalizePublicOrigin, resolveConfiguredPublicOrigin, } from './modules/security/public-origin.js'; -import { SECRET_IDS } from './security/secret-ids.js'; -import { - getPersistedSecret, - isSecretStoreWritable, - setSecret, -} from './security/secret-store.js'; import type { AgentletConnectionCommandResponse, - ConnectionTokenConfig, + AgentletConnectionCommandRequest, ConnectionTokenSource, } from '@huabu/shared'; @@ -37,14 +28,12 @@ import type { * the server process, so agent reachback credentials survive an * agentlet daemon restart. * - * The generated fallback is available during module composition. After the - * SecretStore initializes, {@link initializeConnectionToken} activates the - * persisted/environment/generated precedence before the server listens. + * The environment/generated choice is captured at first use during module + * composition. Persisted overrides are deliberately ignored and retained. */ let generatedToken: string | null = null; let activeToken: string | null = null; let activeSource: ConnectionTokenSource | null = null; -let mutationQueue = Promise.resolve(); function getGeneratedToken(): string { generatedToken ??= randomBytes(32).toString('hex'); @@ -57,7 +46,7 @@ function getEnvironmentToken(): string | null { function resolveFallback(): { token: string; - source: Exclude; + source: ConnectionTokenSource; } { const environment = getEnvironmentToken(); return environment @@ -65,15 +54,6 @@ function resolveFallback(): { : { token: getGeneratedToken(), source: 'generated' }; } -function activateConnectionToken( - token: string, - source: ConnectionTokenSource, -): void { - activeToken = token; - activeSource = source; - getDaemonAuth().setDaemonToken(token); -} - export function getConnectionToken(): string { if (activeToken) return activeToken; const fallback = resolveFallback(); @@ -82,53 +62,8 @@ export function getConnectionToken(): string { return activeToken; } -export function initializeConnectionToken(): ConnectionTokenConfig { - const stored = getPersistedSecret(SECRET_IDS.agentletConnectionToken); - if (stored) activateConnectionToken(stored, 'stored'); - else { - const fallback = resolveFallback(); - activateConnectionToken(fallback.token, fallback.source); - } - return getConnectionTokenConfig(); -} - -export function getConnectionTokenConfig(): ConnectionTokenConfig { - if (!activeSource) getConnectionToken(); - return { - source: activeSource ?? 'generated', - writable: isSecretStoreWritable(), - }; -} - -function disconnectAgentlets(): void { - const gateway = getAgentletGateway(); - for (const connection of gateway?.getAgentlets({ status: 'connected' }) ?? - []) { - connection.disconnect('connection_token_changed'); - } -} - -export function setConnectionToken( - token: string | null, -): Promise { - const mutation = mutationQueue.then(async () => { - await setSecret(SECRET_IDS.agentletConnectionToken, token); - const next = token - ? { token, source: 'stored' as const } - : resolveFallback(); - const changed = next.token !== getConnectionToken(); - activateConnectionToken(next.token, next.source); - if (changed) { - disconnectAgentlets(); - getDaemonSupervisor().restart(); - } - return getConnectionTokenConfig(); - }); - mutationQueue = mutation.then( - () => undefined, - () => undefined, - ); - return mutation; +export function initializeConnectionToken(): void { + getDaemonAuth().setDaemonToken(getConnectionToken()); } function quotePosix(value: string): string { @@ -145,14 +80,30 @@ function isLoopbackHostname(hostname: string): boolean { } export class InvalidAgentletConnectionOriginError extends Error {} +export class InvalidAgentletConnectionEnvFileError extends Error {} + +function quotePowerShell(value: string): string { + return `'${value.replaceAll("'", "''")}'`; +} + +function dotenvValue(key: string, value: string): string { + for (const quote of ["'", '`', '"', '']) { + if (quote && value.includes(quote)) continue; + const line = `${key}=${quote}${value}${quote}\n`; + if (parse(line)[key] === value) return line; + } + throw new InvalidAgentletConnectionEnvFileError( + 'This credential cannot be represented safely in a dotenv file; use Copy connection command instead', + ); +} export function buildAgentletConnectionCommand( - originValue: string, + request: AgentletConnectionCommandRequest, ): AgentletConnectionCommandResponse { let normalizedOrigin: string; try { - normalizedOrigin = - resolveConfiguredPublicOrigin() ?? normalizePublicOrigin(originValue); + const browserOrigin = normalizePublicOrigin(request.origin); + normalizedOrigin = resolveConfiguredPublicOrigin() ?? browserOrigin; } catch { throw new InvalidAgentletConnectionOriginError( 'Origin must be an HTTP(S) origin without a path', @@ -160,17 +111,35 @@ export function buildAgentletConnectionCommand( } const origin = new URL(normalizedOrigin); const insecure = origin.protocol === 'http:'; - const endpoint = `${insecure ? 'ws:' : 'wss:'}//${origin.host}/api/acp/agent`; - const maxAgents = getExternalAgentRuntimeConfig().maxAgents; - const command = [ - 'agentlet daemon', - `--server ${quotePosix(endpoint)}`, - `--max-agents ${maxAgents}`, - `--token ${quotePosix(getConnectionToken())}`, - ...(insecure ? ['--allow-insecure'] : []), - ].join(' '); + const token = getConnectionToken(); + let content: string; + if (request.format === 'env-file') { + content = + dotenvValue('HUABU_PUBLIC_ORIGIN', normalizedOrigin) + + dotenvValue('HUABU_CONNECTION_TOKEN', token); + } else if (request.shell === 'posix') { + const maxAgents = getExternalAgentRuntimeConfig().maxAgents; + content = `HUABU_PUBLIC_ORIGIN=${quotePosix(normalizedOrigin)} HUABU_CONNECTION_TOKEN=${quotePosix(token)} pnpm start:daemon --max-agents ${maxAgents}`; + } else { + const maxAgents = getExternalAgentRuntimeConfig().maxAgents; + content = [ + '& {', + " $huabuPreviousOrigin = [Environment]::GetEnvironmentVariable('HUABU_PUBLIC_ORIGIN', 'Process')", + " $huabuPreviousToken = [Environment]::GetEnvironmentVariable('HUABU_CONNECTION_TOKEN', 'Process')", + ' try {', + ` $env:HUABU_PUBLIC_ORIGIN = ${quotePowerShell(normalizedOrigin)}`, + ` $env:HUABU_CONNECTION_TOKEN = ${quotePowerShell(token)}`, + ` pnpm start:daemon --max-agents ${maxAgents}`, + ' } finally {', + " [Environment]::SetEnvironmentVariable('HUABU_PUBLIC_ORIGIN', $huabuPreviousOrigin, 'Process')", + " [Environment]::SetEnvironmentVariable('HUABU_CONNECTION_TOKEN', $huabuPreviousToken, 'Process')", + ' }', + '}', + ].join('\n'); + } return { - command, + content, + source: activeSource ?? 'generated', warnings: [ ...(isLoopbackHostname(origin.hostname) ? (['loopback'] as const) : []), ...(insecure ? (['insecure'] as const) : []), @@ -182,5 +151,4 @@ export function _resetConnectionTokenForTests(): void { generatedToken = null; activeToken = null; activeSource = null; - mutationQueue = Promise.resolve(); } diff --git a/apps/server/src/modules/agent/acp/connection-token.route.test.ts b/apps/server/src/modules/agent/acp/connection-token.route.test.ts index 27d0fcfda..4f5b10c18 100644 --- a/apps/server/src/modules/agent/acp/connection-token.route.test.ts +++ b/apps/server/src/modules/agent/acp/connection-token.route.test.ts @@ -8,152 +8,129 @@ import connectionTokenRoutes from './connection-token.route.js'; const mocks = vi.hoisted(() => ({ InvalidOriginError: class InvalidOriginError extends Error {}, + InvalidEnvFileError: class InvalidEnvFileError extends Error {}, buildCommand: vi.fn(), - getConfig: vi.fn(), isOwner: vi.fn(), - setToken: vi.fn(), })); - vi.mock('../../../connection-token.js', () => ({ InvalidAgentletConnectionOriginError: mocks.InvalidOriginError, + InvalidAgentletConnectionEnvFileError: mocks.InvalidEnvFileError, buildAgentletConnectionCommand: mocks.buildCommand, - getConnectionTokenConfig: mocks.getConfig, - setConnectionToken: mocks.setToken, -})); - -vi.mock('../../security/owner.js', () => ({ - isOwnerRequest: mocks.isOwner, })); +vi.mock('../../security/owner.js', () => ({ isOwnerRequest: mocks.isOwner })); let app: FastifyInstance | undefined; - async function setup() { app = Fastify({ logger: false }); await app.register(connectionTokenRoutes, { prefix: '/api/acp' }); return app; } - afterEach(async () => { await app?.close(); app = undefined; vi.resetAllMocks(); }); - -describe('connection token routes', () => { - it('keeps token settings owner-only and never returns token material', async () => { - mocks.isOwner.mockReturnValue(false); - const server = await setup(); - - const response = await server.inject('/api/acp/connection-token'); - - expect(response.statusCode).toBe(403); - expect(mocks.getConfig).not.toHaveBeenCalled(); - expect(response.body).not.toContain('token-value'); - }); - - it('returns only the credential source and writability', async () => { +const payload = { + origin: 'https://huabu.example', + shell: 'posix', + format: 'command', +}; + +describe('explicit owner-only connection copy', () => { + it('removes both token configuration endpoints', async () => { mocks.isOwner.mockReturnValue(true); - mocks.getConfig.mockReturnValue({ source: 'stored', writable: true }); const server = await setup(); - - const response = await server.inject('/api/acp/connection-token'); - - expect(response.statusCode).toBe(200); - expect(response.json()).toEqual({ source: 'stored', writable: true }); + expect((await server.inject('/api/acp/connection-token')).statusCode).toBe( + 404, + ); + expect( + ( + await server.inject({ + method: 'PUT', + url: '/api/acp/connection-token', + payload: { token: 'replacement' }, + }) + ).statusCode, + ).toBe(404); }); - - it('validates updates and propagates persistence failures', async () => { - mocks.isOwner.mockReturnValue(true); - mocks.setToken.mockRejectedValue(new Error('credential store unavailable')); - const server = await setup(); - - const invalid = await server.inject({ - method: 'PUT', - url: '/api/acp/connection-token', - payload: { token: '' }, - }); - const failed = await server.inject({ - method: 'PUT', - url: '/api/acp/connection-token', - payload: { token: 'replacement' }, - }); - - expect(invalid.statusCode).toBe(400); - expect(failed.statusCode).toBe(500); - expect(mocks.setToken).toHaveBeenCalledOnce(); - expect(mocks.setToken).toHaveBeenCalledWith('replacement'); - }); - - it('returns a no-store command response for a valid browser origin', async () => { - mocks.isOwner.mockReturnValue(true); - mocks.buildCommand.mockReturnValue({ - command: "agentlet daemon --token 'secret'", - warnings: ['loopback'], - }); + it('rejects non-owner callers before generating credential-bearing content', async () => { + mocks.isOwner.mockReturnValue(false); const server = await setup(); - const response = await server.inject({ method: 'POST', url: '/api/acp/connection-command', - payload: { origin: 'http://localhost:5173' }, + payload, }); - - expect(response.statusCode).toBe(200); - expect(response.headers['cache-control']).toBe('no-store'); - expect(response.headers.pragma).toBe('no-cache'); - expect(mocks.buildCommand).toHaveBeenCalledWith('http://localhost:5173'); + expect(response.statusCode).toBe(403); + expect(mocks.buildCommand).not.toHaveBeenCalled(); }); - - it('rejects malformed and non-origin command inputs', async () => { + it.each(['command', 'env-file'])( + 'returns only explicit no-store %s copy content', + async (format) => { + mocks.isOwner.mockReturnValue(true); + mocks.buildCommand.mockReturnValue({ + content: 'explicit secret-bearing copy text', + source: 'generated', + warnings: ['loopback'], + }); + const server = await setup(); + const response = await server.inject({ + method: 'POST', + url: '/api/acp/connection-command', + payload: { ...payload, format }, + }); + expect(response.statusCode).toBe(200); + expect(response.headers['cache-control']).toBe('no-store'); + expect(response.headers.pragma).toBe('no-cache'); + expect(mocks.buildCommand).toHaveBeenCalledWith({ ...payload, format }); + }, + ); + it.each([ + { origin: 'not-a-url', shell: 'posix', format: 'command' }, + { origin: 'https://huabu.example' }, + { ...payload, shell: 'cmd' }, + { ...payload, format: 'invalid' }, + { ...payload, token: 'caller-override' }, + ])('validates every body field before calling the builder', async (body) => { mocks.isOwner.mockReturnValue(true); - mocks.buildCommand.mockImplementation(() => { - throw new mocks.InvalidOriginError('invalid origin'); - }); const server = await setup(); - - const malformed = await server.inject({ - method: 'POST', - url: '/api/acp/connection-command', - payload: { origin: 'not-a-url' }, - }); - const withPath = await server.inject({ + const response = await server.inject({ method: 'POST', url: '/api/acp/connection-command', - payload: { origin: 'https://example.com/path' }, + payload: body, }); - - expect(malformed.statusCode).toBe(400); - expect(withPath.statusCode).toBe(400); + expect(response.statusCode).toBe(400); + expect(mocks.buildCommand).not.toHaveBeenCalled(); }); - - it('rejects a browser origin that differs from the request origin', async () => { + it('rejects mismatched browser origin', async () => { mocks.isOwner.mockReturnValue(true); const server = await setup(); - const response = await server.inject({ method: 'POST', url: '/api/acp/connection-command', - headers: { origin: 'https://huabu.example' }, - payload: { origin: 'https://other.example' }, + headers: { origin: 'https://other.example' }, + payload, }); - expect(response.statusCode).toBe(400); expect(mocks.buildCommand).not.toHaveBeenCalled(); }); - - it('does not disguise command-generation failures as invalid input', async () => { + it('reports known input problems without disguising operational failures', async () => { mocks.isOwner.mockReturnValue(true); - mocks.buildCommand.mockImplementation(() => { - throw new Error('runtime config unavailable'); - }); const server = await setup(); - - const response = await server.inject({ - method: 'POST', - url: '/api/acp/connection-command', - payload: { origin: 'https://huabu.example' }, - }); - - expect(response.statusCode).toBe(500); + for (const error of [ + new mocks.InvalidOriginError('invalid origin'), + new mocks.InvalidEnvFileError('Use command format'), + new Error('runtime unavailable'), + ]) { + mocks.buildCommand.mockImplementationOnce(() => { + throw error; + }); + const response = await server.inject({ + method: 'POST', + url: '/api/acp/connection-command', + payload, + }); + expect(response.statusCode).toBe(error.constructor === Error ? 500 : 400); + } }); }); diff --git a/apps/server/src/modules/agent/acp/connection-token.route.ts b/apps/server/src/modules/agent/acp/connection-token.route.ts index 0f57b7cdb..2bb692a19 100644 --- a/apps/server/src/modules/agent/acp/connection-token.route.ts +++ b/apps/server/src/modules/agent/acp/connection-token.route.ts @@ -1,16 +1,12 @@ // Copyright (c) Microsoft Corporation. // Licensed under the MIT license. -import { - agentletConnectionCommandRequestSchema, - connectionTokenUpdateSchema, -} from '@huabu/shared'; +import { agentletConnectionCommandRequestSchema } from '@huabu/shared'; import { buildAgentletConnectionCommand, - getConnectionTokenConfig, + InvalidAgentletConnectionEnvFileError, InvalidAgentletConnectionOriginError, - setConnectionToken, } from '../../../connection-token.js'; import { isOwnerRequest } from '../../security/owner.js'; @@ -18,44 +14,10 @@ import type { AgentletConnectionCommandRequest, AgentletConnectionCommandResponse, ApiResult, - ConnectionTokenConfig, - ConnectionTokenUpdate, } from '@huabu/shared'; import type { FastifyPluginAsync } from 'fastify'; const connectionTokenRoutes: FastifyPluginAsync = async (app) => { - app.get<{ Reply: ApiResult }>( - '/connection-token', - async (request, reply) => { - if (!isOwnerRequest(request)) { - return reply.status(403).send({ - message: - 'Forbidden: connection token settings require owner authorization', - }); - } - return getConnectionTokenConfig(); - }, - ); - - app.put<{ - Body: ConnectionTokenUpdate; - Reply: ApiResult; - }>('/connection-token', async (request, reply) => { - if (!isOwnerRequest(request)) { - return reply.status(403).send({ - message: - 'Forbidden: connection token settings require owner authorization', - }); - } - const parsed = connectionTokenUpdateSchema.safeParse(request.body); - if (!parsed.success) { - return reply - .status(400) - .send({ message: parsed.error.issues[0]?.message ?? 'Invalid body' }); - } - return reply.send(await setConnectionToken(parsed.data.token)); - }); - app.post<{ Body: AgentletConnectionCommandRequest; Reply: ApiResult; @@ -80,7 +42,7 @@ const connectionTokenRoutes: FastifyPluginAsync = async (app) => { .send({ message: 'Browser origin does not match request origin' }); } try { - const response = buildAgentletConnectionCommand(parsed.data.origin); + const response = buildAgentletConnectionCommand(parsed.data); return reply .header('Cache-Control', 'no-store') .header('Pragma', 'no-cache') @@ -89,6 +51,8 @@ const connectionTokenRoutes: FastifyPluginAsync = async (app) => { if (error instanceof InvalidAgentletConnectionOriginError) { return reply.status(400).send({ message: 'Invalid browser origin' }); } + if (error instanceof InvalidAgentletConnectionEnvFileError) + return reply.status(400).send({ message: error.message }); throw error; } }); diff --git a/apps/server/src/prompt/external-agent/service-config.md b/apps/server/src/prompt/external-agent/service-config.md index 18b726015..0eab7acda 100644 --- a/apps/server/src/prompt/external-agent/service-config.md +++ b/apps/server/src/prompt/external-agent/service-config.md @@ -2,7 +2,7 @@ Use this guide when the bundled Service entry cannot perform the provider operation you need, or when you have no compatible Node runtime. This is a configuration lease workflow, not a generic provider runner or proxy. -1. Discover configured Services with authenticated `GET $HUABU_RFS_URL/services`. Select only an Agent-facing Service that has a `skill` link. Read its `GET /services//skill` and credential-free `GET /services//manifest`; use the provider documentation linked by that Skill. +1. Discover configured Services with authenticated `GET $HUABU_RFS_URL/services`. Select only a Service with `availableToExternalAgent: true`. Read its `GET /services//skill` and credential-free `GET /services//manifest`; use the provider documentation linked by that Skill. 2. Write a business subprocess in your available language. Inside that process, send authenticated `POST /services//lease`, using `AGENTLET_TOKEN` from its inherited environment, without putting that token in argv. Reject non-2xx HTTP responses and invalid/incoherent lease data explicitly. A successful lease contains `id`, `version`, `manifest`, and `config`; use that one coherent response for the operation, not a separately cached Manifest. 3. Consume the lease in memory and authenticate only to the intended provider. Construct the documented provider request for your business operation; do not forward the Huabu bearer credential to the provider. Respect the Service's declared configuration keys and provider endpoint rather than inventing a universal environment mapping. 4. Emit only the business result (for example artifact bytes or a bounded result description). Do not dump the lease, provider request headers, or credentials into tool output, logs, files, argv, or a global shell environment. Sanitize provider diagnostics that could echo credentials. Do not send credentials to unrelated recipients. diff --git a/apps/server/src/security/environment-secret-store.ts b/apps/server/src/security/environment-secret-store.ts index 17a18361b..ef8b11305 100644 --- a/apps/server/src/security/environment-secret-store.ts +++ b/apps/server/src/security/environment-secret-store.ts @@ -22,9 +22,6 @@ export class EnvironmentSecretStore implements SecretStore { if (id === SECRET_IDS.rapidApiKey) { return process.env.RAPIDAPI_KEY ?? null; } - if (id === SECRET_IDS.agentletConnectionToken) { - return process.env.HUABU_CONNECTION_TOKEN?.trim() || null; - } if (id === SECRET_IDS.inkOcrApiKey) { return process.env.VISION_KEY?.trim() || null; } diff --git a/apps/server/src/security/secret-ids.ts b/apps/server/src/security/secret-ids.ts index 2f5f6dc67..32d5afaa2 100644 --- a/apps/server/src/security/secret-ids.ts +++ b/apps/server/src/security/secret-ids.ts @@ -5,6 +5,7 @@ export const SECRET_IDS = { imageApiKey: 'llm:image:api-key', tavilyApiKey: 'integration:tavily:api-key', rapidApiKey: 'integration:rapidapi:api-key', + // Retained for historical encrypted records, never used for connection auth. agentletConnectionToken: 'integration:agentlet:connection-token', inkOcrApiKey: 'integration:azure-vision:api-key', inkOcrConfig: 'integration:azure-vision:config', diff --git a/apps/web/src/api/_routes.ts b/apps/web/src/api/_routes.ts index 0f99f539b..4b7e450cb 100644 --- a/apps/web/src/api/_routes.ts +++ b/apps/web/src/api/_routes.ts @@ -165,7 +165,6 @@ export const routes = { acpAgentlet: '/acp/agentlet', acpAgentletRestart: '/acp/agentlet/restart', acpRuntimeConfig: '/acp/runtime-config', - acpConnectionToken: '/acp/connection-token', acpConnectionCommand: '/acp/connection-command', acpThreadCachedMeta: ( threadId: string, diff --git a/apps/web/src/api/acp.ts b/apps/web/src/api/acp.ts index 01b3b2563..a86f81ad6 100644 --- a/apps/web/src/api/acp.ts +++ b/apps/web/src/api/acp.ts @@ -17,7 +17,6 @@ * - `GET/POST/PATCH/DELETE /api/acp/profiles` — CRUD for spawn * recipes with revision-checked launch and working-directory edits. * - `GET/POST /api/acp/daemon` — daemon liveness + manual restart. - * - `GET/PUT /api/acp/connection-token` — masked credential configuration. * - `POST /api/acp/connection-command` — explicit owner-only command reveal. * - `GET /api/acp/threads/:threadId/cached-meta` — cached capabilities. * - thread control POSTs — canonical realization plus per-session knobs. @@ -45,8 +44,8 @@ import type { SetAcpSessionModeRequest, SetAcpSessionModeResponse, ExternalAgentRuntimeConfig, - ConnectionTokenConfig, - ConnectionTokenUpdate, + ConnectionShell, + ConnectionCopyFormat, AgentletConnectionCommandResponse, WarmAcpSessionRequest, WarmAcpSessionResponse, @@ -78,8 +77,8 @@ export type { SetAcpSessionModeRequest, SetAcpSessionModeResponse, ExternalAgentRuntimeConfig, - ConnectionTokenConfig, - ConnectionTokenUpdate, + ConnectionShell, + ConnectionCopyFormat, AgentletConnectionCommandResponse, ConnectedAgentletDevice, WarmAcpSessionRequest, @@ -191,28 +190,15 @@ export async function updateExternalAgentRuntimeConfig( }); } -export async function getConnectionTokenConfig(): Promise { - return apiFetch(routes.acpConnectionToken, { - fallbackMessage: 'Failed to read the Agentlet connection token settings', - }); -} - -export async function updateConnectionToken( - update: ConnectionTokenUpdate, -): Promise { - return apiFetch(routes.acpConnectionToken, { - method: 'PUT', - json: update, - fallbackMessage: 'Failed to update the Agentlet connection token', - }); -} - -export async function createAgentletConnectionCommand(): Promise { +export async function createAgentletConnectionCommand( + shell: ConnectionShell, + format: ConnectionCopyFormat, +): Promise { return apiFetch( routes.acpConnectionCommand, { method: 'POST', - json: { origin: window.location.origin }, + json: { origin: window.location.origin, shell, format }, fallbackMessage: 'Failed to create the Agentlet connection command', }, ); diff --git a/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.test.tsx b/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.test.tsx index 0c5bcbcb8..d21540f2f 100644 --- a/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.test.tsx +++ b/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.test.tsx @@ -7,28 +7,22 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; const { createConnectionCommand, - getConnectionTokenConfig, getRuntimeConfig, - updateConnectionToken, updateRuntimeConfig, toast, } = vi.hoisted(() => ({ createConnectionCommand: vi.fn(), - getConnectionTokenConfig: vi.fn(), getRuntimeConfig: vi.fn(), - updateConnectionToken: vi.fn(), updateRuntimeConfig: vi.fn(), toast: vi.fn(), })); - -vi.mock('react-i18next', () => ({ - useTranslation: () => ({ t: (key: string) => key }), -})); +vi.mock('react-i18next', () => { + const t = (key: string) => key; + return { useTranslation: () => ({ t }) }; +}); vi.mock('@/api/acp', () => ({ createAgentletConnectionCommand: createConnectionCommand, - getConnectionTokenConfig, getExternalAgentRuntimeConfig: getRuntimeConfig, - updateConnectionToken, updateExternalAgentRuntimeConfig: updateRuntimeConfig, })); vi.mock('@/components/Common/Toast', () => ({ toast })); @@ -36,30 +30,23 @@ vi.mock('@/components/Common/Toast', () => ({ toast })); import { ExternalAgentRuntimeSettings } from './ExternalAgentRuntimeSettings'; globalThis.IS_REACT_ACT_ENVIRONMENT = true; - let root: Root; let container: HTMLDivElement; - +const originalExecCommand = Object.getOwnPropertyDescriptor( + document, + 'execCommand', +); +const content = + "HUABU_PUBLIC_ORIGIN='https://huabu.example' HUABU_CONNECTION_TOKEN='secret' pnpm start:daemon --max-agents 10"; beforeEach(() => { - getRuntimeConfig.mockResolvedValue({ - idleTimeoutSecs: 600, - maxAgents: 10, - }); + getRuntimeConfig.mockResolvedValue({ idleTimeoutSecs: 600, maxAgents: 10 }); updateRuntimeConfig.mockResolvedValue({ idleTimeoutSecs: 1800, maxAgents: 10, }); - getConnectionTokenConfig.mockResolvedValue({ - source: 'stored', - writable: true, - }); - updateConnectionToken.mockResolvedValue({ - source: 'stored', - writable: true, - }); createConnectionCommand.mockResolvedValue({ - command: - "agentlet daemon --server 'wss://huabu.example/api/acp/agent' --max-agents 10 --token 'secret'", + content, + source: 'environment', warnings: [], }); Object.defineProperty(navigator, 'clipboard', { @@ -70,66 +57,52 @@ beforeEach(() => { document.body.appendChild(container); root = createRoot(container); }); - afterEach(() => { act(() => root.unmount()); container.remove(); vi.clearAllMocks(); + if (originalExecCommand) + Object.defineProperty(document, 'execCommand', originalExecCommand); + else Reflect.deleteProperty(document, 'execCommand'); }); +async function render() { + await act(async () => root.render()); +} +function button(key: string) { + const found = [...container.querySelectorAll('button')].find( + (button) => button.textContent === key, + ); + if (!found) throw new Error(`Button not found: ${key}`); + return found; +} describe('ExternalAgentRuntimeSettings', () => { - it('places responsive token controls below the full-width description', async () => { - await act(async () => { - root.render(); - }); - - const tokenInput = container.querySelector( - '#agentlet-connection-token', + it('shows preparation and responsive How to connect without token editors or automatic reveals', async () => { + await render(); + expect(container.textContent).toContain('settings.agentletHowToConnect'); + expect(container.textContent).toContain('git clone'); + expect(container.textContent).toContain('pnpm install'); + expect(container.textContent).toContain( + 'settings.agentletGeneratedTokenWarning', ); - if (!tokenInput) throw new Error('Connection token input not found'); - - const controls = tokenInput.parentElement; - const controlRow = controls?.parentElement; - const settingRow = controlRow?.parentElement; - expect(settingRow?.classList.contains('flex-col')).toBe(true); - expect(settingRow?.classList.contains('items-stretch')).toBe(true); - expect(controlRow?.classList.contains('w-full')).toBe(true); + expect(container.querySelector('input[type="password"]')).toBeNull(); + expect(container.querySelector('#agentlet-connection-token')).toBeNull(); + expect(container.textContent).not.toContain('secret'); + expect(createConnectionCommand).not.toHaveBeenCalled(); + const controls = button('settings.agentletCommandCopy').parentElement; expect(controls?.classList.contains('flex-wrap')).toBe(true); expect(controls?.classList.contains('w-full')).toBe(true); - expect(tokenInput.classList.contains('flex-1')).toBe(true); - expect(tokenInput.classList.contains('basis-56')).toBe(true); - - const buttons = controls?.querySelectorAll('button') ?? []; - expect(buttons.length).toBeGreaterThan(0); - for (const button of buttons) { - expect(button.classList.contains('shrink-0')).toBe(true); - expect(button.classList.contains('whitespace-nowrap')).toBe(true); - } + expect(controls?.parentElement?.classList.contains('w-full')).toBe(true); }); - it('preserves the process limit when saving the idle timeout', async () => { - await act(async () => { - root.render(); - }); - - const idleTimeout = [...container.querySelectorAll('button')].find( - (button) => button.textContent?.includes('settings.tenMinutesDefault'), - ); - if (!idleTimeout) throw new Error('Idle-timeout selector not found'); - - await act(async () => { - idleTimeout.click(); - }); - - const thirtyMinutes = [...document.body.querySelectorAll('button')].find( + it('preserves the process limit when saving idle timeout', async () => { + await render(); + await act(async () => button('settings.tenMinutesDefault').click()); + const selected = [...document.body.querySelectorAll('button')].find( (button) => button.textContent === 'settings.thirtyMinutes', ); - if (!thirtyMinutes) throw new Error('Thirty-minute option not found'); - - await act(async () => { - thirtyMinutes.click(); - }); - + if (!selected) throw new Error('Thirty-minute option not found'); + await act(async () => selected.click()); expect(updateRuntimeConfig).toHaveBeenCalledWith({ idleTimeoutSecs: 1800, maxAgents: 10, @@ -140,73 +113,87 @@ describe('ExternalAgentRuntimeSettings', () => { ); }); - it('does not render the active token and saves a replacement', async () => { - await act(async () => { - root.render(); - }); - - expect(container.textContent).not.toContain('secret'); - const tokenInput = container.querySelector( - '#agentlet-connection-token', + it.each([ + [ + 'settings.agentletCommandCopy', + 'command', + 'settings.agentletCommandCopied', + ], + [ + 'settings.agentletEnvFileCopy', + 'env-file', + 'settings.agentletEnvFileCopied', + ], + ])( + 'copies only on explicit action without rendering returned secret text', + async (key, format, copied) => { + await render(); + await act(async () => button(key).click()); + expect(createConnectionCommand).toHaveBeenCalledWith('posix', format); + expect(navigator.clipboard.writeText).toHaveBeenCalledWith(content); + expect(container.textContent).not.toContain('secret'); + expect(container.textContent).not.toContain('https://huabu.example'); + expect(toast).toHaveBeenCalledWith(copied, { tone: 'success' }); + }, + ); + + it('uses the explicit PowerShell choice instead of browser platform inference', async () => { + await render(); + const selector = container.querySelector( + '[aria-label="settings.agentletTargetShell"]', ); - if (!tokenInput) throw new Error('Connection token input not found'); - await act(async () => { - Object.getOwnPropertyDescriptor( - HTMLInputElement.prototype, - 'value', - )?.set?.call(tokenInput, 'replacement-token'); - tokenInput.dispatchEvent(new Event('input', { bubbles: true })); - }); - const saveButton = [ - ...(tokenInput.parentElement?.querySelectorAll('button') ?? []), - ].find((button) => button.textContent === 'settings.saveChanges'); - if (!saveButton) throw new Error('Connection token save button not found'); - await act(async () => { - saveButton.click(); - }); - - expect(updateConnectionToken).toHaveBeenCalledWith({ - token: 'replacement-token', - }); - expect(container.textContent).not.toContain('replacement-token'); - }); - - it('copies the generated command directly without rendering it', async () => { - await act(async () => { - root.render(); - }); - - const copyButton = [...container.querySelectorAll('button')].find( - (button) => button.textContent === 'settings.agentletCommandCopy', + if (!selector) throw new Error('Shell selector not found'); + await act(async () => selector.click()); + const powershell = [...document.body.querySelectorAll('button')].find( + (button) => button.textContent === 'PowerShell', ); - if (!copyButton) throw new Error('Copy command button not found'); - await act(async () => { - copyButton.click(); - }); - - expect(createConnectionCommand).toHaveBeenCalledOnce(); - expect(navigator.clipboard.writeText).toHaveBeenCalledWith( - expect.stringContaining('wss://huabu.example/api/acp/agent'), + if (!powershell) throw new Error('PowerShell choice not found'); + await act(async () => powershell.click()); + await act(async () => button('settings.agentletCommandCopy').click()); + expect(createConnectionCommand).toHaveBeenCalledWith( + 'powershell', + 'command', ); - expect(container.textContent).not.toContain('wss://huabu.example'); - expect(toast).toHaveBeenCalledWith('settings.agentletCommandCopied', { - tone: 'success', - }); }); - it('clears only the stored override', async () => { - await act(async () => { - root.render(); + it.each([ + ['generated', [], 'settings.agentletCommandCopiedGenerated'], + ['environment', ['loopback'], 'settings.agentletCommandCopiedLoopback'], + ['environment', ['insecure'], 'settings.agentletCommandCopiedInsecure'], + ])( + 'surfaces generated token and transport warnings', + async (source, warnings, key) => { + createConnectionCommand.mockResolvedValue({ content, source, warnings }); + await render(); + await act(async () => button('settings.agentletCommandCopy').click()); + expect(toast).toHaveBeenCalledWith(key, { tone: 'warning' }); + }, + ); + + it('reports HTTP/clipboard failure explicitly and re-enables both copy actions', async () => { + createConnectionCommand.mockRejectedValueOnce( + new Error('copy endpoint failed'), + ); + await render(); + await act(async () => button('settings.agentletCommandCopy').click()); + expect(toast).toHaveBeenCalledWith('copy endpoint failed', { + tone: 'danger', }); - - const clearButton = [...container.querySelectorAll('button')].find( - (button) => button.textContent === 'settings.agentletTokenClear', + expect(navigator.clipboard.writeText).not.toHaveBeenCalled(); + vi.mocked(navigator.clipboard.writeText).mockRejectedValueOnce( + new Error('clipboard blocked'), ); - if (!clearButton) throw new Error('Clear token button not found'); - await act(async () => { - clearButton.click(); + Object.defineProperty(document, 'execCommand', { + configurable: true, + value: vi.fn(() => { + throw new Error('clipboard blocked'); + }), }); - - expect(updateConnectionToken).toHaveBeenCalledWith({ token: null }); + await act(async () => button('settings.agentletEnvFileCopy').click()); + expect(toast).toHaveBeenCalledWith('clipboard blocked', { tone: 'danger' }); + expect(button('settings.agentletCommandCopy').disabled).toBe(false); + expect(button('settings.agentletEnvFileCopy').disabled).toBe(false); + expect(container.textContent).not.toContain('secret'); + expect(document.querySelector('textarea')).toBeNull(); }); }); diff --git a/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.tsx b/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.tsx index 6715b2e2e..0f58b1721 100644 --- a/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.tsx +++ b/apps/web/src/components/Settings/sections/ExternalAgentRuntimeSettings.tsx @@ -7,20 +7,17 @@ import { useTranslation } from 'react-i18next'; import { createAgentletConnectionCommand, - getConnectionTokenConfig, getExternalAgentRuntimeConfig, - updateConnectionToken, updateExternalAgentRuntimeConfig, } from '@/api/acp'; import { Button } from '@/components/Common/Button'; import { Input } from '@/components/Common/Input'; import { Select } from '@/components/Common/Select'; -import { TextInput } from '@/components/Common/TextInput'; import { toast } from '@/components/Common/Toast'; import { SettingRow } from '@/components/Settings/Common/SettingRow'; import { copyToClipboard } from '@/utils/io/clipboard'; -import type { ConnectionTokenConfig } from '@huabu/shared'; +import type { ConnectionCopyFormat, ConnectionShell } from '@huabu/shared'; const IDLE_TIMEOUT_PRESETS = new Set(['0', '300', '600', '1800', '3600']); @@ -33,13 +30,9 @@ export function ExternalAgentRuntimeSettings() { const [customMinutes, setCustomMinutes] = useState('10'); const [loading, setLoading] = useState(true); const [saving, setSaving] = useState(false); - const [tokenConfig, setTokenConfig] = useState( - null, - ); - const [tokenInput, setTokenInput] = useState(''); - const [tokenLoading, setTokenLoading] = useState(true); - const [tokenSaving, setTokenSaving] = useState(false); - const [copyingCommand, setCopyingCommand] = useState(false); + const [connectionShell, setConnectionShell] = + useState('posix'); + const [copying, setCopying] = useState(null); useEffect(() => { let active = true; @@ -74,29 +67,6 @@ export function ExternalAgentRuntimeSettings() { }; }, [t]); - useEffect(() => { - let active = true; - void getConnectionTokenConfig() - .then((config) => { - if (active) setTokenConfig(config); - }) - .catch((error) => { - if (!active) return; - toast( - error instanceof Error - ? error.message - : t('settings.agentletTokenLoadFailed'), - { tone: 'danger' }, - ); - }) - .finally(() => { - if (active) setTokenLoading(false); - }); - return () => { - active = false; - }; - }, [t]); - const saveIdleTimeout = useCallback( async (nextIdleTimeoutSecs: number) => { setSaving(true); @@ -173,69 +143,43 @@ export function ExternalAgentRuntimeSettings() { parsedCustomMinutes >= 1 && parsedCustomMinutes <= 1440; - const saveConnectionToken = useCallback(async () => { - const token = tokenInput.trim(); - if (!token || !tokenConfig?.writable) return; - setTokenSaving(true); - try { - setTokenConfig(await updateConnectionToken({ token })); - setTokenInput(''); - toast(t('settings.agentletTokenSaved'), { tone: 'success' }); - } catch (error) { - toast( - error instanceof Error - ? error.message - : t('settings.agentletTokenSaveFailed'), - { tone: 'danger' }, - ); - } finally { - setTokenSaving(false); - } - }, [t, tokenConfig?.writable, tokenInput]); - - const clearConnectionToken = useCallback(async () => { - if (!tokenConfig?.writable) return; - setTokenSaving(true); - try { - setTokenConfig(await updateConnectionToken({ token: null })); - setTokenInput(''); - toast(t('settings.agentletTokenCleared'), { tone: 'success' }); - } catch (error) { - toast( - error instanceof Error - ? error.message - : t('settings.agentletTokenSaveFailed'), - { tone: 'danger' }, - ); - } finally { - setTokenSaving(false); - } - }, [t, tokenConfig?.writable]); - - const copyConnectionCommand = useCallback(async () => { - setCopyingCommand(true); - try { - const result = await createAgentletConnectionCommand(); - await copyToClipboard(result.command); - const warningKey = result.warnings.includes('insecure') - ? 'settings.agentletCommandCopiedInsecure' - : result.warnings.includes('loopback') - ? 'settings.agentletCommandCopiedLoopback' - : 'settings.agentletCommandCopied'; - toast(t(warningKey), { - tone: result.warnings.length > 0 ? 'warning' : 'success', - }); - } catch (error) { - toast( - error instanceof Error - ? error.message - : t('settings.agentletCommandCopyFailed'), - { tone: 'danger' }, - ); - } finally { - setCopyingCommand(false); - } - }, [t]); + const copyConnection = useCallback( + async (format: ConnectionCopyFormat) => { + setCopying(format); + try { + const result = await createAgentletConnectionCommand( + connectionShell, + format, + ); + await copyToClipboard(result.content); + const warningKey = result.warnings.includes('insecure') + ? 'settings.agentletCommandCopiedInsecure' + : result.warnings.includes('loopback') + ? 'settings.agentletCommandCopiedLoopback' + : result.source === 'generated' + ? 'settings.agentletCommandCopiedGenerated' + : format === 'env-file' + ? 'settings.agentletEnvFileCopied' + : 'settings.agentletCommandCopied'; + toast(t(warningKey), { + tone: + result.warnings.length > 0 || result.source === 'generated' + ? 'warning' + : 'success', + }); + } catch (error) { + toast( + error instanceof Error + ? error.message + : t('settings.agentletCommandCopyFailed'), + { tone: 'danger' }, + ); + } finally { + setCopying(null); + } + }, + [connectionShell, t], + ); return ( <> @@ -243,7 +187,7 @@ export function ExternalAgentRuntimeSettings() { layout="stacked" title={ - {t('settings.agentletConnectionToken')} + {t('settings.agentletHowToConnect')} - {tokenConfig?.source === 'stored' ? ( - - ) : null}
+

+ {t('settings.agentletEnvFileInstructions')} +

+

+ {t('settings.agentletGeneratedTokenWarning')} +