@zhijiewang/openharness 2.37.0 → 2.39.0

package/dist/commands/info.js

@@ -10,7 +10,7 @@ import { estimateMessageTokens } from "../harness/context-warning.js";
 import { getContextWindow } from "../harness/cost.js";
 import { getHooks, invalidateHookCache } from "../harness/hooks.js";
 import { discoverPlugins, discoverSkills } from "../harness/plugins.js";
-import { formatTrace, listTracedSessions, loadTrace } from "../harness/traces.js";
+import { formatFlameGraph, formatTrace, listTracedSessions, loadTrace } from "../harness/traces.js";
 import { getVerificationConfig, invalidateVerificationCache } from "../harness/verification.js";
 import { normalizeMcpConfig } from "../mcp/config-normalize.js";
 import { connectedMcpServers, disconnectMcpClients, loadMcpTools } from "../mcp/loader.js";
@@ -358,13 +358,18 @@ export function registerInfoCommands(register, getCommandMap) {
     register("hooks", "List loaded hooks grouped by event", () => {
         return { output: formatHooksReport(getHooks()), handled: true };
     });
-    register("traces", "List sessions with persisted OTel-style traces (or show one with /traces <sessionId>)", (args) => {
-        const id = args.trim();
+    register("traces", "List sessions with persisted OTel-style traces (or show one with /traces <sessionId>; add --flame for a flame-graph view)", (args) => {
+        // Parse: `<sessionId>` for tree view, `<sessionId> --flame` (or `--flamegraph`)
+        // for the time-axis flame view. Order doesn't matter — accept the flag
+        // before or after the id.
+        const tokens = args.trim().split(/\s+/).filter(Boolean);
+        const flame = tokens.some((t) => t === "--flame" || t === "--flamegraph" || t === "--flame-graph");
+        const id = tokens.find((t) => !t.startsWith("--"));
         if (id) {
             const spans = loadTrace(id);
             if (spans.length === 0)
                 return { output: `No trace found for session ${id}.`, handled: true };
-            return { output: formatTrace(spans), handled: true };
+            return { output: flame ? formatFlameGraph(spans) : formatTrace(spans), handled: true };
         }
         const sessions = listTracedSessions();
         if (sessions.length === 0) {

package/dist/harness/traces.d.ts

@@ -83,6 +83,31 @@ export declare function loadTrace(sessionId: string): TraceSpan[];
 export declare function listTracedSessions(): string[];
 /** Format trace for display */
 export declare function formatTrace(spans: TraceSpan[]): string;
+/**
+ * Render spans as a flame-graph (icicle-graph really — top-down by depth).
+ * Each span gets one row: indent by tree depth, then a bar of `█` characters
+ * positioned along a wall-time axis sized to `width` columns. Bars start at
+ * the column corresponding to the span's `startTime` relative to the trace's
+ * minimum startTime, and span as many columns as their `durationMs` requires
+ * (minimum 1 column so even sub-millisecond spans are visible).
+ *
+ * Total trace duration sets the time-axis scale: a 5-second trace and a
+ * 50-second trace both fit the same `width`, so the same view works at any
+ * scale without scrolling. Per-span ms label appears to the right of the bar;
+ * span name appears at the left, indented by parent depth.
+ *
+ * Errored spans (status: "error") render in red; others use a stable
+ * per-name color so the same tool keeps the same color across the trace.
+ *
+ * The bottom row is a time ruler with ticks at 0ms, 25%, 50%, 75%, 100%.
+ *
+ * @param spans the spans to render — typically `loadTrace(sessionId)`
+ * @param width target width in columns (defaults to terminal width or 100)
+ * @param opts.color emit ANSI color codes (defaults to true; set false for tests)
+ */
+export declare function formatFlameGraph(spans: TraceSpan[], width?: number, opts?: {
+    color?: boolean;
+}): string;
 /** Export trace in OpenTelemetry-compatible format */
 export declare function exportTraceOTLP(sessionId: string, spans: TraceSpan[]): object;
 //# sourceMappingURL=traces.d.ts.map

package/dist/harness/traces.js

@@ -220,6 +220,174 @@ export function formatTrace(spans) {
     lines.push(`Total: ${spans.length} spans, ${totalMs}ms, ${errors} errors`);
     return lines.join("\n");
 }
+// ── Flame-graph rendering ──
+/** ANSI 256 colors picked for distinguishability across span names. */
+const FLAME_COLORS = [
+    "\x1b[38;5;202m", // orange (query)
+    "\x1b[38;5;39m", // light blue (tool:Read)
+    "\x1b[38;5;208m", // bright orange (tool:Bash)
+    "\x1b[38;5;105m", // purple (tool:Edit)
+    "\x1b[38;5;118m", // green (tool:Glob/Grep)
+    "\x1b[38;5;226m", // yellow (tool:Web*)
+    "\x1b[38;5;213m", // pink (think tools)
+    "\x1b[38;5;245m", // grey (other)
+];
+const ANSI_RESET = "\x1b[0m";
+const ANSI_DIM = "\x1b[2m";
+const ANSI_RED = "\x1b[38;5;196m";
+function colorForSpan(name) {
+    // Stable hash so the same span name always lands the same color across renders.
+    let hash = 0;
+    for (let i = 0; i < name.length; i++)
+        hash = (hash * 31 + name.charCodeAt(i)) >>> 0;
+    return FLAME_COLORS[hash % FLAME_COLORS.length];
+}
+/**
+ * Render spans as a flame-graph (icicle-graph really — top-down by depth).
+ * Each span gets one row: indent by tree depth, then a bar of `█` characters
+ * positioned along a wall-time axis sized to `width` columns. Bars start at
+ * the column corresponding to the span's `startTime` relative to the trace's
+ * minimum startTime, and span as many columns as their `durationMs` requires
+ * (minimum 1 column so even sub-millisecond spans are visible).
+ *
+ * Total trace duration sets the time-axis scale: a 5-second trace and a
+ * 50-second trace both fit the same `width`, so the same view works at any
+ * scale without scrolling. Per-span ms label appears to the right of the bar;
+ * span name appears at the left, indented by parent depth.
+ *
+ * Errored spans (status: "error") render in red; others use a stable
+ * per-name color so the same tool keeps the same color across the trace.
+ *
+ * The bottom row is a time ruler with ticks at 0ms, 25%, 50%, 75%, 100%.
+ *
+ * @param spans the spans to render — typically `loadTrace(sessionId)`
+ * @param width target width in columns (defaults to terminal width or 100)
+ * @param opts.color emit ANSI color codes (defaults to true; set false for tests)
+ */
+export function formatFlameGraph(spans, width = process.stdout.columns || 100, opts = {}) {
+    if (spans.length === 0)
+        return "No trace spans recorded.";
+    const useColor = opts.color !== false;
+    const c = (style, text) => (useColor ? `${style}${text}${ANSI_RESET}` : text);
+    // Trace bounds — every other timestamp is relative to minStart.
+    let minStart = Infinity;
+    let maxEnd = 0;
+    for (const s of spans) {
+        if (s.startTime < minStart)
+            minStart = s.startTime;
+        if (s.endTime > maxEnd)
+            maxEnd = s.endTime;
+    }
+    const totalMs = maxEnd > minStart ? maxEnd - minStart : 1;
+    // Layout: name column gets up to 30 chars; ms label gets up to 10; the rest
+    // is the bar canvas. We need at least ~20 cols of bar canvas to be useful.
+    const NAME_WIDTH = 30;
+    const MS_WIDTH = 10;
+    const PADDING = 3; // spaces between sections
+    const barWidth = Math.max(20, width - NAME_WIDTH - MS_WIDTH - PADDING);
+    // Build the depth map by walking the parent chain (spans are typically in
+    // start-order but we don't rely on it). Caps recursion to prevent infinite
+    // loops on a malformed trace where parent references form a cycle.
+    const byId = new Map(spans.map((s) => [s.spanId, s]));
+    const depthOf = new Map();
+    function depth(span, hops = 0) {
+        if (hops > 50)
+            return hops;
+        if (depthOf.has(span.spanId))
+            return depthOf.get(span.spanId);
+        let d = 0;
+        if (span.parentSpanId) {
+            const parent = byId.get(span.parentSpanId);
+            if (parent)
+                d = depth(parent, hops + 1) + 1;
+        }
+        depthOf.set(span.spanId, d);
+        return d;
+    }
+    for (const s of spans)
+        depth(s);
+    // Sort by start time, ties broken by depth (parents before children).
+    const sorted = [...spans].sort((a, b) => a.startTime - b.startTime || depthOf.get(a.spanId) - depthOf.get(b.spanId));
+    const lines = [];
+    for (const span of sorted) {
+        const d = depthOf.get(span.spanId);
+        const offset = Math.floor(((span.startTime - minStart) / totalMs) * barWidth);
+        const length = Math.max(1, Math.floor((span.durationMs / totalMs) * barWidth));
+        const indent = "  ".repeat(Math.min(d, 4)); // visual cap at 4 indent levels
+        const name = `${indent}${span.name}`.padEnd(NAME_WIDTH).slice(0, NAME_WIDTH);
+        const bar = " ".repeat(offset) + "█".repeat(Math.min(length, barWidth - offset));
+        const paddedBar = bar.padEnd(barWidth);
+        const color = span.status === "error" ? ANSI_RED : colorForSpan(span.name);
+        const msLabel = `${span.durationMs}ms`.padStart(MS_WIDTH);
+        lines.push(`${name}   ${c(color, paddedBar)} ${c(ANSI_DIM, msLabel)}`);
+    }
+    // Time ruler: 3-5 ticks depending on canvas width. We need ~8 columns per
+    // tick to fit timestamp labels without overlap; choose count that fits.
+    const tickCount = barWidth >= 50 ? 5 : barWidth >= 30 ? 3 : 2;
+    const tickPcts = [];
+    for (let i = 0; i < tickCount; i++)
+        tickPcts.push(i / (tickCount - 1));
+    const tickValues = tickPcts.map((pct) => `${Math.round(totalMs * pct)}ms`);
+    const rulerLine = " ".repeat(NAME_WIDTH + 3) + buildTimeRuler(barWidth, tickValues);
+    lines.push("");
+    lines.push(c(ANSI_DIM, rulerLine));
+    // Per-name summary: count + total ms, descending by total ms.
+    const summary = {};
+    for (const s of spans) {
+        const e = summary[s.name] ?? { count: 0, totalMs: 0 };
+        e.count++;
+        e.totalMs += s.durationMs;
+        summary[s.name] = e;
+    }
+    const ranked = Object.entries(summary).sort((a, b) => b[1].totalMs - a[1].totalMs);
+    lines.push("");
+    lines.push(c(ANSI_DIM, "Span breakdown (top by total time):"));
+    for (const [name, { count, totalMs: tms }] of ranked.slice(0, 10)) {
+        const pct = totalMs > 0 ? Math.round((tms / totalMs) * 100) : 0;
+        lines.push(`  ${c(colorForSpan(name), "█")} ${name.padEnd(28)} ${count.toString().padStart(4)}× ${tms.toString().padStart(6)}ms  ${pct}%`);
+    }
+    const errors = spans.filter((s) => s.status === "error").length;
+    lines.push("");
+    lines.push(c(ANSI_DIM, `${spans.length} spans, ${totalMs}ms total${errors > 0 ? `, ${errors} error(s)` : ""}`));
+    return lines.join("\n");
+}
+/**
+ * Build a time ruler line of exactly `width` columns with N tick labels
+ * distributed evenly. Strategy: anchor the last tick right-aligned to the
+ * width, then place earlier ticks at their proportional positions while
+ * truncating any label that would overlap the next tick (or the last
+ * tick's reserved start). Produces a clean ruler at any (width × N).
+ *
+ * The last tick's right-anchor means the rightmost timestamp always lands
+ * exactly at the canvas edge, matching where bars end.
+ */
+function buildTimeRuler(width, ticks) {
+    if (ticks.length === 0 || width <= 0)
+        return "";
+    const buf = new Array(width).fill(" ");
+    // Step 1: place last tick right-aligned. Its start column constrains all
+    // earlier ticks (they must end before lastStart - 1 so there's a gap).
+    const lastLabel = ticks[ticks.length - 1];
+    const lastStart = Math.max(0, width - lastLabel.length);
+    for (let j = 0; j < lastLabel.length && lastStart + j < width; j++) {
+        buf[lastStart + j] = lastLabel[j];
+    }
+    // Step 2: place earlier ticks left-to-right. Each can occupy from its
+    // proportional start column up to either the next tick's start (minus 1
+    // for a separator space) or, for the second-to-last tick, lastStart - 1.
+    for (let i = 0; i < ticks.length - 1; i++) {
+        const label = ticks[i];
+        const start = Math.round((i / (ticks.length - 1)) * (width - 1));
+        const nextProportional = Math.round(((i + 1) / (ticks.length - 1)) * (width - 1));
+        const isPenultimate = i === ticks.length - 2;
+        const endExclusive = isPenultimate ? lastStart - 1 : nextProportional - 1;
+        const maxLen = Math.max(0, endExclusive - start);
+        const out = label.slice(0, maxLen);
+        for (let j = 0; j < out.length; j++)
+            buf[start + j] = out[j];
+    }
+    return buf.join("");
+}
 /**
  * Coerce an arbitrary string (UUID with hyphens, "span-N", etc.) into a fixed-length
  * lowercase hex string suitable for OTLP. OTLP collectors (Jaeger, Tempo, OTel

package/dist/services/AgentDispatcher.d.ts

@@ -8,7 +8,7 @@
 import type { Provider } from "../providers/base.js";
 import type { Tools } from "../Tool.js";
 import type { StreamEvent, ToolCallComplete, ToolCallEnd, ToolCallStart, ToolOutputDelta } from "../types/events.js";
-import type { PermissionMode } from "../types/permissions.js";
+import { type PermissionMode } from "../types/permissions.js";
 /**
  * Forward inner-loop tool events to the outer stream, stamping parentCallId.
  * Exported for direct unit testing.
@@ -20,6 +20,15 @@ export type AgentTask = {
     description?: string;
     blockedBy?: string[];
     allowedTools?: string[];
+    /**
+     * Per-task permission mode override — narrowing-only, same contract as
+     * AgentTool's `permission_mode` (v2.36). When set, the task's effective
+     * mode is `clampSubagentPermissionMode(dispatcher.permissionMode, task.permissionMode)`,
+     * so a task can be the same strictness as the outer call or stricter,
+     * never looser. Use to mark specific tasks in a parallel batch as
+     * read-only review/audit while letting siblings keep full write access.
+     */
+    permissionMode?: PermissionMode;
 };
 export type AgentTaskResult = {
     id: string;

package/dist/services/AgentDispatcher.js

@@ -6,6 +6,7 @@
  * and triggers dependent tasks when their blockers complete.
  */
 import { createWorktree, isGitRepo, removeWorktree } from "../git/index.js";
+import { clampSubagentPermissionMode } from "../types/permissions.js";
 /**
  * Forward inner-loop tool events to the outer stream, stamping parentCallId.
  * Exported for direct unit testing.
@@ -168,11 +169,15 @@ export class AgentDispatcher {
             // matching `process.chdir(originalCwd)` in `finally` — but since
             // `process.cwd()` is process-wide, two concurrent tasks would clobber
             // each other's directory mid-execution.
+            // Per-task permission mode — narrowing-only clamp applied so a task
+            // can override only to a same-or-stricter mode than the dispatcher's
+            // outer mode (#115 contract).
+            const taskPermissionMode = clampSubagentPermissionMode(this.permissionMode, task.permissionMode);
             const config = {
                 provider: this.provider,
                 tools: taskTools,
                 systemPrompt: this.systemPrompt,
-                permissionMode: this.permissionMode,
+                permissionMode: taskPermissionMode,
                 model: this.model,
                 maxTurns: 20,
                 abortSignal: this.abortSignal,

package/dist/tools/GrepTool/index.d.ts

@@ -23,7 +23,7 @@ declare const inputSchema: z.ZodObject<{
     context?: number | undefined;
     glob?: string | undefined;
     offset?: number | undefined;
-    output_mode?: "content" | "files_with_matches" | "count" | undefined;
+    output_mode?: "content" | "count" | "files_with_matches" | undefined;
     head_limit?: number | undefined;
     multiline?: boolean | undefined;
     "-A"?: number | undefined;
@@ -38,7 +38,7 @@ declare const inputSchema: z.ZodObject<{
     context?: number | undefined;
     glob?: string | undefined;
     offset?: number | undefined;
-    output_mode?: "content" | "files_with_matches" | "count" | undefined;
+    output_mode?: "content" | "count" | "files_with_matches" | undefined;
     head_limit?: number | undefined;
     multiline?: boolean | undefined;
     "-A"?: number | undefined;

package/dist/tools/ParallelAgentTool/index.d.ts

@@ -6,15 +6,21 @@ declare const inputSchema: z.ZodObject<{
         prompt: z.ZodString;
         description: z.ZodOptional<z.ZodString>;
         blockedBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowed_tools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        permission_mode: z.ZodOptional<z.ZodEnum<["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"]>>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }, {
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
@@ -22,6 +28,8 @@ declare const inputSchema: z.ZodObject<{
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }[];
 }, {
@@ -29,6 +37,8 @@ declare const inputSchema: z.ZodObject<{
         id: string;
         prompt: string;
         description?: string | undefined;
+        allowed_tools?: string[] | undefined;
+        permission_mode?: "ask" | "deny" | "trust" | "acceptEdits" | "plan" | "auto" | "bypassPermissions" | undefined;
         blockedBy?: string[] | undefined;
     }[];
 }>;

package/dist/tools/ParallelAgentTool/index.js

@@ -5,6 +5,11 @@ const taskSchema = z.object({
     prompt: z.string(),
     description: z.string().optional(),
     blockedBy: z.array(z.string()).optional(),
+    allowed_tools: z.array(z.string()).optional(),
+    permission_mode: z
+        .enum(["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"])
+        .optional()
+        .describe("Restrict THIS task's permission mode. Narrowing-only — clamps to the outer mode if a less-restrictive value is requested. Use to mark a single task as read-only review/audit while sibling tasks keep full write access."),
 });
 const inputSchema = z.object({
     tasks: z.array(taskSchema).min(1),
@@ -27,7 +32,18 @@ export const ParallelAgentTool = {
         const systemPrompt = context.systemPrompt ?? "You are a sub-agent. Complete the delegated task concisely.";
         const dispatcher = new AgentDispatcher(context.provider, context.tools, systemPrompt, context.permissionMode ?? "trust", context.model, context.workingDir, context.abortSignal, 4, // maxConcurrency default
         context.callId, context.emitChildEvent);
-        dispatcher.addTasks(input.tasks);
+        // Map snake_case input fields to the AgentTask camelCase shape — the
+        // input schema uses `allowed_tools` / `permission_mode` to stay
+        // consistent with AgentTool, but the dispatcher's task type uses
+        // `allowedTools` / `permissionMode`.
+        dispatcher.addTasks(input.tasks.map((t) => ({
+            id: t.id,
+            prompt: t.prompt,
+            description: t.description,
+            blockedBy: t.blockedBy,
+            allowedTools: t.allowed_tools,
+            permissionMode: t.permission_mode,
+        })));
         const results = await dispatcher.execute();
         const output = results
             .map((r) => {
@@ -48,12 +64,13 @@ Parameters:
   - prompt (string): Instructions for the sub-agent
   - description (string, optional): Short label
   - blockedBy (string[], optional): IDs of tasks that must complete first
+  - allowed_tools (string[], optional): Restrict THIS task's agent to specific tools
+  - permission_mode (string, optional): Override THIS task's permission mode. Narrowing-only — a less-restrictive value clamps to the outer mode. Useful for marking review/audit tasks as "plan" or "deny" while sibling tasks keep full write access.
 
-Example: Run task A and B in parallel, then task C after both complete:
+Example: parallel test-write + read-only review:
 tasks: [
-  { id: "a", prompt: "..." },
-  { id: "b", prompt: "..." },
-  { id: "c", prompt: "...", blockedBy: ["a", "b"] }
+  { id: "tests", prompt: "Add tests for the new auth module" },
+  { id: "review", prompt: "Audit the new auth module for security issues", permission_mode: "plan" }
 ]`;
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.37.0",
+  "version": "2.39.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {