termdock 1.4.299 → 1.4.301

package/dist/server/agent/integrationSessions.js

@@ -0,0 +1,344 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { atomicJson, integrationError } from './integrationStore.js';
+/** Quote each configured argument as literal shell data, including paths. */
+export function integrationLaunchCommand(record, restore) {
+    const launchArgs = record.profile.argv.map(arg => arg === '{cwd}' ? record.cwd : arg);
+    const args = restore ? record.profile.resumeArgv.flatMap(arg => arg === '{launchArgs}' ? launchArgs
+        : [arg === '{sessionId}' ? record.agent_native_session_id : arg === '{cwd}' ? record.cwd : arg]) : launchArgs;
+    const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+    return `cd -- ${quote(record.cwd)} && ${[record.profile.executable, ...args].map(quote).join(' ')}`;
+}
+function startupInput(record, now) {
+    const condition = record.startup_condition ?? record.profile.startupInput;
+    return condition ? { state: 'pending', deadline: now + (condition.timeoutMs ?? 120000), matched_since: null, observed_at: null } : undefined;
+}
+export function publicIntegrationSession(record) {
+    const { profile: _, deadline: _deadline, launch_submitted: _submitted, startup_condition: _condition, ...publicRecord } = record;
+    return publicRecord;
+}
+export function permittedCwd(profile, cwd) {
+    if (typeof cwd !== 'string' || !path.isAbsolute(cwd) || /[\x00-\x1f\x7f]/.test(cwd))
+        integrationError('SESSION_CWD_DENIED', 'cwd must be absolute', 403);
+    let real;
+    try {
+        real = fs.realpathSync(cwd);
+        if (/[\x00-\x1f\x7f]/.test(real) || !fs.statSync(real).isDirectory())
+            throw new Error();
+    }
+    catch {
+        return integrationError('SESSION_CWD_MISSING', 'Task working directory must exist');
+    }
+    if (!profile.cwdRoots.some(root => { try {
+        const relative = path.relative(fs.realpathSync(root), real);
+        return !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
+    }
+    catch {
+        return false;
+    } }))
+        integrationError('SESSION_CWD_DENIED', 'Working directory is outside the configured roots', 403);
+    return real;
+}
+/** Creation intent and exact launch configuration are durable before any input
+ * enters a PTY. An ambiguous crash never starts another Agent automatically. */
+export class IntegrationSessions {
+    file;
+    adapter;
+    bindingTimeout;
+    doc = { version: 1, sessions: [], requests: {} };
+    pending = new Map();
+    listeners = new Set();
+    restoring = new Set();
+    timers = new Set();
+    stopObservation;
+    stopDeliveryGuard;
+    observing = false;
+    observeAgain = false;
+    constructor(file, adapter, bindingTimeout = 120000) {
+        this.file = file;
+        this.adapter = adapter;
+        this.bindingTimeout = bindingTimeout;
+        try {
+            const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (doc.version !== 1 || !Array.isArray(doc.sessions) || !doc.requests)
+                throw new Error('Invalid integration session store');
+            this.doc = doc;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        for (const record of this.doc.sessions)
+            if (['starting', 'restoring', 'binding_pending'].includes(record.state) || record.startup_input?.state === 'pending')
+                this.scheduleRefresh(record);
+        // A pre-restart partial match cannot prove continuity of the live screen.
+        for (const record of this.doc.sessions)
+            if (record.startup_input && record.startup_input.state !== 'observed')
+                record.startup_input.matched_since = null;
+        this.stopDeliveryGuard = adapter.registerDeliveryGuard?.(id => this.deliveryReadiness(id));
+        this.stopObservation = adapter.subscribe(() => { void this.refreshAll().catch(() => { }); });
+    }
+    scheduleRefresh(record) {
+        for (const deadline of new Set([record.deadline, ...(record.startup_input ? [record.startup_input.deadline] : [])])) {
+            const timer = setTimeout(() => { this.timers.delete(timer); void this.refresh(record.session_id).catch(() => { }); }, Math.max(1, deadline - Date.now() + 5));
+            timer.unref();
+            this.timers.add(timer);
+        }
+    }
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    snapshot() { return structuredClone(this.doc.sessions); }
+    save() { atomicJson(this.file, this.doc); for (const listener of this.listeners) {
+        try {
+            listener();
+        }
+        catch { /* Durable session state is reconciled on restart. */ }
+    } }
+    saveRecord(record) {
+        const before = this.doc.sessions;
+        this.doc.sessions = [...before.filter(s => s.session_id !== record.session_id), structuredClone(record)];
+        try {
+            this.save();
+        }
+        catch (error) {
+            this.doc.sessions = before;
+            throw error;
+        }
+    }
+    lookup(principal, id) {
+        const record = this.doc.sessions.find(s => s.session_id === id && s.group_id === principal.groupId && s.principal_id === principal.id);
+        if (!record)
+            integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Session is not owned by this integration', 404);
+        return structuredClone(record);
+    }
+    request(principal, key, input) {
+        if (!key || typeof key !== 'string' || key.length > 256)
+            integrationError('INVALID_IDEMPOTENCY_KEY', 'An idempotency key is required');
+        const scoped = `${principal.id}:${key}`, hash = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+        const previous = this.doc.requests[scoped];
+        if (previous && previous.hash !== hash)
+            integrationError('IDEMPOTENCY_CONFLICT', 'Key was already used for different session parameters', 409);
+        return { scoped, hash, previous };
+    }
+    async create(principal, input) {
+        const request = this.request(principal, input.idempotencyKey, ['create', input.profile, input.cwd]);
+        if (request.previous)
+            return this.pending.get(request.previous.sessionId) ?? this.get(principal, request.previous.sessionId);
+        const profile = principal.launchProfiles.find(p => p.id === input.profile);
+        if (!profile)
+            integrationError('LAUNCH_PROFILE_DENIED', 'Profile is not allowed by this integration', 403);
+        const cwd = permittedCwd(profile, input.cwd);
+        try {
+            fs.accessSync(profile.executable, fs.constants.X_OK);
+        }
+        catch {
+            return integrationError('LAUNCHER_UNAVAILABLE', 'Configured executable is not available');
+        }
+        if (this.doc.sessions.length >= 2000)
+            integrationError('INTEGRATION_SESSION_LIMIT', 'Integration session storage is full', 409);
+        const now = Date.now(), record = { operation_id: randomUUID(), session_id: randomBytes(6).toString('hex'),
+            group_id: principal.groupId, principal_id: principal.id, agent_slug: profile.agentSlug, agent_native_session_id: null,
+            state: 'starting', error_code: null, cwd, launch_profile: profile.id, profile: structuredClone(profile),
+            created_at: now, updated_at: now, deadline: now + this.bindingTimeout, launch_submitted: false };
+        record.startup_input = startupInput(record, now);
+        this.doc.requests[request.scoped] = { hash: request.hash, sessionId: record.session_id };
+        try {
+            this.saveRecord(record);
+        }
+        catch (error) {
+            delete this.doc.requests[request.scoped];
+            throw error;
+        }
+        return this.launch(record, false);
+    }
+    launch(record, restoring) {
+        const promise = (async () => {
+            try {
+                // Store intent before launching. A failed persistence cannot execute.
+                record.launch_submitted = true;
+                this.saveRecord(record);
+                const prepared = (binding) => { record.terminal_binding = binding; this.saveRecord(record); };
+                if (restoring)
+                    await this.adapter.restore(record, prepared);
+                else
+                    await this.adapter.create(record, prepared);
+                await this.refresh(record.session_id);
+                this.scheduleRefresh(record);
+            }
+            catch (error) {
+                const current = this.doc.sessions.find(s => s.session_id === record.session_id);
+                const code = error.code;
+                this.saveRecord({ ...current, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_LAUNCH_FAILED', updated_at: Date.now() });
+            }
+            return structuredClone(this.doc.sessions.find(s => s.session_id === record.session_id));
+        })().finally(() => this.pending.delete(record.session_id));
+        this.pending.set(record.session_id, promise);
+        return promise;
+    }
+    async get(principal, id) { this.lookup(principal, id); await this.refresh(id); return this.lookup(principal, id); }
+    async restore(principal, id, idempotencyKey) {
+        const request = this.request(principal, idempotencyKey, ['restore', id]);
+        if (request.previous)
+            return this.pending.get(id) ?? this.get(principal, id);
+        if (this.pending.has(id) || this.restoring.has(id))
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Another session operation is in progress', 409);
+        this.restoring.add(id);
+        try {
+            const record = await this.get(principal, id);
+            if (!record.agent_native_session_id)
+                integrationError('NATIVE_SESSION_ID_MISSING', 'An exact native session binding is required', 409);
+            // Recheck the current grant and actual directories; restore uses the
+            // original profile snapshot, never changed model or wrapper defaults.
+            if (!principal.launchProfiles.some(p => p.id === record.launch_profile))
+                integrationError('LAUNCH_PROFILE_DENIED', 'Original launch profile is no longer authorized', 403);
+            permittedCwd(record.profile, record.cwd);
+            const observed = await this.adapter.inspect(record);
+            if (observed.running) {
+                if (observed.agentSlug !== record.agent_slug || observed.nativeId !== record.agent_native_session_id)
+                    integrationError('SESSION_IDENTITY_MISMATCH', 'Existing process does not prove the exact native binding', 409);
+                this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id };
+                try {
+                    this.save();
+                }
+                catch (error) {
+                    delete this.doc.requests[request.scoped];
+                    throw error;
+                }
+                return record;
+            }
+            if (['starting', 'restoring', 'binding_pending'].includes(record.state))
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Prior launch outcome is not yet resolved; inspect the original session', 409);
+            if (observed.exists && !observed.shell)
+                integrationError('SESSION_TARGET_NOT_SHELL', 'Original pane is not a verified shell', 409);
+            record.state = 'restoring';
+            record.error_code = null;
+            record.operation_id = randomUUID();
+            record.deadline = Date.now() + this.bindingTimeout;
+            record.updated_at = Date.now();
+            if (!record.profile.startupInput && !record.startup_condition)
+                record.startup_condition = structuredClone(principal.launchProfiles.find(profile => profile.id === record.launch_profile)?.startupInput);
+            record.startup_input = startupInput(record, Date.now());
+            this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id };
+            try {
+                this.saveRecord(record);
+            }
+            catch (error) {
+                delete this.doc.requests[request.scoped];
+                throw error;
+            }
+            return await this.launch(record, true);
+        }
+        finally {
+            this.restoring.delete(id);
+        }
+    }
+    async refresh(id) {
+        const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
+        if (!record)
+            return;
+        let observed;
+        try {
+            observed = await this.adapter.inspect(record);
+        }
+        catch (error) {
+            const current = this.doc.sessions.find(s => s.session_id === id);
+            if (JSON.stringify(current) !== JSON.stringify(record))
+                return;
+            const code = error.code;
+            if (record.state !== 'failed' || record.error_code !== code)
+                this.saveRecord({ ...record, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_OBSERVATION_FAILED', updated_at: Date.now() });
+            return;
+        }
+        const next = { ...record };
+        if (observed.nativeId && (typeof observed.nativeId !== 'string' || observed.nativeId.length > 256 || /[\x00-\x1f\x7f]/.test(observed.nativeId))) {
+            next.state = 'failed';
+            next.error_code = 'NATIVE_SESSION_ID_INVALID';
+        }
+        else if (observed.running && observed.agentSlug !== record.agent_slug) {
+            next.state = 'failed';
+            next.error_code = 'SESSION_IDENTITY_MISMATCH';
+        }
+        else if (observed.running && observed.nativeId) {
+            if (record.agent_native_session_id && record.agent_native_session_id !== observed.nativeId) {
+                next.state = 'failed';
+                next.error_code = 'NATIVE_SESSION_ID_MISMATCH';
+            }
+            else {
+                next.agent_native_session_id = observed.nativeId;
+                if (next.terminal_binding)
+                    next.terminal_binding = { ...next.terminal_binding, nativeSessionId: observed.nativeId };
+                next.state = 'ready';
+                next.error_code = null;
+            }
+        }
+        else if (observed.running) {
+            next.state = Date.now() > record.deadline ? 'failed' : 'binding_pending';
+            next.error_code = next.state === 'failed' ? 'SESSION_BINDING_TIMEOUT' : null;
+        }
+        else if (record.state === 'ready') {
+            next.state = 'failed';
+            next.error_code = 'AGENT_NOT_RUNNING';
+        }
+        else if (Date.now() > record.deadline && record.state !== 'failed') {
+            next.state = 'failed';
+            next.error_code = 'SESSION_BINDING_TIMEOUT';
+        }
+        if (next.startup_input && next.startup_input.state !== 'observed') {
+            const condition = next.startup_condition ?? next.profile.startupInput;
+            let matched = false;
+            if (observed.running && observed.agentSlug === record.agent_slug && (!next.error_code || next.error_code === 'SESSION_BINDING_TIMEOUT') && this.adapter.capture) {
+                try {
+                    const fold = (text) => text.replace(/[^\S\r\n]+/g, ' ').trim();
+                    const viewport = fold(await this.adapter.capture(next));
+                    matched = condition.allOf.every(term => viewport.includes(fold(term))) && !(condition.noneOf ?? []).some(term => viewport.includes(fold(term)));
+                }
+                catch { /* Missing capture never opens the delivery guard. */ }
+            }
+            const input = { ...next.startup_input };
+            input.matched_since = matched ? input.matched_since ?? Date.now() : null;
+            if (matched && Date.now() - input.matched_since >= (condition.stableMs ?? 1000)) {
+                input.state = 'observed';
+                input.observed_at = Date.now();
+            }
+            else
+                input.state = Date.now() >= input.deadline ? 'timed_out' : 'pending';
+            next.startup_input = input;
+        }
+        if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+            return;
+        if (JSON.stringify(next) !== JSON.stringify(record)) {
+            next.updated_at = Date.now();
+            this.saveRecord(next);
+        }
+    }
+    /** Only gates configured launches. Native UUID and Agent turn state are not input prerequisites. */
+    async deliveryReadiness(id) {
+        if (!this.doc.sessions.find(record => record.session_id === id)?.startup_input)
+            return null;
+        await this.refresh(id);
+        const record = this.doc.sessions.find(record => record.session_id === id);
+        if (record.error_code && record.error_code !== 'SESSION_BINDING_TIMEOUT')
+            return { allowed: false, reason: record.error_code };
+        return record.startup_input.state === 'observed' ? { allowed: true, reason: null }
+            : { allowed: false, reason: record.startup_input.state === 'timed_out' ? 'SESSION_STARTUP_INPUT_TIMEOUT' : 'SESSION_STARTUP_INPUT_PENDING' };
+    }
+    async refreshAll() {
+        if (this.observing) {
+            this.observeAgain = true;
+            return;
+        }
+        this.observing = true;
+        try {
+            do {
+                this.observeAgain = false;
+                for (const record of this.snapshot())
+                    await this.refresh(record.session_id);
+            } while (this.observeAgain);
+        }
+        finally {
+            this.observing = false;
+        }
+    }
+    close() { this.stopObservation(); this.stopDeliveryGuard?.(); for (const timer of this.timers)
+        clearTimeout(timer); }
+}

package/dist/server/agent/integrationStore.js

@@ -0,0 +1,222 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { CollaborationError } from './collaborationProtocol.js';
+export const INTEGRATION_PROTOCOL = 1;
+export const INTEGRATION_OPERATIONS = ['task.read', 'task.create', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore'];
+export function integrationError(code, message, status = 400) { throw new CollaborationError(code, message, status); }
+export function atomicJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.tmp`;
+    const descriptor = fs.openSync(temporary, 'w', 0o600);
+    try {
+        fs.fchmodSync(descriptor, 0o600);
+        fs.writeFileSync(descriptor, JSON.stringify(value));
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+    fs.renameSync(temporary, file);
+    const directory = fs.openSync(path.dirname(file), 'r');
+    try {
+        fs.fsyncSync(directory);
+    }
+    finally {
+        fs.closeSync(directory);
+    }
+}
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+function identifier(value, label) {
+    if (typeof value !== 'string' || !/^[a-zA-Z0-9._-]{1,80}$/.test(value))
+        integrationError('INVALID_INTEGRATION_POLICY', `Invalid ${label}`);
+}
+export function validatePolicy(value) {
+    identifier(value?.id, 'principal id');
+    if (!value.groupId || typeof value.groupId !== 'string' || value.groupId.length > 160)
+        integrationError('INVALID_INTEGRATION_POLICY', 'A single groupId is required');
+    if (!Array.isArray(value.permissions) || value.permissions.some(p => !INTEGRATION_OPERATIONS.includes(p)))
+        integrationError('INVALID_INTEGRATION_POLICY', 'Unknown permission');
+    if (!Array.isArray(value.launchProfiles) || value.launchProfiles.length > 16)
+        integrationError('INVALID_INTEGRATION_POLICY', 'launchProfiles must be an array');
+    const ids = new Set();
+    for (const profile of value.launchProfiles) {
+        identifier(profile?.id, 'profile id');
+        identifier(profile.agentSlug, 'agent slug');
+        if (ids.has(profile.id))
+            integrationError('INVALID_INTEGRATION_POLICY', 'Duplicate launch profile');
+        ids.add(profile.id);
+        if (typeof profile.executable !== 'string' || !path.isAbsolute(profile.executable) || /[\x00-\x1f\x7f]/.test(profile.executable))
+            integrationError('INVALID_INTEGRATION_POLICY', 'Launcher must be an absolute path');
+        if (!Array.isArray(profile.argv) || !Array.isArray(profile.resumeArgv) || [...profile.argv, ...profile.resumeArgv].some(a => typeof a !== 'string' || /[\x00-\x1f\x7f]/.test(a) || a.length > 8192) || profile.argv.length > 128 || profile.resumeArgv.length > 128)
+            integrationError('INVALID_INTEGRATION_POLICY', 'Invalid structured argv');
+        if (profile.resumeArgv.filter(a => a === '{sessionId}').length !== 1 || profile.resumeArgv.filter(a => a === '{launchArgs}').length !== 1 || profile.resumeArgv.some(a => a.includes('{sessionId}') && a !== '{sessionId}') || profile.resumeArgv.includes('--last'))
+            integrationError('INVALID_INTEGRATION_POLICY', 'resumeArgv requires one {sessionId} and one {launchArgs}; --last is forbidden');
+        if (!Array.isArray(profile.cwdRoots) || !profile.cwdRoots.length || profile.cwdRoots.some(root => typeof root !== 'string' || !path.isAbsolute(root) || /[\x00-\x1f\x7f]/.test(root)))
+            integrationError('INVALID_INTEGRATION_POLICY', 'cwdRoots must be absolute paths');
+        if (profile.startupInput !== undefined) {
+            const condition = profile.startupInput;
+            const validTerms = (terms) => Array.isArray(terms) && terms.length <= 16
+                && terms.every(term => typeof term === 'string' && !!term.trim() && term.length <= 256 && !/[\x00-\x1f\x7f]/.test(term));
+            if (!condition || !validTerms(condition.allOf) || !condition.allOf.length || condition.noneOf !== undefined && !validTerms(condition.noneOf)
+                || condition.stableMs !== undefined && (!Number.isInteger(condition.stableMs) || condition.stableMs < 500 || condition.stableMs > 5000)
+                || condition.timeoutMs !== undefined && (!Number.isInteger(condition.timeoutMs) || condition.timeoutMs < 1000 || condition.timeoutMs > 120000)) {
+                integrationError('INVALID_INTEGRATION_POLICY', 'Invalid startupInput literal conditions or timing bounds');
+            }
+        }
+    }
+    // Policies contain launcher configuration, never authentication material.
+    return structuredClone({ id: value.id, groupId: value.groupId, permissions: value.permissions, launchProfiles: value.launchProfiles });
+}
+export class IntegrationStore {
+    file;
+    retention;
+    doc = { version: 1, principals: [], events: [], sequences: {}, prunedThrough: {}, sources: {}, consumers: {} };
+    listeners = new Set();
+    constructor(file, retention = 10000) {
+        this.file = file;
+        this.retention = retention;
+        try {
+            const document = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (document.version !== 1 || !Array.isArray(document.events) || !Array.isArray(document.principals) || !document.sources || !document.consumers || !document.sequences || !document.prunedThrough)
+                throw new Error('Invalid integration journal');
+            this.doc = document;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    write(next) {
+        if (Buffer.byteLength(JSON.stringify(next)) > 64 * 1024 * 1024)
+            integrationError('EVENT_STORAGE_FULL', 'Integration journal is full; no event was acknowledged', 503);
+        atomicJson(this.file, next);
+        this.doc = next;
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch { /* Subscription reports its own failure. */ }
+        }
+    }
+    subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
+    policies() { return this.doc.principals.map(({ tokenHash: _, ...principal }) => structuredClone(principal)); }
+    provision(policy) {
+        const checked = validatePolicy(policy);
+        if (this.doc.principals.some(p => p.id === checked.id))
+            integrationError('INTEGRATION_EXISTS', 'Use a new id; credentials cannot be silently replaced', 409);
+        const token = randomBytes(32).toString('base64url');
+        const next = structuredClone(this.doc);
+        next.principals.push({ ...checked, tokenHash: hash(token), revoked: false });
+        this.write(next);
+        return { principal: checked, token };
+    }
+    update(policy) {
+        const checked = validatePolicy(policy), next = structuredClone(this.doc);
+        const index = next.principals.findIndex(principal => principal.id === checked.id);
+        if (index < 0)
+            integrationError('INTEGRATION_NOT_FOUND', 'Integration does not exist', 404);
+        const existing = next.principals[index];
+        if (existing.revoked)
+            integrationError('INTEGRATION_REVOKED', 'Revoked identities cannot be reactivated', 403);
+        if (existing.groupId !== checked.groupId)
+            integrationError('INTEGRATION_GROUP_IMMUTABLE', 'An existing identity cannot change its group', 409);
+        next.principals[index] = { ...checked, tokenHash: existing.tokenHash, revoked: false };
+        this.write(next);
+    }
+    revoke(id) {
+        const next = structuredClone(this.doc), principal = next.principals.find(p => p.id === id);
+        if (!principal)
+            integrationError('INTEGRATION_NOT_FOUND', 'Integration does not exist', 404);
+        principal.revoked = true;
+        this.write(next);
+    }
+    authenticate(id, token) {
+        const principal = this.doc.principals.find(p => p.id === id);
+        const given = Buffer.from(hash(token)), expected = Buffer.from(principal?.tokenHash ?? hash('invalid'));
+        if (!principal || !timingSafeEqual(given, expected))
+            integrationError('INTEGRATION_UNAUTHORIZED', 'Invalid integration credential', 401);
+        if (principal.revoked)
+            integrationError('INTEGRATION_REVOKED', 'Integration authorization was revoked', 403);
+        return structuredClone(principal);
+    }
+    authorize(principal, permission, groupId = principal.groupId) {
+        const active = this.doc.principals.find(p => p.id === principal.id);
+        if (!active || active.revoked)
+            integrationError('INTEGRATION_REVOKED', 'Integration authorization was revoked', 403);
+        if (groupId !== active.groupId || !active.permissions.includes(permission))
+            integrationError('INTEGRATION_PERMISSION_DENIED', 'Operation is outside the integration grant', 403);
+    }
+    append(updates) {
+        const next = structuredClone(this.doc);
+        let changed = false;
+        for (const update of updates) {
+            if (next.sources[update.sourceKey] === update.sourceVersion)
+                continue;
+            const group = update.event.group_id, sequence = (next.sequences[group] ?? 0) + 1;
+            next.events.push({ ...update.event, event_id: update.eventId ?? randomUUID(), sequence, cursor: this.cursor(group, sequence) });
+            next.sequences[group] = sequence;
+            next.sources[update.sourceKey] = update.sourceVersion;
+            changed = true;
+        }
+        if (!changed)
+            return;
+        const counts = new Map();
+        next.events = next.events.reverse().filter(event => {
+            const count = (counts.get(event.group_id) ?? 0) + 1;
+            counts.set(event.group_id, count);
+            if (count <= this.retention)
+                return true;
+            next.prunedThrough[event.group_id] = Math.max(next.prunedThrough[event.group_id] ?? 0, event.sequence);
+            return false;
+        }).reverse();
+        this.write(next);
+    }
+    cursor(group, sequence) { return Buffer.from(JSON.stringify({ v: 1, group, sequence })).toString('base64url'); }
+    decode(group, cursor) {
+        let value;
+        try {
+            value = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        }
+        catch {
+            return integrationError('INVALID_EVENT_CURSOR', 'Invalid cursor');
+        }
+        if (value.v !== 1 || value.group !== group || !Number.isSafeInteger(value.sequence) || value.sequence < 0 || value.sequence > (this.doc.sequences[group] ?? 0))
+            integrationError('INVALID_EVENT_CURSOR', 'Cursor does not belong to this group');
+        return value.sequence;
+    }
+    key(principal, consumer) { identifier(consumer, 'consumer'); return `${principal.id}:${principal.groupId}:${consumer}`; }
+    page(principal, consumer, cursor) {
+        this.authorize(principal, 'events.read');
+        const key = this.key(principal, consumer), group = principal.groupId;
+        const floor = this.doc.prunedThrough[group] ?? 0;
+        // A new consumer explicitly starts at the earliest retained fact. Existing
+        // consumers never silently skip a retention gap.
+        if (this.doc.consumers[key] === undefined) {
+            const next = structuredClone(this.doc);
+            next.consumers[key] = floor;
+            this.write(next);
+        }
+        const after = cursor ? this.decode(group, cursor) : this.doc.consumers[key];
+        if (after < floor)
+            integrationError('EVENT_RETENTION_GAP', 'Confirmed cursor is older than retained history; reconcile task/session snapshots and use a new consumer', 409);
+        return { events: structuredClone(this.doc.events.filter(e => e.group_id === group && e.sequence > after).slice(0, 100)), cursor: this.cursor(group, after) };
+    }
+    ack(principal, consumer, cursor) {
+        this.authorize(principal, 'events.read');
+        const key = this.key(principal, consumer), sequence = this.decode(principal.groupId, cursor), confirmed = this.doc.consumers[key];
+        if (confirmed === undefined)
+            integrationError('EVENT_CONSUMER_NOT_STARTED', 'Subscribe before acknowledging');
+        if (sequence < confirmed)
+            integrationError('EVENT_ACK_REWIND', 'Acknowledgement cannot rewind');
+        if (confirmed < (this.doc.prunedThrough[principal.groupId] ?? 0))
+            integrationError('EVENT_RETENTION_GAP', 'Consumer has a retention gap', 409);
+        // Cursor is a cumulative declaration that every preceding event is safely
+        // in the bridge inbox. The subscription server separately checks it was sent.
+        const next = structuredClone(this.doc);
+        next.consumers[key] = sequence;
+        this.write(next);
+        return { cursor, ack_semantics: 'durable_received' };
+    }
+    cursorSequence(group, cursor) { return this.decode(group, cursor); }
+}

package/dist/server/cli.js

@@ -15,6 +15,7 @@ if (process.argv.slice(2).some(arg => arg === '--federation-pairing' || arg ===
     const { runFederationCli } = await import('./federation/cli.js');
     process.exit(await runFederationCli(process.argv.slice(2)));
 }
+import { INTEGRATION_HELP, runIntegrationAdmin, revokeIntegration, runIntegrationCollab } from './agent/integrationCli.js';
 import { parseNotifyCommand, NOTIFY_HELP, NOTIFY_PROMPT } from './agent/notifyCli.js';
 import { detectLocalSessionContext, resolveLocalCollaborationContext } from './agent/localSessionContext.js';
 import { parseAutomationCommand, executeAutomationCommand, AUTOMATION_HELP } from './agent/automationCli.js';
@@ -207,6 +208,7 @@ Short commands:
   n [message]       Progress reminder; run td n for help and Agent instructions
   notify [message]  Same as n (see td n --prompt)
   automation         Manage scheduled tasks (see td automation --help)
+  integration       Manage local scoped integrations (see integration help)
   collab status      Show this Session's collaboration groups and peers
   collab inbox       Read messages without acknowledging (see collab --help)
   collab send <session-id> <message>
@@ -658,6 +660,7 @@ function parseArgs(argv) {
     let pluginHooks;
     let pluginRemove;
     let agentEvent;
+    let integration;
     let collab;
     let automation;
     let notify;
@@ -797,6 +800,10 @@ function parseArgs(argv) {
             }
             argv = [];
         }
+        else if (command === 'integration') {
+            integration = argv.slice(1);
+            argv = [];
+        }
         else if (command === 'collab') {
             try {
                 collab = parseCollaborationCommand(argv.slice(1));
@@ -1183,6 +1190,7 @@ function parseArgs(argv) {
         pluginHooks,
         pluginRemove,
         agentEvent,
+        integration,
         collab,
         automation,
         notify,
@@ -1434,6 +1442,10 @@ async function runAutomation(command) {
 }
 async function runCollab(command) {
     const runningState = getRunningState();
+    if (command.options.principal) {
+        process.exitCode = await runIntegrationCollab(command, runningState?.port ?? 9834, { write: line => console.log(line), stdin: readStdinText });
+        return;
+    }
     if (!runningState?.localApiToken) {
         // Help is a plain read: it must stay available without a running server.
         if (command.action === 'help') {
@@ -3475,6 +3487,23 @@ async function main() {
         await runAutomation(options.automation);
         return;
     }
+    if (options.integration) {
+        const argv = options.integration;
+        if (!argv.length || ['help', '--help'].includes(argv[0])) {
+            console.log(INTEGRATION_HELP);
+            return;
+        }
+        const state = getRunningState();
+        if (!state?.localApiToken) {
+            console.error(JSON.stringify({ ok: false, code: 'SERVICE_UNAVAILABLE', error: 'Termdock is not running' }));
+            process.exitCode = 1;
+            return;
+        }
+        process.exitCode = argv[0] === 'revoke' && argv.length === 2
+            ? await revokeIntegration(argv[1], state.port, state.localApiToken, line => console.log(line))
+            : await runIntegrationAdmin(argv, state.port, state.localApiToken, line => console.log(line));
+        return;
+    }
     if (options.collab) {
         await runCollab(options.collab);
         return; // Preserve the receipt exit code and allow piped JSON output to drain.