@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/focus-viewer.js

@@ -0,0 +1,151 @@
+// focus-viewer.ts — bring one node's viewer into view, shared by the CLI and
+// the attach viewer.
+//
+// `crtr surface node focus` and the viewer's own navigation (graph overlay
+// Enter/m, the review-companion roster row, surface-host focus) all run this
+// one implementation. The viewer calls it in-process instead of shelling a
+// `crtr` subprocess, which saved a full cold CLI boot before the new pane
+// started its own. Everything here is pure tmux plus one crtrd round-trip
+// through the caller's `CrtrClient` (`ensureAttach`): no canvas-db read and no
+// engine launch — the server owns revive and the parked-resident decision.
+//
+// Callers own authorization: the viewer only reaches these for a local
+// controller attach, exactly as it previously gated the shelled command.
+import { envHomeOverride } from '../../shared/env.js';
+import { isFinishedWork, isLiveStatus } from '../canvas/node-order.js';
+import { InputError } from '../io.js';
+import { closePane, currentTmux, displayPopupAsync, getPaneOption, listLivePanes, paneExists, paneLocation, renameWindow, respawnPaneSync, selectLayout, selectPane, selectWindow, setPaneOption, shellQuote, splitWindow, switchClient, windowOfPane, } from './placement-tmux.js';
+export function viewerEnv() {
+    const crtrHome = envHomeOverride();
+    return crtrHome !== undefined ? { CRTR_HOME: crtrHome } : {};
+}
+/** Internal startup policy for viewers opened by focus/navigation. Direct
+ * `surface attach` has no marker and keeps its activating default. */
+function focusViewerEnv() {
+    return { ...viewerEnv(), CRTR_ATTACH_WAKE_PARKED: '0' };
+}
+/** The live viewer pane for `nodeId` (the pane a surface-attach viewer tagged
+ *  `@crtr_node`), or undefined. Pure tag scan over live panes. */
+export function viewerPaneOf(nodeId) {
+    const panes = listLivePanes();
+    if (panes === null)
+        return undefined;
+    for (const pane of panes) {
+        if (getPaneOption(pane, '@crtr_node') === nodeId)
+            return pane;
+    }
+    return undefined;
+}
+/** Open a fresh surface-attach viewer SPLIT beside `callerPane` and rebalance
+ *  its window to even side-by-side widths. Pure tmux. */
+function openBesideCaller(callerPane, nodeId, cwd, callerSession, revived) {
+    const opened = splitWindow(callerPane, { cwd, env: focusViewerEnv(), command: `crtr surface attach to ${nodeId}` });
+    if (opened === null)
+        return { focused: false, session: null, inPlace: false, revived };
+    const loc = paneLocation(opened);
+    if (loc !== null)
+        selectLayout(loc.window, 'even-horizontal');
+    selectPane(opened);
+    return { focused: true, session: loc?.session ?? callerSession, inPlace: false, revived };
+}
+/** Bring a node's ONE viewer forefront beside (or navigated to) the caller.
+ *  The server (`ensureAttach`) owns the broker revive + the view.sock
+ *  accept-wait; the `@crtr_node` pane tag is the viewer registry. crtr is
+ *  tmux-only: no caller pane ⇒ not focused. */
+export async function focusViewer(client, nodeId, opts) {
+    const callerPane = opts.pane ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+    if (callerPane === undefined || callerPane === '') {
+        return { focused: false, session: null, inPlace: false, revived: false };
+    }
+    // (a) Server ensures a live broker is attachable, but leaves an exact parked
+    // resident untouched. This policy is unconditional so an active→parked race
+    // is decided at the daemon's synchronous fleet/launch boundary.
+    const attach = await client.ensureAttach(nodeId, { resume: true, revive: true, wakeParked: false });
+    const revived = attach.revived;
+    const callerSession = paneLocation(callerPane)?.session ?? null;
+    // (b0) --in-place → the caller pane BECOMES this node's viewer, replacing what
+    //      it showed. Must be driven from OUTSIDE that pane's process tree.
+    if (opts.inPlace === true) {
+        const priorNodeId = getPaneOption(callerPane, '@crtr_node');
+        const existing = viewerPaneOf(nodeId);
+        if (opts.keepOtherViewers !== true && existing !== undefined && existing !== callerPane && paneExists(existing))
+            closePane(existing);
+        try {
+            setPaneOption(callerPane, '@crtr_node', '');
+        }
+        catch { /* best-effort */ }
+        const window = windowOfPane(callerPane);
+        const env = {
+            ...focusViewerEnv(),
+            ...(priorNodeId !== undefined && priorNodeId !== '' ? { CRTR_ATTACH_ROSTER: priorNodeId } : {}),
+            ...(opts.openTicket !== undefined ? { CRTR_ATTACH_OPEN_TICKET: opts.openTicket } : {}),
+        };
+        const ok = respawnPaneSync({ pane: callerPane, cwd: opts.cwd, env, command: `crtr surface attach to ${nodeId}` });
+        if (ok && window !== null)
+            renameWindow(window, opts.name);
+        return { focused: ok, session: callerSession, inPlace: true, revived };
+    }
+    // (b) --new-pane → always a fresh viewer beside the caller; drop any prior
+    //     viewer this node holds elsewhere (one viewer per node).
+    if (opts.newPane === true) {
+        const prior = viewerPaneOf(nodeId);
+        if (prior !== undefined && paneExists(prior))
+            closePane(prior);
+        return openBesideCaller(callerPane, nodeId, opts.cwd, callerSession, revived);
+    }
+    // (c) Reuse the node's existing tagged viewer wherever it already lives.
+    const existing = viewerPaneOf(nodeId);
+    if (existing !== undefined) {
+        const loc = paneLocation(existing);
+        if (loc !== null) {
+            switchClient(loc.session);
+            selectWindow(loc.session, loc.window);
+            selectPane(existing);
+            return { focused: true, session: loc.session, inPlace: true, revived };
+        }
+    }
+    // (d) No live viewer → open one beside the caller.
+    return openBesideCaller(callerPane, nodeId, opts.cwd, callerSession, revived);
+}
+/** The whole `surface node focus` decision for one fetched node, placed into
+ *  `pane`: refuse a human-ask, open FINISHED work as a read-only saved
+ *  transcript popup, otherwise bring its conversation viewer into view.
+ *  Throws `InputError` for a human-ask; daemon failures propagate as `ApiError`. */
+export async function focusNode(client, node, opts) {
+    const id = node.node_id;
+    // A kind:'human' node is a control-plane ASK (a page on the human's
+    // screen), NOT a pi conversation — it has no session. Reviving one boots a
+    // confused blank "you have been revived" pi, so refuse rather than focus it.
+    // (The nav/resume UIs already hide human nodes; this guards a hand-typed id.)
+    if (node.kind === 'human') {
+        throw new InputError({
+            error: 'not_focusable',
+            message: `node ${id} is a human-ask (kind:human), not a conversation — it has no pi session to focus.`,
+            next: `The pending question is queued for the user; see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
+        });
+    }
+    // Opening history is not resuming work — but a non-live STATUS does not by
+    // itself mean the node finished anything. Finished work (a terminal worker, or
+    // any node that pushed a final report) is archive: show its persisted
+    // transcript, because reviving it would set completed work back in motion, and
+    // `node lifecycle revive` remains the explicit way to do that on purpose.
+    // A RESIDENT node with no final report never finished — its parked `done`
+    // falls through to the conversation path, where focus can seat its saved
+    // snapshot without launching an engine.
+    if (!isLiveStatus(node.status) && isFinishedWork({ lifecycle: node.lifecycle, finalized: node.final_report != null })) {
+        const focused = await displayPopupAsync(opts.pane, node.cwd, `crtr node inspect transcript ${shellQuote(id)}`);
+        return { focused, session: null, revived: false, inPlace: false };
+    }
+    // Local viewer tail: open/move the normal conversation viewer beside the
+    // caller. The server owns the serialized live-vs-parked decision; pure tmux
+    // operations own pane placement.
+    return focusViewer(client, id, {
+        cwd: node.cwd,
+        name: node.name,
+        pane: opts.pane,
+        ...(opts.newPane === true ? { newPane: true } : {}),
+        ...(opts.inPlace === true ? { inPlace: true } : {}),
+        ...(opts.keepOtherViewers === true ? { keepOtherViewers: true } : {}),
+        ...(opts.openTicket !== undefined ? { openTicket: opts.openTicket } : {}),
+    });
+}

package/dist/core/runtime/front-door-env.d.ts

@@ -0,0 +1,5 @@
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export declare const FRONT_DOOR_ENV = "CRTR_FRONT_DOOR";

package/dist/core/runtime/front-door-env.js

@@ -0,0 +1,16 @@
+// The front-door recursion-guard env name, alone in a dependency-free module.
+//
+// `front-door.ts` owns the boot path and reaches the canvas through the
+// dynamic imports inside `maybeBootRoot`; every module that only needs the
+// MARKER NAME must not inherit that reach. The shipped broker extensions are
+// gated on their static import graph, which cannot tell a lazily-imported boot
+// dependency from an eagerly-loaded one, so importing the constant from
+// `front-door.js` reads as an extension reaching canvas.db.
+//
+// `front-door.ts` re-exports this, so `FRONT_DOOR_ENV` stays importable from
+// either module and every pi-booting path keeps setting the same marker.
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export const FRONT_DOOR_ENV = 'CRTR_FRONT_DOOR';

package/dist/core/runtime/headless-pi.d.ts

@@ -0,0 +1,37 @@
+import { type ConstrainedSamplingConfig } from '@earendil-works/pi-ai';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { TSchema } from 'typebox';
+export interface HeadlessTool {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TSchema;
+    constrainedSampling?: false | ConstrainedSamplingConfig;
+}
+export interface HeadlessRequest {
+    systemPrompt: string;
+    userPrompt: string;
+    modelSpec: string;
+    /** Logical `family/strength` intent. Omit for a concrete model request. */
+    modelIntent?: string;
+    timeoutMs: number;
+    tool?: HeadlessTool;
+    /** Exact context to seed into an isolated in-memory session. */
+    seedMessages?: readonly AgentMessage[];
+    /** Reuses a provider cache identity without binding or persisting a session. */
+    sessionId?: string;
+    /** Omit `noTools` to load Pi's builtin tool suite. */
+    toolPolicy?: 'builtin';
+}
+/** Run a one-shot call whose only output channel is one structured tool call. */
+export declare function headlessToolCall(request: HeadlessRequest & {
+    tool: HeadlessTool;
+}): Promise<unknown>;
+/** Run a one-shot call and return the final assistant text. */
+export declare function headlessText(request: HeadlessRequest): Promise<string>;
+/** Run a tool-capable, extension-free in-memory turn against seeded context. */
+export declare function headlessTurn(request: HeadlessRequest & {
+    seedMessages: readonly AgentMessage[];
+    sessionId: string;
+    toolPolicy: 'builtin';
+}): Promise<'completed' | 'failed'>;

package/dist/core/runtime/headless-pi.js

@@ -0,0 +1,173 @@
+// Isolated in-process Pi one-shots for lightweight model work.
+//
+// Each call runs inside a broker (a node token is required; without one the call returns its fallback), over
+// the daemon's `llm`, with an in-memory session. No conversation resources or canvas lifecycle hooks enter
+// the helper session.
+import { envModelIntent, envNodeCwd, envProfileId } from '../../shared/env.js';
+import { join } from 'node:path';
+import { InMemoryCredentialStore } from '@earendil-works/pi-ai';
+import { APP_FAMILY, expandModelCandidates, modelRequestFromConfig } from '../model-routes.js';
+import { defaultModelLaddersConfig } from '../../types.js';
+import { stripThinkingSuffix } from './model-selection.js';
+import { configureBrokerModelRuntime } from './broker/model-adapter.js';
+import { currentNodeToken } from './broker/node-token.js';
+function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message?.role !== 'assistant')
+            continue;
+        if (typeof message.content === 'string')
+            return message.content.trim();
+        if (!Array.isArray(message.content))
+            continue;
+        const text = message.content
+            .map((part) => {
+            const value = part;
+            return value.type === 'text' && typeof value.text === 'string' ? value.text : '';
+        })
+            .join('')
+            .trim();
+        if (text !== '')
+            return text;
+    }
+    return '';
+}
+/** What an app-paid node's one-shot asks for: never an owner-ladder model (the owner may have no vendor). A one-shot
+ *  takes the app's `light` rung; a turn that continues the node's own session (`ownModel`) keeps the node's rung. The
+ *  rung's catalog model only labels the request; the daemon's `llm` picks the rung from the intent. */
+function appPaidRequest(request, ownModel) {
+    const nodeIntent = envModelIntent();
+    if (nodeIntent === undefined || !nodeIntent.startsWith(`${APP_FAMILY}/`))
+        return undefined;
+    if (ownModel)
+        return { modelRequest: modelRequestFromConfig(request.modelSpec, nodeIntent, false), intent: nodeIntent };
+    return {
+        modelRequest: { kind: 'logical', family: APP_FAMILY, strength: 'light', spec: stripThinkingSuffix(defaultModelLaddersConfig().anthropic.light) },
+        intent: `${APP_FAMILY}/light`,
+    };
+}
+async function runHeadless(request, fallback, ownModel, collect) {
+    let session;
+    let disposed = false;
+    let timedOut = false;
+    let timeout;
+    const disposeSession = (abort) => {
+        if (session === undefined || disposed)
+            return;
+        disposed = true;
+        if (abort)
+            void session.abort().catch(() => undefined);
+        session.dispose();
+    };
+    const deadline = new Promise((resolve) => {
+        timeout = setTimeout(() => {
+            timedOut = true;
+            disposeSession(true);
+            resolve(fallback);
+        }, request.timeoutMs);
+    });
+    const run = (async () => {
+        try {
+            const sdk = await import('@earendil-works/pi-coding-agent');
+            if (currentNodeToken() === undefined)
+                return fallback;
+            if (timedOut)
+                return fallback;
+            const nodeCwd = envNodeCwd() ?? process.cwd();
+            const profileId = envProfileId();
+            const agentDir = sdk.getAgentDir();
+            const modelRuntime = await sdk.ModelRuntime.create({
+                credentials: new InMemoryCredentialStore(),
+                modelsPath: join(agentDir, 'models.json'),
+            });
+            const appPaid = appPaidRequest(request, ownModel);
+            configureBrokerModelRuntime(modelRuntime, appPaid?.intent);
+            if (timedOut)
+                return fallback;
+            const services = await sdk.createAgentSessionServices({
+                cwd: nodeCwd,
+                agentDir,
+                modelRuntime,
+                settingsManager: sdk.SettingsManager.inMemory(),
+                resourceLoaderOptions: {
+                    noExtensions: true,
+                    noContextFiles: true,
+                    noSkills: true,
+                    noPromptTemplates: true,
+                    noThemes: true,
+                    systemPrompt: request.systemPrompt,
+                },
+            });
+            if (timedOut)
+                return fallback;
+            const modelRequest = appPaid?.modelRequest ?? modelRequestFromConfig(request.modelSpec, request.modelIntent, false);
+            if (modelRequest === undefined)
+                return fallback;
+            const registry = new sdk.ModelRegistry(services.modelRuntime);
+            const selected = (await expandModelCandidates(modelRequest, nodeCwd, profileId)).map((candidate) => registry.find(candidate.providerId, candidate.modelId)).find((model) => model !== undefined);
+            if (selected === undefined)
+                return fallback;
+            let captured;
+            const tool = request.tool;
+            const customTool = tool === undefined ? undefined : sdk.defineTool({
+                name: tool.name,
+                label: tool.label,
+                description: tool.description,
+                parameters: tool.parameters,
+                ...(tool.constrainedSampling === undefined ? {} : { constrainedSampling: tool.constrainedSampling }),
+                async execute(_toolCallId, params) {
+                    captured = params;
+                    return {
+                        content: [{ type: 'text', text: 'Recorded.' }],
+                        details: { recorded: true },
+                        terminate: true,
+                    };
+                },
+            });
+            const sessionManager = sdk.SessionManager.inMemory(nodeCwd, request.sessionId === undefined ? undefined : { id: request.sessionId });
+            for (const message of request.seedMessages ?? []) {
+                sessionManager.appendMessage(message);
+            }
+            ({ session } = await sdk.createAgentSessionFromServices({
+                services,
+                sessionManager,
+                model: selected,
+                thinkingLevel: 'off',
+                ...(tool === undefined
+                    ? request.toolPolicy === 'builtin' ? {} : { noTools: 'all' }
+                    : { tools: [tool.name], customTools: [customTool] }),
+            }));
+            if (timedOut)
+                return fallback;
+            await session.bindExtensions({});
+            if (timedOut)
+                return fallback;
+            await session.prompt(request.userPrompt);
+            return timedOut ? fallback : collect(session, captured);
+        }
+        catch {
+            return fallback;
+        }
+        finally {
+            disposeSession(false);
+        }
+    })();
+    try {
+        return await Promise.race([run, deadline]);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/** Run a one-shot call whose only output channel is one structured tool call. */
+export function headlessToolCall(request) {
+    return runHeadless(request, null, false, (_session, captured) => captured);
+}
+/** Run a one-shot call and return the final assistant text. */
+export function headlessText(request) {
+    return runHeadless(request, '', false, (session) => lastAssistantText(session.messages));
+}
+/** Run a tool-capable, extension-free in-memory turn against seeded context. */
+export function headlessTurn(request) {
+    return runHeadless(request, 'failed', true, () => 'completed');
+}

package/dist/core/runtime/host.d.ts

@@ -0,0 +1,74 @@
+import { type NodeRow } from '../canvas/index.js';
+import type { PiInvocation } from './invocation.js';
+/** View-side launch hints the broker host needs beyond the PiInvocation. The
+ *  broker uses `cwd` + `resuming`; `name` is carried for the node's display. */
+export interface LaunchPlacement {
+    cwd: string;
+    name: string;
+    resuming: boolean;
+    launchJson?: string;
+}
+/** A handle to a node's running engine container. The broker host supervises via
+ *  the broker pid recorded as pi_pid; no tmux placement coords exist (the engine
+ *  is never in a pane). */
+export interface HostHandle {
+    /** Supervised pid (signal-0 target). Null means the host failed to spawn an
+     *  engine at all. Spawn/revive record this pid immediately; the broker
+     *  re-records the same pid during extension bind. */
+    pid: number | null;
+    /** Real child-exit signal from the launch handle. Resolves when the detached
+     *  broker exits, so readiness waits can fail fast without pid probes. */
+    exited: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+}
+export interface TeardownOptions {
+    excludePid?: number;
+    /** Requested teardowns start when this settles instead of on the next turn. A
+     *  close handler passes its response's `close` so the caller's own broker relay
+     *  outlives the response even when the handler awaits I/O after queuing. */
+    startAfter?: Promise<unknown>;
+    /** Why the stop was requested; stored on the live execution row (`stop_reason`). */
+    reason?: string;
+}
+/** The only completion signal a caller may use for post-teardown work. A false
+ * result means the original engine tree could not be confirmed dead, so no
+ * cleanup may claim it was safe to remove resources it owned. */
+export interface TeardownResult {
+    confirmed: boolean;
+    error?: Error;
+}
+export interface Host {
+    /** Bring a node's ENGINE into existence from its launch recipe; return a
+     *  supervisable handle. */
+    launch(nodeId: string, inv: PiInvocation, opts: LaunchPlacement): HostHandle | Promise<HostHandle>;
+    /** Is this node's engine alive? PURE / non-mutating. `string | NodeRow` so
+     *  both call sites — the revive guard (passes the id) and the daemon (passes a
+     *  row) — share one selector. For the broker this IS isPidAlive(pi_pid). */
+    isAlive(node: string | NodeRow): Promise<boolean>;
+    /** Tear the engine down (close/cancel teardown). Resolves only after the
+     * fixed process snapshot is confirmed dead, or with a diagnostic failure. */
+    teardown(nodeId: string, opts?: TeardownOptions): Promise<TeardownResult>;
+    /** Deliver an OS signal to the engine container — present so the daemon never
+     *  reaches around the abstraction. */
+    signal(nodeId: string, sig: NodeJS.Signals): Promise<void>;
+}
+/** The launch recipe stored in `executions.launch_json`: the invocation, the
+ *  config snapshot, the node's `scopes` (null when unnarrowed) and the scrubbed
+ *  `models` object (null when the operator has no models.json) — everything a
+ *  runner on another machine needs to rebuild the broker's run dir and agent dir. */
+export declare function brokerLaunchJson(nodeId: string, inv: PiInvocation, cwd: string): Promise<string>;
+/** Validate the broker launch recipe before we detach a child process. This is
+ *  the fast-fail seam for known module/path errors: a bad engine resolve or a
+ *  missing plain session path throws here, before spawn(). */
+export declare function preflightBrokerLaunch(nodeId: string, inv: PiInvocation, cwd: string, launchJson?: string): Promise<void>;
+/** Record the stop on the node's live execution row, then tear the broker down in this process: on the next event-loop
+ * turn, or once `opts.startAfter` settles. The row is what survives this process: when it dies before the teardown
+ * completes, the node-lifecycle claim holder enacts the stop from `stop_requested_at` / `stop_after_turn`
+ * (`enactRequestedStops`). Completion includes any post-teardown work, which lets the daemon drain it during shutdown;
+ * that work is this call's closure and does not outlive the process. */
+export declare function requestBrokerTeardown(nodeId: string, opts?: TeardownOptions, after?: () => Promise<void>): Promise<TeardownResult>;
+/** Isolated brokers require the Linux launcher; direct host spawn cannot enforce their filesystem or network policy. */
+export declare function isolatedBrokerLauncherAvailable(): boolean;
+export declare const headlessBrokerHost: Host;