conductor-remote 1.96.2 → 1.96.3

package/dist-node/src/delegations.js

@@ -0,0 +1,556 @@
+/**
+ * Worktree-scoped delegated-job and session-role persistence.
+ *
+ * Conductor owns the chat history; these small files hold only active/failed work
+ * plus durable role identity. A decoder failure is public state, not permission to
+ * delete a file: callers receive warnings and the bytes remain for repair/dismissal.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { decodeRoles } from "./roles.js";
+const DIRECTORY = path.join('.context', 'delegations');
+const SESSIONS_FILE = 'sessions.json';
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const MAX_TEXT = 1_000_000;
+const STATUSES = new Set([
+    'queued',
+    'opening',
+    'configuring',
+    'sending',
+    'running',
+    'returning',
+    'returned',
+    'failed'
+]);
+const ERROR_CODES = new Set([
+    'invalid_request',
+    'role_not_found',
+    'model_missing',
+    'provider_unknown',
+    'same_provider',
+    'workspace_not_found',
+    'session_not_found',
+    'delegation_not_found',
+    'worktree_unavailable',
+    'state_invalid',
+    'opening_failed',
+    'configuration_failed',
+    'send_failed',
+    'completion_failed',
+    'return_failed'
+]);
+function object(raw) {
+    return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+}
+function text(value, field, maximum = 256) {
+    if (typeof value !== 'string' || !value.trim() || value.length > maximum)
+        throw new Error(`${field} is invalid`);
+    return value;
+}
+function integer(value, field, minimum = 0) {
+    if (!Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`${field} is invalid`);
+    return value;
+}
+function decodeError(raw, field) {
+    const value = object(raw);
+    if (!value || !ERROR_CODES.has(value.code))
+        throw new Error(`${field}.code is invalid`);
+    return {
+        code: value.code,
+        message: text(value.message, `${field}.message`, 10_000),
+        retryable: value.retryable === true
+    };
+}
+function decodeOutcome(raw) {
+    const value = object(raw);
+    if (!value)
+        throw new Error('outcome is invalid');
+    if (value.kind === 'success') {
+        return {
+            kind: 'success',
+            assistantRowid: integer(value.assistantRowid, 'outcome.assistantRowid', 1),
+            text: text(value.text, 'outcome.text', MAX_TEXT)
+        };
+    }
+    if (value.kind === 'error') {
+        return {
+            kind: 'error',
+            ...(value.assistantRowid === undefined
+                ? {}
+                : { assistantRowid: integer(value.assistantRowid, 'outcome.assistantRowid', 1) }),
+            ...(value.text === undefined ? {} : { text: text(value.text, 'outcome.text', MAX_TEXT) }),
+            error: text(value.error, 'outcome.error', 10_000)
+        };
+    }
+    throw new Error('outcome.kind is invalid');
+}
+function decodeAttachment(raw) {
+    const value = object(raw);
+    if (!value)
+        throw new Error('handoff is invalid');
+    return {
+        name: text(value.name, 'handoff.name', 256),
+        path: text(value.path, 'handoff.path', 1_024),
+        bytes: integer(value.bytes, 'handoff.bytes'),
+        token: text(value.token, 'handoff.token', 2_048)
+    };
+}
+function decodeResolvedRole(raw) {
+    const value = object(raw);
+    if (!value)
+        throw new Error('resolvedRole is invalid');
+    const agentType = text(value.agentType, 'resolvedRole.agentType', 64);
+    const role = decodeRoles({
+        version: 1,
+        roles: { resolved: Object.fromEntries(Object.entries(value).filter(([field]) => field !== 'agentType')) }
+    }).roles.resolved;
+    return { ...role, agentType };
+}
+function requireStageFields(job) {
+    if (['configuring', 'sending', 'running', 'returning', 'returned'].includes(job.status) && !job.childSessionId) {
+        throw new Error(`${job.status} requires childSessionId`);
+    }
+    if (job.status === 'sending' && !job.handoff)
+        throw new Error('sending requires handoff');
+    if (['running', 'returning', 'returned'].includes(job.status) && job.sentRowid === undefined) {
+        throw new Error(`${job.status} requires sentRowid`);
+    }
+    if (['returning', 'returned'].includes(job.status) && !job.outcome) {
+        throw new Error(`${job.status} requires outcome`);
+    }
+    if (job.returnCursor !== undefined && (!job.returnAttachment || !job.returnText)) {
+        throw new Error('a dispatched return requires returnAttachment and returnText');
+    }
+    if (job.status === 'returned' && job.returnRowid === undefined)
+        throw new Error('returned requires returnRowid');
+    if (job.status === 'failed' && !job.failure)
+        throw new Error('failed requires failure');
+}
+export function decodeDelegation(raw) {
+    const value = object(raw);
+    if (!value)
+        throw new Error('delegation must be an object');
+    if (value.version !== 1)
+        throw new Error(`unsupported delegation version ${String(value.version)}`);
+    const id = text(value.id, 'id', 128);
+    if (!SAFE_ID.test(id))
+        throw new Error('id is invalid');
+    const status = value.status;
+    if (!STATUSES.has(status))
+        throw new Error('status is invalid');
+    const returnMode = value.returnMode;
+    if (returnMode !== 'queue' && returnMode !== 'steer')
+        throw new Error('returnMode is invalid');
+    if (typeof value.includeThinking !== 'boolean')
+        throw new Error('includeThinking is invalid');
+    const job = {
+        version: 1,
+        id,
+        workspaceId: text(value.workspaceId, 'workspaceId'),
+        parentSessionId: text(value.parentSessionId, 'parentSessionId'),
+        ...(value.childSessionId === undefined ? {} : { childSessionId: text(value.childSessionId, 'childSessionId') }),
+        role: text(value.role, 'role', 64),
+        resolvedRole: decodeResolvedRole(value.resolvedRole),
+        prompt: text(value.prompt, 'prompt', MAX_TEXT),
+        returnMode,
+        includeThinking: value.includeThinking,
+        ...(value.throughRowid === undefined ? {} : { throughRowid: integer(value.throughRowid, 'throughRowid', 1) }),
+        status,
+        attempts: integer(value.attempts, 'attempts'),
+        createdAt: integer(value.createdAt, 'createdAt'),
+        updatedAt: integer(value.updatedAt, 'updatedAt'),
+        ...(value.handoff === undefined ? {} : { handoff: decodeAttachment(value.handoff) }),
+        ...(value.sentRowid === undefined ? {} : { sentRowid: integer(value.sentRowid, 'sentRowid', 1) }),
+        ...(value.completionRowid === undefined
+            ? {}
+            : { completionRowid: integer(value.completionRowid, 'completionRowid', 1) }),
+        ...(value.returnCursor === undefined ? {} : { returnCursor: integer(value.returnCursor, 'returnCursor') }),
+        ...(value.returnAttachment === undefined ? {} : { returnAttachment: decodeAttachment(value.returnAttachment) }),
+        ...(value.returnText === undefined ? {} : { returnText: text(value.returnText, 'returnText', MAX_TEXT) }),
+        ...(value.returnRowid === undefined ? {} : { returnRowid: integer(value.returnRowid, 'returnRowid', 1) }),
+        ...(value.outcome === undefined ? {} : { outcome: decodeOutcome(value.outcome) }),
+        ...(value.failure === undefined ? {} : { failure: decodeError(value.failure, 'failure') }),
+        ...(value.lastAttemptAt === undefined ? {} : { lastAttemptAt: integer(value.lastAttemptAt, 'lastAttemptAt') })
+    };
+    requireStageFields(job);
+    return job;
+}
+function decodeSessionRoles(raw) {
+    const value = object(raw);
+    if (!value)
+        throw new Error('session roles must be an object');
+    if (value.version !== 1)
+        throw new Error(`unsupported session roles version ${String(value.version)}`);
+    const sessions = object(value.sessions);
+    if (!sessions)
+        throw new Error('sessions must be an object');
+    const decoded = {};
+    for (const [sessionId, rawAssignment] of Object.entries(sessions)) {
+        text(sessionId, 'session id');
+        const assignment = object(rawAssignment);
+        if (!assignment)
+            throw new Error(`session ${sessionId} role is invalid`);
+        const delegationId = assignment.delegationId;
+        if (delegationId !== undefined && (typeof delegationId !== 'string' || !SAFE_ID.test(delegationId))) {
+            throw new Error(`session ${sessionId} delegationId is invalid`);
+        }
+        decoded[sessionId] = {
+            role: text(assignment.role, `session ${sessionId} role`, 64),
+            ...(delegationId === undefined ? {} : { delegationId }),
+            assignedAt: integer(assignment.assignedAt, `session ${sessionId} assignedAt`)
+        };
+    }
+    return decoded;
+}
+function atomicWrite(file, value) {
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(value, null, '\t')}\n`, { mode: 0o600 });
+        fs.chmodSync(temporary, 0o600);
+        fs.renameSync(temporary, file);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { }
+        throw err;
+    }
+}
+export class DelegationStore {
+    directory;
+    constructor(worktree) {
+        this.directory = path.join(worktree, DIRECTORY);
+    }
+    list() {
+        let files;
+        try {
+            files = fs
+                .readdirSync(this.directory)
+                .filter(file => file.endsWith('.json') && file !== SESSIONS_FILE)
+                .sort();
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return { jobs: [], warnings: [] };
+            return { jobs: [], warnings: [{ file: this.directory, message: String(err) }] };
+        }
+        const jobs = [];
+        const warnings = [];
+        for (const file of files) {
+            try {
+                jobs.push(decodeDelegation(JSON.parse(fs.readFileSync(path.join(this.directory, file), 'utf8'))));
+            }
+            catch (err) {
+                warnings.push({ file, message: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        return { jobs, warnings };
+    }
+    get(id) {
+        if (!SAFE_ID.test(id))
+            return null;
+        try {
+            return decodeDelegation(JSON.parse(fs.readFileSync(path.join(this.directory, `${id}.json`), 'utf8')));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    put(raw) {
+        const job = decodeDelegation(raw);
+        atomicWrite(path.join(this.directory, `${job.id}.json`), job);
+        return job;
+    }
+    remove(id) {
+        if (!SAFE_ID.test(id))
+            return false;
+        try {
+            fs.unlinkSync(path.join(this.directory, `${id}.json`));
+            return true;
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return false;
+            throw err;
+        }
+    }
+    sessionRoles() {
+        const file = path.join(this.directory, SESSIONS_FILE);
+        try {
+            return { sessions: decodeSessionRoles(JSON.parse(fs.readFileSync(file, 'utf8'))) };
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return { sessions: {} };
+            return { sessions: {}, warning: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    assign(sessionId, assignment) {
+        text(sessionId, 'session id');
+        const current = this.sessionRoles();
+        if (current.warning)
+            throw new Error(`cannot update malformed sessions.json: ${current.warning}`);
+        const sessions = decodeSessionRoles({
+            version: 1,
+            sessions: { ...current.sessions, [sessionId]: assignment }
+        });
+        atomicWrite(path.join(this.directory, SESSIONS_FILE), { version: 1, sessions });
+    }
+}
+// ── guarded transitions and the single queue producer ──────────────────────────
+const NEXT = {
+    queued: ['opening', 'failed'],
+    opening: ['configuring', 'failed'],
+    configuring: ['sending', 'failed'],
+    sending: ['running', 'failed'],
+    running: ['returning', 'failed'],
+    returning: ['returned', 'failed'],
+    returned: [],
+    failed: []
+};
+/** Pure state edge: only stage data may change; the accepted envelope stays frozen. */
+export function transitionDelegation(job, status, patch, updatedAt = Date.now()) {
+    if (!NEXT[job.status].includes(status))
+        throw new Error(`illegal delegation transition ${job.status} → ${status}`);
+    if (status === 'failed' && !patch.failure)
+        throw new Error('failed requires failure');
+    return decodeDelegation({
+        ...job,
+        status,
+        updatedAt,
+        ...(patch.childSessionId === undefined ? {} : { childSessionId: patch.childSessionId }),
+        ...(patch.handoff === undefined ? {} : { handoff: patch.handoff }),
+        ...(patch.sentRowid === undefined ? {} : { sentRowid: patch.sentRowid }),
+        ...(patch.completionRowid === undefined ? {} : { completionRowid: patch.completionRowid }),
+        ...(patch.returnCursor === undefined ? {} : { returnCursor: patch.returnCursor }),
+        ...(patch.returnAttachment === undefined ? {} : { returnAttachment: patch.returnAttachment }),
+        ...(patch.returnText === undefined ? {} : { returnText: patch.returnText }),
+        ...(patch.returnRowid === undefined ? {} : { returnRowid: patch.returnRowid }),
+        ...(patch.outcome === undefined ? {} : { outcome: patch.outcome }),
+        ...(patch.failure === undefined ? {} : { failure: patch.failure }),
+        ...(patch.attempts === undefined ? {} : { attempts: patch.attempts }),
+        ...(patch.lastAttemptAt === undefined ? {} : { lastAttemptAt: patch.lastAttemptAt })
+    });
+}
+function actionCode(status) {
+    if (status === 'opening')
+        return 'opening_failed';
+    if (status === 'configuring')
+        return 'configuration_failed';
+    if (status === 'sending')
+        return 'send_failed';
+    if (status === 'returning')
+        return 'return_failed';
+    return 'state_invalid';
+}
+/**
+ * One producer for every worktree registered with this process. It performs at
+ * most one side effect at a time and stops at `running`; the shared session poller
+ * calls `wake()` on later ticks. That keeps waiting jobs out of the UI lock.
+ */
+export class DelegationQueue {
+    deps;
+    now;
+    retryDelayMs;
+    maxAttempts;
+    blockedError;
+    onError;
+    stores = new Set();
+    completionCandidates = new Map();
+    pumping = null;
+    rerun = false;
+    constructor(deps, options = {}) {
+        this.deps = deps;
+        this.now = options.now ?? Date.now;
+        this.retryDelayMs = options.retryDelayMs ?? 5_000;
+        this.maxAttempts = options.maxAttempts ?? 3;
+        this.blockedError = options.blockedError ?? (() => false);
+        this.onError = options.onError ?? (message => console.warn(`[relay] ${message}`));
+    }
+    /** Persist intake before returning, then let the queue finish independently. */
+    enqueue(store, raw) {
+        const roles = store.sessionRoles();
+        if (roles.warning)
+            throw new Error(`cannot enqueue beside malformed sessions.json: ${roles.warning}`);
+        if (!roles.sessions[raw.parentSessionId]) {
+            store.assign(raw.parentSessionId, { role: 'planning', assignedAt: raw.createdAt });
+        }
+        const job = store.put(raw);
+        this.stores.add(store);
+        void this.wake();
+        return job;
+    }
+    /** Register persisted work from startup without rewriting it. */
+    resume(stores) {
+        for (const store of stores)
+            this.stores.add(store);
+        void this.wake();
+    }
+    /** One shared-poller tick (or intake); concurrent calls join the same producer. */
+    wake() {
+        this.rerun = true;
+        if (!this.pumping) {
+            this.pumping = this.pump()
+                .catch(err => this.onError(`delegation queue failed: ${err instanceof Error ? err.message : err}`))
+                .finally(() => {
+                this.pumping = null;
+                if (this.rerun)
+                    void this.wake();
+            });
+        }
+        return this.pumping;
+    }
+    async invoke(status, action) {
+        try {
+            return await action();
+        }
+        catch (err) {
+            return {
+                ok: false,
+                code: actionCode(status),
+                error: err instanceof Error ? err.message : String(err),
+                retryable: true,
+                blocked: this.blockedError(err)
+            };
+        }
+    }
+    async pump() {
+        do {
+            this.rerun = false;
+            while (await this.stepOne()) { }
+        } while (this.rerun);
+    }
+    /** Find one job able to make progress. Waiting/blocked jobs do not hold up others. */
+    async stepOne() {
+        const entries = [...this.stores]
+            .flatMap(store => store.list().jobs.map(job => ({ store, job })))
+            .sort((a, b) => a.job.createdAt - b.job.createdAt || a.job.id.localeCompare(b.job.id));
+        for (const { store, job } of entries) {
+            if (job.status === 'failed')
+                continue;
+            if (job.status === 'returned') {
+                store.remove(job.id);
+                return true;
+            }
+            if (job.status === 'queued') {
+                store.put(transitionDelegation(job, 'opening', {}, this.now()));
+                return true;
+            }
+            if (this.retryPending(job))
+                continue;
+            if (job.status === 'opening') {
+                const result = await this.invoke('opening', () => this.deps.open(job));
+                if (!result.ok) {
+                    if (this.recordFailure(store, job, result))
+                        return true;
+                    continue;
+                }
+                store.assign(result.childSessionId, {
+                    role: job.role,
+                    delegationId: job.id,
+                    assignedAt: this.now()
+                });
+                store.put(transitionDelegation(job, 'configuring', { childSessionId: result.childSessionId, handoff: result.handoff }, this.now()));
+                return true;
+            }
+            if (job.status === 'configuring') {
+                const result = await this.invoke('configuring', () => this.deps.configure(job));
+                if (!result.ok) {
+                    if (this.recordFailure(store, job, result))
+                        return true;
+                    continue;
+                }
+                store.put(transitionDelegation(job, 'sending', {}, this.now()));
+                return true;
+            }
+            if (job.status === 'sending') {
+                const result = await this.invoke('sending', () => this.deps.send(job));
+                if (!result.ok) {
+                    if (this.recordFailure(store, job, result))
+                        return true;
+                    continue;
+                }
+                store.put(transitionDelegation(job, 'running', { sentRowid: result.sentRowid }, this.now()));
+                return true;
+            }
+            if (job.status === 'running') {
+                let completion;
+                try {
+                    completion = await this.deps.completion(job);
+                }
+                catch (err) {
+                    console.warn(`[relay] delegation completion read failed: ${err instanceof Error ? err.message : err}`);
+                    continue;
+                }
+                const key = `${job.workspaceId}\0${job.id}`;
+                if (!completion) {
+                    this.completionCandidates.delete(key);
+                    continue;
+                }
+                const signature = JSON.stringify(completion);
+                if (this.completionCandidates.get(key) !== signature) {
+                    this.completionCandidates.set(key, signature);
+                    continue;
+                }
+                this.completionCandidates.delete(key);
+                store.put(transitionDelegation(job, 'returning', { outcome: completion.outcome, completionRowid: completion.completionRowid }, this.now()));
+                return true;
+            }
+            if (job.status === 'returning') {
+                const result = await this.invoke('returning', () => this.deps.returnResult(job));
+                if (!result.ok) {
+                    if (this.recordFailure(store, job, result))
+                        return true;
+                    continue;
+                }
+                if ('pending' in result) {
+                    // A queued Baton clears the composer before SQLite exposes any row.
+                    // Persist the pre-dispatch cursor once, then only poll for the exact
+                    // eventual row; repeating the UI action here would enqueue a duplicate.
+                    if (job.returnCursor === result.returnCursor)
+                        continue;
+                    store.put(decodeDelegation({
+                        ...job,
+                        returnCursor: result.returnCursor,
+                        returnAttachment: result.returnAttachment,
+                        returnText: result.returnText,
+                        updatedAt: this.now()
+                    }));
+                    return true;
+                }
+                store.put(transitionDelegation(job, 'returned', { returnRowid: result.returnRowid }, this.now()));
+                return true;
+            }
+        }
+        return false;
+    }
+    retryPending(job) {
+        return job.attempts > 0 && job.lastAttemptAt !== undefined && this.now() - job.lastAttemptAt < this.retryDelayMs;
+    }
+    /** True when persistence changed; false for a lock-blocked/no-cost attempt. */
+    recordFailure(store, job, result) {
+        if (result.blocked)
+            return false;
+        const attempts = job.attempts + 1;
+        const now = this.now();
+        if (attempts >= this.maxAttempts || result.retryable === false) {
+            store.put(transitionDelegation(job, 'failed', {
+                attempts,
+                lastAttemptAt: now,
+                failure: {
+                    code: result.code ?? actionCode(job.status),
+                    message: result.error,
+                    retryable: result.retryable !== false
+                }
+            }, now));
+            return true;
+        }
+        store.put(decodeDelegation({ ...job, attempts, lastAttemptAt: now, updatedAt: now }));
+        return true;
+    }
+}

