@comput/pi-intercom 0.6.1 → 0.9.0

package/dist/core-worker-layout.js

@@ -0,0 +1,236 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { coreCall, locateTerminalTab, terminalAddress } from './herdr-core.js';
+/** Source-pinned adapter, NOT a public app-layout schema or a UI readiness probe.
+ * hc 0.1.18's public doc API treats values as opaque JSON. The layout below is
+ * backed by herdr-app 0.1.13 src/{mirror,mirror_sync,model,window}.rs:
+ * - Document::capture/replace uses machine-local IDs; View owns private focus.
+ * - Tab::new uses a row whose ID is the tab ID and one terminal block.
+ * - Model::fresh_id uses a prefix and 32 random hexadecimal digits.
+ * - window::reconcile/start_adoption consumes placement labels. Therefore write
+ *   and verify the document BEFORE labeling, never copy the caller's labels.
+ * Unknown metadata is retained. Unsupported/ambiguous trees fail closed.
+ */
+const DOCUMENT = 'herdr-app';
+const error = (message) => new Error(`PiIntercom HC worker layout: ${message}`);
+const positiveInteger = (n) => Number.isSafeInteger(n) && n > 0;
+/** All attach failures are post-creation uncertainty, including validation and
+ * CAS conflicts. No cleanup, retry, replacement, fallback, or terminal killing.
+ * The launcher must propagate this to its existing uncertain-launch fence. */
+export class CoreWorkerLayoutUncertainError extends Error {
+    outcomeUncertain = true;
+    constructor() {
+        super('PiIntercom HC worker layout attachment failed; outcome unknown, terminal/process and app tab may remain; no automatic cleanup/retry/replacement or fallback');
+        this.name = 'CoreWorkerLayoutUncertainError';
+    }
+}
+// A ticket is one attempt in this process, not persisted launch authorization.
+const tickets = new WeakSet();
+function normalizeCwd(value, platform) {
+    const paths = platform === 'win32' ? path.win32 : path.posix;
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0') || !paths.isAbsolute(value))
+        throw error('absolute root cwd required');
+    return platform === 'win32' ? paths.resolve(value).toLowerCase() : paths.resolve(value);
+}
+function live(record, address, createdMs) {
+    if (record?.address !== address || record.state !== 'live' || !positiveInteger(record.created_ms) ||
+        (createdMs !== undefined && record.created_ms !== createdMs))
+        throw error('terminal identity is not live or changed');
+}
+async function identity(call, expected) {
+    // CoreInfo.id is available in the verified hc 0.1.18 schema. Do not silently
+    // degrade an unavailable identity check into address-only ownership.
+    const status = await call('server.status', {});
+    const id = status?.core?.id;
+    if (typeof id !== 'string' || !id.trim() || (expected !== undefined && id !== expected))
+        throw error('current core identity unavailable or changed');
+    return id;
+}
+function snapshot(value) {
+    if (!Number.isSafeInteger(value?.version) || value.version < 0 || !value.value || typeof value.value !== 'object')
+        throw error('app document unavailable');
+    if (Buffer.byteLength(JSON.stringify(value.value), 'utf8') > 1024 * 1024)
+        throw error('app document exceeds core limit');
+    return value;
+}
+/** locateTerminalTab supplies bounded tree/ID checks. Additionally reject
+ * qualified IDs and inspect floating blocks so they cannot conceal a duplicate
+ * terminal or collide with a generated ID. Stack layouts are not supported by
+ * the shared locator and are deliberately rejected, not rewritten. */
+function inspect(value, caller) {
+    const location = locateTerminalTab(value, caller);
+    const ids = new Set(), terminals = new Set();
+    const localId = (id) => {
+        if (!id || id.length > 256 || /[\/\x00-\x20\x7f]/.test(id))
+            throw error('nonlocal app identity');
+        ids.add(id);
+    };
+    const content = (v) => {
+        if (v?.terminal !== undefined) {
+            terminalAddress(v.terminal);
+            if (terminals.has(v.terminal))
+                throw error('duplicate terminal placement');
+            terminals.add(v.terminal);
+        }
+    };
+    let floats = 0;
+    const node = (v) => {
+        localId(v.id);
+        if (v.type === 'block')
+            content(v.content);
+        if (v.floating !== undefined) {
+            if (!Array.isArray(v.floating))
+                throw error('invalid floating blocks');
+            for (const f of v.floating) {
+                if (++floats > 4096 || typeof f?.id !== 'string' || ids.has(f.id))
+                    throw error('ambiguous floating identity');
+                localId(f.id);
+                content(f.content);
+            }
+        }
+        if (v.type !== 'block')
+            for (const c of v.children)
+                node(c);
+    };
+    // Reserve all regular IDs before inspecting floats for cross-tree collisions.
+    const reserve = (v) => { localId(v.id); if (v.type !== 'block')
+        for (const c of v.children)
+            reserve(c); };
+    for (const s of value.spaces) {
+        localId(s.id);
+        for (const t of s.tabs) {
+            localId(t.id);
+            reserve(t.root);
+        }
+    }
+    for (const s of value.spaces)
+        for (const t of s.tabs)
+            node(t.root);
+    return { location, ids, terminals };
+}
+/** Call BEFORE hc run. Read-only: missing app document/mapping refuses launch.
+ * Labels are not authority: the current document must contain the caller once.
+ * This proves shared state, not that a remote window is connected/rendering. */
+export async function preflightCoreWorkerLayout(request, call = coreCall) {
+    const startedAtMs = Date.now();
+    terminalAddress(request.caller);
+    const platform = request.platform ?? process.platform;
+    if (platform !== 'linux' && platform !== 'win32')
+        throw error('unsupported platform');
+    const cwd = normalizeCwd(request.cwd, platform);
+    if (normalizeCwd(request.workspaceRoot, platform) !== cwd)
+        throw error('worker cwd must equal workspace root');
+    const name = request.name ?? 'Intercom (anonymous)';
+    if (typeof name !== 'string' || !name.trim() || name.length > 128 || /[\x00-\x1f\x7f]/.test(name))
+        throw error('invalid tab name');
+    const coreId = await identity(call);
+    const caller = await call('terminal.get', { terminal: request.caller });
+    live(caller, request.caller);
+    const doc = snapshot(await call('doc.get', { name: DOCUMENT }));
+    const { location } = inspect(doc.value, request.caller);
+    if (location.space.tabs.length >= 512)
+        throw error('app tab limit reached');
+    await identity(call, coreId);
+    live(await call('terminal.get', { terminal: request.caller }), request.caller, caller.created_ms);
+    const ticket = Object.freeze({ caller: request.caller, callerCreatedMs: caller.created_ms, coreId,
+        space: location.space.id, tab: location.tab.id, pane: location.pane.id,
+        version: doc.version, startedAtMs, cwd, platform, name });
+    tickets.add(ticket);
+    return ticket;
+}
+function worker(record, ticket, address, createdMs) {
+    live(record, address, createdMs);
+    if (record.parent !== ticket.caller || record.first_message != null ||
+        normalizeCwd(record.cwd, ticket.platform) !== ticket.cwd ||
+        (record.foreground != null && normalizeCwd(record.foreground.cwd, ticket.platform) !== ticket.cwd))
+        throw error('worker root cwd/parent differs from launch');
+}
+/** Call once AFTER hc run, with its full parsed RunResult (created_ms required).
+ * Appends exactly one dedicated tab in the caller's AUTHORITATIVE CURRENT space,
+ * using the current doc version, not the preflight version. No focus mutations.
+ * Returns shared-state confirmation only, never UI/Pi readiness. */
+export async function attachCoreWorkerLayout(ticket, created, call = coreCall) {
+    try {
+        if (!tickets.delete(ticket))
+            throw error('preflight ticket absent or already consumed');
+        const result = created;
+        terminalAddress(result?.address);
+        if (result.address === ticket.caller || !positiveInteger(result.created_ms) || result.created_ms < ticket.startedAtMs)
+            throw error('worker is not a fresh launch identity');
+        const address = result.address, createdMs = result.created_ms;
+        worker(result, ticket, address, createdMs);
+        await identity(call, ticket.coreId);
+        live(await call('terminal.get', { terminal: ticket.caller }), ticket.caller, ticket.callerCreatedMs);
+        const record = await call('terminal.get', { terminal: address });
+        worker(record, ticket, address, createdMs);
+        // A pre-labeled worker may already have triggered app adoption. Do not
+        // race it, move it, borrow its tab, or attempt to undo that operation.
+        const unplaced = (r) => {
+            if (r.labels?.['herdr.space'] || r.labels?.['herdr.tab'])
+                throw error('worker already has placement labels');
+        };
+        unplaced(record);
+        const doc = snapshot(await call('doc.get', { name: DOCUMENT }));
+        if (doc.version < ticket.version)
+            throw error('app document version regressed since preflight');
+        const value = structuredClone(doc.value);
+        const { location, ids, terminals } = inspect(value, ticket.caller);
+        if (terminals.has(address) || location.space.tabs.length >= 512)
+            throw error('worker already placed or app tab limit reached');
+        const tab = `tb${randomUUID().replaceAll('-', '')}`, pane = `p${randomUUID().replaceAll('-', '')}`;
+        if (ids.has(tab) || ids.has(pane) || tab === pane)
+            throw error('generated app identity collision');
+        const added = { id: tab, name: ticket.name, root: { id: tab, type: 'row', children: [{ id: pane, type: 'block', content: { terminal: address } }] } };
+        location.space.tabs.push(added);
+        inspect(value, ticket.caller); // Also enforce post-append tree bounds.
+        snapshot({ version: doc.version, value });
+        await identity(call, ticket.coreId);
+        live(await call('terminal.get', { terminal: ticket.caller }), ticket.caller, ticket.callerCreatedMs);
+        const fresh = await call('terminal.get', { terminal: address });
+        worker(fresh, ticket, address, createdMs);
+        unplaced(fresh);
+        const written = await call('doc.set', { name: DOCUMENT, version: doc.version, value });
+        if (!Number.isSafeInteger(written?.version) || written.version !== doc.version + 1)
+            throw error('unconfirmed document write');
+        const confirm = async () => {
+            const observed = snapshot(await call('doc.get', { name: DOCUMENT }));
+            if (observed.version < written.version)
+                throw error('stale document readback');
+            const current = inspect(observed.value, ticket.caller).location;
+            const target = locateTerminalTab(observed.value, address);
+            if (current.space.id !== location.space.id || target.space.id !== current.space.id ||
+                target.tab.id !== tab || target.pane.id !== pane || !isDeepStrictEqual(target.tab, added))
+                throw error('placement readback differs');
+            // At the written version, every field must roundtrip, including metadata.
+            if (observed.version === written.version && !isDeepStrictEqual(observed.value, value))
+                throw error('document write differs');
+            return observed.version;
+        };
+        await confirm();
+        await identity(call, ticket.coreId);
+        live(await call('terminal.get', { terminal: ticket.caller }), ticket.caller, ticket.callerCreatedMs);
+        const beforeLabel = await call('terminal.get', { terminal: address });
+        worker(beforeLabel, ticket, address, createdMs);
+        unplaced(beforeLabel);
+        const labels = { 'herdr.space': location.space.id, 'herdr.tab': tab };
+        const labeled = await call('terminal.label', { terminal: address, labels });
+        const verifyLabels = (r) => {
+            worker(r, ticket, address, createdMs);
+            if (r.labels?.['herdr.space'] !== labels['herdr.space'] || r.labels?.['herdr.tab'] !== tab)
+                throw error('placement labels not confirmed');
+        };
+        verifyLabels(labeled);
+        verifyLabels(await call('terminal.get', { terminal: address }));
+        const version = await confirm();
+        await identity(call, ticket.coreId);
+        live(await call('terminal.get', { terminal: ticket.caller }), ticket.caller, ticket.callerCreatedMs);
+        return { terminal: address, terminalCreatedMs: createdMs, coreId: ticket.coreId, space: location.space.id, tab, pane, version, layoutConfirmed: true, uiAcknowledged: false };
+    }
+    catch {
+        // Do not leak transport payloads. This deliberately includes failures before
+        // our CAS: hc run has already happened and cannot safely be replayed.
+        throw new CoreWorkerLayoutUncertainError();
+    }
+}
+//# sourceMappingURL=core-worker-layout.js.map

