@xingular/harness 1.3.1-unstable.0 → 1.3.1-unstable.2

package/dist/sdk/annotations/store.js

@@ -160,6 +160,23 @@ function validNote(note, id) {
     if (!note || note.id !== id || note.author !== 'user' || !Number.isSafeInteger(note.version) || note.version < 1 || !Array.isArray(note.grants) || !Array.isArray(note.history)) {
         throw new HarnessError('invalid_data', `Note ${id} is not a valid note.`);
     }
+    return upgradeDelivery(note);
+}
+/** Notes written before PROP-0048 had a queue and a "fixed" claim: read them as pending or sent. */
+function upgradeDelivery(note) {
+    const delivery = note.delivery;
+    if (!delivery)
+        return note;
+    if (delivery.state === 'queued')
+        delivery.state = 'pending';
+    else if (delivery.state === 'fixed') {
+        delivery.state = 'sent';
+        delivery.sentAt ??= delivery.fixedAt;
+    }
+    delete delivery.fixedAt;
+    delete delivery.summary;
+    if (delivery.state !== 'pending' && delivery.state !== 'sent')
+        note.delivery = null;
     return note;
 }
 export function read(root, id) {
@@ -240,7 +257,7 @@ export function update(root, id, expectedVersion, patch) {
         if (patch.status !== 'open' && patch.status !== 'resolved')
             throw invalid('A note is open or resolved.');
         note.status = patch.status;
-        if (patch.status === 'resolved' && note.delivery?.state === 'queued')
+        if (patch.status === 'resolved' && note.delivery?.state === 'pending')
             note.delivery = null;
     }
     if (patch.target !== undefined)
@@ -263,6 +280,9 @@ export function unshare(root, id, principal) {
     const who = validatePrincipal(principal);
     const note = current(root, id, undefined);
     note.grants = note.grants.filter((grant) => !samePrincipal(grant.principal, who));
+    // A session that may no longer read the note is not sent it either.
+    if (note.delivery?.state === 'pending' && who.sessionId && note.delivery.sessionId === who.sessionId)
+        note.delivery = null;
     return save(root, note, 'unshare');
 }
 /** The host withdrew what a binding stood for (a tab closed or was shared again): every grant made with it ends. */
@@ -320,45 +340,48 @@ export function importNotes(root, notes) {
     }
     return { imported, skipped };
 }
-// ---- Delivery to an agent (PROP-0018) ----------------------------------------------------------
+// ---- Delivery to a session (PROP-0048) ----------------------------------------------------------
 /**
- * A person asks a session to act on the note: it is shared with that session (if it was not) and
- * waits in the session's queue until it is sent.
+ * The note is shared with the session and waits there, unsent, until the person sends it. Calling it
+ * again keeps the original time, so the send order stays the order the notes were made.
  */
