@owlmeans/viable-sdk 0.1.18-rc.1

package/build/run/state.d.ts

@@ -0,0 +1,75 @@
+import { TARGET_API_PORT, TARGET_WEB_PORT, TARGET_WORKER_PORT } from '@owlmeans/viable-common';
+/**
+ * What a local run is, written down.
+ *
+ * A separate module from the run itself, and the separation is load-bearing: `DbSync` has to
+ * bounce the api child, `DbSync` lives in the shell commands, and the shell commands are reached
+ * through the executor the run is built on. Everything that touches a child process therefore
+ * lives here, below both of them, instead of making the three import each other in a circle.
+ *
+ * The record is a file rather than memory because the processes outlive the call that started
+ * them and, on a restarted connector, outlive the process that started them too.
+ */
+export interface LocalProcessRecord {
+    pid: number;
+    port: number;
+    /**
+     * The id this instance answers `/api/healtz` with.
+     *
+     * Port ownership is a restart's only proof: the child is a shell wrapping `bun`, so a signal
+     * the shell dies from and `bun` survives leaves an orphan holding the port while the exit
+     * handler says "gone". A replacement then loses the bind and exits — and since a failed
+     * `listen` announces nothing on its own, everything keeps reporting healthy while the older
+     * build is what is being served.
+     */
+    bootId?: string;
+}
+export interface LocalRunRecord {
+    dir: string;
+    startedAt: string;
+    api?: LocalProcessRecord;
+    worker?: LocalProcessRecord;
+    /** The process serving the built browser app — this connector itself, not a child. */
+    web?: LocalProcessRecord;
+}
+export declare const readRun: (dir: string) => Promise<LocalRunRecord | null>;
+export declare const writeRun: (dir: string, record: LocalRunRecord) => Promise<void>;
+export declare const clearRun: (dir: string) => Promise<void>;
+/** Whether the api recorded here is still a live process. */
+export declare const apiRunning: (record: LocalRunRecord | null) => boolean;
+/**
+ * Start the target's HTTP server as a detached child.
+ *
+ * Detached so the whole group can be signalled later — the child is a shell wrapping `bun`, and a
+ * signal aimed at the shell alone leaves `bun` holding the port.
+ */
+export declare const startApi: (dir: string, env?: Record<string, string>) => Promise<LocalProcessRecord>;
+/**
+ * Start the target's queue worker, when this tree has one.
+ *
+ * The SAME `dist/index.js` as the api, out of the same package tree — the argv marker is the only
+ * thing separating the two processes, which is why nothing may reclaim a port without excluding
+ * the other's marker. Most generated applications declare no queues, and their absence is not a
+ * degraded state.
+ */
+export declare const startWorker: (dir: string) => Promise<LocalProcessRecord | null>;
+/**
+ * Stop a recorded process and wait for its port to actually free.
+ *
+ * The port and not the pid is what a replacement needs, so that is what is waited on.
+ */
+export declare const stopProcess: (record: LocalProcessRecord | undefined) => Promise<void>;
+/**
+ * Bounce the api child so it reconciles the target's tables against its code.
+ *
+ * What `DbSync` means for a target that owns its own structure: every `@owlmeans/postgres`
+ * resource creates and updates its table while the context initializes, so there is nothing to
+ * generate and no migration file to apply — the sync IS the restart. A tree with no run in front
+ * of it answers `null`: there is no process to bounce, and reporting that as a failure would send
+ * a caller after a repair that does not apply.
+ */
+export declare const restartApi: (dir: string) => Promise<string | null>;
+/** Whether anything is answering on the api's port right now. */
+export declare const apiListening: (port?: number) => Promise<boolean>;
+export { TARGET_API_PORT, TARGET_WEB_PORT, TARGET_WORKER_PORT };
+//# sourceMappingURL=state.d.ts.map

