@zhijiewang/openharness 2.16.0 → 2.18.0

package/dist/outputStyles/index.js

@@ -0,0 +1,89 @@
+/**
+ * Output styles — pluggable system-prompt prefaces that swap the agent's
+ * personality without touching the underlying instructions. Mirrors Claude
+ * Code's `outputStyle` setting. Built-ins: default, explanatory, learning.
+ *
+ * Custom styles are markdown files with YAML frontmatter under:
+ *   - .oh/output-styles/<name>.md  (project-level; shadows user)
+ *   - ~/.oh/output-styles/<name>.md (user-level; shadows built-ins)
+ *
+ * A style's `prompt` is prepended to the system prompt by buildSystemPrompt.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const DEFAULT_STYLE = {
+    name: "default",
+    description: "Standard software engineering assistant",
+    prompt: "",
+};
+export const EXPLANATORY_STYLE = {
+    name: "explanatory",
+    description: "Educational mode — adds an 'Insights' section between tasks",
+    prompt: "You are in Explanatory mode. After completing each task, add a short '## Insights' section explaining *why* you made the choices you did — trade-offs you considered, alternatives you rejected, and one concept the user may want to learn more about. Keep insights concise (2–3 sentences).",
+};
+export const LEARNING_STYLE = {
+    name: "learning",
+    description: "Collaborative learn-by-doing — leaves TODO(human) markers",
+    prompt: "You are in Learning mode. When implementing features, leave small `TODO(human)` comments at 1–3 strategic points per task — places where the user will learn the most by writing the code themselves. Explain what each TODO should do in the surrounding comment. Never leave more than 3 TODOs per task.",
+};
+export const BUILTIN_STYLES = [DEFAULT_STYLE, EXPLANATORY_STYLE, LEARNING_STYLE];
+export function resolveStyleName(raw) {
+    const trimmed = raw?.trim();
+    if (!trimmed)
+        return "default";
+    return trimmed.toLowerCase();
+}
+export function loadOutputStyle(name, opts = {}) {
+    const resolved = resolveStyleName(name);
+    const projectRoot = opts.projectRoot ?? process.cwd();
+    const userHome = opts.userHome ?? homedir();
+    // Precedence: project → user → built-in → default fallback
+    const projectStyle = tryLoadFromDir(join(projectRoot, ".oh", "output-styles"), resolved);
+    if (projectStyle)
+        return projectStyle;
+    const userStyle = tryLoadFromDir(join(userHome, ".oh", "output-styles"), resolved);
+    if (userStyle)
+        return userStyle;
+    const builtin = BUILTIN_STYLES.find((s) => s.name === resolved);
+    if (builtin)
+        return builtin;
+    return DEFAULT_STYLE;
+}
+function tryLoadFromDir(dir, name) {
+    const path = join(dir, `${name}.md`);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        return parseStyleFile(raw, name);
+    }
+    catch {
+        return null;
+    }
+}
+function parseStyleFile(content, fallbackName) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match) {
+        // No frontmatter — treat the entire content as the prompt body.
+        return { name: fallbackName, description: "", prompt: content.trim() };
+    }
+    const frontmatter = match[1];
+    const body = match[2] ?? "";
+    let parsed = {};
+    try {
+        const result = parseYaml(frontmatter);
+        if (result && typeof result === "object")
+            parsed = result;
+    }
+    catch {
+        /* malformed frontmatter — fall back to raw body with defaults */
+    }
+    return {
+        name: typeof parsed.name === "string" ? parsed.name : fallbackName,
+        description: typeof parsed.description === "string" ? parsed.description : "",
+        prompt: body.trim(),
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../Tool.js";
+declare const inputSchema: z.ZodObject<{
+    server: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    server?: string | undefined;
+}, {
+    server?: string | undefined;
+}>;
+export type McpResourceEntry = {
+    server: string;
+    uri: string;
+    name: string;
+    description?: string;
+};
+/**
+ * Pure formatter — renders the resource list as a markdown table.
+ * Exported for testing; production callers should use the tool's `.call()`.
+ */
+export declare function formatResourcesList(resources: McpResourceEntry[], serverFilter?: string): string;
+export declare const ListMcpResourcesTool: Tool<typeof inputSchema>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/ListMcpResourcesTool/index.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { listMcpResources } from "../../mcp/loader.js";
+const inputSchema = z.object({
+    server: z.string().optional(),
+});
+/**
+ * Pure formatter — renders the resource list as a markdown table.
+ * Exported for testing; production callers should use the tool's `.call()`.
+ */
+export function formatResourcesList(resources, serverFilter) {
+    const filtered = serverFilter ? resources.filter((r) => r.server === serverFilter) : resources;
+    if (filtered.length === 0) {
+        if (serverFilter) {
+            return `No MCP resources available from server '${serverFilter}'.`;
+        }
+        return "No MCP resources available. Connect an MCP server that exposes resources under mcpServers in .oh/config.yaml.";
+    }
+    const lines = ["| Server | URI | Name | Description |", "|--------|-----|------|-------------|"];
+    for (const r of filtered) {
+        const desc = (r.description ?? "").replace(/\|/g, "\\|").slice(0, 80);
+        const name = r.name.replace(/\|/g, "\\|");
+        const uri = r.uri.replace(/\|/g, "\\|");
+        lines.push(`| ${r.server} | ${uri} | ${name} | ${desc} |`);
+    }
+    return lines.join("\n");
+}
+export const ListMcpResourcesTool = {
+    name: "ListMcpResources",
+    description: "List resources exposed by connected MCP servers.",
+    inputSchema,
+    riskLevel: "low",
+    isReadOnly() {
+        return true;
+    },
+    isConcurrencySafe() {
+        return true;
+    },
+    async call(input) {
+        try {
+            const resources = await listMcpResources();
+            return { output: formatResourcesList(resources, input.server), isError: false };
+        }
+        catch (err) {
+            return { output: `Error listing MCP resources: ${err.message}`, isError: true };
+        }
+    },
+    prompt() {
+        return `List resources exposed by connected MCP servers. Parameters:
+- server (string, optional): restrict to this server's resources.
+Returns a markdown table with columns: Server, URI, Name, Description. Use ReadMcpResource with a URI from the table to fetch the content. Resources are read-only data sources (docs, indices, state) — distinct from MCP tools, which are actions.`;
+    },
+};
+//# sourceMappingURL=index.js.map

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

@@ -11,7 +11,7 @@ declare const inputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     action: "search" | "save" | "list";
     content?: string | undefined;
-    type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
+    type?: "user" | "project" | "convention" | "preference" | "debugging" | "feedback" | "reference" | undefined;
     name?: string | undefined;
     description?: string | undefined;
     global?: boolean | undefined;
@@ -19,7 +19,7 @@ declare const inputSchema: z.ZodObject<{
 }, {
     action: "search" | "save" | "list";
     content?: string | undefined;
-    type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
+    type?: "user" | "project" | "convention" | "preference" | "debugging" | "feedback" | "reference" | undefined;
     name?: string | undefined;
     description?: string | undefined;
     global?: boolean | undefined;

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

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { Tool } from "../../Tool.js";
+declare const inputSchema: z.ZodObject<{
+    uri: z.ZodString;
+    server: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    uri: string;
+    server?: string | undefined;
+}, {
+    uri: string;
+    server?: string | undefined;
+}>;
+/**
+ * Pure helper — truncates resource content to MAX_OUTPUT_CHARS with a
+ * trailing `[...truncated]` marker when exceeded. Exported for testing.
+ */
+export declare function formatResourceContent(content: string, maxChars?: number): string;
+export declare const ReadMcpResourceTool: Tool<typeof inputSchema>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/ReadMcpResourceTool/index.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { readMcpResource } from "../../mcp/loader.js";
+const inputSchema = z.object({
+    uri: z.string(),
+    server: z.string().optional(),
+});
+const MAX_OUTPUT_CHARS = 50_000;
+/**
+ * Pure helper — truncates resource content to MAX_OUTPUT_CHARS with a
+ * trailing `[...truncated]` marker when exceeded. Exported for testing.
+ */
+export function formatResourceContent(content, maxChars = MAX_OUTPUT_CHARS) {
+    if (content.length <= maxChars)
+        return content;
+    return `${content.slice(0, maxChars)}\n[...truncated at ${maxChars} chars, original length ${content.length}]`;
+}
+export const ReadMcpResourceTool = {
+    name: "ReadMcpResource",
+    description: "Read a specific MCP resource by URI from a connected MCP server.",
+    inputSchema,
+    riskLevel: "low",
+    isReadOnly() {
+        return true;
+    },
+    isConcurrencySafe() {
+        return true;
+    },
+    async call(input) {
+        try {
+            const content = await readMcpResource(input.uri, input.server);
+            if (content === null) {
+                const where = input.server ? ` from server '${input.server}'` : "";
+                return {
+                    output: `Resource '${input.uri}' not found${where}. Run ListMcpResources to see available URIs.`,
+                    isError: true,
+                };
+            }
+            return { output: formatResourceContent(content), isError: false };
+        }
+        catch (err) {
+            return { output: `Error reading MCP resource: ${err.message}`, isError: true };
+        }
+    },
+    prompt() {
+        return `Read a specific resource from an MCP server by URI. Parameters:
+- uri (string, required): the resource URI, as shown by ListMcpResources.
+- server (string, optional): restrict lookup to this server. When omitted, the first server whose readResource call succeeds is used.
+Output is truncated at ~50KB. For discovery, call ListMcpResources first to get URIs.`;
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/tools.js

@@ -23,6 +23,7 @@ import { GlobTool } from "./tools/GlobTool/index.js";
 import { GrepTool } from "./tools/GrepTool/index.js";
 import { ImageReadTool } from "./tools/ImageReadTool/index.js";
 import { KillProcessTool } from "./tools/KillProcessTool/index.js";
+import { ListMcpResourcesTool } from "./tools/ListMcpResourcesTool/index.js";
 import { LSTool } from "./tools/LSTool/index.js";
 import { MemoryTool } from "./tools/MemoryTool/index.js";
 import { MonitorTool } from "./tools/MonitorTool/index.js";
@@ -31,6 +32,7 @@ import { NotebookEditTool } from "./tools/NotebookEditTool/index.js";
 import { ParallelAgentTool } from "./tools/ParallelAgentTool/index.js";
 import { PipelineTool } from "./tools/PipelineTool/index.js";
 import { PowerShellTool } from "./tools/PowerShellTool/index.js";
+import { ReadMcpResourceTool } from "./tools/ReadMcpResourceTool/index.js";
 import { RemoteTriggerTool } from "./tools/RemoteTriggerTool/index.js";
 import { ScheduleWakeupTool } from "./tools/ScheduleWakeupTool/index.js";
 import { SendMessageTool } from "./tools/SendMessageTool/index.js";
@@ -106,6 +108,8 @@ export function getAllTools() {
         ScheduleWakeupTool,
         SessionSearchTool,
         TodoWriteTool,
+        ListMcpResourcesTool,
+        ReadMcpResourceTool,
     ];
     return [...core, ...extended.map((t) => new DeferredTool(t))];
 }

package/dist/utils/json-schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal JSON Schema validator — covers the common subset sufficient for
+ * constraining LLM output in headless mode. Supported keywords:
+ *
+ *   - `type`: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null"
+ *             (or an array of those for union types)
+ *   - `properties`: object → sub-schema per field
+ *   - `required`: array of field names that must be present
+ *   - `items`: sub-schema for array elements
+ *   - `enum`: array of allowed literal values (compared with strict equality)
+ *
+ * Anything else is silently accepted. This is intentional — we don't want to
+ * ship a full JSON Schema engine. For cases that need more (e.g. `pattern`,
+ * `oneOf`, `$ref`), use an external validator.
+ */
+export type JsonSchema = Record<string, unknown>;
+export type ValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function validateAgainstJsonSchema(value: unknown, schema: JsonSchema): ValidationResult;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/utils/json-schema.js

@@ -0,0 +1,110 @@
+/**
+ * Minimal JSON Schema validator — covers the common subset sufficient for
+ * constraining LLM output in headless mode. Supported keywords:
+ *
+ *   - `type`: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null"
+ *             (or an array of those for union types)
+ *   - `properties`: object → sub-schema per field
+ *   - `required`: array of field names that must be present
+ *   - `items`: sub-schema for array elements
+ *   - `enum`: array of allowed literal values (compared with strict equality)
+ *
+ * Anything else is silently accepted. This is intentional — we don't want to
+ * ship a full JSON Schema engine. For cases that need more (e.g. `pattern`,
+ * `oneOf`, `$ref`), use an external validator.
+ */
+export function validateAgainstJsonSchema(value, schema) {
+    const errors = [];
+    validate(value, schema, "", errors);
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+function validate(value, schema, path, errors) {
+    if (schema.enum !== undefined && Array.isArray(schema.enum)) {
+        if (!schema.enum.some((allowed) => deepEqual(allowed, value))) {
+            errors.push(`${prefix(path)}value ${JSON.stringify(value)} is not one of the enum values`);
+            return;
+        }
+    }
+    if (schema.type !== undefined) {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if (!types.some((t) => matchesType(value, t))) {
+            errors.push(`${prefix(path)}expected ${types.join(" or ")}, got ${describeActual(value)}`);
+            return;
+        }
+    }
+    if (matchesType(value, "object") && schema.properties) {
+        const properties = schema.properties;
+        const required = schema.required ?? [];
+        const obj = value;
+        for (const field of required) {
+            if (!(field in obj)) {
+                const fullPath = path ? `${path}.${field}` : field;
+                errors.push(`missing required property '${fullPath}'`);
+            }
+        }
+        for (const [field, subSchema] of Object.entries(properties)) {
+            if (field in obj) {
+                validate(obj[field], subSchema, path ? `${path}.${field}` : field, errors);
+            }
+        }
+    }
+    if (matchesType(value, "array") && schema.items) {
+        const items = schema.items;
+        const arr = value;
+        arr.forEach((item, i) => {
+            validate(item, items, `${path}[${i}]`, errors);
+        });
+    }
+}
+function matchesType(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && Number.isFinite(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        default:
+            return false;
+    }
+}
+function describeActual(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function prefix(path) {
+    return path ? `${path}: ` : "";
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a === null || b === null)
+        return a === b;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((x, i) => deepEqual(x, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        if (ka.length !== kb.length)
+            return false;
+        return ka.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+//# sourceMappingURL=json-schema.js.map

package/package.json

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