@north-light/crouter 0.3.184 → 0.3.185

package/dist/core/command-plugins/discovery.js

@@ -3,7 +3,7 @@ import { resolve, sep } from 'node:path';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
 import { projectScopeRoots } from '../scope.js';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
-import { resolveCommandRegistry } from '../command-manifests/registry.js';
+import { qualifiedTopLevelCommandName, resolveCommandRegistry } from '../command-manifests/registry.js';
 import { adaptPluginContributions } from './compose.js';
 import { validateHttpPluginTransport } from './endpoint.js';
 export function effectiveCommandPlugins(startDir = process.cwd(), profileId) {
@@ -139,18 +139,26 @@ export function validateEffectiveCommandPlugins(reservedNames, startDir = proces
     const validations = effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin, reservedNames, coreCommandPaths));
     const claims = new Map();
     for (const validation of validations)
-        for (const contribution of validation.contributions)
-            (claims.get(contribution.node.name) ?? (claims.set(contribution.node.name, []), claims.get(contribution.node.name))).push(validation);
+        for (const contribution of validation.contributions) {
+            const claimants = claims.get(contribution.node.name);
+            if (claimants === undefined)
+                claims.set(contribution.node.name, [contribution]);
+            else
+                claimants.push(contribution);
+        }
     for (const [name, claimants] of claims)
         if (claimants.length > 1)