package/dist-node/src/firstprompt.js

@@ -89,7 +89,7 @@ export class FirstPromptQueue {
      * prompt lands (`null`) or is given up on (the failed entry) — awaited by API
      * callers that asked to block, ignored by the phone.
      */
-    enqueue(workspaceId, text, sendImmediately = true, attachmentIds = [], agent) {
+    enqueue(workspaceId, text, sendImmediately = true, attachmentIds = [], agent, sessionRole) {
         this.entries = [
             ...this.entries.filter(e => e.workspaceId !== workspaceId),
             {
@@ -97,6 +97,7 @@ export class FirstPromptQueue {
                 text,
                 ...(agent && Object.keys(agent).length ? { agent } : {}),
                 ...(attachmentIds.length ? { attachmentIds } : {}),
+                ...(sessionRole ? { sessionRole } : {}),
                 status: 'waiting',
                 attempts: 0,
                 createdAt: Date.now(),
@@ -185,6 +186,17 @@ export class FirstPromptQueue {
         }
         if (!target?.sessionId)
             return;
+        if (entry.sessionRole && !entry.sessionRoleAssigned) {
+            if (!target.worktree)
+                return;
+            if (!this.deps.assignRole)
+                return this.fail(entry, 'the relay cannot assign the workflow root role');
+            const assigned = await this.deps.assignRole(entry.workspaceId, target.sessionId, entry.sessionRole, entry.createdAt);
+            if (!assigned.ok)
+                return this.fail(entry, assigned.error ?? 'the workflow root role could not be saved');
+            entry.sessionRoleAssigned = true;
+            this.save();
+        }
         // It already went — the user sent it from the Mac, where the deep link left it
         // pre-filled in the composer. Sending again would double it, and changing the
         // agent now would affect a later turn instead of the first one they configured.
@@ -309,6 +321,8 @@ export class FirstPromptQueue {
                 Date.now() - (e.createdAt ?? 0) < KEEP_FAILED_MS)
                 .map(e => ({
                 ...e,
+                sessionRole: typeof e.sessionRole === 'string' && e.sessionRole.trim() ? e.sessionRole.trim() : undefined,
+                sessionRoleAssigned: e.sessionRoleAssigned === true ? true : undefined,
                 attachmentIds: Array.isArray(e.attachmentIds)
                     ? e.attachmentIds.filter((id) => typeof id === 'string')
                     : undefined