@router-agent/runtime-herdr 0.0.0-stage → 0.3.31

package/dist/herdr/agents.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Herdr 支持的 Agent kind 与「无人值守」启动参数。
+ *
+ * 这里只放纯常量与纯函数，不能依赖任何 Node 内置模块 —— Web 面板会把它一起打进前端包。
+ */
+export interface HerdrAgentKind {
+    /** Herdr 的 --kind 取值。 */
+    value: string;
+    label: string;
+    /** 无人值守所需的启动参数：Worker 开工时没有人点确认。 */
+    args: string[];
+    /** 模型参数怎么传；不同 CLI 不一样。 */
+    modelFlag?: string;
+}
+/**
+ * ra 支持的 Herdr Agent kind。
+ *
+ * 只列 ra 自己有会话读取器、或已验证过无人值守参数的 Agent；
+ * Herdr 自己支持更多 kind（见 `herdr agent start --help`），但 ra 读不回它们的会话。
+ */
+export declare const HERDR_AGENT_KINDS: readonly HerdrAgentKind[];
+export declare function herdrAgentKindOf(kind: string): HerdrAgentKind | undefined;

package/dist/herdr/agents.js

@@ -0,0 +1,38 @@
+/**
+ * Herdr 支持的 Agent kind 与「无人值守」启动参数。
+ *
+ * 这里只放纯常量与纯函数，不能依赖任何 Node 内置模块 —— Web 面板会把它一起打进前端包。
+ */
+/**
+ * ra 支持的 Herdr Agent kind。
+ *
+ * 只列 ra 自己有会话读取器、或已验证过无人值守参数的 Agent；
+ * Herdr 自己支持更多 kind（见 `herdr agent start --help`），但 ra 读不回它们的会话。
+ */
+export const HERDR_AGENT_KINDS = [
+    {
+        value: 'claude',
+        label: 'claude · Claude Code',
+        // Claude Code 在新目录首次启动会弹「是否信任此文件夹」；跳过权限确认会一并跳过它，
+        // 否则 Herdr 把这个弹窗识别成 blocked，`agent start` 直接以 agent_not_ready 失败。
+        args: ['--dangerously-skip-permissions'],
+        modelFlag: '--model',
+    },
+    {
+        value: 'codex',
+        label: 'codex · Codex',
+        args: ['--dangerously-bypass-approvals-and-sandbox'],
+        modelFlag: '--model',
+    },
+    {
+        value: 'opencode',
+        label: 'opencode · OpenCode',
+        args: ['--auto'],
+        modelFlag: '--model',
+    },
+];
+export function herdrAgentKindOf(kind) {
+    const value = String(kind ?? '').trim();
+    return HERDR_AGENT_KINDS.find(item => item.value === value);
+}
+//# sourceMappingURL=agents.js.map

package/dist/herdr/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../../../../packages/runtime-herdr/src/herdr/agents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA8B;IAC1D;QACE,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,sBAAsB;QAC7B,iDAAiD;QACjD,kEAAkE;QAClE,IAAI,EAAE,CAAC,gCAAgC,CAAC;QACxC,SAAS,EAAE,SAAS;KACrB;IACD;QACE,KAAK,EAAE,OAAO;QACd,KAAK,EAAE,eAAe;QACtB,IAAI,EAAE,CAAC,4CAA4C,CAAC;QACpD,SAAS,EAAE,SAAS;KACrB;IACD;QACE,KAAK,EAAE,UAAU;QACjB,KAAK,EAAE,qBAAqB;QAC5B,IAAI,EAAE,CAAC,QAAQ,CAAC;QAChB,SAAS,EAAE,SAAS;KACrB;CACF,CAAA;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACvC,OAAO,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,CAAA;AAC7D,CAAC"}

