ptbk 0.119.0-16 → 0.119.0-21

package/dist/service/actions.d.ts

@@ -1,27 +1,51 @@
 import type { Agenda } from '../engine/agenda.js';
-import type { UserRequest } from '../engine/requests.js';
 /**
- * Runtime actions shared by every channel (terminal, browser, API, CLI).
+ * Runtime actions shared by every channel (CLI, terminal, browser, API): the engine's lifecycle operations, wait
+ * skipping and coordinated project-browser recovery. `stop-now`/`cancel-stop` remain as compatibility aliases.
  *
  * @private shared runtime controls
  */
-export type ControlAction = 'pause' | 'resume' | 'skip-wait' | 'stop' | 'stop-now' | 'cancel-stop';
+export type ControlAction = 'pause' | 'resume' | 'skip-wait' | 'stop' | 'force-stop' | 'restart' | 'stop-now' | 'cancel-stop' | 'browser-recheck' | 'browser-retry' | 'browser-restart';
 /**
- * Applies one runtime control action and reports its actual outcome.
+ * Every control action name (for request validation).
  *
  * @private shared runtime controls
  */
-export declare function applyControlAction(agenda: Agenda, action: string): {
-    action: string;
-    outcome: string;
-    applied: boolean;
+export declare const CONTROL_ACTIONS: ReadonlySet<string>;
+/**
+ * Outcome of a control action as every client reports it.
+ *
+ * @private shared runtime controls
+ */
+export type ControlOutcome = {
+    readonly action: string;
+    readonly outcome: string;
+    readonly applied: boolean;
+    readonly completed?: boolean;
+    readonly state?: string;
 };
 /**
- * Validates and applies an answer from any channel.
+ * Engine-owned browser recovery operations (the service owns the project browser).
+ *
+ * @private shared runtime controls
+ */
+export type BrowserControls = {
+    readonly recheck: () => Promise<ControlOutcome>;
+    readonly retry: () => Promise<ControlOutcome>;
+    readonly restart: () => Promise<ControlOutcome>;
+};
+/**
+ * Applies one runtime control action and reports its actual outcome (accepted/pending versus completed).
+ *
+ * @private shared runtime controls
+ */
+export declare function applyControlAction(agenda: Agenda, action: string, params?: Readonly<Record<string, unknown>>, browser?: BrowserControls): Promise<ControlOutcome>;
+/**
+ * Chat operations shared by every channel (terminal, browser, API, CLI); writes go through the agenda's chat store.
  *
  * @private shared runtime controls
  */
-export declare function applyAnswer(agenda: Agenda, params: Readonly<Record<string, unknown>>, via: UserRequest['resolvedVia']): Promise<UserRequest>;
+export declare function applyChatAction(agenda: Agenda, method: string, params: Readonly<Record<string, unknown>>, via: string): Promise<unknown>;
 /**
  * Validates raw setting changes from a channel and applies them (temporary unless saved).
  *

package/dist/service/actions.js

@@ -1,46 +1,78 @@
 import { PtbkError } from '../common/errors.js';
 import { parseSettingValue, SETTING_SPEC_BY_KEY } from '../project/config.js';
+import { defaultChatAgent } from '../chats/service.js';
 /**
- * Applies one runtime control action and reports its actual outcome.
+ * Every control action name (for request validation).
  *
  * @private shared runtime controls
  */
-export function applyControlAction(agenda, action) {
+export const CONTROL_ACTIONS = new Set(['pause', 'resume', 'skip-wait', 'stop', 'force-stop', 'restart', 'stop-now', 'cancel-stop', 'browser-recheck', 'browser-retry', 'browser-restart']);
+/**
+ * Applies one runtime control action and reports its actual outcome (accepted/pending versus completed).
+ *
+ * @private shared runtime controls
+ */
+export async function applyControlAction(agenda, action, params = {}, browser) {
     switch (action) {
         case 'pause':
-            return { action, outcome: agenda.pause().state === 'pausing' ? 'Pause pending: the current task finishes first.' : 'Paused.', applied: true };
+            return agenda.pause({ replaceStop: params.replaceStop === true, revision: typeof params.revision === 'number' ? params.revision : undefined });
         case 'resume':
-            agenda.resume();
-            return { action, outcome: 'Resumed.', applied: true };
+            return agenda.resume();
         case 'skip-wait': {
             const result = agenda.skipWait();
             return { action, outcome: result.applied ? 'Wait skipped.' : (result.reason ?? 'Nothing to skip.'), applied: result.applied };
         }
         case 'stop':
-            agenda.requestStop({ cancelCurrent: false });
-            return { action, outcome: 'Stopping after the current task.', applied: true };
+            return agenda.requestStop({});
+        case 'force-stop':
         case 'stop-now':
-            agenda.requestStop({ cancelCurrent: true });
-            return { action, outcome: 'Stopping now; owned work is cancelled and recoverable.', applied: true };
+            return agenda.requestStop({ force: true });
+        case 'restart':
+            return agenda.requestStop({ restart: true });
         case 'cancel-stop':
-            agenda.cancelStop();
-            return { action, outcome: 'Stop cancelled (if it had not taken effect).', applied: true };
+            return agenda.cancelStop();
+        case 'browser-recheck':
+        case 'browser-retry':
+        case 'browser-restart': {
+            if (!browser)
+                return { action, outcome: 'This process does not own a project browser.', applied: false };
+            return action === 'browser-recheck' ? await browser.recheck() : action === 'browser-retry' ? await browser.retry() : await browser.restart();
+        }
         default:
             throw new PtbkError(`Unknown control action "${action}".`, { kind: 'usage' });
     }
 }
 /**
- * Validates and applies an answer from any channel.
+ * Chat operations shared by every channel (terminal, browser, API, CLI); writes go through the agenda's chat store.
  *
  * @private shared runtime controls
  */
-export async function applyAnswer(agenda, params, via) {
-    const id = String(params.id ?? '');
-    const status = params.status ?? 'answered';
-    if (!['answered', 'cancelled', 'rejected', 'unable'].includes(status))
-        throw new PtbkError(`Invalid answer status ${status}.`, { kind: 'usage' });
-    const answer = typeof params.answer === 'string' ? params.answer : '';
-    return await agenda.answer(id, answer, via, status);
+export async function applyChatAction(agenda, method, params, via) {
+    const text = (key) => (typeof params[key] === 'string' ? params[key] : '');
+    switch (method) {
+        case 'chat-list':
+            return await agenda.chatList();
+        case 'chat-agents':
+            return agenda.chatAgents();
+        case 'chat-get':
+            return await agenda.chatGet(text('name'));
+        case 'chat-read':
+            await agenda.chatRead(text('name'));
+            return { read: true };
+        case 'chat-create': {
+            // A new human chat without an explicit target goes to Chatter (diagnosed, never silently replaced).
+            const agent = text('agent') || defaultChatAgent(agenda.chatAgents()).reference;
+            const written = await agenda.chatCreate(agent, text('text'), { name: text('title') || undefined, requestKey: text('requestKey') || undefined });
+            return { name: written.chat.name, path: written.relativePath, commit: written.commit, messages: written.chat.messages.length };
+        }
+        case 'chat-send': {
+            const expected = typeof params.expected === 'number' ? params.expected : undefined;
+            const written = await agenda.chatSend(text('name'), text('text'), { expected, via });
+            return { name: written.chat.name, path: written.relativePath, commit: written.commit, messages: written.chat.messages.length, status: written.chat.status };
+        }
+        default:
+            throw new PtbkError(`Unknown chat action "${method}".`, { kind: 'usage' });
+    }
 }
 /**
  * Validates raw setting changes from a channel and applies them (temporary unless saved).

package/dist/service/actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/service/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/service/actions.ts"],"names":[],"mappings":"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"}

package/dist/service/control.d.ts

@@ -1,3 +1,4 @@
+import { PtbkError } from '../common/errors.js';
 import { type IpcServer } from '../common/ipc.js';
 import type { Project } from '../project/workspace.js';
 import { type ProcessRecord } from './records.js';
@@ -7,6 +8,52 @@ import { type ProcessRecord } from './records.js';
  * @private service control
  */
 export declare const READ_ONLY_METHODS: Set<string>;
+/**
+ * Version of the control contract: the shapes of snapshots and control replies that clients render.
+ *
+ * Engines and clients of different ptbk versions interoperate only when their contracts match. Bump it with every
+ * change that a client of the previous contract could misread (a removed, renamed or retyped field or method); a new
+ * snapshot field keeps the contract only when it is optional, so clients must handle its absence.
+ *
+ * @private service control
+ */
+export declare const CONTROL_CONTRACT = 2;
+/**
+ * Identity of the engine behind a control endpoint, as reported by its `identify` method.
+ *
+ * @private service control
+ */
+export type EngineIdentity = {
+    /** Engine version actually loaded by the service (not this client's version). */
+    readonly version: string;
+    /** Control contract of the engine (absent for engines that predate it). */
+    readonly contract?: number;
+    /** Whether this client can read the engine's snapshots. */
+    readonly compatible: boolean;
+};
+/**
+ * Whether this client can read snapshots of an engine: the same version, or a matching control contract.
+ *
+ * @private service control
+ */
+export declare function engineIdentityOf(reported: {
+    readonly version?: unknown;
+    readonly contract?: unknown;
+}, record: ProcessRecord): EngineIdentity;
+/**
+ * CLI entry point of the installation that runs a service (it may since have been removed or upgraded).
+ *
+ * @private service control
+ */
+export declare function engineBin(record: ProcessRecord): string;
+/**
+ * Actionable error of a client that cannot read the snapshots of an engine of another version.
+ *
+ * @private service control
+ */
+export declare function incompatibleEngineError(project: Project, record: ProcessRecord, engine: EngineIdentity, options?: {
+    readonly installationGone?: boolean;
+}): PtbkError;
 /**
  * Handler of control methods.
  *
@@ -27,6 +74,7 @@ export declare function startControlServer(address: string, token: string, handl
 export type ServiceLookup = {
     readonly state: 'running';
     readonly record: ProcessRecord;
+    readonly engine: EngineIdentity;
     readonly client: ControlClient;
 } | {
     readonly state: 'stopped';
@@ -44,7 +92,11 @@ export type ServiceLookup = {
 export declare class ControlClient {
     private readonly project;
     readonly record: ProcessRecord;
-    constructor(project: Project, record: ProcessRecord);
+    /** Verified identity of the engine; snapshots of an incompatible engine are refused instead of misrendered. */
+    readonly engine?: EngineIdentity | undefined;
+    constructor(project: Project, record: ProcessRecord, 
+    /** Verified identity of the engine; snapshots of an incompatible engine are refused instead of misrendered. */
+    engine?: EngineIdentity | undefined);
     /**
      * Sends a control request. Read-only requests retry briefly (re-authenticating the current record); a lost
      * reply to a mutating request is reported as unconfirmed and never replayed.

package/dist/service/control.js

@@ -1,13 +1,66 @@
+import { join } from 'node:path';
 import { PtbkError } from '../common/errors.js';
 import { IpcError, ipcRequest, startIpcServer } from '../common/ipc.js';
 import { isProcessAlive } from '../common/process.js';
+import { ENGINE_VERSION } from '../common/version.js';
 import { readProcessRecord } from './records.js';
 /**
  * Control methods that only read state (safe to retry).
  *
  * @private service control
  */
-export const READ_ONLY_METHODS = new Set(['identify', 'snapshot', 'watch', 'requests', 'devices']);
+export const READ_ONLY_METHODS = new Set(['identify', 'snapshot', 'summary', 'watch', 'requests', 'devices', 'chat-list', 'chat-agents', 'chat-get']);
+/**
+ * Version of the control contract: the shapes of snapshots and control replies that clients render.
+ *
+ * Engines and clients of different ptbk versions interoperate only when their contracts match. Bump it with every
+ * change that a client of the previous contract could misread (a removed, renamed or retyped field or method); a new
+ * snapshot field keeps the contract only when it is optional, so clients must handle its absence.
+ *
+ * @private service control
+ */
+export const CONTROL_CONTRACT = 2;
+/**
+ * Control methods whose replies are rendered as a service snapshot; reading them from an engine of another
+ * contract would misrender (or crash) the client.
+ */
+const SNAPSHOT_METHODS = new Set(['snapshot', 'watch']);
+/**
+ * Whether this client can read snapshots of an engine: the same version, or a matching control contract.
+ *
+ * @private service control
+ */
+export function engineIdentityOf(reported, record) {
+    const version = typeof reported.version === 'string' ? reported.version : record.engineVersion;
+    const contract = typeof reported.contract === 'number' ? reported.contract : undefined;
+    return { version, contract, compatible: version === ENGINE_VERSION || contract === CONTROL_CONTRACT };
+}
+/**
+ * CLI entry point of the installation that runs a service (it may since have been removed or upgraded).
+ *
+ * @private service control
+ */
+export function engineBin(record) {
+    return join(record.installation, 'bin', 'ptbk.js');
+}
+/**
+ * Actionable error of a client that cannot read the snapshots of an engine of another version.
+ *
+ * @private service control
+ */
+export function incompatibleEngineError(project, record, engine, options = {}) {
+    return new PtbkError(`The running service uses ptbk ${engine.version}; this ptbk ${ENGINE_VERSION} cannot read its status.`, {
+        kind: 'unsupported',
+        project: project.root,
+        reason: `The control contract differs (service ${engine.contract ?? 'unknown'}, this client ${CONTROL_CONTRACT})${options.installationGone ? `, and the service's installation at ${record.installation} no longer holds ptbk ${engine.version}` : ''}.`,
+        effect: 'Nothing was changed; the service keeps running.',
+        next: [
+            ...(options.installationGone ? [] : [`Use the service's own installation: \`node "${engineBin(record)}" dashboard\`.`]),
+            `Switch the service to ptbk ${ENGINE_VERSION}: \`ptbk stop\`, then \`ptbk start\` (unfinished work keeps its recovery record).`,
+            `Or view it with its own version: \`npx ptbk@${engine.version} dashboard\`.`,
+        ],
+    });
+}
 /**
  * Starts the control server of a running process.
  *
@@ -31,15 +84,21 @@ export async function startControlServer(address, token, handler) {
 export class ControlClient {
     project;
     record;
-    constructor(project, record) {
+    engine;
+    constructor(project, record, 
+    /** Verified identity of the engine; snapshots of an incompatible engine are refused instead of misrendered. */
+    engine) {
         this.project = project;
         this.record = record;
+        this.engine = engine;
     }
     /**
      * Sends a control request. Read-only requests retry briefly (re-authenticating the current record); a lost
      * reply to a mutating request is reported as unconfirmed and never replayed.
      */
     async request(method, params = {}, timeoutMs = 30_000) {
+        if (this.engine && !this.engine.compatible && SNAPSHOT_METHODS.has(method))
+            throw incompatibleEngineError(this.project, this.record, this.engine);
         const readOnly = READ_ONLY_METHODS.has(method);
         let record = this.record;
         for (let attempt = 1;; attempt++) {
@@ -51,7 +110,7 @@ export class ControlClient {
                     throw error;
                 if (error.stage === 'remote') {
                     const details = error.details;
-                    throw new PtbkError(error.message, { kind: details?.kind ?? 'technical', reason: details?.reason, next: details?.next });
+                    throw new PtbkError(error.message, { kind: details?.kind ?? 'technical', reason: details?.reason, effect: details?.effect, next: details?.next, data: details?.data });
                 }
                 if (!readOnly) {
                     throw new PtbkError(error.stage === 'connect' ? 'The service did not accept the request.' : `The outcome of "${method}" is unconfirmed.`, {
@@ -92,7 +151,8 @@ export async function lookupService(project) {
         const identity = await ipcRequest(record.controlAddress, { token: record.token, method: 'identify', params: {} }, 5000);
         if (identity.instanceId !== record.instanceId)
             return { state: 'unreachable', record, reason: 'The control endpoint belongs to a different instance.' };
-        return { state: 'running', record, client: new ControlClient(project, record) };
+        const engine = engineIdentityOf(identity, record);
+        return { state: 'running', record, engine, client: new ControlClient(project, record, engine) };
     }
     catch (error) {
         return { state: 'unreachable', record, reason: error instanceof Error ? error.message : String(error) };

package/dist/service/control.js.map

@@ -1 +1 @@
-{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/service/control.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"control.js","sourceRoot":"","sources":["../../src/service/control.ts"],"names":[],"mappings":"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"}

package/dist/service/discovery.d.ts

@@ -0,0 +1,133 @@
+import { ControlClient } from './control.js';
+/**
+ * Version of the host-wide discovery contract (kept interoperable across engine versions).
+ *
+ * @private service discovery
+ */
+export declare const DISCOVERY_VERSION = 1;
+/**
+ * One running engine as registered in the host-wide discovery registry (`<app data>/services/<instance>.json`).
+ *
+ * It points back to the verified owner of one concrete project. It is not a project lock, a credential (no control
+ * token) or a task store: connecting still requires the project's own owner-readable process record.
+ *
+ * @private service discovery
+ */
+export type DiscoveryEntry = {
+    readonly version: typeof DISCOVERY_VERSION;
+    /** Unique instance of the engine process. */
+    readonly instanceId: string;
+    /** PID of the process hosting the engine. */
+    readonly pid: number;
+    /** PID of the daemon supervisor, when any. */
+    readonly supervisorPid?: number;
+    /** Placement of the engine. */
+    readonly mode: 'daemon' | 'foreground' | 'run';
+    /** Canonical project directory the engine owns. */
+    readonly projectRoot: string;
+    /** Display name of the project. */
+    readonly projectName: string;
+    /** Engine version actually loaded by the process. */
+    readonly engineVersion: string;
+    /** Installation running the engine. */
+    readonly installation: string;
+    /** Local control endpoint (useless without the project's token). */
+    readonly controlAddress: string;
+    /** Engine start (ISO). */
+    readonly startedAt: string;
+};
+/**
+ * Directory of the registry for the current OS user (other users' engines are outside it by design).
+ *
+ * @private service discovery
+ */
+export declare function discoveryDirectory(env?: NodeJS.ProcessEnv): string;
+/**
+ * Registers a running engine; returns the owner's own unregistration (it never touches other entries).
+ *
+ * @private service discovery
+ */
+export declare function registerEngine(entry: DiscoveryEntry, env?: NodeJS.ProcessEnv): Promise<() => Promise<void>>;
+/**
+ * Reads every registration of this OS user. A missing registry is an empty (successful) result; an unreadable one is
+ * reported as a problem instead of being presented as zero services.
+ *
+ * @private service discovery
+ */
+export declare function readRegistry(env?: NodeJS.ProcessEnv): Promise<{
+    readonly entries: DiscoveryEntry[];
+    readonly problem?: string;
+}>;
+/**
+ * Compact live summary of one engine for the global table (the `summary` control method, or a full snapshot from
+ * engines that predate it).
+ *
+ * @private service discovery
+ */
+export type EngineSummary = {
+    readonly state: string;
+    readonly phase: string;
+    readonly intent?: string;
+    readonly work?: string;
+    readonly waitingChats: number;
+    readonly observedAt: string;
+};
+/**
+ * Observed status of one registration.
+ *
+ * @private service discovery
+ */
+export type DiscoveredEngine = {
+    readonly status: 'live';
+    readonly entry: DiscoveryEntry;
+    readonly client: ControlClient;
+    readonly summary: EngineSummary;
+} | {
+    readonly status: 'unreachable';
+    readonly entry: DiscoveryEntry;
+    readonly reason: string;
+} | {
+    readonly status: 'ended';
+    readonly entry: DiscoveryEntry;
+    readonly reason: string;
+};
+/**
+ * Verifies a registration against the project's own process record and the engine's control identity before it is
+ * shown as live. A proven-dead entry (process gone, or the project verifiably owned by another instance) is removed
+ * from the registry; nothing is killed and no project lock or project file is touched.
+ *
+ * @private service discovery
+ */
+export declare function verifyEngine(entry: DiscoveryEntry, env?: NodeJS.ProcessEnv): Promise<DiscoveredEngine>;
+/**
+ * Minimal shape of a full snapshot (engines without the `summary` method).
+ */
+type SnapshotLike = {
+    readonly observedAt: string;
+    readonly phase: string;
+    readonly service: {
+        readonly state: string;
+        readonly lifecycle?: {
+            readonly intent?: string;
+        };
+    };
+    readonly current?: {
+        readonly agent: {
+            readonly name: string;
+        };
+        readonly taskTitle: string;
+    };
+    readonly wait?: {
+        readonly reason: string;
+    };
+    readonly chats?: {
+        readonly waiting: readonly unknown[];
+    };
+};
+/**
+ * Compact summary of a snapshot.
+ *
+ * @private service discovery
+ */
+export declare function summaryOfSnapshot(snapshot: SnapshotLike): EngineSummary;
+export {};