@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.0.0

package/src/lib/drivers.js

@@ -0,0 +1,280 @@
+import os from 'node:os';
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { redactText } from './redaction.js';
+
+function parseJsonOutput(stdout, provider) {
+  const lines = String(stdout).trim().split('\n').reverse();
+  for (const line of lines) {
+    try {
+      return JSON.parse(line);
+    } catch {
+      // Continue to the prior line.
+    }
+  }
+  throw new HubError('HUB_PROVIDER_OUTPUT_INVALID', `${provider} returned no JSON result`);
+}
+
+function textFrom(value) {
+  if (typeof value === 'string') return value;
+  if (!value || typeof value !== 'object') return '';
+  for (const key of ['result', 'text', 'output', 'response']) {
+    const text = textFrom(value[key]);
+    if (text) return text;
+  }
+  return '';
+}
+
+function providerFailureCode(message, signal) {
+  if (signal) return 'HUB_PROVIDER_CRASHED';
+  const text = String(message).toLowerCase();
+  if (/\b(?:login|logged in|authentication|unauthorized|credential)\b/.test(text)) {
+    return 'HUB_PROVIDER_AUTH';
+  }
+  if (/\b(?:429|rate limit|throttl)\w*/.test(text)) {
+    return 'HUB_PROVIDER_THROTTLED';
+  }
+  if (/\b(?:resume|session)\b.*\b(?:missing|not found|invalid|expired)\b/.test(text)) {
+    return 'HUB_PROVIDER_UNRESUMABLE';
+  }
+  if (/\b(?:unsupported|minimum|required)\b.*\bversion\b|\bversion\b.*\btoo old\b/.test(text)) {
+    return 'HUB_PROVIDER_VERSION_UNSUPPORTED';
+  }
+  return 'HUB_PROVIDER_FAILED';
+}
+
+function providerEnvironment(provider, source = process.env) {
+  const common = new Set(['PATH', 'HOME', 'TMPDIR', 'LANG', 'LC_ALL', 'TERM']);
+  const allowed = new Set(common);
+  if (provider === 'cursor') {
+    for (const key of Object.keys(source)) {
+      if (key.startsWith('CURSOR_')) allowed.add(key);
+    }
+  } else if (provider === 'claude') {
+    for (const key of Object.keys(source)) {
+      if (key.startsWith('ANTHROPIC_') || key.startsWith('CLAUDE_')) allowed.add(key);
+    }
+  }
+  return Object.fromEntries(
+    [...allowed].filter((key) => source[key] !== undefined).map((key) => [key, source[key]])
+  );
+}
+
+function normalizeResult(provider, processResult, existingSessionId = null) {
+  if (processResult.exitCode !== 0) {
+    const detail = processResult.stderr || processResult.stdout || processResult.signal || processResult.exitCode;
+    const safeDetail = redactText(String(detail), { maxBytes: 300 }).text;
+    throw new HubError(
+      providerFailureCode(detail, processResult.signal),
+      `${provider} exited with ${processResult.signal || processResult.exitCode}: ${safeDetail}`
+    );
+  }
+  const output = parseJsonOutput(processResult.stdout, provider);
+  if (output.is_error || output.terminal_reason === 'api_error') {
+    const detail = textFrom(output).slice(0, 300) || 'unknown error';
+    const safeDetail = redactText(detail, { maxBytes: 300 }).text;
+    throw new HubError(
+      providerFailureCode(detail),
+      `${provider} failed: ${safeDetail}`
+    );
+  }
+  return {
+    provider,
+    processRef: processResult.processRef,
+    processIdentity: processResult.processIdentity ?? null,
+    sessionId: output.session_id || output.sessionId || existingSessionId,
+    text: textFrom(output),
+    usage: {
+      tokens: output.usage?.total_tokens ?? output.usage?.tokens ?? null,
+      costUsd: output.total_cost_usd ?? output.usage?.costUsd ?? null,
+      turns: output.num_turns ?? output.usage?.turns ?? null,
+    },
+  };
+}
+
+function neutralDriver({ id, bin, supervisor, buildArgs }) {
+  const execute = async (request, sessionId = null) => {
+    const processResult = await supervisor.run({
+      bin,
+      args: buildArgs(request, sessionId),
+      cwd: request.workspace,
+      timeoutMs: request.budget.maxWallMs,
+      maxOutputBytes: request.budget.maxOutputBytes,
+      signal: request.signal,
+      onStart: request.onStart,
+      input: request.prompt,
+      env: providerEnvironment(id),
+      provider: id,
+      attempt: request.attempt,
+      shell: false,
+    });
+    const result = normalizeResult(id, processResult, sessionId);
+    if (Number.isFinite(request.budget.maxTokens)) {
+      if (!Number.isFinite(result.usage.tokens) || result.usage.tokens < 0) {
+        throw new HubError('HUB_BUDGET_USAGE_UNKNOWN', 'Provider did not report valid token usage');
+      }
+      if (result.usage.tokens > request.budget.maxTokens) {
+        throw new HubError('HUB_BUDGET_TOKENS', 'Provider token budget exceeded');
+      }
+    }
+    if (Number.isFinite(request.budget.maxCostUsd)) {
+      if (!Number.isFinite(result.usage.costUsd) || result.usage.costUsd < 0) {
+        throw new HubError('HUB_BUDGET_USAGE_UNKNOWN', 'Provider did not report valid cost usage');
+      }
+      if (result.usage.costUsd > request.budget.maxCostUsd) {
+        throw new HubError('HUB_BUDGET_COST', 'Provider cost budget exceeded');
+      }
+    }
+    return result;
+  };
+  return Object.freeze({
+    id,
+    probe: () => supervisor.probe(bin, ['--version']),
+    start: (request) => execute(request),
+    resume: (request) => execute(request, request.sessionId),
+    send: (request) => execute(request, request.sessionId),
+    cancel: (processIdentity) => supervisor.cancel(processIdentity),
+    status: (processRef) => supervisor.status(processRef),
+    collectSummary(result) {
+      const redacted = redactText(result.text, { maxBytes: 4_000 });
+      return {
+        text: redacted.text,
+        usage: result.usage ?? null,
+        redacted: redacted.redactions > 0 || redacted.truncated,
+      };
+    },
+  });
+}
+
+export function createCursorDriver({
+  supervisor,
+  bin = process.env.CURSOR_AGENT || path.join(os.homedir(), '.local', 'bin', 'cursor-agent'),
+} = {}) {
+  return neutralDriver({
+    id: 'cursor',
+    bin,
+    supervisor,
+    buildArgs(request, sessionId) {
+      const args = ['-p', '--output-format', 'json', '--workspace', request.workspace];
+      if (sessionId) args.push('--resume', sessionId);
+      args.push('--model', request.model);
+      if (request.mode === 'read') args.push('--mode', 'ask');
+      else args.push('--sandbox', 'enabled');
+      return args;
+    },
+  });
+}
+
+export function createClaudeDriver({
+  supervisor,
+  bin = process.env.CLAUDE_BIN || path.join(os.homedir(), '.local', 'bin', 'claude'),
+} = {}) {
+  return neutralDriver({
+    id: 'claude',
+    bin,
+    supervisor,
+    buildArgs(request, sessionId) {
+      const args = [
+        '-p',
+        '--output-format',
+        'json',
+        '--model',
+        request.model,
+        '--settings',
+        JSON.stringify({ disableAllHooks: true }),
+      ];
+      if (sessionId) args.push('--resume', sessionId);
+      if (request.mode === 'read') {
+        args.push('--permission-mode', 'plan');
+      } else {
+        args.push(
+          '--permission-mode',
+          'acceptEdits',
+          '--allowedTools',
+          'Read,Glob,Grep,Edit,Write'
+        );
+      }
+      return args;
+    },
+  });
+}
+
+export class DriverRegistry {
+  constructor({ drivers, policy }) {
+    this.drivers = new Map(drivers.map((driver) => [driver.id, driver]));
+    this.policy = policy;
+    this.active = 0;
+    this.wrappers = new Map();
+  }
+
+  driver(provider, model) {
+    const allowedModels = this.policy.providers[provider];
+    if (!allowedModels || !this.drivers.has(provider)) {
+      throw new HubError('HUB_PROVIDER_DENIED', `Provider is not allowed: ${provider}`);
+    }
+    if (!allowedModels.includes(model)) {
+      throw new HubError(
+        'HUB_PROVIDER_MODEL_DENIED',
+        `Model ${model} is not allowed for provider ${provider}`
+      );
+    }
+    const key = `${provider}\0${model}`;
+    if (this.wrappers.has(key)) return this.wrappers.get(key);
+    const driver = this.drivers.get(provider);
+    const limits = this.policy.limits || {};
+    const run = async (method, request) => {
+      if (request.model !== model) {
+        throw new HubError(
+          'HUB_PROVIDER_MODEL_DENIED',
+          `Request model ${String(request.model)} does not match validated model ${model}`
+        );
+      }
+      if (Number.isFinite(limits.maxConcurrency) && this.active >= limits.maxConcurrency) {
+        throw new HubError('HUB_BUDGET_CONCURRENCY', 'Machine provider concurrency exceeded');
+      }
+      if (!['read', 'write'].includes(request.mode)) {
+        throw new HubError('HUB_PROVIDER_MODE_DENIED', 'Provider mode must be read or write');
+      }
+      const roleModes = this.policy.roleModes?.[request.role];
+      if (!Array.isArray(roleModes) || !roleModes.includes(request.mode)) {
+        throw new HubError(
+          'HUB_PROVIDER_ROLE_DENIED',
+          `Role ${String(request.role)} is not allowed in ${request.mode} mode`
+        );
+      }
+      const comparisons = [
+        ['maxTokens', 'maxTokensPerRun', 'HUB_BUDGET_TOKENS'],
+        ['maxCostUsd', 'maxCostUsd', 'HUB_BUDGET_COST'],
+        ['maxWallMs', 'maxWallMs', 'HUB_BUDGET_TIME'],
+        ['maxOutputBytes', 'maxOutputBytes', 'HUB_BUDGET_OUTPUT'],
+      ];
+      for (const [requestKey, policyKey, code] of comparisons) {
+        if (
+          Number.isFinite(limits[policyKey]) &&
+          (!Number.isFinite(request.budget?.[requestKey]) ||
+            request.budget[requestKey] > limits[policyKey])
+        ) {
+          throw new HubError(code, `Requested ${requestKey} exceeds local provider policy`);
+        }
+      }
+      this.active += 1;
+      try {
+        return await driver[method](request);
+      } finally {
+        this.active = Math.max(0, this.active - 1);
+      }
+    };
+    const wrapper = Object.freeze({
+      id: driver.id,
+      probe: () => driver.probe(),
+      start: (request) => run('start', request),
+      resume: (request) => run('resume', request),
+      send: (request) => run('send', request),
+      cancel: (processIdentity) => driver.cancel(processIdentity),
+      status: (processRef) => driver.status(processRef),
+      collectSummary: (result) => driver.collectSummary(result),
+    });
+    this.wrappers.set(key, wrapper);
+    return wrapper;
+  }
+}

