@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/agentSessions.js

@@ -0,0 +1,279 @@
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { ensureOwnerOnlyDirectory, readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PROVIDERS = new Set(['cursor', 'claude']);
+const BINDING_FIELDS = [
+  'agentSessionId',
+  'agentId',
+  'deliveryId',
+  'streamId',
+  'rootId',
+  'provider',
+];
+
+function invalid(message = 'Agent session binding is invalid') {
+  return new HubError('HUB_AGENT_SESSION_INVALID', message);
+}
+
+function bindingMismatch() {
+  return new HubError(
+    'HUB_AGENT_SESSION_BINDING_MISMATCH',
+    'Continuation does not exactly match its durable cloud and local session binding'
+  );
+}
+
+function sameFields(left, right, fields) {
+  return fields.every((field) => left?.[field] === right?.[field]);
+}
+
+function assertBinding(value) {
+  if (
+    !value ||
+    Object.keys(value).length !== BINDING_FIELDS.length ||
+    !BINDING_FIELDS.every((field) => Object.hasOwn(value, field)) ||
+    !UUID.test(String(value.agentSessionId || '')) ||
+    !UUID.test(String(value.agentId || '')) ||
+    !UUID.test(String(value.deliveryId || '')) ||
+    !UUID.test(String(value.streamId || '')) ||
+    typeof value.rootId !== 'string' ||
+    value.rootId.length < 1 ||
+    value.rootId.length > 80 ||
+    !PROVIDERS.has(value.provider)
+  ) {
+    throw invalid();
+  }
+  return value;
+}
+
+function assertLocalSession(value) {
+  if (
+    !value ||
+    !UUID.test(String(value.agentId || '')) ||
+    !UUID.test(String(value.deliveryId || '')) ||
+    !UUID.test(String(value.streamId || '')) ||
+    typeof value.rootId !== 'string' ||
+    value.rootId.length < 1 ||
+    value.rootId.length > 80 ||
+    !PROVIDERS.has(value.provider) ||
+    typeof value.providerSessionId !== 'string' ||
+    value.providerSessionId.length < 1 ||
+    value.providerSessionId.length > 180 ||
+    typeof value.model !== 'string' ||
+    value.model.length < 1 ||
+    value.model.length > 100 ||
+    !['read', 'write'].includes(value.mode) ||
+    !['architect', 'coder', 'reviewer', 'auditor'].includes(value.role) ||
+    !['active', 'stopped'].includes(value.state) ||
+    (value.worktreeId !== null &&
+      (typeof value.worktreeId !== 'string' ||
+        value.worktreeId.length < 1 ||
+        value.worktreeId.length > 180)) ||
+    (value.mode === 'write' && typeof value.worktreeId !== 'string') ||
+    (value.processIdentity !== undefined &&
+      value.processIdentity !== null &&
+      (typeof value.processIdentity !== 'object' ||
+        typeof value.processIdentity.processRef !== 'string' ||
+        !Number.isInteger(value.processIdentity.pid) ||
+        !Number.isInteger(value.processIdentity.pgid) ||
+        typeof value.processIdentity.bootId !== 'string' ||
+        typeof value.processIdentity.startToken !== 'string'))
+  ) {
+    throw invalid();
+  }
+}
+
+export class AgentSessionStore {
+  #queue = Promise.resolve();
+
+  static async open(directory) {
+    await ensureOwnerOnlyDirectory(directory);
+    const file = path.join(directory, 'agent-sessions.json');
+    const data = await readOwnerOnlyJson(file, {
+      schemaVersion: 2,
+      pendingStarts: {},
+      sessions: {},
+      startBindings: {},
+    });
+    if (
+      data.schemaVersion !== 2 ||
+      !data.pendingStarts ||
+      typeof data.pendingStarts !== 'object' ||
+      !data.sessions ||
+      typeof data.sessions !== 'object' ||
+      !data.startBindings ||
+      typeof data.startBindings !== 'object'
+    ) {
+      throw new HubError('HUB_AGENT_SESSION_STORE_INVALID', 'Agent session store is invalid');
+    }
+    if (
+      Object.keys(data.sessions).length > 1_000 ||
+      Object.keys(data.pendingStarts).length > 100 ||
+      Object.keys(data.startBindings).length > 1_000 ||
+      Buffer.byteLength(JSON.stringify(data), 'utf8') > 2 * 1024 * 1024
+    ) {
+      throw new HubError('HUB_AGENT_SESSION_STORE_INVALID', 'Agent session store exceeds safety bounds');
+    }
+    for (const [id, session] of Object.entries(data.sessions)) {
+      assertBinding({
+        agentSessionId: id,
+        agentId: session.agentId,
+        deliveryId: session.deliveryId,
+        streamId: session.streamId,
+        rootId: session.rootId,
+        provider: session.provider,
+      });
+      assertLocalSession(session);
+    }
+    for (const [jobId, session] of Object.entries(data.pendingStarts)) {
+      if (!UUID.test(jobId)) throw invalid();
+      assertLocalSession(session);
+    }
+    for (const [jobId, binding] of Object.entries(data.startBindings)) {
+      if (!UUID.test(jobId)) throw invalid();
+      assertBinding(binding);
+    }
+    return new AgentSessionStore(file, data);
+  }
+
+  constructor(file, data) {
+    this.file = file;
+    this.data = data;
+  }
+
+  get(id) {
+    const value = Object.hasOwn(this.data.sessions, id) ? this.data.sessions[id] : null;
+    return value ? structuredClone(value) : null;
+  }
+
+  list() {
+    return Object.entries(this.data.sessions).map(([id, value]) => ({
+      id,
+      ...structuredClone(value),
+    }));
+  }
+
+  async #mutate(operation) {
+    const pending = this.#queue.then(async () => {
+      const draft = structuredClone(this.data);
+      const result = operation(draft);
+      if (Buffer.byteLength(JSON.stringify(draft), 'utf8') > 2 * 1024 * 1024) {
+        throw new HubError('HUB_AGENT_SESSION_STORE_FULL', 'Agent session store exceeds safety bounds');
+      }
+      await writeOwnerOnlyJson(this.file, draft);
+      this.data = draft;
+      return structuredClone(result);
+    });
+    this.#queue = pending.catch(() => {});
+    return pending;
+  }
+
+  async recordPendingStart(jobId, value) {
+    if (!UUID.test(String(jobId || ''))) throw invalid('Start job id is invalid');
+    assertLocalSession(value);
+    return this.#mutate((draft) => {
+      const existing = draft.pendingStarts[jobId];
+      if (existing && JSON.stringify(existing) !== JSON.stringify(value)) throw bindingMismatch();
+      if (!existing && Object.keys(draft.pendingStarts).length >= 100) {
+        throw new HubError('HUB_AGENT_SESSION_STORE_FULL', 'Pending start store is full');
+      }
+      draft.pendingStarts[jobId] = structuredClone(value);
+      return value;
+    });
+  }
+
+  async applyStartAcknowledgement(jobId, acknowledgement) {
+    if (
+      !UUID.test(String(jobId || '')) ||
+      acknowledgement?.job?.id !== jobId ||
+      acknowledgement.job.type !== 'agent.start' ||
+      !['succeeded', 'failed', 'cancelled'].includes(acknowledgement.job.state)
+    ) {
+      throw invalid('Agent start acknowledgement is invalid');
+    }
+    return this.#mutate((draft) => {
+      const pending = draft.pendingStarts[jobId];
+      if (acknowledgement.job.state !== 'succeeded') {
+        if (acknowledgement.sessionBinding !== undefined) throw bindingMismatch();
+        delete draft.pendingStarts[jobId];
+        return null;
+      }
+      const binding = assertBinding(acknowledgement.sessionBinding);
+      const priorBinding = draft.startBindings[jobId];
+      if (priorBinding) {
+        if (!sameFields(priorBinding, binding, BINDING_FIELDS)) throw bindingMismatch();
+        const priorSession = draft.sessions[binding.agentSessionId];
+        if (!priorSession) throw bindingMismatch();
+        return priorSession;
+      }
+      if (!pending || !sameFields(pending, binding, BINDING_FIELDS.slice(1))) {
+        throw bindingMismatch();
+      }
+      const existing = draft.sessions[binding.agentSessionId];
+      const session = {
+        ...structuredClone(pending),
+        agentId: binding.agentId,
+        deliveryId: binding.deliveryId,
+        streamId: binding.streamId,
+        rootId: binding.rootId,
+        provider: binding.provider,
+      };
+      if (existing && JSON.stringify(existing) !== JSON.stringify(session)) throw bindingMismatch();
+      if (!existing && Object.keys(draft.sessions).length >= 1_000) {
+        throw new HubError('HUB_AGENT_SESSION_STORE_FULL', 'Agent session store is full');
+      }
+      draft.sessions[binding.agentSessionId] = session;
+      draft.startBindings[jobId] = structuredClone(binding);
+      delete draft.pendingStarts[jobId];
+      return session;
+    });
+  }
+
+  async rejectStartSettlement(jobId) {
+    if (!UUID.test(String(jobId || ''))) throw invalid('Start job id is invalid');
+    return this.#mutate((draft) => {
+      if (!Object.hasOwn(draft.pendingStarts, jobId)) return null;
+      delete draft.pendingStarts[jobId];
+      return null;
+    });
+  }
+
+  resolveContinuation(job) {
+    if (!['agent.turn', 'agent.stop'].includes(job?.type)) return null;
+    const binding = assertBinding(job.sessionBinding);
+    const session = this.get(binding.agentSessionId);
+    const expectedCapability = `agent.${binding.provider}.invoke`;
+    if (
+      !session ||
+      job.arguments?.agentSessionId !== binding.agentSessionId ||
+      job.arguments?.rootId !== binding.rootId ||
+      job.delivery_id !== binding.deliveryId ||
+      job.stream_id !== binding.streamId ||
+      job.root_id !== binding.rootId ||
+      job.capability !== expectedCapability ||
+      (session.state !== 'active' && !(job.type === 'agent.stop' && session.state === 'stopped')) ||
+      !sameFields(session, binding, BINDING_FIELDS.slice(1))
+    ) {
+      throw bindingMismatch();
+    }
+    return {
+      provider: binding.provider,
+      cloudSessionId: binding.agentSessionId,
+      session,
+    };
+  }
+
+  async put(id, value) {
+    if (!UUID.test(String(id || ''))) throw invalid();
+    assertLocalSession(value);
+    return this.#mutate((draft) => {
+      const existing = draft.sessions[id];
+      if (!existing || !sameFields(existing, value, BINDING_FIELDS.slice(1))) {
+        throw bindingMismatch();
+      }
+      draft.sessions[id] = structuredClone(value);
+      return value;
+    });
+  }
+}