taskflow-hosts 0.2.8 → 0.2.10

package/README.md

@@ -3,9 +3,9 @@
 > Shared host-runner collection for [taskflow](https://github.com/heggria/taskflow).
 
 This package holds the `SubagentRunner` implementations for taskflow's non-pi
-hosts — **codex**, **claude**, **opencode**, and **grok** — plus their pure argv
+hosts — **codex**, **claude**, **opencode**, **grok**, and **hermes** — plus their pure argv
 builders (`buildCodexArgs` / `buildClaudeArgs` / `buildOpencodeArgs` /
-`buildGrokArgs`) and event-stream parsers. It is the **single place** host
+`buildGrokArgs` / `buildHermesArgs`) and event-stream parsers. It is the **single place** host
 runners live; a new host adds a `<host>-runner.ts` here.
 
 ## Why a separate package
@@ -17,13 +17,13 @@ Each host has two halves:
    permission/model helpers.
 2. **The delivery** — the per-host MCP server + bin + plugin scaffold, which is
    that host ecosystem's install target (`codex plugin add`, `claude plugin
-   install`, OpenCode config, `grok plugin install`).
+   install`, OpenCode config, `grok plugin install`, Hermes `mcp_servers`).
 
 Half #1 is nearly identical in *shape* across hosts and changes for the same
 reasons (a `taskflow-core` contract change, or a host CLI flag change). Half #2
 is genuinely host-specific (different install mechanisms, different plugin
 manifests). So #1 is collected here; #2 stays in `codex-taskflow` /
-`claude-taskflow` / `opencode-taskflow` / `grok-taskflow`, which import their
+`claude-taskflow` / `opencode-taskflow` / `grok-taskflow` / `hermes-taskflow`, which import their
 runner from this package.
 
 ## Install
@@ -31,7 +31,7 @@ runner from this package.
 You usually don't install this directly — install the host delivery package:
 
 ```bash
-npm install -g codex-taskflow     # or claude-taskflow / opencode-taskflow / grok-taskflow
+npm install -g codex-taskflow     # or claude-taskflow / opencode-taskflow / grok-taskflow / hermes-taskflow
 ```
 
 For code-level use:
@@ -46,12 +46,14 @@ npm install taskflow-hosts
 // one host, tree-shaken:
 import { codexSubagentRunner, buildCodexArgs } from "taskflow-hosts/codex";
 import { grokSubagentRunner, buildGrokArgs } from "taskflow-hosts/grok";
+import { hermesSubagentRunner, buildHermesArgs } from "taskflow-hosts/hermes";
 
 // or the barrel:
 import {
 	claudeSubagentRunner,
 	opencodeSubagentRunner,
 	grokSubagentRunner,
+	hermesSubagentRunner,
 } from "taskflow-hosts";
 ```
 
@@ -69,6 +71,7 @@ helpers (`sandboxForTools`, `permissionArgsForTools` / `permissionArgsForGrokToo
 | Claude Code | `claude -p --output-format stream-json` | `claude-taskflow` |
 | OpenCode | `opencode run --format json` | `opencode-taskflow` |
 | Grok Build | `grok -p --output-format streaming-json` | `grok-taskflow` |
+| Hermes Agent | `hermes chat -q -Q --source tool` | `hermes-taskflow` |
 
 ## Adding a host
 

