@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/dist/sdk/agents/builtin.js

@@ -1,6 +1,6 @@
 import { PLAN_RESEARCH_PLUGINS } from "./planResearch.js";
 const RECALL = ['history_search', 'history_read', 'trajectory_search', 'trajectory_read', 'wiki_search', 'wiki_read', 'wiki_list', 'skill_load'];
-const PROGRESS = ['checklist_write', 'session_name'];
+const PROGRESS = ['todo_write', 'session_name'];
 const WEB = ['web_search', 'web_fetch'];
 export const BUILTIN_PROFILES = [
     {
@@ -10,7 +10,7 @@ export const BUILTIN_PROFILES = [
         instructions: [
             'You carry out one piece of work from your brief, end to end.',
             '- Read the code you change first and follow the conventions you find.',
-            '- Keep a checklist with checklist_write when the brief has more than one step, and name your session with session_name.',
+            '- Keep a todo list with todo_write when the brief has more than one step, and name your session with session_name.',
             '- Make the change, then check it: run the relevant tests, type checks or commands.',
             '- Stay inside the brief. If something outside it blocks you, stop and say so instead of widening the change.',
             '- Finish with a short report: what you changed (files), how you checked it, and anything left open.'
@@ -25,7 +25,7 @@ export const BUILTIN_PROFILES = [
         instructions: [
             'You answer a question about the code, files or history in your brief. You never change anything.',
             '- Search broadly first, then read the parts that matter.',
-            '- Keep a checklist with checklist_write when the search has several parts, and name your session with session_name.',
+            '- Keep a todo list with todo_write when the search has several parts, and name your session with session_name.',
             '- Cite what you found as path:line.',
             '- Return conclusions, not file dumps: what you found, where, and how sure you are.'
         ].join('\n'),

package/dist/sdk/agents/planResearch.d.ts

@@ -1,5 +1,27 @@
+import type { CapabilitySet } from "../capabilities/types.js";
+import type { PluginDescriptor } from "../plugins/types.js";
 import type { AgentProfile } from "./profiles.js";
 export declare const PLAN_RESEARCH_TOOLS: ReadonlySet<string>;
 export declare const PLAN_RESEARCH_PLUGINS: readonly string[];
 export declare const PLAN_RESEARCH_EVIDENCE_TOOLS: ReadonlySet<string>;
-export declare function planResearchProfile(profile: Pick<AgentProfile, 'tools' | 'plugins'> | null | undefined): boolean;
+/** Capability snapshot needed to tell whether a profile can research in this particular run. */
+export interface PlanResearchContext {
+    frozenTools: readonly string[];
+    contributions: readonly string[];
+    descriptors: readonly PluginDescriptor[];
+}
+export interface PlanResearchEligibility {
+    eligible: boolean;
+    refusal: string | null;
+    /** The exact safe child snapshot to launch when eligible. */
+    capabilities: CapabilitySet;
+    unavailableTools: string[];
+}
+/** Whether the profile's explicit allowlists are restricted to read-only research. */
+export declare function planResearchProfile(profile: Pick<AgentProfile, 'name' | 'tools' | 'plugins'> | null | undefined): boolean;
+/**
+ * Evaluate the same effective intersection used for launch, including tool ownership removed by
+ * profile plugin narrowing. An explicit request is a strict override; omission inherits the safe
+ * profile/parent intersection.
+ */
+export declare function planResearchEligibility(profile: Pick<AgentProfile, 'name' | 'tools' | 'plugins'> | null | undefined, context: PlanResearchContext, requested?: readonly string[]): PlanResearchEligibility;

package/dist/sdk/agents/planResearch.js

@@ -1,5 +1,6 @@
+import { narrowForProfile } from "./narrow.js";
 export const PLAN_RESEARCH_TOOLS = new Set([
-    'read', 'grep', 'find', 'ls', 'checklist_write', 'session_name',
+    'read', 'grep', 'find', 'ls', 'todo_write', 'session_name',
     'history_search', 'history_read', 'trajectory_search', 'trajectory_read',
     'wiki_entrypoint', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load',
     'web_search', 'web_fetch'
@@ -8,12 +9,74 @@ export const PLAN_RESEARCH_PLUGINS = ['history', 'variant', 'web', 'wiki'];
 export const PLAN_RESEARCH_EVIDENCE_TOOLS = new Set([
     'read', 'grep', 'find', 'ls', 'history_search', 'trajectory_search', 'wiki_search', 'web_search', 'web_fetch'
 ]);
+function profileRefusal(profile) {
+    if (!profile)
+        return 'Plan-mode delegation requires a named, eligible read-only research profile.';
+    if (!Array.isArray(profile.tools) || profile.tools.length === 0) {
+        return `Profile ${profile.name} must declare an explicit tools allowlist for plan-mode research.`;
+    }
+    const unsafeTools = profile.tools.filter(name => !PLAN_RESEARCH_TOOLS.has(name));
+    if (unsafeTools.length) {
+        return `Profile ${profile.name} includes non-research tools: ${[...new Set(unsafeTools)].join(', ')}. Use a profile whose tools are all plan research tools.`;
+    }
+    if (!profile.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))) {
+        return `Profile ${profile.name} must allow at least one read-only research evidence tool.`;
+    }
+    if (!Array.isArray(profile.plugins)) {
+        return `Profile ${profile.name} must declare an explicit plugin allowlist for plan-mode research.`;
+    }
+    const unsafePlugins = profile.plugins.filter(name => !PLAN_RESEARCH_PLUGINS.includes(name));
+    if (unsafePlugins.length) {
+        return `Profile ${profile.name} includes non-research plugins: ${[...new Set(unsafePlugins)].join(', ')}. Use only the plan research plugins: ${PLAN_RESEARCH_PLUGINS.join(', ')}.`;
+    }
+    return null;
+}
+/** Whether the profile's explicit allowlists are restricted to read-only research. */
 export function planResearchProfile(profile) {
-    return Boolean(profile
-        && Array.isArray(profile.tools)
-        && profile.tools.length > 0
-        && profile.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))
-        && profile.tools.every(name => PLAN_RESEARCH_TOOLS.has(name))
-        && Array.isArray(profile.plugins)
-        && profile.plugins.every(name => PLAN_RESEARCH_PLUGINS.includes(name)));
+    return profileRefusal(profile) === null;
+}
+/**
+ * Evaluate the same effective intersection used for launch, including tool ownership removed by
+ * profile plugin narrowing. An explicit request is a strict override; omission inherits the safe
+ * profile/parent intersection.
+ */
+export function planResearchEligibility(profile, context, requested) {
+    const empty = { version: 1, tools: [], connectors: [], contributions: [] };
+    const profileProblem = profileRefusal(profile);
+    if (profileProblem)
+        return { eligible: false, refusal: profileProblem, capabilities: empty, unavailableTools: [] };
+    const parent = {
+        version: 1,
+        tools: [...context.frozenTools],
+        connectors: [],
+        contributions: [...context.contributions]
+    };
+    const narrowed = narrowForProfile(parent, profile, requested, context.descriptors);
+    const capabilities = {
+        ...narrowed.capabilities,
+        tools: narrowed.capabilities.tools.filter(name => PLAN_RESEARCH_TOOLS.has(name)),
+        connectors: []
+    };
+    if (requested) {
+        const effective = new Set(capabilities.tools);
+        const incompatible = [...new Set(requested.filter(name => !PLAN_RESEARCH_TOOLS.has(name)
+                || !profile.tools.includes(name)
+                || !context.frozenTools.includes(name)
+                || !effective.has(name)))];
+        if (incompatible.length) {
+            return {
+                eligible: false,
+                refusal: `Plan-mode tools override contains incompatible tool(s): ${incompatible.join(', ')}. Omit \`tools\` to inherit the selected profile's safe research intersection, or retry with only tools allowed by that profile, available in this parent run, and in the plan research set.`,
+                capabilities,
+                unavailableTools: narrowed.unavailable
+            };
+        }
+    }
+    if (!capabilities.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))) {
+        const refusal = requested
+            ? `The tools override [${requested.join(', ')}] leaves no available research evidence tool for profile ${profile.name}. Omit \`tools\` to inherit the safe intersection, or retry with an available evidence tool from this profile.`
+            : `Profile ${profile.name} has no read-only research evidence tool after intersecting its allowlists with this run's frozen capabilities and plugin contributions. Choose a profile with an available evidence tool.`;
+        return { eligible: false, refusal, capabilities, unavailableTools: narrowed.unavailable };
+    }
+    return { eligible: true, refusal: null, capabilities, unavailableTools: narrowed.unavailable };
 }

package/dist/sdk/agents/profiles.d.ts

@@ -1,8 +1,11 @@
 import { type Effort } from "../core/effort.js";
+import { type PlanResearchContext } from "./planResearch.js";
 export declare const PROFILE_NAME: RegExp;
+/** Names a profile cannot take: `main` is how rosters show the agent a person talks to. */
+export declare const RESERVED_PROFILE_NAMES: readonly string[];
 export declare const PROFILE_COLORS: readonly ["blue", "green", "yellow", "red", "magenta", "cyan", "orange", "purple"];
 export type ProfileColor = (typeof PROFILE_COLORS)[number];
-export type ProfileSource = 'builtin' | 'global' | 'project' | 'variant';
+export type ProfileSource = 'builtin' | 'global' | 'project' | 'variant' | 'plugin';
 /** Where a person's own profile file lives. */
 export type ProfileScope = 'global' | 'project';
 /** Which variant a profile's subagent runs: a scope's head or version, none, or the parent's (null). */
@@ -51,12 +54,21 @@ export declare function formatVariant(variant: ProfileVariant): string | null;
 export declare function parseProfile(text: string, name: string, source: ProfileSource, path: string | null): AgentProfile;
 /** The file text for a profile, as `createProfile` writes it. */
 export declare function profileText(profile: ProfileDefinition): string;
+/**
+ * A profile a package brings. It is named by its frontmatter, since such packages are often written
+ * for other agent harnesses whose files are not named after their agents. What only those
+ * harnesses understand is dropped: their tool names are translated, a model without a provider
+ * (`inherit`, `sonnet`) is left to the parent, and a package never pins a variant or plugins. A
+ * tool list of which nothing translates keeps the subagent read-only rather than widening it.
+ */
+export declare function parsePackageProfile(text: string, path: string): AgentProfile;
 /**
  * Every profile a session in `cwd` can use. An unreadable file is reported in `problems`; it hides
  * nothing, so a broken project file leaves the global or built-in profile of that name in force.
+ * `packageProfiles` are the profile files of the session's switched-on packages.
  */
-export declare function listProfiles(root: string, cwd?: string | null, variantDir?: string | null): ProfileListing;
-export declare function resolveProfile(root: string, cwd: string | null | undefined, name: string, variantDir?: string | null): AgentProfile | null;
+export declare function listProfiles(root: string, cwd?: string | null, variantDir?: string | null, packageProfiles?: readonly string[]): ProfileListing;
+export declare function resolveProfile(root: string, cwd: string | null | undefined, name: string, variantDir?: string | null, packageProfiles?: readonly string[]): AgentProfile | null;
 /** Writes a new profile file from the template, or a copy of `from`. Refuses to overwrite one. */
 export declare function createProfile(root: string, cwd: string | null | undefined, input: {
     name: string;
@@ -71,7 +83,7 @@ export declare function removeProfile(root: string, cwd: string | null | undefin
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export declare const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean): {
+export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean, researchContext?: PlanResearchContext, packageProfiles?: readonly string[]): {
     id: string;
     title: string;
     body: string;

package/dist/sdk/agents/profiles.js

@@ -1,17 +1,21 @@
 // Agent profiles (PROP-0029): named bundles a subagent starts from, with its instructions, colour,
 // tools, plugins, variant, model and effort. They come from four places, later ones winning:
 // built-ins in code, `<data root>/agents/*.md`, `<project>/.xingular/agents/*.md`; a variant's own
-// c5 subagents fill in names nobody else took. Profiles only narrow what the parent has.
+// c5 subagents, then the profiles of switched-on packages, fill in names nobody else took.
+// Profiles only narrow what the parent has.
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { EFFORTS } from "../core/effort.js";
 import { invalid, notFound } from "../core/errors.js";
 import { parse, serialize } from "../core/frontmatter.js";
 import { atomicWrite } from "../core/fs.js";
 import { subagentOf } from "../variant/materialise.js";
 import { BUILTIN_PROFILES } from "./builtin.js";
-import { planResearchProfile } from "./planResearch.js";
+import { planResearchEligibility, planResearchProfile } from "./planResearch.js";
 export const PROFILE_NAME = /^[a-z0-9][a-z0-9_-]*$/;
+/** Names a profile cannot take: `main` is how rosters show the agent a person talks to. */
+export const RESERVED_PROFILE_NAMES = ['main'];
+const reservedRefusal = (name) => `${name} is reserved for the main agent; choose another profile name.`;
 export const PROFILE_COLORS = ['blue', 'green', 'yellow', 'red', 'magenta', 'cyan', 'orange', 'purple'];
 /** Nearest folder above `cwd` that holds `.git`, or `cwd` itself. */
 export function projectRoot(cwd) {
@@ -65,6 +69,8 @@ export function formatVariant(variant) {
 export function parseProfile(text, name, source, path) {
     if (!PROFILE_NAME.test(name))
         throw invalid('A profile name uses lowercase letters, digits, - and _, and starts with a letter or digit.');
+    if (RESERVED_PROFILE_NAMES.includes(name))
+        throw invalid(reservedRefusal(name));
     const parsed = parse(text);
     if (!parsed)
         throw invalid('The profile needs a frontmatter block between --- lines.');
@@ -124,7 +130,7 @@ function variantDefinitions(variantDir) {
     if (!folder || !existsSync(folder))
         return [];
     return readdirSync(folder).sort().flatMap(name => {
-        const definition = subagentOf(variantDir, name);
+        const definition = RESERVED_PROFILE_NAMES.includes(name) ? null : subagentOf(variantDir, name);
         if (!definition)
             return [];
         return [{
@@ -134,11 +140,49 @@ function variantDefinitions(variantDir) {
             }];
     });
 }
+// Tool names that agent plugins written for other harnesses use, as this harness names them.
+const FOREIGN_TOOLS = {
+    Read: 'read', Grep: 'grep', Glob: 'find', LS: 'ls', Edit: 'edit', MultiEdit: 'edit', Write: 'write', Bash: 'bash',
+    WebSearch: 'web_search', WebFetch: 'web_fetch', TodoWrite: 'todo_write'
+};
+const READ_ONLY_TOOLS = ['read', 'grep', 'find', 'ls'];
+/**
+ * A profile a package brings. It is named by its frontmatter, since such packages are often written
+ * for other agent harnesses whose files are not named after their agents. What only those
+ * harnesses understand is dropped: their tool names are translated, a model without a provider
+ * (`inherit`, `sonnet`) is left to the parent, and a package never pins a variant or plugins. A
+ * tool list of which nothing translates keeps the subagent read-only rather than widening it.
+ */
+export function parsePackageProfile(text, path) {
+    const parsed = parse(text);
+    if (!parsed)
+        throw invalid('The profile needs a frontmatter block between --- lines.');
+    const front = parsed.front;
+    const name = optionalText(front.name, 'name');
+    if (!name || !PROFILE_NAME.test(name))
+        throw invalid('A profile name uses lowercase letters, digits, - and _, and starts with a letter or digit.');
+    if (RESERVED_PROFILE_NAMES.includes(name))
+        throw invalid(reservedRefusal(name));
+    const description = optionalText(front.description, 'description');
+    if (!description)
+        throw invalid('The profile needs a description.');
+    const declared = stringList(front.tools, 'tools');
+    const tools = declared ? [...new Set(declared.flatMap((tool) => FOREIGN_TOOLS[tool] ?? (/^[a-z][a-z0-9_]*$/.test(tool) ? [tool] : [])))] : null;
+    const color = typeof front.color === 'string' && PROFILE_COLORS.includes(front.color) ? front.color : 'blue';
+    const model = typeof front.model === 'string' && front.model.includes('/') ? front.model : null;
+    const effort = typeof front.effort === 'string' && EFFORTS.includes(front.effort) ? front.effort : null;
+    return {
+        name, description, color, instructions: parsed.body.trim(),
+        tools: tools && !tools.length ? READ_ONLY_TOOLS : tools, plugins: null, variant: null, model, effort,
+        source: 'plugin', path
+    };
+}
 /**
  * Every profile a session in `cwd` can use. An unreadable file is reported in `problems`; it hides
  * nothing, so a broken project file leaves the global or built-in profile of that name in force.
+ * `packageProfiles` are the profile files of the session's switched-on packages.
  */
-export function listProfiles(root, cwd, variantDir) {
+export function listProfiles(root, cwd, variantDir, packageProfiles = []) {
     const profiles = new Map();
     const problems = [];
     for (const definition of BUILTIN_PROFILES)
@@ -149,12 +193,25 @@ export function listProfiles(root, cwd, variantDir) {
     for (const definition of variantDefinitions(variantDir))
         if (!profiles.has(definition.name))
             profiles.set(definition.name, definition);
+    // A package cannot replace a profile a person, the harness or the variant already has.
+    for (const path of packageProfiles) {
+        try {
+            const profile = parsePackageProfile(readFileSync(path, 'utf8'), path);
+            if (!profiles.has(profile.name))
+                profiles.set(profile.name, profile);
+            else
+                problems.push({ name: profile.name, source: 'plugin', path, error: `A ${profiles.get(profile.name).source} profile already has this name, so the package's is not used.` });
+        }
+        catch (error) {
+            problems.push({ name: basename(path, '.md'), source: 'plugin', path, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
     return { profiles: [...profiles.values()].sort((left, right) => left.name.localeCompare(right.name)), problems };
 }
-export function resolveProfile(root, cwd, name, variantDir) {
+export function resolveProfile(root, cwd, name, variantDir, packageProfiles = []) {
     if (!PROFILE_NAME.test(name))
         return null;
-    return listProfiles(root, cwd, variantDir).profiles.find(profile => profile.name === name) ?? null;
+    return listProfiles(root, cwd, variantDir, packageProfiles).profiles.find(profile => profile.name === name) ?? null;
 }
 function scopeDir(root, cwd, scope) {
     const dirs = profileDirs(root, cwd);
@@ -175,6 +232,8 @@ export function createProfile(root, cwd, input) {
     const name = typeof input.name === 'string' ? input.name.trim() : '';
     if (!PROFILE_NAME.test(name))
         throw invalid('A profile name uses lowercase letters, digits, - and _, and starts with a letter or digit.');
+    if (RESERVED_PROFILE_NAMES.includes(name))
+        throw invalid(reservedRefusal(name));
     if (input.scope !== 'global' && input.scope !== 'project')
         throw invalid('scope must be global or project.');
     const dir = scopeDir(root, cwd, input.scope);
@@ -207,16 +266,20 @@ export function removeProfile(root, cwd, input) {
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export function profileSection(root, cwd, variantDir, planResearchOnly = false) {
-    const { profiles } = listProfiles(root, cwd, variantDir);
-    const listed = planResearchOnly ? profiles.filter(planResearchProfile) : profiles;
+export function profileSection(root, cwd, variantDir, planResearchOnly = false, researchContext, packageProfiles = []) {
+    const { profiles } = listProfiles(root, cwd, variantDir, packageProfiles);
+    const listed = planResearchOnly
+        ? profiles.filter(profile => researchContext
+            ? planResearchEligibility(profile, researchContext).eligible
+            : planResearchProfile(profile))
+        : profiles;
     return {
         id: 'subagents',
         title: 'Subagents',
         body: [
             planResearchOnly
-                ? 'Plan mode may start only a named profile listed here, for read-only research. Do not omit agent or use a profile not listed.'
-                : 'Delegate when it meaningfully reduces work: choose a substantial, bounded task that can proceed independently, such as unfamiliar cross-file research likely to take several searches or a self-contained implementation. Do a known-file lookup, one or two simple tool calls, a tiny edit or tightly coupled work yourself. Prefer a named profile: explorer for repository research, researcher for public-source research, and worker for a defined change it can own end to end; omit agent only when no profile fits. Each child starts without this conversation, so give it the goal, relevant context or paths, non-goals, expected result and acceptance or verification; use its own checklist for multi-step work. Prefer context-heavy research with concise evidence-backed findings. Parallelize only independent tasks and never assign overlapping edits. Return without waiting only when useful independent work remains; otherwise wait. You own integration, verification and the user-facing report. A profile can only narrow your tools.',
+                ? 'Plan mode may start only a named profile listed here, for read-only research. Do not omit agent or use a profile not listed. Omit the optional tools field to inherit the safe available intersection; specify it only to narrow further.'
+                : 'Delegate when it meaningfully reduces work: choose a substantial, bounded task that can proceed independently, such as unfamiliar cross-file research likely to take several searches or a self-contained implementation. Do a known-file lookup, one or two simple tool calls, a tiny edit or tightly coupled work yourself. Prefer a named profile: explorer for repository research, researcher for public-source research, and worker for a defined change it can own end to end; omit agent only when no profile fits. Each child starts without this conversation, so give it the goal, relevant context or paths, non-goals, expected result and acceptance or verification; use its own todo list for multi-step work. Prefer context-heavy research with concise evidence-backed findings. Parallelize only independent tasks and never assign overlapping edits. Return without waiting only when useful independent work remains; otherwise wait. You own integration, verification and the user-facing report. A profile can only narrow your tools.',
             ...(listed.length ? listed.map((profile) => `- ${profile.name} — ${profile.description}`) : ['- No eligible read-only research profiles are configured.'])
         ].join('\n'),
         budget: 6_000,

package/dist/sdk/annotations/bridge.d.ts

@@ -29,6 +29,8 @@ export declare class NotesBridge {
     private settingsFile;
     /** Starts the bridge (once) on the port and token kept from last time, so the app's snippet stays valid. */
     start(): Promise<BridgeInfo>;
+    /** What a window loads, once the bridge is listening. */
+    current(): BridgeInfo | null;
     private listen;
     list(): BridgeWindow[];
     /** Sends one helper operation to a window and waits for its JSON reply. */

package/dist/sdk/annotations/bridge.js

@@ -71,6 +71,10 @@ export class NotesBridge {
         this.starting ??= this.listen().finally(() => { this.starting = null; });
         return this.starting;
     }
+    /** What a window loads, once the bridge is listening. */
+    current() {
+        return this.info;
+    }
     async listen() {
         const settingsFile = this.settingsFile();
         if (existsSync(settingsFile))

package/dist/sdk/annotations/capture.d.ts

@@ -28,7 +28,7 @@ export interface CaptureWindow {
 /** One comment the person submitted in the inspector's popover. */
 export interface InspectResult extends CaptureEnvelope {
     body: string;
-    action: 'save' | 'queue' | 'send';
+    action: 'save' | 'send';
 }
 export interface InspectState {
     /** False once the person or the page ended it. */
@@ -44,16 +44,43 @@ export interface InspectState {
 }
 /** Opens a DevTools connection to a running app; tests replace it. */
 export type AppConnector = (endpoint: string) => Promise<Browser>;
+/** A desktop app on this computer that answers on a DevTools port. */
+export interface DevToolsApp {
+    endpoint: string;
+    port: number;
+    /** The title of its first window, or what the app calls itself. */
+    name: string;
+    /** What the DevTools port reports, such as `Chrome/126.0` or `Electron/31.0`. */
+    browser: string;
+    electron: boolean;
+    windows: number;
+}
+/** Reads a JSON answer from a loopback DevTools port, or null when nothing answers in time; tests replace it. */
+export type DevToolsFetch = (url: string, timeoutMs: number) => Promise<unknown>;
+/** Starts an app the person named; tests replace it. */
+export type AppSpawner = (command: string, args: string[]) => void;
 export interface AnnotationCaptureOptions {
     stateDir: string;
     launch?: Launcher;
     network?: NetworkPolicy;
     connect?: AppConnector;
     bridge?: NotesBridge;
+    fetchJson?: DevToolsFetch;
+    spawnApp?: AppSpawner;
+    /** A free loopback port for an app started here; tests replace it. */
+    freePort?: () => Promise<number>;
+    /** How long a started app has to open its DevTools port, in milliseconds. */
+    launchTimeoutMs?: number;
 }
+/** Where apps started with `--remote-debugging-port` or `--inspect` usually listen. */
+export declare const DEVTOOLS_PORTS: readonly [9222, 9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230];
+/** The program inside a macOS `.app` bundle, or the path itself. */
+export declare function appExecutable(path: string): string;
 export declare class AnnotationCapture {
     private readonly options;
     private readonly targets;
+    /** Ports the person attached to or started an app on, checked again by `discover`. */
+    private readonly knownPorts;
     private readonly inspecting;
     private readonly network;
     readonly bridge: NotesBridge;
@@ -62,11 +89,14 @@ export declare class AnnotationCapture {
     private target;
     private replace;
     private call;
-    /** What `key` captures in now. */
+    /** What `key` captures in now, with the script to load while it captures a bridge. */
     describe(key: string): {
         kind: CaptureTargetSpec['kind'];
         app: NoteApp | null;
         inspecting: boolean;
+        bridge?: {
+            snippet: string;
+        };
     };
     /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
     attach(key: string, spec: CaptureTargetSpec): Promise<{
@@ -76,6 +106,18 @@ export declare class AnnotationCapture {
         bridge?: BridgeInfo;
     }>;
     windows(key: string): Promise<CaptureWindow[]>;
+    /** Apps on this computer that answer on a DevTools port: the usual ports and any used before. */
+    discover(ports?: readonly number[]): Promise<DevToolsApp[]>;
+    /**
+     * Starts the app the person named with a DevTools port and attaches to its windows. A macOS `.app`
+     * bundle starts its own program. The app keeps running when the capture ends.
+     */
+    launchApp(key: string, path: string, args?: readonly string[]): Promise<{
+        kind: 'cdp';
+        app: NoteApp | null;
+        windows: CaptureWindow[];
+        endpoint: string;
+    }>;
     /** Switches to another window or tab of the target; an inspector there starts again. */
     selectWindow(key: string, id: string): Promise<void>;
     /** Shows the capture window, at `url` when given. Captures in the browser again if an app was attached. */

package/dist/sdk/annotations/capture.js

@@ -5,8 +5,11 @@
 // - `bridge`: app windows that loaded the page bridge script (a macOS web view has no DevTools port).
 // The person selects text, clicks an element, or inspects with the popover; the front end pulls
 // what they did through the page helper.
+import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { join } from 'node:path';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { basename, join } from 'node:path';
 import { readBrowserConfig } from "../browser/config.js";
 import { NetworkPolicy } from "../browser/network.js";
 import { BrowserSession, fileName, launchBrowser } from "../browser/session.js";
@@ -14,6 +17,56 @@ import { NotesBridge } from "./bridge.js";
 import { evaluateIsolated } from "./isolated.js";
 import { pageCall, pageReply } from "./pageScript.js";
 import { validateUrl } from "./store.js";
+/** Where apps started with `--remote-debugging-port` or `--inspect` usually listen. */
+export const DEVTOOLS_PORTS = [9222, 9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230];
+const PROBE_MS = 400;
+const fetchJson = async (url, timeoutMs) => {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        return response.ok ? await response.json() : null;
+    }
+    catch {
+        return null;
+    }
+};
+const spawnApp = (command, args) => {
+    // The app is the person's: it keeps running after the terminal ends.
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => undefined);
+    child.unref();
+};
+const freePort = () => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        server.close(() => typeof address === 'object' && address ? resolve(address.port) : reject(new Error('No free port.')));
+    });
+});
+/** The program inside a macOS `.app` bundle, or the path itself. */
+export function appExecutable(path) {
+    if (!/\.app\/?$/.test(path))
+        return path;
+    const folder = join(path, 'Contents', 'MacOS');
+    if (!existsSync(folder))
+        throw new Error(`${path} has no Contents/MacOS folder.`);
+    const programs = readdirSync(folder).filter((name) => !name.startsWith('.') && statSync(join(folder, name)).isFile());
+    const named = basename(path.replace(/\/$/, ''), '.app');
+    const program = programs.find((name) => name === named) ?? programs[0];
+    if (!program)
+        throw new Error(`${path} has no program in Contents/MacOS.`);
+    return join(folder, program);
+}
+function describeApp(port, version, list) {
+    const agent = typeof version['User-Agent'] === 'string' ? version['User-Agent'] : '';
+    const electron = /Electron\/([\d.]+)/.exec(agent);
+    const browser = electron ? `Electron/${electron[1]}` : typeof version.Browser === 'string' ? version.Browser : 'DevTools';
+    const pages = Array.isArray(list) ? list.filter((entry) => !!entry && typeof entry === 'object' && entry.type === 'page' && !/^(?:devtools|chrome-extension):/.test(String(entry.url ?? ''))) : [];
+    const title = pages.map((page) => typeof page.title === 'string' ? page.title.trim() : '').find(Boolean);
+    const product = /\)\s+([A-Za-z][\w .-]*?)\/[\d.]+\s+(?:Chrome|Electron)\//.exec(agent)?.[1];
+    return { endpoint: `http://127.0.0.1:${port}`, port, name: (title || product || browser).slice(0, 120), browser, electron: !!electron, windows: pages.length };
+}
 const IDLE_MS = 60 * 60_000;
 const LOOPBACK = /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/;
 const connectApp = async (endpoint) => {
@@ -130,6 +183,8 @@ class WebTarget {
 export class AnnotationCapture {
     options;
     targets = new Map();
+    /** Ports the person attached to or started an app on, checked again by `discover`. */
+    knownPorts = new Set();
     inspecting = new Map();
     network;
     bridge;
@@ -170,10 +225,11 @@ export class AnnotationCapture {
     async call(key, operation) {
         return pageReply((await this.target(key).evaluate(operation)).reply);
     }
-    /** What `key` captures in now. */
+    /** What `key` captures in now, with the script to load while it captures a bridge. */
     describe(key) {
         const target = this.targets.get(key);
-        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key) };
+        const bridge = target?.kind === 'bridge' ? this.bridge.current() : null;
+        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key), ...(bridge ? { bridge: { snippet: bridge.snippet } } : {}) };
     }
     /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
     async attach(key, spec) {
@@ -189,6 +245,9 @@ export class AnnotationCapture {
             const name = spec.name?.trim() || `App at ${new URL(spec.endpoint).host}`;
             const target = new CdpTarget(browser, { kind: 'cdp', name: name.slice(0, 200) });
             await this.replace(key, target);
+            const port = Number(new URL(spec.endpoint).port);
+            if (port)
+                this.knownPorts.add(port);
             return { kind: 'cdp', app: target.app, windows: await target.windows() };
         }
         if (spec.kind === 'bridge') {
@@ -202,6 +261,48 @@ export class AnnotationCapture {
     windows(key) {
         return this.target(key).windows();
     }
+    /** Apps on this computer that answer on a DevTools port: the usual ports and any used before. */
+    async discover(ports = []) {
+        const probe = this.options.fetchJson ?? fetchJson;
+        const wanted = [...new Set([...DEVTOOLS_PORTS, ...this.knownPorts, ...ports])].filter((port) => Number.isInteger(port) && port > 0 && port < 65536);
+        const found = await Promise.all(wanted.map(async (port) => {
+            const version = await probe(`http://127.0.0.1:${port}/json/version`, PROBE_MS);
+            if (!version || typeof version !== 'object')
+                return null;
+            // A Node `--inspect` port answers too, but has no windows to annotate.
+            if (typeof version.webSocketDebuggerUrl !== 'string' && typeof version.Browser !== 'string')
+                return null;
+            if (/^node(?:\.js)?\//i.test(String(version.Browser ?? '')))
+                return null;
+            return describeApp(port, version, await probe(`http://127.0.0.1:${port}/json/list`, PROBE_MS));
+        }));
+        return found.filter((app) => app !== null).sort((left, right) => left.port - right.port);
+    }
+    /**
+     * Starts the app the person named with a DevTools port and attaches to its windows. A macOS `.app`
+     * bundle starts its own program. The app keeps running when the capture ends.
+     */
+    async launchApp(key, path, args = []) {
+        const program = appExecutable(path.trim());
+        if (!program)
+            throw new Error('Give the path of the app to start.');
+        const port = await (this.options.freePort ?? freePort)();
+        (this.options.spawnApp ?? spawnApp)(program, [...args, `--remote-debugging-port=${port}`]);
+        this.knownPorts.add(port);
+        const endpoint = `http://127.0.0.1:${port}`;
+        const probe = this.options.fetchJson ?? fetchJson;
+        const deadline = Date.now() + (this.options.launchTimeoutMs ?? 20_000);
+        for (;;) {
+            if (await probe(`${endpoint}/json/version`, PROBE_MS))
+                break;
+            if (Date.now() > deadline)
+                throw new Error(`${basename(path)} did not open a DevTools port. Only Chromium and Electron apps can be inspected this way.`);
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        const name = basename(path.trim().replace(/\/$/, '')).replace(/\.app$/, '');
+        const attached = await this.attach(key, { kind: 'cdp', endpoint, name });
+        return { kind: 'cdp', app: attached.app, windows: attached.windows, endpoint };
+    }
     /** Switches to another window or tab of the target; an inspector there starts again. */
     async selectWindow(key, id) {
         const inspecting = this.inspecting.has(key);