package/src/lib/errors.js

@@ -0,0 +1,19 @@
+export class HubError extends Error {
+  constructor(code, message, options = {}) {
+    super(message, options);
+    this.name = 'HubError';
+    this.code = code;
+    this.exit = options.exit ?? 1;
+    this.details = options.details;
+  }
+}
+
+export function assertNever(value, label = 'value') {
+  throw new HubError('HUB_INTERNAL_UNHANDLED_VARIANT', `Unhandled ${label}: ${String(value)}`);
+}
+
+export function requireCondition(condition, code, message, details) {
+  if (!condition) {
+    throw new HubError(code, message, { details });
+  }
+}

package/src/lib/graphWindows.js

@@ -0,0 +1,149 @@
+import { createHash } from 'node:crypto';
+import { MIRROR_CONTRACT, MIRROR_LIMITS, itemBytes, sanitizePart } from './mirrorContract.js';
+
+const SCHEMA = MIRROR_CONTRACT.kinds.graph_window.properties;
+export const GRAPH_HOURS = Object.freeze([...SCHEMA.windows.items.enum]);
+export const GRAPH_SECTIONS = Object.freeze(SCHEMA.section.enum.filter((section) => section !== 'meta'));
+const ITEM_HEADROOM = 1024;
+
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const digest = (value) => createHash('sha256').update(canonical(value)).digest('hex').slice(0, 16);
+const list = (value) => (Array.isArray(value) ? value : []);
+
+/** The local projection's sections; a delivery's streams are rows of their own so a delivery item stays small. */
+function sectionRows(graph) {
+  const deliveries = list(graph.deliveries);
+  return {
+    deliveries: deliveries.map(({ streams: _streams, ...delivery }) => delivery),
+    streams: deliveries.flatMap((delivery) => list(delivery.streams).map((stream) => ({ ...stream, deliveryId: delivery.id }))),
+    agents: list(graph.agents),
+    nodes: list(graph.nodes),
+    links: list(graph.links),
+    events: list(graph.events),
+    requests: list(graph.requests),
+  };
+}
+
+// Events have no id on the local hub and never change once written, so their content is their key.
+const ROW_KEY = {
+  deliveries: (row) => row.id,
+  streams: (row) => row.key,
+  agents: (row) => row.id,
+  nodes: (row) => row.id,
+  links: (row) => `${row.source}>${row.target}:${row.kind}`,
+  requests: (row) => row.id,
+};
+function keyOf(section, row) {
+  const key = ROW_KEY[section]?.(row);
+  return typeof key === 'string' && key ? key : digest(row);
+}
+
+/**
+ * The /api/graph?hours= bodies of every window as graph_window items: one item per row, shared by the windows whose
+ * projection holds exactly that row, and a meta item per window. A row that is unchanged keeps its bytes, so the mirror
+ * uploads only rows that moved. Every row is redacted and checked on its own; one that still fails is left out and
+ * counted in `dropped`, never silently.
+ */
+export function graphWindowItems(windows, options = {}) {
+  return mergeWindows(windows.map(({ hours, body }) => windowRows(hours, body, options)));
+}
+
+/**
+ * What redacting and checking each row gave, kept from one pass to the next. Most rows are in several windows and
+ * unchanged since the last pass, so each distinct row is redacted and checked once, and again only once it moves.
+ * The results hold for one redactor: begin() with another signature (a new repo root, workspace or secret) drops them.
+ */
+export class RowMemo {
+  constructor() {
+    this.signature = null;
+    this.previous = new Map();
+    this.current = new Map();
+  }
+
+  /** Starts a pass. Only what this pass and the last one used is kept, so rows that left every window are let go. */
+  begin(signature) {
+    this.previous = signature === this.signature ? this.current : new Map();
+    this.current = new Map();
+    this.signature = signature;
+  }
+
+  take(key, compute) {
+    const value = this.current.get(key) ?? this.previous.get(key) ?? compute();
+    this.current.set(key, value);
+    return value;
+  }
+}
+
+function checkedRow(section, row, { redact, secrets, maxBytes }) {
+  const result = sanitizePart(SCHEMA[section], redact(row), { secrets });
+  const error = result.error || (itemBytes({ section, windows: GRAPH_HOURS, [section]: result.data }) > maxBytes ? 'item_too_large' : null);
+  if (error) return { error };
+  return { key: keyOf(section, result.data), text: canonical(result.data), data: result.data };
+}
+
+/**
+ * One window's redacted, checked rows and its meta item: the costly half of graphWindowItems, which a caller may keep
+ * and merge again with fresher windows. With a RowMemo, rows already checked under the same redactor are not again.
+ */
+export function windowRows(hours, body, { redact = (value) => value, secrets = [], maxBytes = MIRROR_LIMITS.maxItemBytes - ITEM_HEADROOM, memo = null } = {}) {
+  const reasons = {};
+  const counts = {};
+  const droppedRows = {};
+  const rows = [];
+  const check = { redact, secrets, maxBytes };
+  for (const [section, raw] of Object.entries(sectionRows(body))) {
+    const seen = new Map();
+    counts[section] = 0;
+    for (const row of raw) {
+      const checked = memo
+        ? memo.take(`${section}\0${JSON.stringify(row)}`, () => checkedRow(section, row, check))
+        : checkedRow(section, row, check);
+      if (checked.error) {
+        droppedRows[section] = (droppedRows[section] || 0) + 1;
+        reasons[section] ||= {};
+        reasons[section][checked.error] = (reasons[section][checked.error] || 0) + 1;
+        continue;
+      }
+      const nth = (seen.get(checked.key) || 0) + 1;
+      seen.set(checked.key, nth);
+      rows.push({ id: `${section}/${nth > 1 ? `${checked.key}~${nth}` : checked.key}`, text: checked.text, section, row: checked.data });
+      counts[section] += 1;
+    }
+  }
+  const totals = sanitizePart(SCHEMA.totals, body.totals ?? null, { secrets, depth: 2 });
+  const manager = sanitizePart(SCHEMA.manager, body.manager ? redact(body.manager) : null, { secrets, depth: 2 });
+  const meta = {
+    externalId: `meta/${hours}h`,
+    data: { section: 'meta', hours, totals: totals.error ? null : totals.data, manager: manager.error ? null : manager.data, counts, dropped: droppedRows },
+  };
+  return { hours, rows, meta, reasons };
+}
+
+/** Rows that are identical in several windows become one item held by all of them. */
+export function mergeWindows(perWindow) {
+  const variants = new Map();
+  const dropped = {};
+  const metas = [];
+  for (const { hours, rows, meta, reasons } of [...perWindow].sort((a, b) => a.hours - b.hours)) {
+    for (const { id, text, section, row } of rows) {
+      if (!variants.has(id)) variants.set(id, new Map());
+      const group = variants.get(id);
+      if (!group.has(text)) group.set(text, { section, row, windows: [] });
+      group.get(text).windows.push(hours);
+    }
+    metas.push(meta);
+    dropped[`${hours}h`] = reasons;
+  }
+  const items = [];
+  for (const [id, group] of variants) {
+    for (const { section, row, windows: held } of group.values()) items.push({ externalId: `${id}@${held.at(-1)}h`, data: { section, windows: held, [section]: row } });
+  }
+  return { items: [...metas, ...items], dropped };
+}