package/dist/hermes-runner.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Hermes Agent subagent runner — the Hermes host's `SubagentRunner`.
+ *
+ * Spawns an isolated one-shot:
+ *   hermes chat -q <prompt> -Q --source tool [--in cwd] [-m model] [-t toolsets]
+ *     [--reasoning level] [--max-turns N] [--yolo]
+ *
+ * Quiet mode (`-Q`) emits plain text on stdout (final answer).
+ * Session id is printed on stderr by Hermes so piped stdout stays clean.
+ * Mapping to the host-neutral contract:
+ *   - output       = stdout answer text (session id is stderr-only metadata)
+ *   - lastActivity = last non-empty stdout line
+ *   - usage        = unavailable from quiet mode (emptyUsage); budgeted runs
+ *                    still fail-closed at the engine when costs are required
+ *   - failure      = non-zero exit, or empty output with non-zero semantics
+ *
+ * Permission mapping:
+ *   - read-only + local-read tools → `-t taskflow_readonly_files`
+ *     (ephemeral plugin: read_file + search_files only; write_file/patch blocked)
+ *   - read-only without local tools → explicit empty model-only `-t`; network opt-in via
+ *     PI_TASKFLOW_HERMES_READONLY_WEB=1 → web,search
+ *   - mutating / default-capable → requires PI_TASKFLOW_HERMES_UNSAFE_YOLO=1 + `--yolo`
+ *   - isolation: ephemeral HERMES_HOME (creds + minimal config + RO plugin) and
+ *     `--ignore-rules` (not `--safe-mode`, so our config can disable reasoning UI)
+ *
+ * Quiet mode (`-Q`): answer on stdout; `session_id:` on stderr. Reasoning boxes
+ * are suppressed via config and stripped from output as defense-in-depth.
+ * Process handling (idle watchdog, abort, signal-kill, stderr cap, sanitize)
+ * is delegated to shared `runSubagentProcess` in taskflow-core.
+ *
+ * @see https://hermes-agent.nousresearch.com/docs/
+ */
+import { type AgentConfig, type LiveUpdate, type RunOptions, type RunResult, type SubagentRunner, type UsageStats } from "taskflow-core";
+/** Explicit operator acknowledgement required before Hermes may use `--yolo`
+ * (bypass dangerous-command approvals) for mutating/default-capable phases. */
+export declare const HERMES_UNSAFE_YOLO_ENV = "PI_TASKFLOW_HERMES_UNSAFE_YOLO";
+/** Optional max-turns override for child Hermes runs (default 64). */
+export declare const HERMES_MAX_TURNS_ENV = "PI_TASKFLOW_HERMES_MAX_TURNS";
+export declare function hermesUnsafeYoloEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Build a least-privilege env for a Hermes child.
+ * Keeps provider credentials + HERMES_HOME (for .env auth), but strips YOLO and
+ * other process-scoped bypass flags so parent gateway yolo cannot silently arm
+ * a read-only phase. Also strips prompt-injection HERMES_* control vars.
+ */
+export declare function hermesChildEnv(source?: NodeJS.ProcessEnv, opts?: {
+    allowUnsafeYolo?: boolean;
+}): NodeJS.ProcessEnv;
+/** Accumulated state folded from Hermes quiet-mode plain-text stdout. */
+export interface HermesAccumulator {
+    usage: UsageStats;
+    model?: string;
+    finalText: string;
+    lastActivity: string;
+    fatalError?: string;
+    /** Quiet mode has no structured terminal event; set true once we have seen
+     *  any non-meta stdout (or on process end via the runner when empty is OK). */
+    terminalSeen?: boolean;
+    sessionId?: string;
+}
+export declare function newHermesAccumulator(model?: string): HermesAccumulator;
+/**
+ * Fold one stdout line from `hermes chat -Q`. Stdout is answer text; Hermes
+ * session metadata is parsed from stderr after process exit. Empty lines are
+ * ignored for activity but preserved inside the body once content has started.
+ */
+export declare function foldHermesQuietLine(acc: HermesAccumulator, line: string): LiveUpdate | null;
+/** Override the hermes binary (tests / unusual installs). */
+export declare function hermesBin(): string;
+/**
+ * Decide whether a phase is read-only from its tool whitelist. No whitelist →
+ * not read-only (default-capable, needs --yolo opt-in).
+ *
+ * Hermes-mutating tool aliases (taskflow DSL style + hermes native names).
+ */
+export declare function isHermesReadOnlyPhase(tools: string[] | undefined): boolean;
+/** Hermes toolset name registered by the ephemeral taskflow_readonly plugin. */
+export declare const HERMES_READONLY_FILES_TOOLSET = "taskflow_readonly_files";
+/** Empty toolset — always pass `-t` so Hermes does not fall back to hermes-cli defaults. */
+export declare const HERMES_MODEL_ONLY_TOOLSET = "taskflow_model_only";
+/**
+ * Map a phase tool whitelist to Hermes `-t` toolsets. Best-effort:
+ *   - read-only + local-read aliases → `taskflow_readonly_files` (plugin)
+ *   - read-only + READONLY_WEB → adds web,search
+ *   - read-only otherwise → `taskflow_model_only` (empty toolset; NEVER omit -t —
+ *     Hermes defaults to full hermes-cli tools when -t is absent)
+ *   - mutating with explicit tools → union of matching toolsets (narrow)
+ *   - default / empty tools → file,terminal (network/control-plane denied)
+ *   - unmapped non-empty tools list → throw (never fail-open to wide default)
+ */
+export declare function resolveHermesToolsets(tools: string[] | undefined, readOnly: boolean, opts?: {
+    readonlyWeb?: boolean;
+}): string;
+/**
+ * Strip Hermes quiet-mode reasoning chrome and model think-tags from text.
+ * Primary suppression is `display.show_reasoning: false` in the ephemeral
+ * config; this is defense-in-depth when a model still leaks boxes/tags.
+ */
+export declare function stripHermesReasoningNoise(text: string): string;
+/** Opt-in network for read-only Hermes phases (default off). */
+export declare const HERMES_READONLY_WEB_ENV = "PI_TASKFLOW_HERMES_READONLY_WEB";
+export declare function hermesReadonlyWebEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Resolve a taskflow model id to something `hermes chat -m` accepts. */
+export declare function resolveHermesModel(model: string | undefined): string | undefined;
+/** Normalize Taskflow thinking aliases to Hermes `--reasoning` levels. */
+export declare function resolveHermesReasoning(thinking: string | undefined): string | undefined;
+export interface HermesArgsCtx {
+    systemPrompt: string;
+    task: string;
+    model?: string;
+    thinking?: string;
+    tools?: string[];
+    cwd?: string;
+    /** Explicit acknowledgement for Hermes `--yolo`. */
+    allowUnsafeYolo?: boolean;
+    /** Max tool-calling iterations (default 64). */
+    maxTurns?: number;
+    /** Opt-in network for read-only phases (PI_TASKFLOW_HERMES_READONLY_WEB=1). */
+    readonlyWeb?: boolean;
+}
+export interface HermesArgs {
+    args: string[];
+    readOnly: boolean;
+    toolsets: string;
+}
+/**
+ * Build the full `hermes chat` argv — PURE (no process.env, no spawn).
+ *
+ *   hermes chat -q <prompt> -Q --source tool
+ *     --ignore-rules
+ *     [--in cwd] [-m model] [-t toolsets] [--reasoning level]
+ *     [--max-turns N] [--yolo]
+ *
+ * Isolation: ephemeral HERMES_HOME (credentials + show_reasoning:false + RO
+ * plugin). `--ignore-rules` skips AGENTS.md injection. Do not use --safe-mode
+ * (it would ignore our ephemeral config/plugin).
+ * Credentials still load from the ephemeral home's .env/auth.json. */
+export declare function buildHermesArgs(ctx: HermesArgsCtx): HermesArgs;
+/** Keep only explicitly supported inference-provider assignments from dotenv. */
+export declare function filterHermesProviderDotenv(source: string): string;
+/** Filter Hermes auth.json to known inference-provider credential entries. */
+export declare function filterHermesAuthJson(source: string, routedProviders?: ReadonlySet<string>): string;
+/**
+ * Pull a top-level YAML mapping block (e.g. `model:`) from parent config text.
+ * Indentation-based; no full YAML parser dependency.
+ */
+export declare function extractYamlTopLevelBlock(source: string, key: string): string | undefined;
+/**
+ * Carry only non-secret scalar routing fields from the parent config.
+ * This deliberately omits `providers:` and all nested mappings (MCP/plugins/
+ * api_key/token) rather than treating indentation as a security boundary.
+ */
+export declare function sanitizeHermesRoutingConfig(source: string): string;
+/** Build ephemeral config.yaml text: isolation defaults + parent model routing. */
+export declare function buildEphemeralHermesConfigYaml(parentHome: string, opts?: {
+    readOnly?: boolean;
+}): string;
+export interface EphemeralHermesHome {
+    /** Temp directory used as HERMES_HOME for one child. */
+    home: string;
+    /** Remove the temp home (best-effort). */
+    cleanup: () => void;
+}
+/**
+ * Build a throwaway HERMES_HOME with credentials + minimal config + RO plugin.
+ * Children authenticate via .env/auth.json, cannot see parent skills/MCP, and
+ * get display.show_reasoning=false so quiet stdout stays clean.
+ */
+export declare function prepareEphemeralHermesHome(parentHome: string, opts?: {
+    tmpRoot?: string;
+    readOnly?: boolean;
+}): EphemeralHermesHome;
+/**
+ * Resolve the operator Hermes profile to clone credentials/model routing from.
+ * Prefer `PI_TASKFLOW_HERMES_PARENT_HOME`, then a usable `HERMES_HOME`, then `~/.hermes`.
+ * Skips ephemeral taskflow temps and empty tmp HERMES_HOME leftovers.
+ */
+export declare function resolveParentHermesHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * Run a single subagent task via `hermes chat -q -Q`. Resolves the agent from
+ * `agents` by name; returns the same structured `RunResult` the other host
+ * runners produce.
+ */
+export declare function runHermesAgentTask(defaultCwd: string, agents: AgentConfig[], agentName: string, task: string, opts: RunOptions, globalThinking?: string): Promise<RunResult>;
+/** The Hermes host's `SubagentRunner`. Drops into `RuntimeDeps.runTask`. */
+export declare const hermesSubagentRunner: SubagentRunner<AgentConfig>;
+//# sourceMappingURL=hermes-runner.d.ts.map

package/dist/hermes-runner.d.ts.map

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