@oharness/engine 0.10.0 → 0.12.0

package/dist/harness.d.ts

@@ -27,6 +27,7 @@ import type { Catalog, CatalogProvider } from "./providers/catalog.ts";
 import type { EffortChoice, ModelSpec } from "./providers/types.ts";
 import type { BrowserTargetFactory } from "./browser/target.ts";
 import type { BrowserUsePlugin, BrowserUseSession } from "./browser/plugin.ts";
+import type { BrowserTurnShot } from "./browser/session.ts";
 import type { ComputerUsePlugin } from "./computer/plugin.ts";
 import type { ComputerUseSession } from "./computer/session.ts";
 import type { BrowserProviderPlugin } from "./browser/provider.ts";
@@ -126,6 +127,15 @@ export declare class Harness {
      * offered and `task` runs everything in the foreground.
      */
     taskWaker?: (sessionId: string) => void;
+    /**
+     * Where pictures of the browser tabs a turn left go, and whether to take
+     * them at all. Set by a frontend that shows them; while unset, none are.
+     * `at` is the conversation's message count when the turn ended.
+     */
+    turnShotSink?: {
+        enabled(): boolean;
+        save(sessionId: string, at: number, shots: BrowserTurnShot[]): void;
+    };
     /** Browser state belongs to a conversation, not to its project harness. */
     private readonly sessionBrowsers;
     /** Computer Use state belongs to a conversation too. */
@@ -212,6 +222,30 @@ export declare class Harness {
      * started with the browser off has no tools to switch, so that one stays as
      * it is until a restart.
      */
+    /** The Claude Agent definition this harness registered, while it is on. */
+    private claudeRegistered?;
+    /**
+     * Whether Claude Agent is switched on, and whether it could be.
+     *
+     * `available` is whether this machine has the user's `claude` (and `npx`
+     * for the adapter); `unavailable` is the reason it would not run even so,
+     * such as an old Node. Detected afresh each time, since installing Claude
+     * Code is something done in another window while this page is open.
+     */
+    claudeAgentStatus(): Promise<{
+        on: boolean;
+        available: boolean;
+        unavailable?: string;
+    }>;
+    /**
+     * Turn Claude Agent on or off, now and for later launches.
+     *
+     * Written to the user's own config, the same place `claudeAgent` is read
+     * from at startup, so the terminal frontends and the page agree. Takes
+     * effect at once: open conversations share this harness's subagent list.
+     */
+    setClaudeAgent(on: boolean): Promise<void>;
+    private registerClaudeAgent;
     setBrowserMode(mode: "auto" | "builtin" | "extension"): Promise<void>;
     /**
      * Whether permission decisions are being recorded, and who decided that.
@@ -370,6 +404,12 @@ export declare class Harness {
      * happen to — and answers 404 when picked. Nothing to refresh from (no
      * listing ever made) counts as stale. Resolves to undefined when the list
      * was fresh enough to leave alone.
+     *
+     * The age is the oldest provider's, from `discovered`, not `discoveredAt`:
+     * that one moves whenever any single provider is listed — a sign-in, a
+     * key saved for one vendor — and read alone it kept every other provider's
+     * week-old list looking fresh. `discoveredAt` is the fallback for a file
+     * written before `discovered` existed.
      */
     refreshStaleModels(maxAgeMs?: number): Promise<ModelSpec[] | undefined>;
     /**
@@ -390,6 +430,7 @@ export declare class Harness {
      * it: merging only ever grew the file, so a model the vendor withdrew stayed
      * in the picker for good. `discovered` records which providers have a live
      * listing, so the pi-ai snapshot stops filling in models for them.
+     * `cleared` names local servers that listed nothing, whose entries go.
      */
     private saveDiscovered;
     /**
@@ -400,6 +441,33 @@ export declare class Harness {
      * which breaks the one loop that would let the agent improve itself.
      */
     reloadSkills(): Promise<number>;
+    /**
+     * Switch one skill off or back on, now and for later launches.
+     *
+     * Off rather than deleted: most skills in the list are files another tool
+     * put there — Claude Code's, Codex's, a plugin's — and removing someone
+     * else's file to hide it from this harness would take it from that tool
+     * too.
+     */
+    setSkillEnabled(name: string, on: boolean): Promise<void>;
+    /**
+     * Every markdown agent this harness reads, with the dialect each was
+     * written in: a Claude Code plugin's names tools and models the way
+     * Claude Code does, and is translated on the way in.
+     */
+    private markdownAgents;
+    /**
+     * Take in a plugin that arrived while the harness was running.
+     *
+     * What `create` does for every plugin at launch, for one: its skills and
+     * agents join the registries, its servers connect. Without this an install
+     * from the menu would sit inert until a restart, which reads as a broken
+     * install. A server name the config already has is left to the config, the
+     * same precedence a launch gives it.
+     */
+    adoptPlugin(directory: string): Promise<PluginDefinition | undefined>;
+    /** Undo `adoptPlugin` for a plugin whose directory is gone. */
+    dropPlugin(directory: string): Promise<void>;
     /** Providers declared by the catalog, for `/models` and login hints. */
     listCatalogProviders(): CatalogProvider[];
     listModels(configuredOnly?: boolean): ModelSpec[];
@@ -472,6 +540,11 @@ export declare class Harness {
      * control its conversation held, so another need not wait out the lease.
      */
     private trackRun;
+    /**
+     * The tabs a turn left, beside the conversation (see BrowserUseSession.endTurn).
+     * Where the turn ended is read now, before a queued message starts the next.
+     */
+    private pictureBrowserTurn;
     /**
      * A subagent's own browser and computer.
      *
@@ -517,6 +590,12 @@ export declare class Harness {
      * picked in the composer; it wins over the first-configured guess.
      */
     generateText(system: string, prompt: string, signal?: AbortSignal, maxOutputTokens?: number, fallback?: string): Promise<string>;
+    /**
+     * The same one reply, from a model the caller names rather than the small
+     * one: for a chore that should cost and sound like the conversation it is
+     * about, such as the composer's next-message suggestion.
+     */
+    generateWith(ref: string, system: string, prompt: string, signal?: AbortSignal, maxOutputTokens?: number): Promise<string>;
     /**
      * First model whose provider has credentials. Only the cheap synchronous
      * check runs here — a subscription-only provider is picked up once the

package/dist/harness.js

@@ -6,6 +6,8 @@ import { HookRegistry } from "./agent/hooks.js";
 import { Session } from "./agent/session.js";
 import { SessionStore } from "./agent/store.js";
 import { BUILTIN_SUBAGENTS, SubagentRegistry, loadMarkdownSubagents } from "./agent/subagent.js";
+import { foreignAgentRoots, foreignSkillRoots } from "./foreign.js";
+import { claudeAgent } from "./acp/claude.js";
 import { SkillRegistry } from "./agent/skills.js";
 import { SettingsStore } from "./agent/settings.js";
 import { createPolicy } from "./agent/workspace.js";
@@ -73,6 +75,12 @@ export class Harness {
      * offered and `task` runs everything in the foreground.
      */
     taskWaker;
+    /**
+     * Where pictures of the browser tabs a turn left go, and whether to take
+     * them at all. Set by a frontend that shows them; while unset, none are.
+     * `at` is the conversation's message count when the turn ended.
+     */
+    turnShotSink;
     /** Browser state belongs to a conversation, not to its project harness. */
     sessionBrowsers = new Map();
     /** Computer Use state belongs to a conversation too. */
@@ -198,7 +206,14 @@ export class Harness {
                 ...(config.skillDirs ?? []),
                 ...(config.agentDirs ?? []),
             ],
-            ...(config.readableRoots !== undefined ? { readableRoots: config.readableRoots } : {}),
+            // Claude Code's and Codex's skill and agent directories are read, so
+            // the agent can open a skill's scripts/, but not written: those belong
+            // to the user's other tools, not to anything this harness installed.
+            readableRoots: [
+                ...(config.readableRoots ?? []),
+                ...Object.values(foreignSkillRoots(this.cwd, config.imports)).flat().map((root) => root.dir),
+                ...Object.values(foreignAgentRoots(this.cwd, config.imports)).flat().map((root) => root.dir),
+            ],
         });
         this.mcp = new McpManager(this.logger, this.auth.store, (id) => this.auth.secret(id));
         this.store = new SessionStore(config.sessionDir);
@@ -234,7 +249,7 @@ export class Harness {
             : (await ensureProjectManifest(cwd)).id;
         opts = { ...opts, cwd };
         const baseConfig = opts.config ?? (await loadConfig(cwd));
-        const plugins = await discoverPlugins(cwd, baseConfig.plugins);
+        const plugins = await discoverPlugins(cwd, pluginOptions(baseConfig));
         // Explicit user/project config is applied after plugins, so it can always
         // tighten policy or replace a plugin's MCP server declaration.
         const config = mergeConfig(pluginContributions(plugins), baseConfig);
@@ -262,10 +277,16 @@ export class Harness {
                 })
                     .catch((err) => harness.logger.warn("session pruning failed", { error: String(err) }));
             }