-export function queue(root, id, expectedVersion, sessionId, options = {}) {
+export function markPending(root, id, expectedVersion, sessionId, options = {}) {
     const session = safeId(sessionId);
     const note = current(root, id, expectedVersion);
     if (note.status === 'resolved')
-        throw invalid('Reopen this note before queueing it.');
+        throw invalid('Reopen this note before sending it.');
     if (!note.grants.some((grant) => grant.principal.sessionId === session))
         note.grants.push({ principal: { sessionId: session }, grantedAt: now() });
-    const confirmationRequired = options.confirm === true || (note.delivery?.confirm === true && options.confirmed !== true);
+    const previous = note.delivery?.state === 'pending' && note.delivery.sessionId === session ? note.delivery : null;
+    const confirmationRequired = options.confirm === true || (previous?.confirm === true && options.confirmed !== true);
     note.delivery = {
-        state: 'queued',
+        state: 'pending',
         sessionId: session,
-        queuedAt: now(),
-        ...(options.autoSend ? { autoSend: true } : {}),
+        queuedAt: previous?.queuedAt ?? now(),
+        ...(options.autoSend || previous?.autoSend ? { autoSend: true } : {}),
         ...(confirmationRequired ? { confirm: true } : {})
     };
-    return save(root, note, 'queue');
-}
-/** Takes the note out of the queue. It stays shared; unshare withdraws that. */
-export function dequeue(root, id, expectedVersion) {
-    const note = current(root, id, expectedVersion);
-    if (note.delivery?.state !== 'queued')
-        throw invalid('This note is not waiting to be sent.');
-    note.delivery = null;
-    return save(root, note, 'dequeue');
+    return save(root, note, 'pending');
 }
-/** The notes waiting for one session, oldest first. `auto` keeps only those to send when it is idle. */
-export function queued(root, sessionId, filter = {}) {
+/** The unsent notes of one session, oldest first. `auto` keeps only those to send when it is idle. */
+export function pending(root, sessionId, filter = {}) {
     const ids = filter.ids ? new Set(filter.ids) : null;
     return all(root)
-        .filter((note) => note.status === 'open' && note.delivery?.state === 'queued' && note.delivery.sessionId === sessionId)
+        .filter((note) => note.status === 'open' && note.delivery?.state === 'pending' && note.delivery.sessionId === sessionId)
         .filter((note) => !filter.auto || (note.delivery?.autoSend === true && note.delivery.confirm !== true))
         .filter((note) => !ids || ids.has(note.id))
         .sort((left, right) => (left.delivery.queuedAt).localeCompare(right.delivery.queuedAt) || left.id.localeCompare(right.id));
 }
+/** `/annotate:clear`: the session's unsent notes are resolved and no longer shared with it. They can be reopened. */
+export function clearPending(root, sessionId) {
+    const session = safeId(sessionId);
+    return pending(root, session).map((note) => {
+        note.status = 'resolved';
+        note.delivery = null;
+        note.grants = note.grants.filter((grant) => grant.principal.sessionId !== session);
+        return save(root, note, 'clear');
+    });
+}
 /** The notes went to the session as part of `runId`. */
 export function markSent(root, ids, sessionId, runId) {
     const session = safeId(sessionId);
@@ -367,8 +390,8 @@ export function markSent(root, ids, sessionId, runId) {
     for (const note of notes) {
         if (note.status !== 'open')
             throw invalid('Resolved notes cannot be sent.');
-        if (note.delivery?.state !== 'queued' || note.delivery.sessionId !== session)
-            throw invalid('This note is not queued for this session.');
+        if (note.delivery?.state !== 'pending' || note.delivery.sessionId !== session)
+            throw invalid('This note is not waiting to be sent to this session.');
         if (note.delivery.confirm)
             throw invalid('Confirm this note before sending it.');
     }
@@ -379,16 +402,3 @@ export function markSent(root, ids, sessionId, runId) {
         return save(root, note, 'deliver');
     });
 }
-/** The agent says it acted on a note shared with it. The note stays open until a person resolves it. */
-export function markFixed(root, id, caller, summary) {
-    const note = current(root, id, undefined);
-    if (!visibleTo(note, caller))
-        throw notFound('Note');
-    const sessionId = note.delivery?.sessionId ?? caller.sessionId ?? note.grants.find((grant) => grant.principal.sessionId)?.principal.sessionId;
-    if (!sessionId)
-        throw invalid('This note was never sent to a session.');
-    note.delivery = { ...(note.delivery ?? { queuedAt: now() }), state: 'fixed', sessionId, fixedAt: now(), summary: bounded(summary.trim(), 2000, true, 'summary') };
-    delete note.delivery.autoSend;
-    delete note.delivery.confirm;
-    return save(root, note, 'mark_fixed');
-}

package/dist/sdk/commands/list.js

@@ -22,6 +22,8 @@ export function listCommands(plugins) {
         aliases.forEach((alias) => taken.add(alias));
     }
     for (const command of BUILTIN_PLUGIN_REGISTRY.commands()) {
+        if (command.rootOnly)
+            continue;
         const name = `${command.prefix}:${command.name}`;
         out.set(name, { name, description: command.description, group: 'Plugins', source: 'plugin', owner: command.pluginId });
     }

package/dist/sdk/core/links.d.ts

@@ -0,0 +1,51 @@
+/** What a link names, before anything touches the filesystem. */
+export type LinkTarget = {
+    kind: 'web';
+    url: string;
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'path';
+    path: string;
+};
+/** What the operating system is asked to open, after the file it names was checked. */
+export type OpenedTarget = {
+    kind: 'web';
+    url: string;
+} | {
+    kind: 'mail';
+    address: string;
+} | {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'directory';
+    path: string;
+};
+/** Hands an opened target to the operating system. Replaced in tests, and by a host that has its own opener. */
+export type LinkOpener = (target: OpenedTarget) => Promise<void>;
+export interface LinkOpenCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * What a link names, or null when it names nothing a surface may open. Pure: a path is not
+ * checked against the filesystem here, so hover and rendering can classify without I/O.
+ */
+export declare function linkTarget(raw: string | null | undefined, options?: {
+    base?: string | null;
+}): LinkTarget | null;
+/** The target with its path checked, or the reason the operating system must not be asked. */
+export declare function openableTarget(target: LinkTarget): OpenedTarget;
+/** The address the operating system is given, and the argv that carries it without a shell. */
+export declare function linkOpenCommand(target: OpenedTarget, platform?: NodeJS.Platform): LinkOpenCommand;
+/** The default opener: the operating system's own handler for this kind of target. */
+export declare function openWithSystem(target: OpenedTarget): Promise<void>;
+/** Checks the target and opens it. Returns what was opened, for a caller that reports it. */
+export declare function openLink(target: LinkTarget, opener?: LinkOpener): Promise<OpenedTarget>;
+/** Classifies and opens in one step: the door a host calls for a link a person clicked. */
+export declare function openLinkTarget(raw: string, options?: {
+    base?: string | null;
+    opener?: LinkOpener;
+}): Promise<OpenedTarget>;

package/dist/sdk/core/links.js

@@ -0,0 +1,155 @@
+// What a link points at, and the one door that hands it to the operating system. Both front ends
+// classify with `linkTarget` and open through `openLink`, so a destination one surface accepts is
+// the destination the other accepts.
+import { spawn } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { HarnessError } from "./errors.js";
+const MAX_LENGTH = 4096;
+const CONTROL_CHARACTERS = /[\x00-\x1f\x7f-\x9f]/u;
+const WEB_ADDRESS = /^https?:/iu;
+const MAIL_ADDRESS = /^mailto:/iu;
+const FILE_ADDRESS = /^file:/iu;
+const SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
+const LINE_SUFFIX = /:\d+(?::\d+)?$/u;
+/** A folder the system would launch or install rather than show. */
+const BUNDLE = /\.(?:app|appex|bundle|framework|kext|plugin|prefpane|workflow|xpc)$/iu;
+/** A document whose default application runs it, so a click would execute rather than open. */
+const LAUNCHABLE = /\.(?:action|appimage|bat|cmd|command|desktop|dmg|exe|jar|lnk|mpkg|osax|pkg|ps1|scpt|sh|terminal|tool|url|vb|vbs|webloc|workflow)$/iu;
+const unopenable = (message) => new HarnessError('link_not_openable', message, 'Open the file from the project instead.');
+/**
+ * What a link names, or null when it names nothing a surface may open. Pure: a path is not
+ * checked against the filesystem here, so hover and rendering can classify without I/O.
+ */
+export function linkTarget(raw, options = {}) {
+    const value = raw?.trim();
+    if (!value || value.length > MAX_LENGTH || CONTROL_CHARACTERS.test(value) || value.startsWith('#'))
+        return null;
+    if (WEB_ADDRESS.test(value)) {
+        try {
+            const url = new URL(value);
+            if ((url.protocol !== 'http:' && url.protocol !== 'https:') || !url.hostname || url.username || url.password)
+                return null;
+            return { kind: 'web', url: url.href };
+        }
+        catch {
+            return null;
+        }
+    }
+    if (MAIL_ADDRESS.test(value)) {
+        const address = value.slice('mailto:'.length).split('?')[0].trim();
+        return address && address.includes('@') && !/\s/u.test(address) ? { kind: 'mail', address } : null;
+    }
+    const path = filePath(value, options.base);
+    return path ? { kind: 'path', path } : null;
+}
+function filePath(value, base) {
+    let raw = value;
+    if (FILE_ADDRESS.test(raw)) {
+        try {
+            const url = new URL(raw);
+            if (url.hostname && url.hostname !== 'localhost')
+                return null;
+            raw = url.pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    const address = raw.split('#')[0].split('?')[0].replace(LINE_SUFFIX, '');
+    let decoded;
+    try {
+        decoded = decodeURIComponent(address);
+    }
+    catch {
+        return null;
+    }
+    if (!decoded || decoded.includes('\0') || decoded.startsWith('~') || decoded.startsWith('//'))
+        return null;
+    if (isAbsolute(decoded))
+        return decoded;
+    if (SCHEME.test(decoded))
+        return null;
+    if (!base || !isAbsolute(base))
+        return null;
+    return resolve(base, decoded);
+}
+/** The target with its path checked, or the reason the operating system must not be asked. */
+export function openableTarget(target) {
+    if (target.kind !== 'path')
+        return target;
+    let stats = statsOf(target.path);
+    let path = target.path;
+    if (stats.isSymbolicLink()) {
+        try {
+            path = realpathSync(target.path);
+        }
+        catch {
+            throw unopenable('That link points at a file that is not there.');
+        }
+        stats = statsOf(path);
+    }
+    if (stats.isDirectory()) {
+        if (BUNDLE.test(path))
+            throw unopenable('That link points at an application, not a document.');
+        return { kind: 'directory', path };
+    }
+    if (!stats.isFile())
+        throw unopenable('That link does not point at a file or a folder.');
+    if (LAUNCHABLE.test(path))
+        throw unopenable('That kind of file runs when it is opened, so a link cannot open it.');
+    if ((stats.mode & 0o111) !== 0)
+        throw unopenable('That file is executable, so a link cannot open it.');
+    return { kind: 'file', path };
+}
+function statsOf(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        throw unopenable('That link points at a file that is not there.');
+    }
+}
+/** The address the operating system is given, and the argv that carries it without a shell. */
+export function linkOpenCommand(target, platform = process.platform) {
+    const address = target.kind === 'web' ? target.url : target.kind === 'mail' ? `mailto:${target.address}` : target.path;
+    if (platform === 'darwin')
+        return { command: 'open', args: [address] };
+    if (platform === 'win32')
+        return { command: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', address] };
+    if (platform === 'linux' || platform === 'freebsd' || platform === 'openbsd')
+        return { command: 'xdg-open', args: [address] };
+    throw unopenable(`Opening links is not supported on ${platform}.`);
+}
+/** The default opener: the operating system's own handler for this kind of target. */
+export async function openWithSystem(target) {
+    const { command, args } = linkOpenCommand(target);
+    await new Promise((done, fail) => {
+        let child;
+        try {
+            child = spawn(command, args, { detached: process.platform !== 'win32', stdio: 'ignore', windowsHide: true });
+        }
+        catch (error) {
+            fail(error);
+            return;
+        }
+        child.once('error', fail);
+        child.once('spawn', () => {
+            child.unref();
+            done();
+        });
+    });
+}
+/** Checks the target and opens it. Returns what was opened, for a caller that reports it. */
+export async function openLink(target, opener = openWithSystem) {
+    const opened = openableTarget(target);
+    await opener(opened);
+    return opened;
+}
+/** Classifies and opens in one step: the door a host calls for a link a person clicked. */
+export async function openLinkTarget(raw, options = {}) {
+    const target = linkTarget(raw, { base: options.base });
+    if (!target)
+        throw unopenable('This link cannot be opened here.');
+    return openLink(target, options.opener);
+}

package/dist/sdk/harness.d.ts

@@ -4,6 +4,7 @@ import { Hub, type HubOptions } from "./hub/hub.js";
 import { type SecretStore } from "./accounts/secrets.js";
 import { Bus } from "./core/bus.js";
 import { type Directory, type HarnessEnv } from "./core/env.js";
+import { type LinkOpener } from "./core/links.js";
 import { ConnectedApps } from "./mcp/service.js";
 import type { AppOAuthClients } from "./mcp/types.js";
 import { Lessons } from "./history/lessons.js";
@@ -69,6 +70,8 @@ export interface HarnessOptions {
     hookImporter?: (address: string) => Promise<unknown>;
     /** Where managed worktrees are made, the prefix of branches they get, and how many `prune` keeps. */
     worktrees?: WorktreesOptions;
+    /** How a link a person clicked reaches the operating system. Defaults to the system's own opener. */
+    linkOpener?: LinkOpener;
 }
 /** What starting on a data root found and repaired. */
 export interface Recovery {
@@ -99,6 +102,8 @@ export declare class Harness {
     readonly env: Env;
     readonly stateDir: string;
     readonly policy: ToolPolicy;
+    /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
+    readonly linkOpener: LinkOpener;
     readonly accounts: Accounts;
     readonly approvals: Approvals;
     readonly runs: RunRegistry;

package/dist/sdk/harness.js

@@ -15,6 +15,7 @@ import { DEFAULT_PRODUCT_NAME, EMPTY_DIRECTORY } from "./core/env.js";
 import { HarnessError } from "./core/errors.js";
 import { readJsonOr } from "./core/fs.js";
 import { closeIndex } from "./core/index.js";
+import { openWithSystem } from "./core/links.js";
 import { ConnectedApps } from "./mcp/service.js";
 import { migrateConnectionScopes } from "./mcp/scopeMigration.js";
 import { Lessons } from "./history/lessons.js";
@@ -26,6 +27,7 @@ import { VariantTrust } from "./variant/trust.js";
 import * as notes from "./wiki/notes.js";
 import * as pluginApi from "./plugins/api.js";
 import * as pluginInstall from "./plugins/install.js";
+import * as pluginProposals from "./plugins/proposals.js";
 import * as attachments from "./plugins/attachments.js";
 import { HARNESS_PLUGINS } from "./plugins/builtin.js";
 import { World } from "./world/world.js";
@@ -72,6 +74,8 @@ export class Harness {
     env;
     stateDir;
     policy;
+    /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
+    linkOpener;
     accounts;
     approvals;
     runs;
@@ -118,6 +122,7 @@ export class Harness {
         this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus);
         this.hub = new Hub(this, options.hub);
         this.policy = options.policy ?? {};
+        this.linkOpener = options.linkOpener ?? openWithSystem;
         configureBuiltins(options.builtins ?? []);
         this.trust = new VariantTrust(this.stateDir);
         this.refineHost = options.refineHost ?? null;
@@ -189,7 +194,7 @@ export class Harness {
             worktrees: this.worktrees
         });
         this.sideQuestions = new SideQuestions({ env: this.env, sessions: this.sessions, runs: this.runs });
-        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false, notesChanged: (sessionId, ids) => this.bus.emit({ type: 'annotations.changed', sessionId, ids }) });
+        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false });
         // The harness's own world tools come first; a tool an application provides under the same name is not added again.
         this.sessions.provide(this.world.provider());
         this.doctor = new Doctor({
@@ -200,7 +205,7 @@ export class Harness {
         this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: refineRuntime });
         this.lessons = new Lessons({ root: () => this.env.root, runtime: refineRuntime });
         this.pageNotes = new NoteDeliveries({ root: () => this.env.root, bus: this.bus, terminals: () => this.terminals ?? null });
-        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params) }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
+        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, usage: this.usage, usageLimits: this.usageLimits, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
         this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)));
         this.runs.listen((event, run) => {
             this.accounts.onRunEvent(event, run);
@@ -215,9 +220,9 @@ export class Harness {
             if (runEnded)
                 indexRunUsage(this.env.root, event.runId);
             if (runEnded && run?.sessionId) {
-                // Notes sent with "Proceed now" while this session was working go out now; the terminal
-                // needs a moment to see its run as ended.
-                setTimeout(() => void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+                // Notes sent while this session was working go out now (runEnded waits for the terminal to
+                // see its run as ended, and tries again while it is still busy).
+                void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error)));
             }
             if ((event.type === 'completed' || event.type === 'failed') && run) {
                 if (event.type === 'completed')
@@ -294,7 +299,7 @@ export class Harness {
                     if (!sessionId || recoveredSessions.has(sessionId))
                         continue;
                     recoveredSessions.add(sessionId);
-                    setTimeout(() => void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+                    void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error)));
                 }
                 catch {
                     // A malformed run record does not prevent the rest of recovery.

package/dist/sdk/index.d.ts

@@ -6,6 +6,7 @@ export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema,
 export { Bus, log, type Notice } from "./core/bus.js";
 export { EMPTY_DIRECTORY, type Directory, type HarnessEnv } from "./core/env.js";
 export { HarnessError, invalid, notFound, toErrorShape, type ErrorShape } from "./core/errors.js";
+export { linkOpenCommand, linkTarget, openableTarget, openLink, openLinkTarget, openWithSystem, type LinkOpener, type LinkTarget, type OpenedTarget } from "./core/links.js";
 export { findBinary, searchPath } from "./core/path.js";
 export { fileSecretStore, memorySecretStore, secretKey, type SecretStore } from "./accounts/secrets.js";
 export type { Account, AccountsOverview, Pool } from "./accounts/store.js";

package/dist/sdk/index.js

@@ -15,6 +15,7 @@ export { hubCatalogSchema, hubEntrySchema, hubOverviewSchema, hubReceiptSchema }
 export { Bus, log } from "./core/bus.js";
 export { EMPTY_DIRECTORY } from "./core/env.js";
 export { HarnessError, invalid, notFound, toErrorShape } from "./core/errors.js";
+export { linkOpenCommand, linkTarget, openableTarget, openLink, openLinkTarget, openWithSystem } from "./core/links.js";
 export { findBinary, searchPath } from "./core/path.js";
 export { fileSecretStore, memorySecretStore, secretKey } from "./accounts/secrets.js";
 export { dispatch as harnessCall } from "./tools/dispatch.js";

package/dist/sdk/plugins/builtin.js

@@ -7,7 +7,7 @@ import { sliceOf } from "../sessions/workSlice.js";
 import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
 import { subagentTools } from "../tools/spawnSubagent.js";
 import { SESSION_NAME } from "../tools/sessionName.js";
-import { RECALL_TOOLS, SKILL_TOOLS, TRAJECTORY_TOOLS, WIKI_READ_TOOLS, WIKI_WRITE_TOOLS } from "../tools/definitions.js";
+import { PLUGIN_PROPOSAL_TOOLS, RECALL_TOOLS, SKILL_TOOLS, TRAJECTORY_TOOLS, WIKI_READ_TOOLS, WIKI_WRITE_TOOLS } from "../tools/definitions.js";
 import { FIRST_PARTY_PLUGINS } from "./firstParty.js";
 import { WEB_PLUGIN } from "../web/tools.js";
 import { KEYLESS_SEARCH, webPart } from "../web/part.js";
@@ -93,6 +93,7 @@ const CONNECTED_APPS_PLUGIN = {
 const DOCTOR_PLUGIN = { id: 'doctor', title: 'Doctor', description: 'Local readiness checks and explicitly confirmed live probes for accounts, models and tools.', required: 'Every local terminal has readiness diagnostics.' };
 const WORKTREES_PLUGIN = { id: 'worktrees', title: 'Worktrees', description: 'Create and manage isolated git worktrees, move changes between them, and restore removed worktrees.', required: 'Managed worktrees are available to every local terminal.' };
 const HUB_PLUGIN = { id: 'hub', title: 'Hub', description: 'Browse and install reviewed skills, plugins and documents from configured registries.', required: 'Reviewed Harness resources are available to every host.' };
+const PLUGIN_AUTHORING = { id: 'plugin-authoring', title: 'Plugin authoring', description: 'Propose plugins for a person to review.', required: 'Plugin proposals are reviewed before installation.', tools: tools(PLUGIN_PROPOSAL_TOOLS) };
 const REFINEMENT_PLUGIN = { id: 'refinement', title: 'Refinement', description: 'Improve variants from recorded evidence through isolated refinement runs and reviewed candidates.', required: 'Variant refinement is available to every host.' };
 const CAPABILITIES_PLUGIN = { id: 'capabilities', title: 'Capability discovery', description: 'Inspect the callable tools of the current run, including their input schemas. Discovery never grants access.', required: 'Every interactive session can inspect its own registered capabilities.', tools: [{ name: GET_CAPABILITIES, description: 'Inspect current capabilities' }] };
 const USAGE_PLUGIN = {
@@ -139,6 +140,7 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
         serverMethods: connectedAppServerMethods
     },
     { descriptor: HUB_PLUGIN, serverMethods: hubServerMethods },
+    { descriptor: PLUGIN_AUTHORING, ...toolContribution(PLUGIN_PROPOSAL_TOOLS, 31) },
     { descriptor: REFINEMENT_PLUGIN, serverMethods: refinementServerMethods },
     { descriptor: SIDE_QUESTIONS_PLUGIN, serverMethods: sideQuestionServerMethods },
     {
@@ -154,12 +156,14 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
     {
         descriptor: ANNOTATIONS_PLUGIN,
         commandPrefix: 'annotate',
-        defaultCommand: 'annotate',
+        defaultCommand: 'open',
         commands: [
-            { name: 'notes', description: 'Review web annotations saved from pages and apps' },
-            { name: 'annotate', description: 'Inspect a page or app, comment on components, and send fixes: /annotate:annotate [url | --app <devtools address> | --bridge]' }
+            { name: 'open', rootOnly: true, description: 'Annotate a page or app and send it to the agent: /annotate: [url | --app <port> | --bridge]' },
+            { name: 'notes', description: 'Every saved web annotation, searchable' },
+            { name: 'submit', description: 'Send this session\'s unsent annotations with your request: /annotate:submit <request>' },
+            { name: 'clear', description: 'Resolve this session\'s unsent annotations and stop sharing them' }
         ],
-        createWorldPart: ({ options }) => annotationsPart({ root: options.root, changed: options.notesChanged }),
+        createWorldPart: ({ options }) => annotationsPart({ root: options.root }),
         serverMethods: annotationServerMethods
     },
     { descriptor: CAPABILITIES_PLUGIN },
@@ -169,7 +173,8 @@ export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
         defaultCommand: 'analysis',
         commands: [
             { name: 'analysis', description: 'Token, cost and latency totals: /usage:analysis [today | 7d | 30d | all]' },
-            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' }
+            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' },
+            { name: 'accounts', description: 'Provider limits across all accounts: /usage:accounts' }
         ],
         serverMethods: usageServerMethods
     },

package/dist/sdk/plugins/builtinRegistry.d.ts

@@ -14,6 +14,8 @@ export interface BuiltinPluginCommand {
     name: string;
     description: string;
     legacyBare: boolean;
+    /** Reached only as the namespace root (`/annotate:`); it has no `/<prefix>:<name>` route and is not listed by name. */
+    rootOnly?: boolean;
 }
 export interface BuiltinWorldContext {
     options: WorldOptions;
@@ -36,7 +38,7 @@ export interface BuiltinPluginModule {
     descriptor: PluginDescriptor;
     /** Stable terminal command namespace; defaults to the plugin id. */
     commandPrefix?: string;
-    /** Command invoked by the namespace root, such as `/annotate:`. */
+    /** Command invoked by the namespace root, such as `/annotate:`. Mark it `rootOnly` to give it no named route. */
     defaultCommand?: string;
     /** Stable order for model tools, independent of descriptor display order. */
     toolOrder?: number;

package/dist/sdk/plugins/builtinRegistry.js

@@ -27,6 +27,10 @@ export function createBuiltinPluginRegistry(modules) {
         if (module.defaultCommand && !module.commands?.some(command => command.name === module.defaultCommand)) {
             throw new Error(`Unknown default command for built-in plugin ${id}: ${module.defaultCommand}`);
         }
+        for (const command of module.commands ?? []) {
+            if (command.rootOnly && command.name !== module.defaultCommand)
+                throw new Error(`Root-only command ${prefix}:${command.name} must be the default command of built-in plugin ${id}.`);
+        }
     }
     const commands = modules.flatMap(module => (module.commands ?? []).map(command => ({
         pluginId: module.descriptor.id,
@@ -34,12 +38,14 @@ export function createBuiltinPluginRegistry(modules) {
         ...command,
         legacyBare: !!module.descriptor.required
     })));
-    const byRoute = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const allRoutes = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const routed = commands.filter(command => !command.rootOnly);
+    const byRoute = new Map(routed.map(command => [`${command.prefix}:${command.name}`, command]));
     const byName = new Map();
-    for (const command of commands)
+    for (const command of routed)
         byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
     const defaults = new Map(modules.flatMap(module => module.defaultCommand
-        ? [[module.commandPrefix ?? module.descriptor.id, byRoute.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
+        ? [[module.commandPrefix ?? module.descriptor.id, allRoutes.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
         : []));
     const toolModules = modules.map((module, index) => ({ module, index })).filter(({ module }) => module.tools)
         .sort((left, right) => (left.module.toolOrder ?? left.index) - (right.module.toolOrder ?? right.index));

package/dist/sdk/plugins/discover.d.ts

@@ -1,8 +1,9 @@
 /**
  * `context` is an instruction file Pi reads on its own: `AGENTS.md`, `SYSTEM.md` and their kin.
  * `hook` is a package's hooks file, which the harness runs itself; Pi never loads it.
+ * `agent` is a subagent profile a package brings; the harness reads it, Pi never does.
  */
-export type FoundKind = 'extension' | 'skill' | 'prompt' | 'theme' | 'context' | 'hook';
+export type FoundKind = 'extension' | 'skill' | 'prompt' | 'theme' | 'context' | 'hook' | 'agent';
 /** Where a found item comes from. `builtin` is one of the Pi command's own extensions. */
 export type FoundOrigin = 'shared' | 'package' | 'project' | 'home' | 'builtin';
 export interface Found {
@@ -33,6 +34,11 @@ export type Resolver = (input: ResolveInput) => Promise<Found[]>;
 /** The extensions built into the `pi` command. A terminal loads them; an SDK session has none. */
 export declare const PI_BUILTINS: readonly ["llama.cpp", "codemode", "tool-search", "mcp"];
 export declare const BUILTIN_PREFIX = "builtin:";
+/**
+ * The subagent profiles in a package's agents folder: Markdown files whose frontmatter has a
+ * `name` and a `description`. Anything else there (notes, a README) is not a profile.
+ */
+export declare function packageProfiles(root: string, folder: string): string[];
 /**
  * Runs an install with the package manager's install scripts switched off, so fetching a
  * package runs none of its code. A package that builds itself on install then fails to load,