package/src/lib/http.js

@@ -0,0 +1,84 @@
+import { gzipSync } from 'node:zlib';
+import { HubError } from './errors.js';
+import { CONNECTOR_RESPONSE_MAX_BYTES } from './transportContract.js';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
+
+export function cleanOrigin(value, label = 'URL') {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new HubError('HUB_URL_INVALID', `${label} is not a valid URL`);
+  }
+  const loopbackHttp = parsed.protocol === 'http:' && LOOPBACK_HOSTS.has(parsed.hostname);
+  if (
+    (parsed.protocol !== 'https:' && !loopbackHttp) ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash ||
+    !['', '/'].includes(parsed.pathname)
+  ) {
+    throw new HubError('HUB_URL_INVALID', `${label} must be a clean HTTPS origin`);
+  }
+  return parsed.origin;
+}
+
+export function decodeJwtClaims(token) {
+  const parts = typeof token === 'string' ? token.split('.') : [];
+  if (parts.length !== 3) return null;
+  try {
+    const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+    return claims && typeof claims === 'object' && !Array.isArray(claims) ? claims : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchJson({
+  fetch,
+  url,
+  method = 'POST',
+  headers = {},
+  body,
+  timeoutMs = 30_000,
+  maxBytes = CONNECTOR_RESPONSE_MAX_BYTES,
+  gzipAboveBytes = Infinity,
+}) {
+  const json = body === undefined ? null : Buffer.from(JSON.stringify(body), 'utf8');
+  const gzip = json !== null && json.length > gzipAboveBytes;
+  const sent = gzip ? gzipSync(json) : json;
+  const response = await fetch(url, {
+    method,
+    headers: {
+      accept: 'application/json',
+      ...(json === null ? {} : { 'content-type': 'application/json; charset=utf-8' }),
+      ...(gzip ? { 'content-encoding': 'gzip' } : {}),
+      ...headers,
+    },
+    ...(sent === null ? {} : { body: sent }),
+    redirect: 'error',
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.length > maxBytes) {
+    throw new HubError('HUB_TRANSPORT_RESPONSE_TOO_LARGE', `Response exceeded ${maxBytes} bytes`);
+  }
+  let parsed = {};
+  try {
+    parsed = bytes.length ? JSON.parse(bytes.toString('utf8')) : {};
+  } catch (error) {
+    throw new HubError('HUB_TRANSPORT_INVALID_JSON', 'Server returned invalid JSON', { cause: error });
+  }
+  return {
+    status: response.status,
+    ok: response.ok,
+    body: parsed && typeof parsed === 'object' ? parsed : {},
+    retryAfter: response.headers.has('retry-after') ? Number(response.headers.get('retry-after')) : Number.NaN,
+    serverTiming: response.headers.get('server-timing'),
+    contractAccepts: response.headers.get('x-pulse-contract-accepts'),
+    bytes: json?.length ?? 0,
+    sentBytes: sent?.length ?? 0,
+  };
+}

package/src/lib/hubActions.js

@@ -0,0 +1,74 @@
+import { assertNever, HubError } from './errors.js';
+import { HUB_JOB_TYPES } from './intents.js';
+
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+async function write(writer, type, args) {
+  switch (type) {
+    case 'hub.chat.post': {
+      const out = await writer.post('/api/chat/post', { ch: args.ch, text: args.text });
+      if (out.queued) return { outcome: 'queued', summary: `Queued for ${args.ch.slice(3)}; the agent reads it on its next turn.` };
+      return { outcome: 'posted', summary: `Posted to ${out.channel || args.ch}.` };
+    }
+    case 'hub.nudge': {
+      const out = await writer.post('/api/message', { to: args.to, type: args.type, text: args.text });
+      return { outcome: 'sent', summary: `Sent ${args.type} to ${plural(Number(out.sent) || args.to.length, 'agent')}.` };
+    }
+    case 'hub.decision':
+      await writer.post('/api/decision', { key: args.key, kind: args.kind, text: args.text, ...(args.ref ? { ref: args.ref } : {}) });
+      return { outcome: 'recorded', summary: `Recorded ${args.kind} on ${args.key}.` };
+    case 'hub.accept':
+      await writer.post('/api/accept', { delivery: args.delivery, note: args.note || '' });
+      return { outcome: 'accepted', summary: `Accepted ${args.delivery}.` };
+    case 'hub.bus.reply':
+      await writer.post('/bus/ack', { as: 'user', id: args.id, reply: args.text });
+      return { outcome: 'replied', summary: `Replied to ${args.id}.` };
+    case 'hub.status.set': {
+      const out = await writer.post('/api/status', args);
+      if (args.step) {
+        const step = args.step[0].toUpperCase() + args.step.slice(1);
+        if (out.unchanged) return { outcome: 'recorded', summary: `${args.target.id} was already in ${step}.` };
+        const noted = Array.isArray(out.posted) && out.posted.length ? '; noted in its channel' : '';
+        return { outcome: 'recorded', summary: out.cleared ? `Moved ${args.target.id} back to ${step}, the step its work is in${noted}.` : `Moved ${args.target.id} to ${step}${noted}.` };
+      }
+      const status = `${args.status.replace('-', ' ')}${args.to ? ` to ${args.to}` : ''}`;
+      if (out.unchanged) return { outcome: 'recorded', summary: `${args.target.id} was already ${status}.` };
+      const posted = Array.isArray(out.posted) ? out.posted.length : 0;
+      return { outcome: 'recorded', summary: `Set ${args.target.id} to ${status}${posted ? `; noted in ${plural(posted, 'channel')}` : ''}.` };
+    }
+    default:
+      return assertNever(type, 'hub job type');
+  }
+}
+
+/**
+ * What a requeued action's earlier attempt on this machine settles for it. A write that may have reached the hub is
+ * never repeated: the user sees `hub_write_unconfirmed` and checks the hub rather than getting a second post.
+ */
+export function replayPriorAttempt(prior) {
+  if (!prior) return null;
+  if (prior.state === 'succeeded' && prior.result) return { result: prior.result };
+  if (prior.state === 'failed' && prior.result?.code) {
+    return { error: new HubError(prior.result.code, prior.result.summary || 'The earlier attempt failed') };
+  }
+  if (prior.startedAt || ['running', 'cancel_requested'].includes(prior.state)) {
+    return {
+      error: new HubError(
+        'hub_write_unconfirmed',
+        'An earlier attempt reached the local hub but its result was not recorded; check the hub before sending again',
+      ),
+    };
+  }
+  return null;
+}
+
+/** Job handlers for the typed `hub.*` actions; `writerFor()` resolves the local hub per job so a moved hub is found. */
+export function createHubActionHandlers({ writerFor }) {
+  const handle = (type) => async (job, context = {}) => {
+    const replay = replayPriorAttempt(context.priorAttempt);
+    if (replay?.error) throw replay.error;
+    if (replay) return replay.result;
+    return write(await writerFor(), type, job.arguments);
+  };
+  return Object.fromEntries(HUB_JOB_TYPES.map((type) => [type, handle(type)]));
+}