@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/dist/src/lavish-tools.js

@@ -0,0 +1,400 @@
+/** Host-owned Lavish Editor lifecycle tools for issue #443. */
+import { realpath } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { LavishLocalSession, } from '../capabilities/lavish-local.js';
+export function registerLavishTools(options) {
+    const cliPackageRoot = options.getConfig().lavishAxiPackageRoot ?? '';
+    if (cliPackageRoot.length === 0)
+        return { registered: false, reason: 'lavishAxiPackageRoot is not configured' };
+    if (!isAbsolute(cliPackageRoot))
+        return { registered: false, reason: 'lavishAxiPackageRoot must be absolute' };
+    const records = new Map();
+    const disposedIds = new Set();
+    // Registrar-wide terminal: once set, bind() refuses any new record creation
+    // or reuse, regardless of authority or cwd. Set synchronously by the plugin
+    // unload disposer before any await so unload cannot race a late bind call.
+    let closed = false;
+    const closedFailure = () => failure('lavish-plugin-closed', 'Lavish plugin is unloaded; no new host sessions may be opened');
+    const bind = async (exec) => {
+        const authority = readAuthority(exec);
+        if (!authority.ok)
+            return failure('lavish-authority-rejected', authority.detail);
+        if (closed)
+            return closedFailure();
+        if (disposedIds.has(authority.id))
+            return failure('lavish-session-terminal', `host session ${authority.id} was disposed`);
+        const existing = records.get(authority.id);
+        if (existing && existing.rawCwd !== authority.cwd) {
+            return failure('lavish-cwd-drift', `host session ${authority.id} is already bound to a different raw cwd`);
+        }
+        let canonicalCwd;
+        try {
+            canonicalCwd = await realpath(authority.cwd);
+        }
+        catch {
+            return failure('lavish-authority-rejected', 'host session header.cwd must name an existing directory');
+        }
+        if (closed)
+            return closedFailure();
+        if (disposedIds.has(authority.id))
+            return failure('lavish-session-terminal', `host session ${authority.id} was disposed`);
+        // Another first call for this id may have bound the record while realpath awaited.
+        const bound = records.get(authority.id);
+        if (bound) {
+            if (bound.rawCwd !== authority.cwd || bound.canonicalCwd !== canonicalCwd) {
+                return failure('lavish-cwd-drift', `host session ${authority.id} canonical cwd changed`);
+            }
+            return bound;
+        }
+        if (closed)
+            return closedFailure();
+        const record = {
+            id: authority.id,
+            rawCwd: authority.cwd,
+            canonicalCwd,
+            session: null,
+            terminal: null,
+            tail: Promise.resolve(),
+            cleanup: null,
+            stopResult: null,
+        };
+        records.set(authority.id, record);
+        return record;
+    };
+    const runActive = async (exec, operation) => {
+        const record = await bind(exec);
+        if (!isRecord(record))
+            return record;
+        return enqueue(record, async () => {
+            if (record.terminal)
+                return terminalFailure(record);
+            return operation(record);
+        });
+    };
+    const getSession = async (record) => {
+        if (record.session)
+            return record.session;
+        const creation = LavishLocalSession.create({
+            cliPackageRoot,
+            cwd: record.rawCwd,
+            allowedRoot: record.rawCwd,
+        });
+        try {
+            const session = await creation;
+            record.session = session;
+            return session;
+        }
+        catch (error) {
+            return failure('lavish-create-failed', error instanceof Error ? error.message : 'Lavish session creation failed');
+        }
+    };
+    const finishCommand = async (record, result) => {
+        // Snapshot host authority before any adapter signal latches: a stop/dispose
+        // that fired during this in-flight command must preserve its precedence
+        // over a just-completed user-ended / poll-outcome-unknown result.
+        const prior = record.terminal;
+        latchAdapterTerminal(record, result);
+        if (prior === 'disposed' || prior === 'stopped') {
+            record.terminal = prior;
+            await cleanup(record);
+            return terminalFailure(record);
+        }
+        if (record.terminal === 'disposed' || record.terminal === 'stopped') {
+            await cleanup(record);
+            return terminalFailure(record);
+        }
+        return present(result);
+    };
+    const finishEnd = async (record, result) => {
+        // End must preserve host authority: a concurrent stop/dispose that fired
+        // during this end() call retains terminal, and the explicit 'ended'
+        // latch must not overwrite an existing 'ended' / 'stopped' / 'disposed'.
+        const prior = record.terminal;
+        latchAdapterTerminal(record, result);
+        if (prior === 'disposed' || prior === 'stopped') {
+            record.terminal = prior;
+            await cleanup(record);
+            return terminalFailure(record);
+        }
+        if (record.terminal === 'disposed' || record.terminal === 'stopped') {
+            await cleanup(record);
+            return terminalFailure(record);
+        }
+        if (result.ok && !record.terminal)
+            record.terminal = 'ended';
+        return present(result);
+    };
+    options.register(defineTool({
+        name: 'gotry_lavish_open',
+        description: 'Open an existing HTML artifact in the host-owned local Lavish Editor. The trusted pinned CLI and workspace root come only from host configuration and session metadata.',
+        parameters: { path: { type: 'string', required: true, description: 'HTML/HTM artifact path under the host session cwd' } },
+        output: outputPresentation('Lavish open'),
+        async execute(args, exec) {
+            return runActive(exec, async (record) => {
+                const session = await getSession(record);
+                if (!isSession(session))
+                    return session;
+                if (record.terminal) {
+                    await cleanup(record);
+                    return terminalFailure(record);
+                }
+                const result = await session.open(args.path);
+                return finishCommand(record, result);
+            });
+        },
+        presentCall: args => callPresentation('Lavish open', args),
+        presentResult: resultPresentation('Lavish open'),
+    }));
+    options.register(defineTool({
+        name: 'gotry_lavish_poll',
+        description: 'Wait once for untrusted user feedback from the host session Lavish Editor. An uncertain poll outcome is terminal because retrying could double-consume feedback.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'Previously opened HTML/HTM artifact path' },
+            timeoutMs: { type: 'integer', description: 'Optional bounded positive poll timeout in milliseconds' },
+        },
+        output: outputPresentation('Lavish poll'),
+        async execute(args, exec) {
+            return runActive(exec, async (record) => {
+                if (!record.session)
+                    return failure('lavish-session-missing', 'call gotry_lavish_open first');
+                const result = await record.session.poll(args.path, args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs });
+                return finishCommand(record, result);
+            });
+        },
+        presentCall: args => callPresentation('Lavish poll', args),
+        presentResult: resultPresentation('Lavish poll'),
+    }));
+    options.register(defineTool({
+        name: 'gotry_lavish_reply',
+        description: 'Send one bounded visible reply and wait once for the next untrusted Lavish feedback state.',
+        parameters: {
+            path: { type: 'string', required: true, description: 'Previously opened HTML/HTM artifact path' },
+            reply: { type: 'string', required: true, description: 'Visible reply text' },
+            timeoutMs: { type: 'integer', description: 'Optional bounded positive poll timeout in milliseconds' },
+        },
+        output: outputPresentation('Lavish reply'),
+        async execute(args, exec) {
+            return runActive(exec, async (record) => {
+                if (!record.session)
+                    return failure('lavish-session-missing', 'call gotry_lavish_open first');
+                const result = await record.session.reply(args.path, args.reply, args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs });
+                return finishCommand(record, result);
+            });
+        },
+        presentCall: args => callPresentation('Lavish reply', args),
+        presentResult: resultPresentation('Lavish reply'),
+    }));
+    options.register(defineTool({
+        name: 'gotry_lavish_end',
+        description: 'End the current Lavish review session while retaining the owned server handle for explicit stop or host disposal cleanup.',
+        parameters: { path: { type: 'string', required: true, description: 'Previously opened HTML/HTM artifact path' } },
+        output: outputPresentation('Lavish end'),
+        async execute(args, exec) {
+            return runActive(exec, async (record) => {
+                if (!record.session)
+                    return failure('lavish-session-missing', 'call gotry_lavish_open first');
+                const result = await record.session.end(args.path);
+                return finishEnd(record, result);
+            });
+        },
+        presentCall: args => callPresentation('Lavish end', args),
+        presentResult: resultPresentation('Lavish end'),
+    }));
+    options.register(defineTool({
+        name: 'gotry_lavish_stop',
+        description: 'Terminally stop and reap only the Lavish server owned by this exact host session. Cleanup failure remains visible on later stop calls.',
+        parameters: {},
+        output: outputPresentation('Lavish stop'),
+        async execute(_args, exec) {
+            const authority = readAuthority(exec);
+            if (!authority.ok)
+                return failure('lavish-authority-rejected', authority.detail);
+            let record = records.get(authority.id);
+            if (record) {
+                if (record.rawCwd !== authority.cwd)
+                    return failure('lavish-cwd-drift', `host session ${authority.id} is bound to a different raw cwd`);
+                // Terminal before any await: an in-flight create/open cannot publish success afterwards.
+                record.terminal = record.terminal ?? 'stopped';
+            }
+            else {
+                if (disposedIds.has(authority.id)) {
+                    return present({ ok: true, kind: 'stop', status: 'not-running', ownedServerExited: true });
+                }
+                const bound = await bind(exec);
+                if (!isRecord(bound))
+                    return bound;
+                record = bound;
+                record.terminal = 'stopped';
+            }
+            return enqueue(record, async () => present(await cleanup(record)));
+        },
+        presentCall: args => callPresentation('Lavish stop', args),
+        presentResult: resultPresentation('Lavish stop'),
+    }));
+    const ctxOn = options.ctx.on;
+    if (typeof ctxOn === 'function') {
+        ;
+        ctxOn.call(options.ctx, 'session/disposed', async (subject) => {
+            const id = disposedSubjectId(subject);
+            if (!id)
+                return;
+            disposedIds.add(id);
+            const record = records.get(id);
+            if (!record)
+                return;
+            // Terminal before any await: queued and in-flight commands re-check this state.
+            record.terminal = 'disposed';
+            await enqueue(record, async () => { await cleanup(record); });
+        });
+    }
+    const ctxEffect = options.ctx.effect;
+    if (typeof ctxEffect === 'function') {
+        ;
+        ctxEffect.call(options.ctx, () => async () => {
+            // Synchronous registrar closure before any await: a bind() call that
+            // is currently awaiting realpath (or about to start one) must observe
+            // the closed flag and refuse to create a new record, regardless of
+            // whether the bind target id is fresh or already known. This is the
+            // only point where closed becomes true.
+            closed = true;
+            const active = [...records.values()];
+            // Freeze every record before awaiting any queue, so unload cannot race a late command.
+            for (const record of active) {
+                disposedIds.add(record.id);
+                record.terminal = 'disposed';
+            }
+            const results = await Promise.all(active.map(record => enqueue(record, () => cleanup(record))));
+            const unreaped = results.filter(result => !result.ok || result.ownedServerExited !== true);
+            if (unreaped.length > 0) {
+                throw new Error(`Lavish plugin cleanup failed: ${unreaped.map(item => item.ok ? item.status : item.code).join(', ')}`);
+            }
+        }, 'gotry-lavish-lifecycle');
+    }
+    return { registered: true };
+}
+function enqueue(record, operation) {
+    const result = record.tail.then(operation);
+    record.tail = result.then(() => undefined, () => undefined);
+    return result;
+}
+async function cleanup(record) {
+    if (record.stopResult)
+        return record.stopResult;
+    if (record.cleanup)
+        return record.cleanup;
+    if (!record.session) {
+        const result = { ok: true, kind: 'stop', status: 'not-running', ownedServerExited: true };
+        record.stopResult = result;
+        return result;
+    }
+    const session = record.session;
+    record.cleanup = (async () => {
+        try {
+            const result = await session.stop();
+            record.stopResult = result;
+            return result;
+        }
+        catch (error) {
+            const result = {
+                ok: false,
+                kind: 'error',
+                code: 'command-failed',
+                detail: error instanceof Error ? error.message : 'Lavish cleanup failed',
+            };
+            record.stopResult = result;
+            return result;
+        }
+    })();
+    return record.cleanup;
+}
+function latchAdapterTerminal(record, result) {
+    // Host-authority terminals (stopped/disposed) and explicit 'ended' are
+    // precedence-preserving; adapter signals (user-ended / poll-outcome-unknown)
+    // must not overwrite them.
+    if (record.terminal === 'disposed' || record.terminal === 'stopped' || record.terminal === 'ended')
+        return;
+    const state = record.session?.state();
+    const view = result;
+    if (state?.pollOutcomeUnknown)
+        record.terminal = 'poll-outcome-unknown';
+    else if (state?.userEnded)
+        record.terminal = 'user-ended';
+    if (result && typeof result === 'object') {
+        if (view.code === 'poll-outcome-unknown')
+            record.terminal = 'poll-outcome-unknown';
+        if (view.code === 'session-user-ended')
+            record.terminal = 'user-ended';
+        if (view.sessionEnded === true && view.endedBy === 'user')
+            record.terminal = 'user-ended';
+        if (view.status === 'ended' && view.endedBy === 'user')
+            record.terminal = 'user-ended';
+    }
+}
+function readAuthority(exec) {
+    const candidate = exec;
+    const id = candidate?.agent?.session?.id;
+    if (typeof id !== 'string' || id.trim().length === 0) {
+        return { ok: false, detail: 'exec.agent.session.id is required; agent.id fallback is forbidden' };
+    }
+    const cwd = candidate?.agent?.session?.header?.cwd;
+    if (typeof cwd !== 'string' || cwd.trim().length === 0 || !isAbsolute(cwd)) {
+        return { ok: false, detail: 'exec.agent.session.header.cwd must be a nonblank absolute path' };
+    }
+    return { ok: true, id, cwd };
+}
+function disposedSubjectId(subject) {
+    if (!subject || typeof subject !== 'object')
+        return null;
+    const id = subject.id;
+    return typeof id === 'string' && id.trim().length > 0 ? id : null;
+}
+function isRecord(value) {
+    return 'rawCwd' in value && 'canonicalCwd' in value && 'tail' in value;
+}
+function isSession(value) {
+    return value instanceof LavishLocalSession;
+}
+function terminalFailure(record) {
+    return failure('lavish-session-terminal', `host session ${record.id} is terminal: ${record.terminal ?? 'unknown'}`);
+}
+function failure(code, detail) {
+    return { ok: false, code, error: detail, summary: `${code}: ${detail}`.slice(0, 800) };
+}
+function present(result) {
+    const view = result;
+    if (!view.ok) {
+        const detail = String(view.detail ?? view.error ?? 'Lavish operation failed');
+        return { ...view, error: detail, summary: `${String(view.code ?? 'lavish-error')}: ${detail}`.slice(0, 800) };
+    }
+    const summary = view.kind === 'open'
+        ? `Lavish opened ${String(view.file ?? '')} at ${String(view.url ?? '')}`
+        : `Lavish ${String(view.kind ?? 'operation')}: ${String(view.status ?? 'ok')}`;
+    return { ...view, summary };
+}
+function outputPresentation(title) {
+    return {
+        schema: { type: 'json' },
+        // The model needs the usable loopback URL and actual bounded feedback fields.
+        // Adapter feedback remains explicitly tagged `trust: "untrusted"` in this JSON.
+        render: (_args, value) => [{ type: 'text', text: renderValue(value, title) }],
+    };
+}
+function callPresentation(title, args) {
+    return { card: 'generic', title, kind: 'execute', rawInput: args };
+}
+function resultPresentation(title) {
+    return (_args, value) => ({
+        card: 'generic',
+        title,
+        content: [{ type: 'text', text: renderValue(value, title) }],
+    });
+}
+function renderValue(value, fallback) {
+    try {
+        return JSON.stringify(value).slice(0, 128 * 1024);
+    }
+    catch {
+        return String(value?.summary ?? fallback);
+    }
+}