package/dist/herdr/commands.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Herdr CLI 的 argv 构造。
+ *
+ * 只放纯函数：拼命令的地方集中在一处，adapter 与单测都从这里取。
+ *
+ * Herdr CLI 的约定（见 https://herdr.dev/docs/cli-reference）：
+ * - 结果类命令把 JSON 打到 stdout；
+ * - 失败时把 `{"id":…,"error":{"code":…,"message":…}}` 打到 stderr，退出码 1；
+ * - `agent read` / `pane read` 例外：它们直接把终端文本打到 stdout，不是 JSON。
+ *
+ * 检出与分支由 ra 自己用 git worktree 管（见 GitWorktreeProvider），
+ * Herdr 只负责「在终端里跑 Agent」这件基础事 —— 所以这里没有 worktree 命令。
+ */
+import type { CommandResult, CommandRunner } from '@router-agent/infra/process.js';
+export type { CommandResult, CommandRunner };
+/** `agent start` 的启动超时；Herdr 要求大于 3000 且不超过 300000 毫秒。 */
+export declare const HERDR_AGENT_START_TIMEOUT_MS = 60000;
+/** 在指定目录上开一个 Herdr workspace；它会带出第一个 tab 与根 pane。 */
+export declare function workspaceCreate(opts: {
+    cwd: string;
+    label?: string;
+}): string[];
+/** 关掉 workspace（连带它的 tab 与 pane）。 */
+export declare function workspaceClose(workspaceId: string): string[];
+/** 在指定 pane 里启动 Agent；`args` 原样透传给 Agent 可执行文件。 */
+export declare function agentStart(opts: {
+    name: string;
+    kind: string;
+    pane: string;
+    timeoutMs?: number;
+    args?: string[];
+}): string[];
+/** 提交一条输入（Herdr 会补上 Enter）。 */
+export declare function agentPrompt(target: string, text: string): string[];
+export declare function agentGet(target: string): string[];
+/** 读取终端渲染文本。`recent-unwrapped` 会展开软换行，适合看 Agent 的回复。 */
+export declare function agentRead(target: string, opts?: {
+    lines?: number;
+    source?: string;
+}): string[];
+export declare function paneRead(paneId: string, opts?: {
+    lines?: number;
+    source?: string;
+}): string[];
+export declare function agentList(): string[];
+/** 给 Agent 的交互界面发按键（enter / esc / down / ctrl+c …）。 */
+export declare function agentSendKeys(target: string, keys: string[]): string[];
+export declare function paneClose(paneId: string): string[];
+export declare function serverStatus(): string[];
+export declare function version(): string[];

package/dist/herdr/commands.js

@@ -0,0 +1,68 @@
+/** `agent start` 的启动超时；Herdr 要求大于 3000 且不超过 300000 毫秒。 */
+export const HERDR_AGENT_START_TIMEOUT_MS = 60_000;
+/** 在指定目录上开一个 Herdr workspace；它会带出第一个 tab 与根 pane。 */
+export function workspaceCreate(opts) {
+    return [
+        'workspace', 'create',
+        '--cwd', opts.cwd,
+        ...(opts.label ? ['--label', opts.label] : []),
+        // 不抢焦点：Router 不是交互式终端，抢焦点会打断用户正在看的 Herdr 窗口。
+        '--no-focus',
+    ];
+}
+/** 关掉 workspace（连带它的 tab 与 pane）。 */
+export function workspaceClose(workspaceId) {
+    return ['workspace', 'close', workspaceId];
+}
+/** 在指定 pane 里启动 Agent；`args` 原样透传给 Agent 可执行文件。 */
+export function agentStart(opts) {
+    return [
+        'agent', 'start', opts.name,
+        '--kind', opts.kind,
+        '--pane', opts.pane,
+        '--timeout', String(opts.timeoutMs ?? HERDR_AGENT_START_TIMEOUT_MS),
+        // `--` 之后的参数原样交给 Agent；没有参数时不要多传一个裸 `--`。
+        ...(opts.args?.length ? ['--', ...opts.args] : []),
+    ];
+}
+/** 提交一条输入（Herdr 会补上 Enter）。 */
+export function agentPrompt(target, text) {
+    return ['agent', 'prompt', target, text];
+}
+export function agentGet(target) {
+    return ['agent', 'get', target];
+}
+/** 读取终端渲染文本。`recent-unwrapped` 会展开软换行，适合看 Agent 的回复。 */
+export function agentRead(target, opts = {}) {
+    return [
+        'agent', 'read', target,
+        '--source', opts.source ?? 'recent-unwrapped',
+        '--lines', String(opts.lines ?? 60),
+    ];
+}
+// pane 级读取不要求 Agent 已被 Herdr 登记，因此「Agent 卡在启动前的确认弹窗」
+// 这种状态也读得到 —— 判断「是否信任此文件夹」弹窗正需要它。
+export function paneRead(paneId, opts = {}) {
+    return [
+        'pane', 'read', paneId,
+        '--source', opts.source ?? 'visible',
+        '--lines', String(opts.lines ?? 40),
+    ];
+}
+export function agentList() {
+    return ['agent', 'list'];
+}
+/** 给 Agent 的交互界面发按键（enter / esc / down / ctrl+c …）。 */
+export function agentSendKeys(target, keys) {
+    return ['agent', 'send-keys', target, ...keys];
+}
+export function paneClose(paneId) {
+    return ['pane', 'close', paneId];
+}
+export function serverStatus() {
+    return ['status', 'server'];
+}
+export function version() {
+    return ['--version'];
+}
+//# sourceMappingURL=commands.js.map

