@north-light/api 0.3.507 → 0.3.509

package/dist/api/client.d.ts

@@ -21,7 +21,7 @@ import type { CreateProfileRequest, DeleteProfileRequest, DeleteProfileResultDTO
 import type { FileEncoding, FileListDTO, FilePeekDTO, FileWriteDTO } from './dto/files.js';
 import type { BashRunDTO, BashRunParams } from './dto/bash.js';
 import type { EdgesDTO, EdgesQuery, ObjectListDTO, ObjectListRequest, ObjectReadDTO, ObjectReadQuery, ObjectSearchDTO, ObjectSearchRequest, UnwatchQuery, UnwatchResultDTO, WatchRequest, WatchResultDTO } from './dto/objects.js';
-import type { DocDeletedDTO, DocEditRequest, DocEditedDTO, DocHistoryDTO, DocHistoryQuery, DocLintDTO, DocLintRequest, DocMoveRequest, DocMovedDTO, DocWriteRequest, DocWrittenDTO, ReconcilePackagesDTO } from './dto/docs.js';
+import type { DocDeletedDTO, DocEditRequest, DocEditedDTO, DocHistoryDTO, DocHistoryQuery, DocLintDTO, DocLintRequest, DocMoveRequest, DocMovedDTO, DocWriteRequest, DocWrittenDTO, ReconcilePackagesDTO, DocumentAccessDTO } from './dto/docs.js';
 import type { PluginAppTokenDTO, PluginCallHeadersDTO, PluginCallHeadersRequestDTO } from './dto/plugins.js';
 import type { BackgroundedJobDTO, BackgroundedJobRequest, DeliveryDryRunRequest, DeliveryRequest, DeliveryResponse } from './dto/delivery.js';
 import type { ChatInventoryDTO, ProspectiveChatInventoryDTO, ProspectiveChatInventoryQuery } from './dto/chat-inventory.js';
@@ -299,6 +299,7 @@ export declare class CrtrClient {
     };
     /** Package (builtin and plugin) documents. */
     readonly documents: {
+        browserAccess: () => Promise<DocumentAccessDTO>;
         reconcilePackages: () => Promise<ReconcilePackagesDTO>;
     };
     /** A plugin's `crtr_app_` credential and the headers crtrd adds to its local HTTP calls. */

package/dist/api/client.js

@@ -530,6 +530,7 @@ export class CrtrClient {
     };
     /** Package (builtin and plugin) documents. */
     documents = {
+        browserAccess: () => this.request('GET', routes.documentsBrowserAccess()),
         reconcilePackages: () => this.request('POST', routes.documentsReconcilePackages()),
     };
     /** A plugin's `crtr_app_` credential and the headers crtrd adds to its local HTTP calls. */

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.18";
+export declare const CONTRACT_LEVEL = "1.19";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.18';
+export const CONTRACT_LEVEL = '1.19';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/dto/docs.d.ts

@@ -118,6 +118,10 @@ export interface DocLintFindingDTO {
 export interface DocLintDTO {
     findings: DocLintFindingDTO[];
 }
+/** `GET /v1/documents/browser-access`: the secret that opens the localhost document listener (put in a link as `?t=`). */
+export interface DocumentAccessDTO {
+    secret: string;
+}
 export interface ReconcilePackagesDTO {
     created: number;
     updated: number;

package/dist/api/routes.d.ts

@@ -164,5 +164,6 @@ export declare const routes: {
     readonly docsLint: () => string;
     readonly pluginAppToken: (name: string) => string;
     readonly pluginCallHeaders: (name: string) => string;
+    readonly documentsBrowserAccess: () => string;
     readonly documentsReconcilePackages: () => string;
 };

package/dist/api/routes.js

@@ -197,5 +197,6 @@ export const routes = {
     docsLint: () => `${V}/docs/lint`,
     pluginAppToken: (name) => `${V}/plugins/${encodeURIComponent(name)}/app-token`,
     pluginCallHeaders: (name) => `${V}/plugins/${encodeURIComponent(name)}/call-headers`,
+    documentsBrowserAccess: () => `${V}/documents/browser-access`,
     documentsReconcilePackages: () => `${V}/documents/reconcile-packages`,
 };

package/dist/core/config.js

@@ -2,7 +2,7 @@ import { envProfileId } from '../shared/env.js';
 import { basename, join } from 'node:path';
 import { existsSync, mkdirSync, statSync } from 'node:fs';
 import { isDeepStrictEqual } from 'node:util';
-import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, DOC_LINK_OPEN_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
 import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
 import { notFound } from './errors.js';
 import { emitEvent } from './events/emit.js';
@@ -833,9 +833,8 @@ function mergeConfig(partial) {
     const fold_finished_tools = typeof partial.fold_finished_tools === 'boolean' ? partial.fold_finished_tools : defaults.fold_finished_tools;
     const summarize_tool_calls = typeof partial.summarize_tool_calls === 'boolean' ? partial.summarize_tool_calls : defaults.summarize_tool_calls;
     const detailed_tool_recaps = typeof partial.detailed_tool_recaps === 'boolean' ? partial.detailed_tool_recaps : defaults.detailed_tool_recaps;
-    const doc_link_open = DOC_LINK_OPEN_MODES.includes(partial.doc_link_open)
-        ? partial.doc_link_open
-        : defaults.doc_link_open;
+    const document_port = Number.isInteger(partial.document_port) && partial.document_port >= 1 && partial.document_port <= 65535
+        ? partial.document_port : defaults.document_port;
     const consolidate_replies = typeof partial.consolidate_replies === 'boolean' ? partial.consolidate_replies : defaults.consolidate_replies;
     const keybindings = normalizeKeybindings(partial.keybindings);
     const tmux_passthrough = normalizeTmuxPassthrough(partial.tmux_passthrough);
@@ -860,7 +859,7 @@ function mergeConfig(partial) {
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
     const humanActions = normalizeHumanActions(partial.humanActions);
-    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, doc_link_open, consolidate_replies, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, api, ...(paths ? { paths } : {}), ...(store ? { store } : {}), ...(runtime ? { runtime } : {}), spawnEnv };
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, document_port, consolidate_replies, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, api, ...(paths ? { paths } : {}), ...(store ? { store } : {}), ...(runtime ? { runtime } : {}), spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/user-settings.d.ts

@@ -275,19 +275,19 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
             setFromString: (config: ScopeConfig, raw: string) => string | null;
         };
     };
-    doc_link_open: {
+    document_port: {
         surface: "settings";
         setting: {
-            key: "doc_link_open";
+            key: "document_port";
             label: string;
             description: string;
             valueConstraint: string;
             applies: string;
             group: "display";
             order: number;
-            format: (config: ScopeConfig) => "browser" | "nvim";
+            format: (config: ScopeConfig) => string;
             cycle: (config: ScopeConfig, delta: number) => void;
-            setFromString: (config: ScopeConfig, raw: string) => string | null;
+            setFromString: (config: ScopeConfig, raw: string) => "document_port must be an integer from 1 to 65535" | null;
         };
     };
     detailed_tool_recaps: {

package/dist/core/user-settings.js

@@ -1,4 +1,4 @@
-import { CONDENSED_HISTORY_MODES, DOC_LINK_OPEN_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES } from '../types.js';
+import { CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES } from '../types.js';
 function cycleChoice(choices, current, delta) {
     const index = choices.indexOf(current);
     const start = index >= 0 ? index : 0;
@@ -370,22 +370,23 @@ export const CONFIG_SETTINGS_COVERAGE = {
             },
         },
     },
-    doc_link_open: {
+    document_port: {
         surface: 'settings',
         setting: {
-            key: 'doc_link_open',
-            label: 'Document links open in',
-            description: 'Where clicking a [[document]] link in a viewer opens it: a read-only browser page with a rendered/raw toggle, or Neovim to edit it and save a new revision (needs iTerm Semantic History).',
-            valueConstraint: DOC_LINK_OPEN_MODES.join('|'),
-            applies: 'Applies on the next attach.',
+            key: 'document_port',
+            label: 'Document browser port',
+            description: 'Fixed localhost port where crtrd serves editable document pages.',
+            valueConstraint: '1-65535',
+            applies: 'Applies after daemon handover and on the next attach.',
             group: 'display',
             order: 37.5,
-            format: (config) => config.doc_link_open,
-            cycle: (config, delta) => { config.doc_link_open = cycleChoice(DOC_LINK_OPEN_MODES, config.doc_link_open, delta); },
+            format: (config) => String(config.document_port),
+            cycle: (config, delta) => { config.document_port = Math.max(1, Math.min(65535, config.document_port + delta)); },
             setFromString: (config, raw) => {
-                if (!DOC_LINK_OPEN_MODES.includes(raw))
-                    return `doc_link_open must be one of: ${DOC_LINK_OPEN_MODES.join('|')}`;
-                config.doc_link_open = raw;
+                const port = Number(raw);
+                if (!/^\d+$/.test(raw) || !Number.isInteger(port) || port < 1 || port > 65535)
+                    return 'document_port must be an integer from 1 to 65535';
+                config.document_port = port;
                 return null;
             },
         },

package/dist/types.d.ts

@@ -361,12 +361,8 @@ export interface ScopeConfig {
     /** Show individual document reads and edited files in a folded tool recap.
      * Off shows the compact activity-count line instead. Default true. */
     detailed_tool_recaps: boolean;
-    /** Where a `[[owner/name]]` document link in the attach viewer opens.
-     *  `browser` (default) points the link at a self-contained HTML page with a
-     *  rendered/raw toggle, which any OSC-8-capable terminal opens without setup;
-     *  `nvim` keeps the editable Markdown copy opened through iTerm Semantic
-     *  History, with save-back as a new revision. */
-    doc_link_open: DocLinkOpenMode;
+    /** Port of the localhost-only document browser listener. */
+    document_port: number;
     /** Experiment: show one consolidated agent reply per message the person typed.
      *  The broker rewrites a turn's prose messages into one reply with a light
      *  model; the attach viewer folds the rest of the turn behind a working row
@@ -578,9 +574,6 @@ export declare const DEFAULT_WHIP_MESSAGE_MODE: WhipMessageMode;
 export declare const DEFAULT_LIVE_CYCLES = 2;
 export declare const MOUSE_MODE_DEFAULTS: readonly ["tmux", "on", "off"];
 export type MouseModeDefault = (typeof MOUSE_MODE_DEFAULTS)[number];
-/** Where an attach-viewer document link opens (see `doc_link_open`). */
-export declare const DOC_LINK_OPEN_MODES: readonly ["browser", "nvim"];
-export type DocLinkOpenMode = (typeof DOC_LINK_OPEN_MODES)[number];
 /** Messages kept from a condensed cycle (see `condensed_history`). */
 export declare const CONDENSED_HISTORY_MODES: readonly ["none", "user", "agent", "both"];
 export type CondensedHistoryMode = (typeof CONDENSED_HISTORY_MODES)[number];

package/dist/types.js

@@ -66,8 +66,6 @@ export const WHIP_MESSAGE_MODES = ['random', 'go-faster'];
 export const DEFAULT_WHIP_MESSAGE_MODE = 'random';
 export const DEFAULT_LIVE_CYCLES = 2;
 export const MOUSE_MODE_DEFAULTS = ['tmux', 'on', 'off'];
-/** Where an attach-viewer document link opens (see `doc_link_open`). */
-export const DOC_LINK_OPEN_MODES = ['browser', 'nvim'];
 /** Messages kept from a condensed cycle (see `condensed_history`). */
 export const CONDENSED_HISTORY_MODES = ['none', 'user', 'agent', 'both'];
 export const DEFAULT_CONDENSED_HISTORY = 'none';
@@ -102,7 +100,7 @@ export function defaultScopeConfig() {
         fold_finished_tools: true,
         summarize_tool_calls: true,
         detailed_tool_recaps: true,
-        doc_link_open: 'browser',
+        document_port: 7472,
         consolidate_replies: false,
         keybindings: {},
         tmux_passthrough: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.507",
+  "version": "0.3.509",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",