package/build/run/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/run/state.ts"],"names":[],"mappings":"AAKA,OAAO,EACoD,eAAe,EAAE,eAAe,EAEzF,kBAAkB,EACnB,MAAM,yBAAyB,CAAA;AAOhC;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,kBAAkB,CAAA;IACxB,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,sFAAsF;IACtF,GAAG,CAAC,EAAE,kBAAkB,CAAA;CACzB;AAID,eAAO,MAAM,OAAO,QAAe,MAAM,KAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAWxE,CAAA;AAED,eAAO,MAAM,QAAQ,QAAe,MAAM,UAAU,cAAc,KAAG,OAAO,CAAC,IAAI,CAGhF,CAAA;AAED,eAAO,MAAM,QAAQ,QAAe,MAAM,KAAG,OAAO,CAAC,IAAI,CAExD,CAAA;AAED,6DAA6D;AAC7D,eAAO,MAAM,UAAU,WAAY,cAAc,GAAG,IAAI,KAAG,OACf,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,QACd,MAAM,QAAO,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KACvC,OAAO,CAAC,kBAAkB,CA0B5B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,QAAe,MAAM,KAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAyBhF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAkB,kBAAkB,GAAG,SAAS,KAAG,OAAO,CAAC,IAAI,CAUtF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,QAAe,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAYnE,CAAA;AAED,iEAAiE;AACjE,eAAO,MAAM,YAAY,UACjB,MAAM,KACX,OAAO,CAAC,OAAO,CAA+B,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAA"}

package/build/run/state.js