package/dist/herdr/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../../../../packages/runtime-herdr/src/herdr/commands.ts"],"names":[],"mappings":"AAiBA,0DAA0D;AAC1D,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAA;AAElD,qDAAqD;AACrD,MAAM,UAAU,eAAe,CAAC,IAAqC;IACnE,OAAO;QACL,WAAW,EAAE,QAAQ;QACrB,OAAO,EAAE,IAAI,CAAC,GAAG;QACjB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,6CAA6C;QAC7C,YAAY;KACb,CAAA;AACH,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,OAAO,CAAC,WAAW,EAAE,OAAO,EAAE,WAAW,CAAC,CAAA;AAC5C,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,UAAU,CAAC,IAM1B;IACC,OAAO;QACL,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI;QAC3B,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,QAAQ,EAAE,IAAI,CAAC,IAAI;QACnB,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,4BAA4B,CAAC;QACnE,0CAA0C;QAC1C,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;KACnD,CAAA;AACH,CAAC;AAED,+BAA+B;AAC/B,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,IAAY;IACtD,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAA;AACjC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,OAA4C,EAAE;IACtF,OAAO;QACL,OAAO,EAAE,MAAM,EAAE,MAAM;QACvB,UAAU,EAAE,IAAI,CAAC,MAAM,IAAI,kBAAkB;QAC7C,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;KACpC,CAAA;AACH,CAAC;AAED,qDAAqD;AACrD,kCAAkC;AAClC,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,OAA4C,EAAE;IACrF,OAAO;QACL,MAAM,EAAE,MAAM,EAAE,MAAM;QACtB,UAAU,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS;QACpC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;KACpC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC1B,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,IAAc;IAC1D,OAAO,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,CAAA;AAChD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAAc;IACtC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,CAAC,WAAW,CAAC,CAAA;AACtB,CAAC"}

package/dist/herdr/index.d.ts