package/dist/core-worker-layout.js.map

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

package/dist/herdr-core.d.ts

@@ -0,0 +1,53 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+export type CoreCall = (method: string, params: Record<string, unknown>) => Promise<any>;
+export interface CoreSessionOptions {
+    /** Explicit documented HC_SOCKET endpoint; no endpoint discovery or path guessing. */
+    endpoint?: string;
+    /** Test-only trusted seams. Supplying startClient requires readStatus. */
+    startClient?: () => ChildProcessWithoutNullStreams;
+    readStatus?: () => Promise<unknown>;
+    /** Tests may shorten, never extend, the ten-second whole-operation deadline. */
+    timeoutMs?: number;
+}
+/** Resolve only documented Unix defaults. An existing config may override the
+ * socket, so require explicit HC_SOCKET rather than silently ignoring that file. */
+export declare function defaultCoreEndpoint(env?: NodeJS.ProcessEnv, home?: string, uid?: number | undefined): Promise<string>;
+/** One bounded, sequential operation on ONE verified connection; never reconnects.
+ * Core v0.1.18 schema hello + server.status bind protocol, version, permanent core
+ * identity and (with CLI preflight) pid before the callback can send requests.
+ * This is not cryptographic authentication or a boot nonce; local endpoint access
+ * is the upstream trust boundary. The call handle expires with the callback.
+ *
+ * IMPORTANT: v0.1.18 cli.rs/server + platform/unix.rs status_may_start_core() show
+ * `hc server status` ITSELF autostarts on Unix. Unix therefore connects directly
+ * via HC_SOCKET or documented defaults (only when no config override can exist),
+ * without starting a process.
+ * Public contract: herdr-core v0.1.18 schema/README.md "Connecting" and
+ * docs/security.md "State and endpoints". No undocumented endpoint discovery.
+ * On Windows only, status is require_existing; preflight precedes hc connect.
+ * That check is NOT atomic start avoidance: core could disappear before connect.
+ * Use an explicit endpoint even on Windows when strict no-autostart is required.
+ */
+export declare function withCoreSession<T>(operation: (call: CoreCall) => Promise<T>, options?: CoreSessionOptions): Promise<T>;
+/** Standalone compatibility API: one call per bounded session. Multi-call operations
+ * MUST use withCoreSession, not repeated coreCall invocations. */
+export declare const coreCall: CoreCall;
+export declare function terminalAddress(value: unknown): asserts value is string;
+/** SOURCE-BACKED PRIVATE FORMAT, not a stable app API or production-readiness claim.
+ * herdr-app v0.1.13 src/mirror.rs Document/SharedSpace/SharedTab and src/layout.rs
+ * Node/Kind/Content define this opaque core doc. There is NO app-version handshake:
+ * core 0.1.18 alone cannot establish app compatibility. An upstream versioned
+ * layout contract is still needed. Tested subset: rows/columns, terminal/mod blocks,
+ * and mod-only floats (src/layout.rs Float), whose IDs are checked too. Reject
+ * stacks, terminal floats and dynamic context/agent content anywhere, including
+ * unrelated tabs, rather than silently miss aliases.
+ * Unknown metadata is preserved verbatim, not interpreted as a layout extension.
+ * Private focus state is separate and is never inferred or changed here. */
+export declare function locateTerminalTab(document: any, terminal: string): {
+    space: any;
+    tab: any;
+    pane: any;
+};
+/** Change only the owning tab name using the app's optimistic document protocol.
+ * Success proves shared state, not that an attached Windows window has rendered it. */
+export declare function renameCoreTab(terminal: string, name: string, call?: CoreCall): Promise<void>;