-            for (const validation of claimants) {
-                validation.contributions = validation.contributions.filter((contribution) => contribution.node.name !== name);
-                validation.issues.push({ code: 'command_collision', plugin: validation.plugin.name, path: name, message: `top-level command "${name}" is claimed by multiple plugins`, received: claimants.map((claimant) => claimant.plugin.name).join(', '), expected: 'exactly one plugin per top-level command name', next: 'Disable or remove all but one claimant.' });
+            for (const claimant of claimants) {
+                const { plugin } = claimant;
+                const qualifiedName = qualifiedTopLevelCommandName({ name: plugin.name, sourceMarketplace: plugin.sourceMarketplace }, name);
+                const validation = validations.find((candidate) => candidate.plugin.root === plugin.root);
+                validation.contributions = validation.contributions.map((contribution) => contribution === claimant ? { ...contribution, node: { ...contribution.node, name: qualifiedName } } : contribution);
+                validation.issues.push({ code: 'command_collision', plugin: plugin.name, path: name, message: `top-level command "${name}" is claimed by ${claimants.map((entry) => entry.plugin.name).join(', ')} — mounted as "${qualifiedName}"`, received: claimants.map((entry) => entry.plugin.name).join(', '), expected: 'an origin-qualified top-level command for each claimant', next: `Invoke "${qualifiedName}" to use this plugin command.` });
             }
     return validations;
 }
 function contributorIssue(plugin, issue) {
-    return { ...issue, contributor: { name: plugin.name, scope: plugin.scope } };
+    return { ...issue, contributor: { name: plugin.name, scope: plugin.scope, sourceMarketplace: plugin.sourceMarketplace } };
 }
 export function discoverCommandContributions(reservedNames, startDir = process.cwd(), profileId) {
     const validations = validateEffectiveCommandPlugins(reservedNames, startDir, profileId);

package/dist/core/keybindings/catalog.d.ts

@@ -1,6 +1,6 @@
 import type { BindingDefinition, SafetyRequirement } from './types.js';
 import type { AttachBindingId, AttachMenuBindingId } from './attach-control.js';
-type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'fold-tools' | 'metadata' | 'promote' | 'resume' | 'fork' | 'demote' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'providers' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
+type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'fold-tools' | 'metadata' | 'promote' | 'resume' | 'fork' | 'demote' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'providers' | 'plugins' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
 type TmuxMenuEntryAction = Exclude<TmuxMenuAction, 'open' | 'attach'> | `issue.${'idea' | 'bug'}`;
 type GraphAction = 'down' | 'up' | 'first' | 'last' | 'collapse-or-manager' | 'expand-or-child' | 'focus' | 'revive' | 'focus-manager' | 'close-subtree' | 'dismiss';
 type BrowseAction = 'quit' | 'down' | 'up' | 'first' | 'last' | 'expand-or-child' | 'collapse-or-parent' | 'toggle-fold' | 'tab-next' | 'tab-previous' | `tab.${1 | 2 | 3 | 4 | 5}` | 'close-subtree' | 'confirm-close' | 'sort' | 'scope' | 'profile' | 'residents' | 'preview' | 'search' | 'revive-now' | 'focus' | 'focus-background';

package/dist/core/keybindings/catalog.js

@@ -53,6 +53,7 @@ export const BINDING_CATALOG = Object.freeze([
     ...menuEntry('metadata', 'Show metadata', 'Show the focused node’s metadata dossier.', ['m'], ['tmux.menu.show']),
     ...menuEntry('context', 'Browse context', 'Browse the focused node context.', ['c'], ['tmux.menu.show']),
     ...menuEntry('providers', 'Open settings', 'Open the crouter settings panel.', [','], ['tmux.menu']),
+    ...menuEntry('plugins', 'Browse plugins', 'Open the crouter plugin browser.', ['k'], ['tmux.menu']),
     ...menuEntry('graph', 'Canvas graph', 'Open the canvas graph.', ['g'], ['tmux.menu']),
     ...menuEntry('focus-manager', 'Go to manager', 'Focus this node’s manager.', ['h'], ['tmux.menu']),
     ...menuEntry('copy-id', 'Copy node id', 'Copy the focused node id to the system clipboard.', ['y'], ['tmux.menu']),

package/dist/core/resolver.d.ts

@@ -8,7 +8,7 @@ export interface ParsedSkillQualifier {
     segments: string[];
 }
 export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
-export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
+export declare function listInstalledMarketplaces(scope: Exclude<Scope, 'builtin'>): InstalledMarketplace[];
 export declare function listAllMarketplaces(): InstalledMarketplace[];
-export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;
+export declare function findMarketplaceByName(name: string, scope?: Exclude<Scope, 'builtin'>): InstalledMarketplace | null;
 export declare function scopeRootsLabel(): string;

package/dist/core/runtime/tmux-bindings.js

@@ -33,6 +33,7 @@ const LEAF_MENU_ACTIONS = {
     // The settings page lays out a grouped rail beside a content panel; the
     // default dialog-sized popup clipped both the rail and the models matrix.
     'crtr.tmux.menu.providers': { description: 'settings', action: { kind: 'popup', run: 'sys settings', size: { w: '90%', h: '85%' } } },
+    'crtr.tmux.menu.plugins': { description: 'plugins', action: { kind: 'popup', run: 'pkg browse', size: { w: '90%', h: '85%' } } },
     'crtr.tmux.menu.graph': { description: 'canvas graph', action: { kind: 'keys', keys: '/graph' } },
     'crtr.tmux.menu.focus-manager': { description: 'go to manager', action: { kind: 'command', run: 'surface node focus {manager}' } },
     'crtr.tmux.menu.copy-id': { description: 'copy node id', action: { kind: 'command', run: 'surface node id --pane {pane}' } },
@@ -301,6 +302,7 @@ function menuItems(bindings, entries) {
     ]));
     addGroup('System', boundItems([
         'crtr.tmux.menu.providers',
+        'crtr.tmux.menu.plugins',
         'crtr.tmux.menu.issues',
     ]));
     const prefixGestures = bindings.gestures('crtr.tmux.menu.open');

package/dist/core/tui/page-host.d.ts

@@ -0,0 +1,25 @@
+import { ProcessTerminal, TUI, type Component, type Focusable } from "@earendil-works/pi-tui";
+import { readRawScopeConfig } from "../config.js";
+import { type BindingId, type BindingResolution } from "../keybindings/index.js";
+/** A full-screen page: a focusable TUI component that cleans up after itself. */
+export type TuiPageSurface = Component & Focusable & {
+    dispose(): void;
+};
+export interface TuiPageContext {
+    tui: TUI;
+    terminal: ProcessTerminal;
+    bindings: BindingResolution<BindingId>;
+    rawUserConfig: ReturnType<typeof readRawScopeConfig>;
+}
+export interface TuiPageControl<Result> {
+    /** Close the page with a result. */
+    submit(result: Result): void;
+    /** Close the page with no result. */
+    cancel(): void;
+}
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export declare function runTuiPage<Result>(createSurface: (context: TuiPageContext, control: TuiPageControl<Result>) => TuiPageSurface, interceptCancel?: (data: string, bindings: BindingResolution<BindingId>) => boolean): Promise<Result | undefined>;

package/dist/core/tui/page-host.js

@@ -0,0 +1,65 @@
+// The process-level terminal host for crouter's full-screen TUI pages —
+// `crtr sys settings`, the setup wizard, and `crtr pkg browse`.
+//
+// It owns exactly the concerns every page shares: theme, resolved keybindings,
+// the raw user config those pages edit, the ProcessTerminal/TUI pair, and a
+// restore path that survives an exception, a signal, and process exit. Anything
+// a single page needs beyond that — pi's model runtime, a canvas client — the
+// page's own runner builds and closes over before calling in here.
+import { ProcessTerminal, TUI, } from "@earendil-works/pi-tui";
+import { applyTheme } from "../../clients/attach/config.js";
+import { readRawScopeConfig } from "../config.js";
+import { resolveKeybindings, } from "../keybindings/index.js";
+/** Mount one page as the TUI's only child and resolve when it closes.
+ *
+ *  `interceptCancel` is a process-level escape hatch for surfaces that must be
+ *  abandonable while a nested component holds the keyboard; it runs before the
+ *  page sees the input and closes the page when it returns true. */
+export async function runTuiPage(createSurface, interceptCancel) {
+    applyTheme({ cwd: process.cwd() });
+    const rawUserConfig = readRawScopeConfig("user");
+    const bindings = resolveKeybindings(rawUserConfig?.keybindings);
+    const terminal = new ProcessTerminal();
+    const tui = new TUI(terminal, true);
+    return new Promise((resolve, reject) => {
+        let surface;
+        let restored = false;
+        const restore = () => {
+            if (restored)
+                return;
+            restored = true;
+            surface?.dispose();
+            try {
+                tui.stop();
+            }
+            catch {
+                /* terminal restore */
+            }
+        };
+        const finish = (result) => {
+            restore();
+            resolve(result);
+        };
+        try {
+            surface = createSurface({ tui, terminal, bindings, rawUserConfig }, { submit: finish, cancel: () => finish(undefined) });
+            tui.addChild(surface);
+            tui.setFocus(surface);
+            process.once("exit", restore);
+            for (const signal of ["SIGTERM", "SIGHUP", "SIGINT"])
+                process.once(signal, () => finish(undefined));
+            if (interceptCancel !== undefined) {
+                tui.addInputListener((data) => {
+                    if (!interceptCancel(data, bindings))
+                        return undefined;
+                    finish(undefined);
+                    return { consume: true };
+                });
+            }
+            tui.start();
+        }
+        catch (error) {
+            restore();
+            reject(error);
+        }
+    });
+}

package/dist/pi-extensions/canvas-bash-valve.js

@@ -28,6 +28,7 @@ import { spawn } from 'node:child_process';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { backgroundBashJob, bashJobPaths, formatBashElapsed, newBashJobId } from '../core/bash-jobs.js';
+import { Type } from 'typebox';
 import { createBashToolDefinition } from '@earendil-works/pi-coding-agent';
 // ---------------------------------------------------------------------------
 // Deadline — 5 minutes by default, overridable via CRTR_BASH_VALVE_MS
@@ -342,6 +343,49 @@ export function createValveOperations(nodeId, contextDir) {
 // ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// `purpose` — the one line a person reads while a command runs
+//
+// A deliberate deviation from taking pi's definition verbatim, and the only one
+// here. Everywhere crtr's output reaches a non-technical audience, the host has
+// to render SOMETHING per step, and without this field its only material is the
+// command — which yields "Running command" for an entire turn. The model is the
+// only party that knows why it is running this, so it says so, in one clause,
+// before the command streams.
+//
+// Declared FIRST so it arrives ahead of `command` in the argument stream: a host
+// parsing partial JSON can show the label while the command is still being
+// written, rather than after the call is complete and about to finish.
+//
+// The execute path ignores it entirely — this is a labelling channel, not an
+// input. Optional, so a model that omits it behaves exactly as before.
+//
+// Upstream ask: pi's own bash tool should carry this (Claude Code's bash tool
+// has shipped an equivalent `description` field for years). Until it does, the
+// field is re-declared here on top of pi's schema rather than forked into it.
+// ---------------------------------------------------------------------------
+const PURPOSE_DESCRIPTION = [
+    'One short clause naming what this step is FOR, in the words of the person you',
+    'are working for — "Reading the Acme thread", not "Fetching emails" and never',
+    '"Running GMAIL_FETCH_EMAILS". A person reads this while the command runs; it',
+    'is the only thing they see of this step. Under about eight words. Omit it for',
+    'steps that only touch your own scratch work.',
+].join(' ');
+/**
+ * Prepend an optional `purpose` to pi's bash schema, carrying pi's own property
+ * definitions through verbatim — so a future upstream change to the `command`
+ * or `timeout` wording still reaches the model, and this file owns exactly one
+ * field.
+ */
+function withPurpose(definition) {
+    return {
+        ...definition,
+        parameters: Type.Object({
+            purpose: Type.Optional(Type.String({ description: PURPOSE_DESCRIPTION })),
+            ...definition.parameters.properties,
+        }),
+    };
+}
 export default function (pi) {
     const nodeId = process.env['CRTR_NODE_ID'];
     if (nodeId === undefined || nodeId.trim() === '')
@@ -356,6 +400,6 @@ export default function (pi) {
     // every session_start is idempotent (last registration wins).
     pi.on('session_start', (_event, ctx) => {
         const operations = createValveOperations(nodeId, contextDir);
-        pi.registerTool(createBashToolDefinition(ctx.cwd, { operations }));
+        pi.registerTool(withPurpose(createBashToolDefinition(ctx.cwd, { operations })));
     });
 }

package/dist/types.d.ts

@@ -301,7 +301,10 @@ export interface InstalledPlugin {
 }
 export interface InstalledMarketplace {
     name: string;
-    scope: Scope;
+    /** Never `builtin`: marketplaces are registered by the user into the user or
+     *  project scope, and `listInstalledMarketplaces` has no builtin directory to
+     *  read. `builtin` describes plugins that ship with crtr, not their source. */
+    scope: Exclude<Scope, 'builtin'>;
     root: string;
     manifest: MarketplaceManifest;
     url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.184",
+  "version": "0.3.185",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.184",
+  "version": "0.3.185",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.184",
+      "version": "0.3.185",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {