@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/world/world.d.ts

@@ -0,0 +1,65 @@
+import type { SecretStore } from "../accounts/secrets.js";
+import type { CallerContext } from "../core/caller.js";
+import type { PluginDescriptor } from "../plugins/types.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { ToolProvider, ToolSpec } from "../tools/types.js";
+import type { WebRequest } from "../web/safeRequest.js";
+import { type BrowserConfig } from "../browser/config.js";
+import { type BrowserPartOptions } from "../browser/index.js";
+/** What a world tool knows about the session calling it. */
+export interface WorldContext {
+    /** The run the call belongs to, when there is one; approvals go through it. */
+    run: ActiveRun | null;
+    caller: CallerContext;
+    /** A person can answer an approval now (not a refinement, reflection or other unattended run). */
+    attended: boolean;
+    /** The call comes from a child run. */
+    subagent: boolean;
+    /** One key per live session: its browser, its pages. */
+    sessionKey: string;
+    cwd: string;
+}
+export interface WorldOptions {
+    root: () => string;
+    stateDir: string;
+    secrets: SecretStore;
+    /** Replaces network reads in tests. */
+    request?: WebRequest;
+    /** Replaces the browser's launcher and address check in tests. */
+    browser?: Omit<BrowserPartOptions, 'stateDir'> | false;
+}
+/** A family of world tools, switched as one plugin. */
+export interface WorldPart {
+    plugin: PluginDescriptor;
+    tools(context: WorldContext): ToolSpec[];
+    diagnostics?: import("../doctor/types.js").ProviderDiagnostics['diagnostics'];
+    /** A live session ended: let go of what it held. */
+    release?(sessionKey: string): Promise<void>;
+    close?(): Promise<void>;
+}
+export declare class World {
+    private readonly options;
+    readonly parts: WorldPart[];
+    private readonly web;
+    constructor(options: WorldOptions);
+    add(part: WorldPart): void;
+    get plugins(): PluginDescriptor[];
+    /** A number a person set on one of these plugins. */
+    setting(pluginId: string, key: string): number;
+    /** Every world tool for a context, with the plugin each belongs to. */
+    tools(context: WorldContext, on: (pluginId: string, tool: string) => boolean): ToolSpec[];
+    /** The provider an SDK session asks: only tools whose plugin is on for the caller. */
+    provider(): ToolProvider;
+    /** Which search services have a key, and whether keyless search is on. Never the keys. */
+    searchStatus(): Promise<{
+        id: string;
+        title: string;
+        ready: boolean;
+    }[]>;
+    /** Saves or forgets a search service's key. */
+    setSearchKey(providerId: string, key: string | null): Promise<void>;
+    browserConfig(): BrowserConfig;
+    configureBrowser(change: Partial<BrowserConfig>): BrowserConfig;
+    release(sessionKey: string): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/sdk/world/world.js

@@ -0,0 +1,80 @@
+import * as attachments from "../plugins/attachments.js";
+import { settingValue } from "../plugins/firstParty.js";
+import { contributionId } from "../plugins/identity.js";
+import { findRun } from "../sessions/runStore.js";
+import { KEYLESS_SEARCH, WEB_PLUGIN, WEB_SETTINGS, webTools } from "../web/tools.js";
+import { SEARCH_PROVIDERS } from "../web/search.js";
+import { invalid } from "../core/errors.js";
+import { readBrowserConfig, writeBrowserConfig } from "../browser/config.js";
+import { browserPart } from "../browser/index.js";
+const UNATTENDED = new Set(['probe', 'improver', 'reflection']);
+export class World {
+    options;
+    parts = [];
+    web;
+    constructor(options) {
+        this.options = options;
+        this.web = webTools({ secrets: options.secrets, request: options.request, keyless: () => this.setting(WEB_PLUGIN.id, KEYLESS_SEARCH) === 1 });
+        this.parts.push({ plugin: WEB_PLUGIN, tools: () => this.web({}) });
+        if (options.browser !== false)
+            this.parts.push(browserPart({ stateDir: options.stateDir, ...options.browser }));
+    }
+    add(part) {
+        this.parts.push(part);
+    }
+    get plugins() {
+        return this.parts.map((part) => part.plugin);
+    }
+    /** A number a person set on one of these plugins. */
+    setting(pluginId, key) {
+        const descriptor = pluginId === WEB_PLUGIN.id ? { settings: WEB_SETTINGS } : this.parts.find((part) => part.plugin.id === pluginId)?.plugin;
+        const setting = descriptor?.settings?.find((candidate) => candidate.key === key);
+        return setting ? settingValue(setting, attachments.load(this.options.root()).settings[pluginId]) : 0;
+    }
+    /** Every world tool for a context, with the plugin each belongs to. */
+    tools(context, on) {
+        return this.parts.flatMap((part) => part.tools(context).filter((tool) => on(part.plugin.id, tool.name)));
+    }
+    /** The provider an SDK session asks: only tools whose plugin is on for the caller. */
+    provider() {
+        const provider = (session) => {
+            const record = findRun(this.options.root(), session.run.runId);
+            const contributions = new Set(session.capabilities.contributions);
+            return this.tools({ run: session.run, caller: session.caller, attended: !UNATTENDED.has(record?.trigger ?? ''), subagent: session.depth > 0 || record?.relation === 'subagent', sessionKey: session.run.sessionId, cwd: session.cwd }, (pluginId, tool) => !contributions.size || contributions.has(contributionId(pluginId, 'tool', tool)));
+        };
+        provider.diagnostics = async (context) => (await Promise.all(this.parts.map(part => part.diagnostics?.(context) ?? []))).flat();
+        return provider;
+    }
+    /** Which search services have a key, and whether keyless search is on. Never the keys. */
+    async searchStatus() {
+        return Promise.all(SEARCH_PROVIDERS.map(async (provider) => ({
+            id: provider.id,
+            title: provider.title,
+            ready: provider.key ? Boolean(await this.options.secrets.get(provider.key)) : this.setting(WEB_PLUGIN.id, KEYLESS_SEARCH) === 1
+        })));
+    }
+    /** Saves or forgets a search service's key. */
+    async setSearchKey(providerId, key) {
+        const provider = SEARCH_PROVIDERS.find((candidate) => candidate.id === providerId && candidate.key);
+        if (!provider?.key)
+            throw invalid(`Search keys are kept for ${SEARCH_PROVIDERS.filter((candidate) => candidate.key).map((candidate) => candidate.id).join(', ')}.`);
+        if (key === null)
+            await this.options.secrets.delete(provider.key);
+        else if (!key.trim() || /\s/.test(key.trim()))
+            throw invalid('A key is one word with no spaces.');
+        else
+            await this.options.secrets.set(provider.key, key.trim());
+    }
+    browserConfig() {
+        return readBrowserConfig(this.options.stateDir);
+    }
+    configureBrowser(change) {
+        return writeBrowserConfig(this.options.stateDir, change);
+    }
+    async release(sessionKey) {
+        await Promise.all(this.parts.map((part) => part.release?.(sessionKey)));
+    }
+    async close() {
+        await Promise.all(this.parts.map((part) => part.close?.()));
+    }
+}