-            await harness.skills.discover(cwd, config.skillDirs ?? []);
+            harness.skills.setDisabled(config.disabledSkills ?? []);
+            await harness.skills.discover(cwd, config.skillDirs ?? [], config.imports ?? {});
+            // Claude Agent, when the user turned it on and this machine has their
+            // own Claude Code to hand work to. Before the markdown ones, so a
+            // project can redefine it.
+            if (config.claudeAgent === true)
+                await harness.registerClaudeAgent();
             // Markdown definitions layer over the JSON ones, so a repo can drop in an
             // agent file without editing config.
-            for (const definition of await loadMarkdownSubagents(cwd, config.agentDirs ?? [])) {
+            for (const definition of await harness.markdownAgents()) {
                 harness.subagents.register(definition);
             }
             if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
@@ -422,6 +443,50 @@ export class Harness {
      * started with the browser off has no tools to switch, so that one stays as
      * it is until a restart.
      */
+    /** The Claude Agent definition this harness registered, while it is on. */
+    claudeRegistered;
+    /**
+     * Whether Claude Agent is switched on, and whether it could be.
+     *
+     * `available` is whether this machine has the user's `claude` (and `npx`
+     * for the adapter); `unavailable` is the reason it would not run even so,
+     * such as an old Node. Detected afresh each time, since installing Claude
+     * Code is something done in another window while this page is open.
+     */
+    async claudeAgentStatus() {
+        const found = await claudeAgent().catch(() => undefined);
+        return {
+            on: this.config.claudeAgent === true,
+            available: Boolean(found),
+            ...(found?.runtime?.unavailable ? { unavailable: found.runtime.unavailable } : {}),
+        };
+    }
+    /**
+     * Turn Claude Agent on or off, now and for later launches.
+     *
+     * Written to the user's own config, the same place `claudeAgent` is read
+     * from at startup, so the terminal frontends and the page agree. Takes
+     * effect at once: open conversations share this harness's subagent list.
+     */
+    async setClaudeAgent(on) {
+        await updateUserConfig((current) => ({ ...current, claudeAgent: on }));
+        this.config.claudeAgent = on;
+        if (on)
+            await this.registerClaudeAgent();
+        else if (this.claudeRegistered) {
+            this.subagents.unregister(this.claudeRegistered);
+            this.claudeRegistered = undefined;
+        }
+    }
+    async registerClaudeAgent() {
+        if (this.claudeRegistered || process.env["OHARNESS_NO_CLAUDE_AGENT"] === "1")
+            return;
+        const claude = await claudeAgent().catch(() => undefined);
+        if (!claude)
+            return;
+        this.subagents.register(claude);
+        this.claudeRegistered = claude;
+    }
     async setBrowserMode(mode) {
         await updateUserConfig((current) => ({ ...current, browser: { ...current.browser, mode } }));
         this.config.browser = { ...this.config.browser, mode };
@@ -771,9 +836,9 @@ export class Harness {
      * the user catalog so the next run starts with a current list.
      */
     async refreshModels(providerId) {
-        const discovered = await this.providers.refreshModels(providerId);
-        if (discovered.length > 0) {
-            await this.saveDiscovered(discovered).catch((err) => this.logger.warn("could not persist the discovered catalog", {
+        const { changed: discovered, cleared } = await this.providers.refreshListings(providerId);
+        if (discovered.length > 0 || cleared.length > 0) {
+            await this.saveDiscovered(discovered, cleared).catch((err) => this.logger.warn("could not persist the discovered catalog", {
                 error: String(err),
             }));
         }
@@ -788,12 +853,22 @@ export class Harness {
      * happen to — and answers 404 when picked. Nothing to refresh from (no
      * listing ever made) counts as stale. Resolves to undefined when the list
      * was fresh enough to leave alone.
+     *
+     * The age is the oldest provider's, from `discovered`, not `discoveredAt`:
+     * that one moves whenever any single provider is listed — a sign-in, a
+     * key saved for one vendor — and read alone it kept every other provider's
+     * week-old list looking fresh. `discoveredAt` is the fallback for a file
+     * written before `discovered` existed.
      */
     async refreshStaleModels(maxAgeMs = MODEL_LIST_MAX_AGE_MS) {
         let at = NaN;
         try {
             const raw = JSON.parse(await readFile(userCatalogPath(), "utf8"));
-            at = Date.parse(String(raw["discoveredAt"] ?? ""));
+            const each = raw["discovered"];
+            const times = each && typeof each === "object" && !Array.isArray(each)
+                ? Object.values(each).map((value) => Date.parse(String(value))).filter(Number.isFinite)
+                : [];
+            at = times.length > 0 ? Math.min(...times) : Date.parse(String(raw["discoveredAt"] ?? ""));
         }
         catch {
             // No file or an unreadable one: never listed, so due.
@@ -828,8 +903,9 @@ export class Harness {
      * it: merging only ever grew the file, so a model the vendor withdrew stayed
      * in the picker for good. `discovered` records which providers have a live
      * listing, so the pi-ai snapshot stops filling in models for them.
+     * `cleared` names local servers that listed nothing, whose entries go.
      */
-    async saveDiscovered(models) {
+    async saveDiscovered(models, cleared = []) {
         const file = userCatalogPath();
         let existing = {};
         try {
@@ -841,7 +917,7 @@ export class Harness {
         const byId = new Map((Array.isArray(existing["models"]) ? existing["models"] : [])
             .filter((m) => !!m && typeof m === "object")
             .map((m) => [String(m["id"]), m]));
-        const listed = new Set(models.map((model) => model.provider));
+        const listed = new Set([...models.map((model) => model.provider), ...cleared]);
         const fresh = new Set(models.map((model) => model.id));
         for (const [id, model] of byId) {
             const { provider, model: wire } = model;
@@ -872,9 +948,109 @@ export class Harness {
      * which breaks the one loop that would let the agent improve itself.
      */
     async reloadSkills() {
-        await this.skills.discover(this.cwd, this.config.skillDirs ?? []);
+        await this.skills.discover(this.cwd, this.config.skillDirs ?? [], this.config.imports ?? {});
         return this.skills.size;
     }
+    /**
+     * Switch one skill off or back on, now and for later launches.
+     *
+     * Off rather than deleted: most skills in the list are files another tool
+     * put there — Claude Code's, Codex's, a plugin's — and removing someone
+     * else's file to hide it from this harness would take it from that tool
+     * too.
+     */
+    async setSkillEnabled(name, on) {
+        await updateUserConfig((current) => {
+            const off = new Set(current.disabledSkills ?? []);
+            if (on)
+                off.delete(name);
+            else
+                off.add(name);
+            return { ...current, disabledSkills: [...off].sort() };
+        });
+        const off = new Set(this.config.disabledSkills ?? []);
+        if (on)
+            off.delete(name);
+        else
+            off.add(name);
+        this.config.disabledSkills = [...off];
+        this.skills.setDisabled(off);
+    }
+    /**
+     * Every markdown agent this harness reads, with the dialect each was
+     * written in: a Claude Code plugin's names tools and models the way
+     * Claude Code does, and is translated on the way in.
+     */
+    async markdownAgents() {
+        const claude = new Set(this.plugins.filter((plugin) => plugin.claudeFormat).map((plugin) => plugin.agentDir));
+        const roots = (this.config.agentDirs ?? []).map((dir) => claude.has(dir) ? { dir, dialect: "claude" } : { dir });
+        return loadMarkdownSubagents(this.cwd, roots, this.config.imports ?? {});
+    }
+    /**
+     * Take in a plugin that arrived while the harness was running.
+     *
+     * What `create` does for every plugin at launch, for one: its skills and
+     * agents join the registries, its servers connect. Without this an install
+     * from the menu would sit inert until a restart, which reads as a broken
+     * install. A server name the config already has is left to the config, the
+     * same precedence a launch gives it.
+     */
+    async adoptPlugin(directory) {
+        const plugin = (await discoverPlugins(this.cwd, pluginOptions(this.config))).find((one) => one.directory === directory);
+        if (!plugin)
+            return undefined;
+        const known = this.plugins.findIndex((one) => one.name === plugin.name);
+        if (known >= 0)
+            this.plugins.splice(known, 1, plugin);
+        else
+            this.plugins.push(plugin);
+        const contributed = pluginContributions([plugin]);
+        this.config.skillDirs = [...new Set([...(this.config.skillDirs ?? []), ...contributed.skillDirs])];
+        this.config.agentDirs = [...new Set([...(this.config.agentDirs ?? []), ...contributed.agentDirs])];
+        await this.reloadSkills();
+        for (const definition of contributed.subagents)
+            this.subagents.register(definition);
+        for (const definition of await this.markdownAgents()) {
+            this.subagents.register(definition);
+        }
+        for (const [name, server] of Object.entries(contributed.mcpServers)) {
+            if (this.config.mcpServers?.[name] || this.mcp.configFor(name))
+                continue;
+            this.config.mcpServers = { ...(this.config.mcpServers ?? {}), [name]: server };
+            // One server that will not start is not a failed install; its row says
+            // why, as any connector's does.
+            await this.addMcpServer(name, server).catch((err) => this.logger.warn("plugin server unavailable", { server: name, error: String(err) }));
+        }
+        return plugin;
+    }
+    /** Undo `adoptPlugin` for a plugin whose directory is gone. */
+    async dropPlugin(directory) {
+        const index = this.plugins.findIndex((one) => one.directory === directory);
+        if (index < 0)
+            return;
+        const [plugin] = this.plugins.splice(index, 1);
+        const contributed = pluginContributions([plugin]);
+        const before = await this.markdownAgents();
+        this.config.skillDirs = (this.config.skillDirs ?? []).filter((dir) => !contributed.skillDirs.includes(dir));
+        this.config.agentDirs = (this.config.agentDirs ?? []).filter((dir) => !contributed.agentDirs.includes(dir));
+        await this.reloadSkills();
+        const after = new Set((await this.markdownAgents()).map((one) => one.name));
+        for (const definition of [...before, ...contributed.subagents]) {
+            if (after.has(definition.name))
+                continue;
+            const registered = this.subagents.get(definition.name);
+            if (registered)
+                this.subagents.unregister(registered);
+        }
+        for (const name of Object.keys(contributed.mcpServers)) {
+            const mine = this.config.mcpServers?.[name] === contributed.mcpServers[name];
+            if (!mine)
+                continue;
+            const { [name]: _gone, ...rest } = this.config.mcpServers ?? {};
+            this.config.mcpServers = rest;
+            await this.removeMcpServer(name);
+        }
+    }
     /** Providers declared by the catalog, for `/models` and login hints. */
     listCatalogProviders() {
         return this.providers.listCatalogProviders();
@@ -975,7 +1151,8 @@ export class Harness {
      */
     async forkSession(id, opts = {}) {
         const forked = await Session.fork(id, {
-            model: opts.model ?? this.config.model ?? this.defaultModel(),
+            model: opts.model ?? "",
+            fallbackModel: this.config.model ?? this.defaultModel(),
             providers: this.providers,
             permissionMode: this.config.permissionMode,
             permissionRules: this.config.permissions,
@@ -1004,7 +1181,10 @@ export class Harness {
     /** Reload a persisted session by id; returns undefined if it is unknown. */
     async resumeSession(id, model) {
         const resumed = await Session.resume(id, {
-            model: model ?? this.config.model ?? this.defaultModel(),
+            // Empty means "the session's own": a conversation reopens on the model
+            // it was using, and the default is only for one whose model is gone.
+            model: model ?? "",
+            fallbackModel: this.config.model ?? this.defaultModel(),
             providers: this.providers,
             permissionMode: this.config.permissionMode,
             permissionRules: this.config.permissions,
@@ -1052,7 +1232,7 @@ export class Harness {
             worktreeLauncher: () => this.worktreeLauncher,
             taskWaker: () => this.taskWaker,
             equipSubagent: (sessionId, label, tools) => this.equipSubagent(sessionId, label, tools),
-            onRunStart: () => this.trackRun(computer),
+            onRunStart: () => this.trackRun(computer, browser, session),
             onAudit: (event) => { if (this.config.audit !== false)
                 this.runtimeAudit.publish(event); },
             ...overrides,
@@ -1062,11 +1242,33 @@ export class Harness {
      * Count a run toward shutdown's drain. Its end lets go of the windows and
      * control its conversation held, so another need not wait out the lease.
      */
-    trackRun(computer) {
+    trackRun(computer, browser, session) {
         let finish;
         const done = new Promise((resolve) => { finish = resolve; });
         this.activeRuns.add(done);
-        return () => { this.activeRuns.delete(done); computer?.endTurn(); finish(); };
+        return () => {
+            this.activeRuns.delete(done);
+            computer?.endTurn();
+            // A subagent's tabs are not pictured: it has no transcript of its own.
+            if (session)
+                this.pictureBrowserTurn(browser, session);
+            finish();
+        };
+    }
+    /**
+     * The tabs a turn left, beside the conversation (see BrowserUseSession.endTurn).
+     * Where the turn ended is read now, before a queued message starts the next.
+     */
+    pictureBrowserTurn(browser, session) {
+        if (!browser?.endTurn)
+            return;
+        const sink = this.turnShotSink;
+        const at = session.messages.length;
+        void browser
+            .endTurn(Boolean(sink?.enabled()))
+            .then((shots) => { if (shots.length)
+            sink?.save(session.id, at, shots); })
+            .catch(() => { });
     }
     /**
      * A subagent's own browser and computer.
@@ -1235,7 +1437,15 @@ export class Harness {
      * picked in the composer; it wins over the first-configured guess.
      */
     async generateText(system, prompt, signal, maxOutputTokens = 8_000, fallback) {
-        const model = this.providers.resolve(this.config.smallModel ?? fallback ?? this.config.model ?? this.defaultModel());
+        return this.generateWith(this.config.smallModel ?? fallback ?? this.config.model ?? this.defaultModel(), system, prompt, signal, maxOutputTokens);
+    }
+    /**
+     * The same one reply, from a model the caller names rather than the small
+     * one: for a chore that should cost and sound like the conversation it is
+     * about, such as the composer's next-message suggestion.
+     */
+    async generateWith(ref, system, prompt, signal, maxOutputTokens = 8_000) {
+        const model = this.providers.resolve(ref);
         const provider = this.providers.getProvider(model.provider);
         const parts = [];
         for await (const event of provider.stream({
@@ -1260,4 +1470,18 @@ export class Harness {
         return first.id;
     }
 }
+/**
+ * Plugin discovery, with `imports` deciding for the two other tools' caches
+ * where `plugins` does not: switching Codex off is switching off its skills,
+ * servers and plugins together.
+ */
+function pluginOptions(config) {
+    const claudeCode = config.plugins?.claudeCode ?? config.imports?.claudeCode;
+    const codex = config.plugins?.codex ?? config.imports?.codex;
+    return {
+        ...config.plugins,
+        ...(claudeCode !== undefined ? { claudeCode } : {}),
+        ...(codex !== undefined ? { codex } : {}),
+    };
+}
 //# sourceMappingURL=harness.js.map