@@ -0,0 +1,136 @@
+import fs from 'fs-extra';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import p from 'node:path';
+import { CONNECT_MARKER_DIR, CONNECT_RUN_FILE, TARGET_API_MARKER, TARGET_API_PORT, TARGET_WEB_PORT, TARGET_WORKER_MARKER, TARGET_WORKER_PORT } from '@owlmeans/viable-common';
+import { backendEnv } from '../executor/env.js';
+import { apiPath, hasWorker, workerPath } from '../executor/layout.js';
+import { integrityRefusal } from '../executor/integrity.js';
+import { isAlive, probeListening, reclaimPort, signalGroup, waitForPortFree } from '../executor/spawn.js';
+const runFile = (dir) => p.join(dir, CONNECT_RUN_FILE);
+export const readRun = async (dir) => {
+    const content = await fs.readFile(runFile(dir), 'utf-8').catch(() => null);
+    if (content == null)
+        return null;
+    try {
+        const parsed = JSON.parse(content);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+export const writeRun = async (dir, record) => {
+    await fs.ensureDir(p.join(dir, CONNECT_MARKER_DIR));
+    await fs.writeFile(runFile(dir), `${JSON.stringify(record, null, 2)}\n`);
+};
+export const clearRun = async (dir) => {
+    await fs.rm(runFile(dir), { force: true }).catch(() => undefined);
+};
+/** Whether the api recorded here is still a live process. */
+export const apiRunning = (record) => record != null && isAlive(record.api?.pid);
+/**
+ * Start the target's HTTP server as a detached child.
+ *
+ * Detached so the whole group can be signalled later — the child is a shell wrapping `bun`, and a
+ * signal aimed at the shell alone leaves `bun` holding the port.
+ */
+export const startApi = async (dir, env = {}) => {
+    const bootId = randomUUID();
+    const cwd = apiPath(dir);
+    // A run killed without a stop leaves this child alive — detaching it is what keeps it
+    // running after the tool that started it exits. What survives holds the port, and the
+    // replacement then loses the bind and exits without announcing it.
+    if (!await waitForPortFree(TARGET_API_PORT, 2_000)) {
+        await reclaimPort(TARGET_API_PORT, TARGET_API_MARKER);
+    }
+    const child = spawn('bun', ['dist/index.js', TARGET_API_MARKER], {
+        cwd,
+        detached: true,
+        shell: true,
+        stdio: 'ignore',
+        env: {
+            ...process.env,
+            ...await backendEnv(dir),
+            BACKEND_PORT: `${TARGET_API_PORT}`,
+            BACKEND_BOOT_ID: bootId,
+            ...env,
+        },
+    });
+    child.unref();
+    return { pid: child.pid ?? -1, port: TARGET_API_PORT, bootId };
+};
+/**
+ * Start the target's queue worker, when this tree has one.
+ *
+ * The SAME `dist/index.js` as the api, out of the same package tree — the argv marker is the only
+ * thing separating the two processes, which is why nothing may reclaim a port without excluding
+ * the other's marker. Most generated applications declare no queues, and their absence is not a
+ * degraded state.
+ */
+export const startWorker = async (dir) => {
+    if (!hasWorker(dir))
+        return null;
+    const cwd = workerPath(dir);
+    if (cwd == null)
+        return null;
+    const bootId = randomUUID();
+    const child = spawn('bun', ['dist/index.js', TARGET_WORKER_MARKER], {
+        cwd,
+        detached: true,
+        shell: true,
+        stdio: 'ignore',
+        env: {
+            ...process.env,
+            ...await backendEnv(dir),
+            // The target reads one "port I bind" variable and the worker binds its health port with it;
+            // `WORKER_PORT` travels beside it so a worker that grew its own variable finds it.
+            BACKEND_PORT: `${TARGET_WORKER_PORT}`,
+            WORKER_PORT: `${TARGET_WORKER_PORT}`,
+            BACKEND_BOOT_ID: bootId,
+        },
+    });
+    child.unref();
+    return { pid: child.pid ?? -1, port: TARGET_WORKER_PORT, bootId };
+};
+/**
+ * Stop a recorded process and wait for its port to actually free.
+ *
+ * The port and not the pid is what a replacement needs, so that is what is waited on.
+ */
+export const stopProcess = async (record) => {
+    if (record == null)
+        return;
+    if (isAlive(record.pid)) {
+        signalGroup(record.pid, 'SIGTERM');
+        if (!await waitForPortFree(record.port, 5_000)) {
+            signalGroup(record.pid, 'SIGKILL');
+        }
+    }
+    await waitForPortFree(record.port, 5_000);
+};
+/**
+ * Bounce the api child so it reconciles the target's tables against its code.
+ *
+ * What `DbSync` means for a target that owns its own structure: every `@owlmeans/postgres`
+ * resource creates and updates its table while the context initializes, so there is nothing to
+ * generate and no migration file to apply — the sync IS the restart. A tree with no run in front
+ * of it answers `null`: there is no process to bounce, and reporting that as a failure would send
+ * a caller after a repair that does not apply.
+ */
+export const restartApi = async (dir) => {
+    const record = await readRun(dir);
+    if (record == null || record.api == null)
+        return null;
+    const refused = await integrityRefusal(dir, 'Refused to restart');
+    if (refused != null)
+        return refused;
+    await stopProcess(record.api);
+    const api = await startApi(dir);
+    await writeRun(dir, { ...record, api });
+    return null;
+};
+/** Whether anything is answering on the api's port right now. */
+export const apiListening = async (port = TARGET_API_PORT) => await probeListening(port);
+export { TARGET_API_PORT, TARGET_WEB_PORT, TARGET_WORKER_PORT };
+//# sourceMappingURL=state.js.map

package/build/run/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../src/run/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,UAAU,CAAA;AACzB,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,CAAC,MAAM,WAAW,CAAA;AAEzB,OAAO,EACL,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,eAAe,EAAE,eAAe,EACzF,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAsCzG,MAAM,OAAO,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAA;AAEtE,MAAM,CAAC,MAAM,OAAO,GAAG,KAAK,EAAE,GAAW,EAAkC,EAAE;IAC3E,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;IAC1E,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAEhC,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAE3C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAwB,CAAC,CAAC,CAAC,IAAI,CAAA;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAW,EAAE,MAAsB,EAAiB,EAAE;IACnF,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC,CAAA;IACnD,MAAM,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAA;AAC1E,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,GAAW,EAAiB,EAAE;IAC3D,MAAM,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;AACnE,CAAC,CAAA;AAED,6DAA6D;AAC7D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAA6B,EAAW,EAAE,CACnE,MAAM,IAAI,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,GAAW,EAAE,GAAG,GAA2B,EAAE,EAChB,EAAE;IAC/B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACxB,sFAAsF;IACtF,sFAAsF;IACtF,mEAAmE;IACnE,IAAI,CAAC,MAAM,eAAe,CAAC,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC;QACnD,MAAM,WAAW,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAA;IACvD,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,eAAe,EAAE,iBAAiB,CAAC,EAAE;QAC/D,GAAG;QACH,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,QAAQ;QACf,GAAG,EAAE;YACH,GAAG,OAAO,CAAC,GAAG;YACd,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC;YACxB,YAAY,EAAE,GAAG,eAAe,EAAE;YAClC,eAAe,EAAE,MAAM;YACvB,GAAG,GAAG;SACP;KACF,CAAC,CAAA;IACF,KAAK,CAAC,KAAK,EAAE,CAAA;IAEb,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,CAAA;AAChE,CAAC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,GAAW,EAAsC,EAAE;IACnF,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAEhC,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAE5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,eAAe,EAAE,oBAAoB,CAAC,EAAE;QAClE,GAAG;QACH,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,QAAQ;QACf,GAAG,EAAE;YACH,GAAG,OAAO,CAAC,GAAG;YACd,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC;YACxB,4FAA4F;YAC5F,mFAAmF;YACnF,YAAY,EAAE,GAAG,kBAAkB,EAAE;YACrC,WAAW,EAAE,GAAG,kBAAkB,EAAE;YACpC,eAAe,EAAE,MAAM;SACxB;KACF,CAAC,CAAA;IACF,KAAK,CAAC,KAAK,EAAE,CAAA;IAEb,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,CAAA;AACnE,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,MAAsC,EAAiB,EAAE;IACzF,IAAI,MAAM,IAAI,IAAI;QAAE,OAAM;IAE1B,IAAI,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;QAClC,IAAI,CAAC,MAAM,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YAC/C,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;QACpC,CAAC;IACH,CAAC;IACD,MAAM,eAAe,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;AAC3C,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAAE,GAAW,EAA0B,EAAE;IACtE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAA;IACjC,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,CAAC,GAAG,IAAI,IAAI;QAAE,OAAO,IAAI,CAAA;IAErD,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAA;IACjE,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,OAAO,CAAA;IAEnC,MAAM,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC7B,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC/B,MAAM,QAAQ,CAAC,GAAG,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAEvC,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,IAAI,GAAW,eAAe,EACZ,EAAE,CAAC,MAAM,cAAc,CAAC,IAAI,CAAC,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAA"}

package/build/session/index.d.ts

@@ -0,0 +1,17 @@
+import { ConnectSessionStatus } from '@owlmeans/viable-common';
+import type { ConnectorApi, LocalExecutor, OpenSessionArgs, SessionRuntime } from '../types.js';
+export interface SessionOptions {
+    api: ConnectorApi;
+    open: OpenSessionArgs;
+    /** Absent for a cloud target: the platform's own pod executes its commands. */
+    executor?: LocalExecutor;
+    /** Which deployment this is, recorded in the project's marker so a later connector finds it. */
+    apiUrl?: string;
+    log?: (line: string) => void;
+}
+export declare const openSession: (opts: SessionOptions) => Promise<SessionRuntime>;
+export { ConnectSessionStatus };
+export * from './queue.js';
+export * from './tasks.js';
+export * from './questions.js';
+//# sourceMappingURL=index.d.ts.map

package/build/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAC8B,oBAAoB,EACxD,MAAM,yBAAyB,CAAA;AAMhC,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAgB,MAAM,aAAa,CAAA;AAM7G,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,YAAY,CAAA;IACjB,IAAI,EAAE,eAAe,CAAA;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,gGAAgG;IAChG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B;AAgDD,eAAO,MAAM,WAAW,SAAgB,cAAc,KAAG,OAAO,CAAC,cAAc,CA6L9E,CAAA;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/build/session/index.js

@@ -0,0 +1,226 @@
+import { ConnectOpErrorKind, ConnectOpKind, ConnectSessionStatus } from '@owlmeans/viable-common';
+import { PULL_WAIT_MS } from '../consts.js';
+import { writeEnv } from '../project/env.js';
+import { readMarker, writeMarker } from '../project/marker.js';
+import { QuestionQueue } from './questions.js';
+import { TaskQueue } from './tasks.js';
+/**
+ * One attached connector, running.
+ *
+ * The loop is deliberately simple and deliberately serial: pull operations, answer them one at a
+ * time, put model tasks aside for the parent agent to drain. Serial because the thing on the other
+ * end of a local operation is a filesystem the platform believes it is the only writer of — two
+ * concurrent template writes into the same tree is not a throughput problem, it is a corrupted
+ * tree.
+ *
+ * Results are remembered by operation id. A connector that reconnects is handed everything still
+ * outstanding, including whatever it had already answered when the connection dropped, and
+ * re-executing a build or a model task because an acknowledgement was lost is exactly the cost
+ * this avoids.
+ */
+/**
+ * Record which project a directory belongs to.
+ *
+ * Attaching a connector to a project IS the moment the directory becomes that project's, so it is
+ * the moment to say so on disk. Without it `attach_project` cannot find a project by its directory
+ * and a connector started here tomorrow has to be told again which project this is — the marker is
+ * read at startup for exactly that. It holds no secret and is meant to be committed.
+ *
+ * Best-effort: a session that works is worth more than a note about it, and the platform is the
+ * authority on what this project is either way.
+ */
+const recordMarker = async (opts, projectId) => {
+    const dir = opts.open.projectDir;
+    if (dir == null)
+        return;
+    try {
+        const existing = await readMarker(dir);
+        if (existing?.projectId === projectId)
+            return;
+        const status = await opts.api.project.status(projectId);
+        await writeMarker(dir, {
+            version: 1,
+            apiUrl: opts.apiUrl ?? '',
+            projectId,
+            slug: status.slot?.slug ?? status.project.alias,
+            createdAt: new Date().toISOString(),
+        });
+    }
+    catch (e) {
+        (opts.log ?? (() => undefined))(`could not record the project marker: ${e.message}`);
+    }
+};
+export const openSession = async (opts) => {
+    const log = opts.log ?? (() => undefined);
+    const session = await opts.api.openSession(opts.open);
+    if (session.projectId != null)
+        await recordMarker(opts, session.projectId);
+    const tasks = new TaskQueue();
+    const questions = new QuestionQueue();
+    const answered = new Map();
+    const stats = {
+        opsDone: 0,
+        opsFailed: 0,
+        tasksDelivered: 0,
+        tasksSubmitted: 0,
+        questionsDelivered: 0,
+        questionsAnswered: 0,
+        lastActivityAt: Date.now(),
+        transport: 'pull',
+    };
+    let closed = false;
+    const submit = async (result) => {
+        answered.set(result.opId, result);
+        stats.lastActivityAt = Date.now();
+        try {
+            await opts.api.submitOp(session.id, result);
+        }
+        catch (e) {
+            // A lost acknowledgement is not a lost answer: the operation stays in the platform's store
+            // and is redelivered, and the cached result answers it without doing the work again.
+            log(`submit failed for ${result.opId}: ${e.message}`);
+        }
+    };
+    const perform = async (op) => {
+        const cached = answered.get(op.id);
+        if (cached != null) {
+            await submit(cached);
+            return;
+        }
+        if (op.kind === ConnectOpKind.ModelTask) {
+            // Not executed here at all — it is the parent agent's to run, in its own clean subagent.
+            // What this loop owes it is delivery and nothing else.
+            if (tasks.push(op.payload, op.id)) {
+                stats.tasksDelivered += 1;
+                stats.lastActivityAt = Date.now();
+            }
+            return;
+        }
+        if (op.kind === ConnectOpKind.Inquiry) {
+            // Executed by nobody: it is a decision about the user's own project, and a connector that
+            // answered one itself would build a whole application on a guess nobody made. Queued for
+            // the parent agent to put to a person, exactly as a model task is queued for its subagent.
+            if (questions.push(op.payload, op.id)) {
+                stats.questionsDelivered += 1;
+                stats.lastActivityAt = Date.now();
+            }
+            return;
+        }
+        try {
+            const value = op.kind === ConnectOpKind.Configure
+                ? await writeEnv(requireExecutor().dir, op.payload)
+                : await requireExecutor().execute(op.payload);
+            stats.opsDone += 1;
+            await submit({ opId: op.id, sessionId: session.id, ok: true, value });
+        }
+        catch (e) {
+            stats.opsFailed += 1;
+            const error = e;
+            log(`operation ${op.id} failed: ${error.message}`);
+            await submit({
+                opId: op.id,
+                sessionId: session.id,
+                ok: false,
+                error: {
+                    type: error.name,
+                    message: error.message,
+                    // A local failure is the connector's own — it ran and could not do the thing. Saying
+                    // `Unavailable` here would tell the platform to give up on a run that is fine.
+                    kind: ConnectOpErrorKind.Refused,
+                },
+            });
+        }
+    };
+    const requireExecutor = () => {
+        if (opts.executor == null) {
+            throw new Error('this session executes nothing locally — its target is a platform slot');
+        }
+        return opts.executor;
+    };
+    /**
+     * The pull loop.
+     *
+     * A long poll rather than a socket, as the first transport: it works through every proxy, needs
+     * no reconnection logic, and is the only option the URL-configured host has at all. The socket
+     * is an optimisation over it, not a replacement for it.
+     */
+    const loop = async () => {
+        while (!closed) {
+            try {
+                const ops = await opts.api.pullOps(session.id, Math.floor(PULL_WAIT_MS / 1000));
+                stats.lastActivityAt = Date.now();
+                for (const op of ops) {
+                    if (closed)
+                        break;
+                    await perform(op);
+                }
+            }
+            catch (e) {
+                if (closed)
+                    break;
+                log(`pull failed: ${e.message}`);
+                await new Promise(resolve => setTimeout(resolve, 2_000));
+            }
+        }
+    };
+    void loop();
+    return {
+        session,
+        stats,
+        nextTask: async (waitMs) => {
+            const task = await tasks.take(waitMs);
+            if (task != null)
+                stats.lastActivityAt = Date.now();
+            return task;
+        },
+        submitTask: async (result) => {
+            const opId = tasks.opIdOf(result.taskId);
+            if (opId == null) {
+                log(`no operation is waiting for task ${result.taskId}`);
+                return;
+            }
+            tasks.settle(result.taskId);
+            stats.tasksSubmitted += 1;
+            await submit({ opId, sessionId: session.id, ok: true, value: result });
+        },
+        taskById: taskId => tasks.outstandingById(taskId),
+        outstandingTasks: () => tasks.outstandingTasks(),
+        pendingTasks: () => tasks.size(),
+        nextQuestion: async (waitMs) => {
+            const question = await questions.take(waitMs);
+            if (question != null)
+                stats.lastActivityAt = Date.now();
+            return question;
+        },
+        answerQuestion: async (answer) => {
+            const opId = questions.opIdOf(answer.inquiryId);
+            if (opId == null) {
+                // The question outlived its operation — the run parked and stopped waiting on this
+                // session. The answer is not lost: it is sent by id through `connect.inquiry.answer`,
+                // which is the caller's fallback and the reason this reports rather than throws.
+                log(`no operation is waiting for question ${answer.inquiryId}`);
+                return;
+            }
+            questions.settle(answer.inquiryId);
+            stats.questionsAnswered += 1;
+            await submit({ opId, sessionId: session.id, ok: true, value: answer });
+        },
+        questionById: inquiryId => questions.outstandingById(inquiryId),
+        outstandingQuestions: () => questions.outstandingQuestions(),
+        pendingQuestions: () => questions.size(),
+        close: async () => {
+            closed = true;
+            try {
+                await opts.api.closeSession(session.id);
+            }
+            catch (e) {
+                log(`close failed: ${e.message}`);
+            }
+        },
+    };
+};
+export { ConnectSessionStatus };
+export * from './queue.js';
+export * from './tasks.js';
+export * from './questions.js';
+//# sourceMappingURL=index.js.map

package/build/session/index.js.map

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

package/build/session/questions.d.ts

@@ -0,0 +1,16 @@
+import type { InquiryPayload } from '@owlmeans/viable-common';
+import { OpQueue } from './queue.js';
+/**
+ * Questions waiting for the person the parent agent is working for.
+ *
+ * The same queue as the model tasks, and deliberately a SEPARATE one: a question outranks a task
+ * because a person is slower than a subagent, and a parent draining one list would hand a question
+ * to a subagent — which is precisely the outcome the whole primitive exists to prevent. Nothing
+ * here executes anything: a question is delivered, and its answer comes back through the tool the
+ * parent calls after asking.
+ */
+export declare class QuestionQueue extends OpQueue<InquiryPayload> {
+    /** Put to the parent and still unanswered, oldest first. */
+    outstandingQuestions(): InquiryPayload[];
+}
+//# sourceMappingURL=questions.d.ts.map

package/build/session/questions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../../src/session/questions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAE7D,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEpC;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,OAAO,CAAC,cAAc,CAAC;IACxD,4DAA4D;IAC5D,oBAAoB,IAAI,cAAc,EAAE,CAEvC;CACF"}

package/build/session/questions.js

@@ -0,0 +1,17 @@
+import { OpQueue } from './queue.js';
+/**
+ * Questions waiting for the person the parent agent is working for.
+ *
+ * The same queue as the model tasks, and deliberately a SEPARATE one: a question outranks a task
+ * because a person is slower than a subagent, and a parent draining one list would hand a question
+ * to a subagent — which is precisely the outcome the whole primitive exists to prevent. Nothing
+ * here executes anything: a question is delivered, and its answer comes back through the tool the
+ * parent calls after asking.
+ */
+export class QuestionQueue extends OpQueue {
+    /** Put to the parent and still unanswered, oldest first. */
+    outstandingQuestions() {
+        return this.outstanding();
+    }
+}
+//# sourceMappingURL=questions.js.map

package/build/session/questions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"questions.js","sourceRoot":"","sources":["../../src/session/questions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEpC;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,OAAuB;IACxD,4DAA4D;IAC5D,oBAAoB;QAClB,OAAO,IAAI,CAAC,WAAW,EAAE,CAAA;IAC3B,CAAC;CACF"}

package/build/session/queue.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Operations waiting for the parent agent — the model calls it performs, and the questions it
+ * puts to a person.
+ *
+ * A queue rather than a callback because of who drains it: the parent agent asks for work when it
+ * is ready, through a tool call, and may take minutes to answer. Nothing here pushes — the whole
+ * point of the local-LLM mode is that the platform waits on somebody else's schedule, and a
+ * question waits on a slower schedule still.
+ *
+ * Generic over the payload rather than copied per kind: both of them are handed out once, both are
+ * redelivered by the platform until they are answered, and both route their answer back on an
+ * operation id. A second copy of these rules is a second place for the redelivery guard to be
+ * forgotten, and the symptom of forgetting it is real model calls paid for and thrown away.
+ *
+ * The operation id is kept beside each item and never shown to the parent. It is what an answer is
+ * routed back on, and a parent that could name one could answer an operation it was never given.
+ */
+export declare class OpQueue<T extends {
+    id: string;
+}> {
+    private readonly queue;
+    private readonly ops;
+    /**
+     * Every item this session has ever been handed.
+     *
+     * The platform redelivers an operation on every poll until it is answered — that is what makes a
+     * connector restart cost a round trip instead of a run. A model task takes a parent agent tens of
+     * seconds to answer, so without this the queue grew one copy per poll for the whole time it was
+     * being answered, and the parent then ran the same task over and over: real model calls, paid
+     * for, thrown away. Kept after settling too, so a redelivery that raced the platform's deletion
+     * is ignored rather than answered a second time.
+     */
+    private readonly seen;
+    /**
+     * Handed out and not yet answered. An answer is checked against the item that asked for it.
+     *
+     * Named `held` rather than `outstanding` so the public reading of it can carry that name: the
+     * two subclasses expose it as `outstandingTasks()` / `outstandingQuestions()`, and a field and
+     * a method cannot share one name.
+     */
+    private readonly held;
+    private readonly waiting;
+    /** @returns whether the item was accepted — `false` for a redelivery of one already handed over. */
+    push(item: T, opId: string): boolean;
+    /** The next item, or null once `waitMs` elapses. Never rejects: nothing to do is not a failure. */
+    take(waitMs: number): Promise<T | null>;
+    opIdOf(id: string): string | null;
+    outstandingById(id: string): T | null;
+    /** Handed out and still unanswered, oldest first. */
+    outstanding(): T[];
+    settle(id: string): void;
+    size(): number;
+}
+//# sourceMappingURL=queue.d.ts.map

package/build/session/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../../src/session/queue.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,OAAO,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAChD;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoB;IACzC;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD,oGAAoG;IACpG,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAgBnC;IAED,mGAAmG;IAC7F,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAuB5C;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEhC;IAED,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAEpC;IAED,qDAAqD;IACrD,WAAW,IAAI,CAAC,EAAE,CAEjB;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAGvB;IAED,IAAI,IAAI,MAAM,CAEb;CACF"}