@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/lib/daemonComposition.js

@@ -0,0 +1,338 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { AgentSessionStore } from './agentSessions.js';
+import { CloudAuth } from './cloudAuth.js';
+import { defaultSecretStore } from './secretStore.js';
+import { HubError } from './errors.js';
+import { createHubActionHandlers } from './hubActions.js';
+import { discoverLocalHub } from './localHub.js';
+import { LocalHubWriter } from './localHubWriter.js';
+import { assertPairedConfig } from './pairedConfig.js';
+import { canonicalJson, validateDeliveryPlan } from './planContract.js';
+import { TokenStore } from './tokenStore.js';
+import { ConnectorTransport } from './transport.js';
+import { validateRootGrant, WorktreeRegistry, createOwnedWorktree } from './rootPolicy.js';
+import { execFileBounded as execFile } from './subprocess.js';
+
+export async function createProductionDependencies({
+  config,
+  configDir,
+  secretStore = defaultSecretStore(),
+  fetch = globalThis.fetch,
+  log = () => {},
+  onTransportAttempt = () => {},
+}) {
+  assertPairedConfig(config);
+  const tokenStore = new TokenStore({ secretStore, configDir });
+  const sessionId = randomUUID();
+  const worktrees = await WorktreeRegistry.open(configDir);
+  const sessions = await AgentSessionStore.open(configDir);
+  const roots = new Map((config.localRoots || []).map((root) => [root.rootId, root]));
+  let transport;
+  let transportKey;
+
+  const transportFactory = async (currentConfig) => {
+    const paired = assertPairedConfig(currentConfig);
+    const key = [paired.machineId, paired.policyVersion, paired.baseUrl, paired.userId].join('\0');
+    if (transport && transportKey === key) return transport;
+    const auth = new CloudAuth({
+      tokenStore,
+      fetch,
+      target: {
+        platformUrl: paired.target.platformUrl,
+        devOrg: paired.target.devOrg,
+        instanceUrl: paired.baseUrl,
+        userId: paired.userId,
+        teamId: paired.teamId,
+      },
+    });
+    transport = new ConnectorTransport({
+      baseUrl: paired.baseUrl,
+      machine: { machineId: paired.machineId, sessionId, policyVersion: paired.policyVersion },
+      auth,
+      fetch,
+      onAttempt: onTransportAttempt,
+    });
+    transportKey = key;
+    return transport;
+  };
+
+  const hubActions = createHubActionHandlers({
+    writerFor: async () => {
+      let hub;
+      try {
+        hub = await discoverLocalHub({ config });
+      } catch (error) {
+        throw new HubError('hub_unreachable', error.message);
+      }
+      return new LocalHubWriter({ ...hub, fetch, log });
+    },
+  });
+
+  const handlersFactory = ({ drivers, policy }) => {
+    const plannerChoices = Object.entries(policy.providers).flatMap(([provider, models]) =>
+      models.map((model) => ({ provider, model }))
+    );
+    const defaultProvider = plannerChoices.length === 1 ? plannerChoices[0].provider : null;
+    const defaultModel = plannerChoices.length === 1 ? plannerChoices[0].model : null;
+    const budget = (requested = {}) => ({
+      maxTokens: requested.maxTokens || policy.limits.maxTokensPerRun,
+      maxCostUsd: requested.maxCostUsd ?? policy.limits.maxCostUsd,
+      maxWallMs: requested.maxWallMs || policy.limits.maxWallMs,
+      maxOutputBytes: requested.maxOutputBytes || policy.limits.maxOutputBytes,
+    });
+    const workspaceFor = (rootId, mode, cloudJob = {}, expectedWorktreeId = null) => {
+      const root = roots.get(rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      if (mode === 'read') return root.canonicalRoot;
+      const candidates = worktrees
+        .list(rootId)
+        .filter(
+          (record) =>
+            record.deliveryId === cloudJob.delivery_id &&
+            record.streamId === cloudJob.stream_id
+        );
+      if (candidates.length !== 1) {
+        throw new HubError(
+          'HUB_WRITE_REQUIRES_WORKTREE',
+          'Write-mode agent requires exactly one connector-owned worktree'
+        );
+      }
+      if (expectedWorktreeId && candidates[0].worktreeId !== expectedWorktreeId) {
+        throw new HubError(
+          'HUB_AGENT_SESSION_BINDING_MISMATCH',
+          'Continuation worktree does not match its durable local agent binding'
+        );
+      }
+      return candidates[0].canonicalPath;
+    };
+    return {
+    'delivery.plan': async (job, context) => {
+      if (!defaultProvider || !defaultModel) {
+        throw new HubError(
+          'HUB_PROVIDER_DENIED',
+          'Planner requires exactly one signed provider/model assignment'
+        );
+      }
+      const rootId = job.arguments.rootIds[0];
+      const result = await drivers.driver(defaultProvider, defaultModel).start({
+        workspace: workspaceFor(rootId, 'read', context.cloudJob),
+        provider: defaultProvider,
+        model: defaultModel,
+        role: 'architect',
+        mode: 'read',
+        prompt: `Produce only a bounded JSON delivery plan for this approved outcome:\n${job.arguments.description}`,
+        budget: budget(job.arguments.budget),
+        attempt: context.attempt,
+        onStart: context.onProcessStart,
+        signal: context.signal,
+      });
+      let plan;
+      try {
+        plan = JSON.parse(result.text);
+      } catch {
+        throw new HubError('HUB_PROVIDER_OUTPUT_INVALID', 'Planner did not return JSON');
+      }
+      const validatedPlan = validateDeliveryPlan(plan, grant);
+      return {
+        plan: validatedPlan,
+        planDigest: createHash('sha256').update(canonicalJson(validatedPlan)).digest('hex'),
+      };
+    },
+    'workspace.inspect': async (job) => {
+      const root = roots.get(job.arguments.rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      await validateRootGrant(root);
+      return {
+        summary: 'Approved workspace root is available.',
+        repo: { rootId: root.rootId, repoWrite: root.repoWrite },
+        fileManifestHash: createHash('sha256').update(root.repositoryIdentity).digest('hex'),
+      };
+    },
+    'worktree.create': async (job, context) => {
+      const root = roots.get(job.arguments.rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      const record = await createOwnedWorktree({
+        grant: root,
+        deliveryId: context.cloudJob.delivery_id,
+        streamId: context.cloudJob.stream_id,
+        baseRef: root.baseRef,
+        registry: worktrees,
+      });
+      return {
+        summary: 'Connector-owned worktree created.',
+        branch: record.branch,
+        worktreeRef: record.worktreeId,
+        repoHash: root.repositoryIdentity,
+      };
+    },
+    'git.inspect': async (job) => {
+      const root = roots.get(job.arguments.rootId);
+      if (!root) throw new HubError('HUB_CAPABILITY_DENIED', 'Root is not locally approved');
+      await validateRootGrant(root);
+      const env = {
+        PATH: process.env.PATH || '/usr/bin:/bin',
+        LC_ALL: 'C',
+        GIT_CONFIG_GLOBAL: '/dev/null',
+        GIT_CONFIG_SYSTEM: '/dev/null',
+        GIT_TERMINAL_PROMPT: '0',
+      };
+      const status = await execFile(
+        'git',
+        ['status', '--porcelain=v1', '--untracked-files=no'],
+        { cwd: root.canonicalRoot, env, timeout: 30_000, maxBuffer: 512 * 1024 }
+      );
+      let refSha = null;
+      let diffSummary = '';
+      if (job.arguments.ref) {
+        const resolved = await execFile(
+          'git',
+          ['rev-parse', '--verify', '--end-of-options', `${job.arguments.ref}^{commit}`],
+          { cwd: root.canonicalRoot, env, timeout: 30_000, maxBuffer: 64 * 1024 }
+        );
+        refSha = resolved.stdout.trim();
+        if (job.arguments.includeDiffSummary) {
+          const diff = await execFile(
+            'git',
+            ['diff', '--stat', '--no-ext-diff', `${refSha}..HEAD`],
+            { cwd: root.canonicalRoot, env, timeout: 30_000, maxBuffer: 512 * 1024 }
+          );
+          diffSummary = diff.stdout;
+        }
+      }
+      return {
+        summary: 'Git metadata inspected under the approved root.',
+        status: {
+          clean: status.stdout.length === 0,
+          changedEntries: status.stdout.trim() ? status.stdout.trim().split('\n').length : 0,
+          refSha,
+        },
+        diffSummaryHash: createHash('sha256').update(diffSummary).digest('hex'),
+      };
+    },
+    'agent.start': async (job, context) => {
+      const args = job.arguments;
+      const mode = args.role === 'coder' ? 'write' : 'read';
+      const result = await drivers.driver(args.provider, args.model).start({
+        workspace: workspaceFor(args.rootId, mode, context.cloudJob),
+        model: args.model,
+        role: args.role,
+        mode,
+        prompt: `Execute this approved structured intent only:\n${JSON.stringify(args.intent)}`,
+        budget: budget(args.budget),
+        attempt: context.attempt,
+        onStart: context.onProcessStart,
+        signal: context.signal,
+      });
+      await sessions.recordPendingStart(context.cloudJob.id, {
+        agentId: args.agentId,
+        provider: args.provider,
+        model: args.model,
+        role: args.role,
+        mode,
+        rootId: args.rootId,
+        deliveryId: context.cloudJob.delivery_id,
+        streamId: context.cloudJob.stream_id,
+        worktreeId:
+          mode === 'write'
+            ? worktrees
+                .list(args.rootId)
+                .find(
+                  (record) =>
+                    record.deliveryId === context.cloudJob.delivery_id &&
+                    record.streamId === context.cloudJob.stream_id
+                )?.worktreeId
+            : null,
+        providerSessionId: result.sessionId,
+        processIdentity: result.processIdentity,
+        state: 'active',
+      });
+      return {
+        summary: drivers.driver(args.provider, args.model).collectSummary(result).text,
+        agentSessionRefHash: createHash('sha256')
+          .update(String(result.sessionId))
+          .digest('hex'),
+      };
+    },
+    'agent.turn': async (job, context) => {
+      const args = job.arguments;
+      const session = context.sessionBinding?.session;
+      if (!session) throw new HubError('HUB_AGENT_SESSION_MISSING', 'Agent session is not local');
+      await sessions.put(args.agentSessionId, session);
+      const result = await drivers.driver(session.provider, session.model).send({
+        workspace: workspaceFor(
+          args.rootId,
+          session.mode,
+          context.cloudJob,
+          session.worktreeId
+        ),
+        model: session.model,
+        role: session.role,
+        mode: session.mode,
+        sessionId: session.providerSessionId,
+        prompt: `Execute this approved structured intent only:\n${JSON.stringify(args.intent)}`,
+        budget: budget(args.budget),
+        attempt: context.attempt,
+        onStart: context.onProcessStart,
+        signal: context.signal,
+      });
+      await sessions.put(args.agentSessionId, {
+        ...session,
+        providerSessionId: result.sessionId,
+        processIdentity: result.processIdentity,
+      });
+      const summary = drivers.driver(session.provider, session.model).collectSummary(result);
+      return {
+        summary: summary.text,
+        usage: result.usage,
+        evidenceIds: [],
+        needsUser: false,
+      };
+    },
+    'agent.stop': async (job, context) => {
+      const args = job.arguments;
+      const session = context.sessionBinding?.session;
+      if (!session) throw new HubError('HUB_AGENT_SESSION_MISSING', 'Agent session is not local');
+      await sessions.put(args.agentSessionId, session);
+      if (session.processIdentity) {
+        const outcome = await drivers
+          .driver(session.provider, session.model)
+          .cancel(session.processIdentity);
+        if (!outcome.verifiedStopped) {
+          throw new HubError('HUB_CANCELLATION_UNPROVEN', 'Agent process did not stop');
+        }
+      }
+      await sessions.put(args.agentSessionId, { ...session, state: 'stopped' });
+      return { summary: args.reason, stopped: true };
+    },
+    'evidence.collect': async (job) => ({
+      summary: 'Evidence remains local until explicitly approved for upload.',
+      artifacts: job.arguments.kinds.map((kind) => ({
+        kind,
+        label: `Local ${kind.replaceAll('_', ' ')}`,
+        mimeType: 'application/octet-stream',
+        byteSize: 0,
+        sha256: createHash('sha256').update('').digest('hex'),
+        storageMode: 'local_only',
+        redactionVersion: 1,
+        userVisible: true,
+      })),
+    }),
+    ...hubActions,
+  };
+  };
+
+  const sessionResolver = (job) => sessions.resolveContinuation(job);
+  const settlementObserver = (attempt, response, error = null) => {
+    if (attempt.jobType !== 'agent.start') return null;
+    if (error) return sessions.rejectStartSettlement(attempt.jobId);
+    return sessions.applyStartAcknowledgement(attempt.jobId, response);
+  };
+
+  return {
+    tokenStore,
+    transportFactory,
+    handlersFactory,
+    sessionResolver,
+    settlementObserver,
+  };
+}

package/src/lib/daemonLock.js

@@ -0,0 +1,57 @@
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { acquireOwnerLock } from './ownerLock.js';
+import { CONNECTOR_VERSION } from './pairingLifecycle.js';
+import { ProcessIdentityProvider } from './processOwnership.js';
+import { ensureOwnerOnlyDirectory, writeOwnerOnlyJson } from './storage.js';
+
+export class DaemonLock {
+  constructor({
+    directory,
+    pid = process.pid,
+    identityProvider = new ProcessIdentityProvider(),
+  }) {
+    this.directory = directory;
+    this.pid = pid;
+    this.identityProvider = identityProvider;
+    this.pidFile = path.join(directory, 'daemon.pid');
+    this.healthFile = path.join(directory, 'daemon-health.json');
+    this.acquired = false;
+  }
+
+  async acquire() {
+    await ensureOwnerOnlyDirectory(this.directory);
+    this.releaseLock = await acquireOwnerLock({
+      file: this.pidFile,
+      identity: await this.identityProvider.capture(this.pid),
+      identityProvider: this.identityProvider,
+      heldError: (owner) => new HubError(
+        'HUB_DAEMON_ALREADY_RUNNING',
+        `Pulse daemon is already running${owner?.pid ? ` with pid ${owner.pid}` : ''}`
+      ),
+    });
+    this.acquired = true;
+    return { pid: this.pid };
+  }
+
+  heartbeat(status) {
+    if (!this.acquired) {
+      throw new HubError('HUB_DAEMON_NOT_OWNER', 'Daemon lock is not held by this process');
+    }
+    return writeOwnerOnlyJson(this.healthFile, {
+      pid: this.pid,
+      heartbeatAt: new Date().toISOString(),
+      ...status,
+      connectorVersion: CONNECTOR_VERSION,
+    });
+  }
+
+  async release() {
+    if (!this.acquired) return;
+    try {
+      await this.releaseLock();
+    } finally {
+      this.acquired = false;
+    }
+  }
+}

package/src/lib/daemonLoop.js

@@ -0,0 +1,72 @@
+export const TERMINAL_STATES = new Set(['revoked', 'upgrade_required', 'auth_required', 'stopped']);
+const LOOP_RETRY_MS = 5_000;
+/** The heartbeat step that waits on the mirror; a pass that keeps reading or pushing keeps it alive. */
+export const MIRROR_UPDATE_STEP = 'mirror_update';
+
+/**
+ * One daemon heartbeat: re-read config.json, run a runtime cycle, then always hand the same fresh config to the mirror
+ * and publish health. A failed cycle must not leave the mirror on an old policy version, so the cycle's error becomes
+ * the heartbeat's state instead of skipping the rest. progress(step) names each step for the watchdog; extraHealth()
+ * adds fields such as the restart state to every health write.
+ */
+export function createHeartbeat({
+  readConfig, runtime, mirror, shadow = null, runner = null, lock, ledger, ownerStore, progress = () => {}, extraHealth = () => ({}),
+}) {
+  let last = null;
+  const health = (config, status) => ({
+    state: status.state,
+    ...(status.code ? { code: status.code } : {}),
+    ...(status.message ? { message: status.message } : {}),
+    ...(status.accepts ? { accepts: status.accepts } : {}),
+    paired: Boolean(config?.paired),
+    protocolVersion: config?.protocolVersion ?? 1,
+    recovery: ledger.recover(),
+    ownedProcesses: Object.values(ownerStore.data.owners)
+      .filter((owner) => owner.state === 'running')
+      .map((owner) => ({
+        processRef: owner.processRef,
+        jobId: owner.jobId,
+        attemptNo: owner.attemptNo,
+        fenceToken: owner.fenceToken,
+      })),
+    recovering: runtime.recovering(),
+    settleFailed: ledger.settleFailed().slice(0, 5),
+    ...(runtime.lastJobError ? { lastJobError: runtime.lastJobError } : {}),
+    ...extraHealth(),
+  });
+  // Writes are chained and each builds its health when its turn comes, so a republish never overwrites a newer cycle.
+  let writing = Promise.resolve();
+  const write = (override = null) => {
+    writing = writing.catch(() => {}).then(async () => {
+      await lock.heartbeat(health(last?.config ?? null, { ...(last?.status ?? {}), ...override }));
+      heartbeat.writtenAt = Date.now();
+    });
+    return writing;
+  };
+  const heartbeat = async () => {
+    progress('config');
+    const config = await readConfig();
+    runtime.updateConfig(config);
+    let status;
+    try {
+      progress('cycle');
+      status = await runtime.runOnce();
+    } catch (error) {
+      status = { state: 'error', code: error.code || 'HUB_DAEMON_LOOP_FAILED', retryAfterMs: LOOP_RETRY_MS };
+    }
+    progress(MIRROR_UPDATE_STEP);
+    // A cloud that refused the contract would refuse every batch too, so the mirror waits for the next session.
+    const usable = !(TERMINAL_STATES.has(status.state) || status.code === 'contract_unsupported');
+    await mirror.update(usable ? config : null);
+    shadow?.update(usable ? config : null);
+    runner?.update(usable ? config : null);
+    progress('health');
+    last = { config, status };
+    await write();
+    return status;
+  };
+  /** Writes health again from the last cycle, with status fields overridden, while a cycle is still running. */
+  heartbeat.republish = write;
+  heartbeat.writtenAt = 0;
+  return heartbeat;
+}