@@ -0,0 +1,152 @@
+import type { ActivityQuery, AgentOutput, AgentStatus, DeliveryReceipt, DeliverOptions, DiagnosticCheck, InboundMessage, RuntimeCapabilities, SessionSnapshot, StartResult, WorkerContext, WorkerRef, WorkerRuntime, WorkspaceInfo, WorkspaceRef } from '@router-agent/runtime';
+import { type HerdrServerSpawner } from './server.js';
+import { type CommandResult, type CommandRunner } from './commands.js';
+export interface HerdrRuntimeOptions {
+    herdr: CommandRunner;
+    /** git runner；用来创建 / 回收检出。 */
+    git: CommandRunner;
+    /** ~/.router-agent/workers */
+    workersDir: string;
+    /** 状态目录；传入后 Worker 规范优先读 `<home>/specs/worker/` 下的覆盖文件。 */
+    home?: string;
+    /** 派工时启动哪个 Agent（Herdr 的 kind）；缺省用选项声明里的默认值。 */
+    agent?: string;
+    /** 传给 Agent 的模型；缺省用 Agent 自己的配置。 */
+    model?: string;
+    /** Claude Code 会话记录目录；默认 ~/.claude/projects，测试可注入临时目录。 */
+    claudeProjectsDir?: string;
+    /** 允许创建检出的根目录；默认 <home>/worktrees。 */
+    worktreesRoot?: string;
+    /** 拉起 Herdr 服务端用的动作；测试可注入空实现。 */
+    spawnServer?: HerdrServerSpawner;
+}
+/** Herdr 的错误体：`{"id":…,"error":{"code":…,"message":…}}`。 */
+export interface HerdrCliError {
+    code: string;
+    message: string;
+}
+export declare class HerdrRuntime implements WorkerRuntime {
+    readonly id = "herdr";
+    readonly capabilities: RuntimeCapabilities;
+    private herdr;
+    private git;
+    private workersDir;
+    private home?;
+    private agent;
+    private model?;
+    private claudeProjectsDir?;
+    private worktreesRoot;
+    private gitProvider;
+    private spawnServer?;
+    constructor(opts: HerdrRuntimeOptions);
+    start(ctx: WorkerContext): Promise<StartResult>;
+    deliver(ref: WorkerRef, inputs: InboundMessage[], _opts?: DeliverOptions): Promise<DeliveryReceipt>;
+    /**
+     * 停止：关掉承载 Agent 的 pane（连带 workspace）。
+     *
+     * 回收检出不在这里做 —— 那是 removeWorkspace 的事，拆开是为了让
+     * 「先停 Agent、稍后再回收目录」这种节奏也能成立。
+     */
+    stop(ref: WorkerRef, _reason: string): Promise<void>;
+    /** 状态：把 Herdr 的屏幕识别结果映射成中立的 AgentStatus。 */
+    status(ref: WorkerRef): Promise<AgentStatus | null>;
+    /** 输出尾部：读终端渲染文本；Agent 正在忙时退回 visible 源。 */
+    output(ref: WorkerRef, opts?: {
+        limit?: number;
+    }): Promise<AgentOutput | null>;
+    /** 结构化活动：读 Agent 自己的会话记录，比终端屏幕干净。 */
+    activity(query: ActivityQuery): Promise<SessionSnapshot | null>;
+    inspectWorkspace(ref: WorkspaceRef): Promise<WorkspaceInfo | null>;
+    /** 回收检出：先关 Herdr 窗口，再让 git 删掉 worktree。 */
+    removeWorkspace(ref: WorkspaceRef): Promise<void>;
+    doctor(): Promise<DiagnosticCheck[]>;
+    /**
+     * 本地路径仓库的 PR 跟踪需要 owner/repo。
+     *
+     * 检出是源仓库的 linked worktree，origin 与源仓库一致，
+     * 所以直接在检出目录里读 remote 就行。
+     */
+    repoSlug(ref: WorkerRef): Promise<string | null>;
+    /** 服务端不在就把它拉起来；拉不起来时给出可重试的 runtime:unavailable。 */
+    private ensureServer;
+    private createWorkspace;
+    /**
+     * 拉起 Agent，并处理两种「起不来」：
+     * - 名字被上一轮残留的 Agent 占了：把那个 pane 关掉再试一次；
+     * - Agent 卡在启动前的确认弹窗（Claude Code 的「信任此文件夹」）：替用户点掉。
+     */
+    private startAgent;
+    /**
+     * 自动确认「是否信任此文件夹」。
+     *
+     * 弹窗默认选中「No, exit」，所以往下挪一格选「Yes, I trust this folder」再回车。
+     * 只在文本确实命中时才动手，避免误触别的确认框。
+     */
+    private acceptTrustPrompt;
+    /** 等 Agent 从 blocked 变成能收输入的状态。 */
+    private waitForAgentReady;
+    private agentKind;
+    private launchArgs;
+    private startError;
+    private run;
+    /** 启动半失败时把窗口与检出回收掉，避免重试撞分支。 */
+    private rollback;
+    /**
+     * 删检出。
+     *
+     * `git worktree remove` 必须在仓库上下文里跑，所以 cwd 给源仓库而不是检出目录；
+     * 检出里有改动时先温和地删，失败了再强制删。
+     */
+    private removeWorktree;
+    private metaPath;
+    private readMeta;
+    private writeMeta;
+    private clearMeta;
+}
+/** 投递时带上输入 id：worker 只有看到 id 才能写进 acked_inputs，Router 才不会重投。 */
+export declare function renderInput(input: InboundMessage): string;
+/**
+ * 把契约里的「工作目录待定」占位换成 Herdr 实际建出来的检出路径。
+ *
+ * 中立契约里写的是「(由运行时决定)」，Orca 的手册里写的是「(由 Orca 决定)」；
+ * 两种都换成真实路径，worker 才知道自己在哪。
+ */
+export declare function withWorkdir(text: string, workdir: string): string;
+/**
+ * Agent 名字：`<项目>-<分支>-<短哈希>`。
+ *
+ * Herdr 要求名字匹配 `[a-z][a-z0-9_-]{0,31}` 且存活期间唯一。
+ * 末尾的短哈希由「工具 + 项目路径 + 分支」算出：同一个组合永远得到同一个名字，
+ * 换个工具或换个分支立刻不同 —— 比工单号这种递增数字稳定，
+ * 重派工时也能算出同名（撞名就回收旧窗口）。
+ */
+export declare function agentNameFor(opts: {
+    kind: string;
+    repo: string;
+    branch: string;
+}): string;
+/** 内容哈希：短、稳定、只做唯一后缀。 */
+export declare function shortHash(input: string, length?: number): string;
+export interface HerdrWorkspaceResult {
+    paneId?: string;
+    workspaceId?: string;
+    tabId?: string;
+}
+/** 解析 `herdr workspace create` 的返回。 */
+export declare function parseWorkspaceResult(stdout: string): HerdrWorkspaceResult;
+/** 从「名字被占用」的错误里捞出占用者所在的 pane。 */
+export declare function parseStalePaneId(message: string): string | null;
+export interface HerdrAgentInfo {
+    status: string;
+    kind?: string;
+    name?: string;
+    paneId?: string;
+    stateChangeSeq?: number;
+    completionSeq?: number;
+    sessionId?: string;
+    interactiveReady?: boolean;
+}
+/** 解析 `herdr agent get/start/prompt` 里的 Agent 快照。 */
+export declare function parseAgent(stdout: string): HerdrAgentInfo | null;
+/** 解析 Herdr CLI 的错误体。 */
+export declare function parseCliError(res: CommandResult): HerdrCliError | null;