pactive 0.0.2-alpha.1 → 0.0.4-alpha.1

package/src/core/scheduler.mjs

@@ -1,3 +1,4 @@
+import { defaultAssistantId } from './assistants.mjs';
 import { pactiveError } from './errors.mjs';
 
 export const TASK_KINDS = ['in', 'at', 'every'];
@@ -28,26 +29,34 @@ export const schedule = {
       if (everyMs <= 0) throw pactiveError('TASK_INTERVAL_REQUIRED', 'an "every" task needs a positive interval');
       dueAt = ts + everyMs;
     } else {
+      // A relative delay may arrive either as a duration (delayMs/afterMs/ms) or already
+      // resolved to an absolute time (spec.at — what every host-surface parseWhen produces).
       const delay = Number.isFinite(spec.delayMs) ? spec.delayMs
         : Number.isFinite(spec.afterMs) ? spec.afterMs
-          : Number.isFinite(spec.ms) ? spec.ms : 0;
-      dueAt = ts + delay;
+          : Number.isFinite(spec.ms) ? spec.ms : null;
+      dueAt = delay === null && Number.isFinite(spec.at) ? spec.at : ts + (delay ?? 0);
     }
 
     const owner = spec.owner ?? state.identity?.ownerKey ?? '';
     const id = spec.id ?? `task-${ts}-${(seq += 1)}`;
+    // Every task belongs to exactly one assistant (contract §2 / I65): an unqualified task lands
+    // on the default assistant, never on "whoever happens to be first".
+    const assistantId = spec.assistantId ?? defaultAssistantId(state.identity?.ownerKey ?? '');
 
     const existing = state.tasks.find((t) => t.id === id && t.owner === owner && t.dueAt === dueAt && t.active !== false);
     if (existing) return existing;
 
     const task = {
       id,
+      assistantId,
       kind,
       dueAt,
       owner,
       everyMs,
       label: spec.label ?? null,
       payload: spec.payload ?? null,
+      // The prompt is what the trigger injects later; dropping it registers an empty reminder.
+      prompt: spec.prompt ?? spec.content ?? null,
       createdAt: ts,
       lastRunAt: 0,
       active: true,
@@ -64,8 +73,11 @@ export const schedule = {
     return state.tasks.length !== before;
   },
 
-  list(state) {
-    return Array.isArray(state.tasks) ? [...state.tasks] : [];
+  /** All tasks, or only one assistant's tasks when `assistantId` is given. */
+  list(state, assistantId) {
+    const all = Array.isArray(state.tasks) ? [...state.tasks] : [];
+    if (typeof assistantId !== 'string' || assistantId === '') return all;
+    return all.filter((t) => t && t.assistantId === assistantId);
   },
 
   /** Returns the tasks that are due now and consumes them (once for "in"/"at"). */

package/src/core/state.mjs

@@ -1,14 +1,31 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import {
+  DEFAULT_ASSISTANT_NAME,
+  defaultAssistantId,
+  makeAssistant,
+  normalizeAssistantTable,
+} from './assistants.mjs';
 import { pactiveError } from './errors.mjs';
 import { ensureDir, withLock } from './lock.mjs';
 import { ledger } from './lineage.mjs';
 
-export const SCHEMA_VERSION = 1;
+/** Schema v2 adds the assistant fleet (contract §2 / I61–I66). */
+export const SCHEMA_VERSION = 2;
+export const LEGACY_SCHEMA_VERSION = 1;
+export const GLOBAL_HOURLY_LIMIT_DEFAULT = 24;
 
 let tmpSeq = 0;
 
+export function defaultGuard() {
+  return { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 };
+}
+
+export function defaultGlobalGuard() {
+  return { hourWindowStart: 0, hourCount: 0, hourlyLimit: GLOBAL_HOURLY_LIMIT_DEFAULT };
+}
+
 export function defaultState() {
   return {
     schemaVersion: SCHEMA_VERSION,
@@ -27,9 +44,14 @@ export function defaultState() {
       minIntervalMs: 600000,
       cooldownMs: 1800000,
     },
-    // lastTriggerEpoch is the extra field the frozen shape does not carry: the
-    // "one trigger per activity epoch" rule needs the epoch of the last trigger.
-    guard: { hourWindowStart: 0, hourCount: 0, lastTriggerAt: 0, lastTriggerEpoch: -1 },
+    // `guard` stays the guard bucket of the `default` assistant (the schema-v1 shape is
+    // exactly one assistant's counters, so no migration shim is needed for it).
+    guard: defaultGuard(),
+    // Every named assistant gets its own bucket: A's cooldown must not throttle B (I62).
+    guardByAssistant: {},
+    // One fleet-wide ceiling no amount of assistants can bypass (I64).
+    globalGuard: defaultGlobalGuard(),
+    assistants: {},
     tasks: [],
     peers: {},
     outbox: [],
@@ -78,6 +100,42 @@ export function ensureStateDirs(paths) {
   return paths;
 }
 
+function normalizeGuard(raw, fallback) {
+  const guard = { ...fallback, ...(raw && typeof raw === 'object' ? raw : {}) };
+  if (!Number.isFinite(guard.hourWindowStart)) guard.hourWindowStart = 0;
+  if (!Number.isFinite(guard.hourCount)) guard.hourCount = 0;
+  if (!Number.isFinite(guard.lastTriggerAt)) guard.lastTriggerAt = 0;
+  if (!Number.isFinite(guard.lastTriggerEpoch)) guard.lastTriggerEpoch = -1;
+  return guard;
+}
+
+function normalizeGuardTable(raw) {
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof key !== 'string' || key === '') continue;
+    out[key] = normalizeGuard(value, defaultGuard());
+  }
+  return out;
+}
+
+function normalizeTasks(raw, fallbackAssistantId) {
+  const list = Array.isArray(raw) ? raw : [];
+  const out = [];
+  for (const task of list) {
+    // A non-object entry is dropped, but the caller can see the count change: the read path
+    // normalises rather than inventing fields on garbage.
+    if (!task || typeof task !== 'object') continue;
+    out.push({
+      ...task,
+      assistantId: typeof task.assistantId === 'string' && task.assistantId
+        ? task.assistantId
+        : fallbackAssistantId,
+    });
+  }
+  return out;
+}
+
 function normalize(raw) {
   const base = defaultState();
   const state = { ...base, ...raw };
@@ -85,9 +143,13 @@ function normalize(raw) {
   state.identity = { ...base.identity, ...(raw.identity || {}) };
   state.idle = { ...base.idle, ...(raw.idle || {}) };
   state.policy = { ...base.policy, ...(raw.policy || {}) };
-  state.guard = { ...base.guard, ...(raw.guard || {}) };
-  if (!Number.isFinite(state.guard.lastTriggerEpoch)) state.guard.lastTriggerEpoch = -1;
-  state.tasks = Array.isArray(raw.tasks) ? raw.tasks : [];
+  state.guard = normalizeGuard(raw.guard, base.guard);
+  state.guardByAssistant = normalizeGuardTable(raw.guardByAssistant);
+  state.globalGuard = { ...base.globalGuard, ...(raw.globalGuard || {}) };
+  if (!Number.isFinite(state.globalGuard.hourlyLimit)) state.globalGuard.hourlyLimit = GLOBAL_HOURLY_LIMIT_DEFAULT;
+  const ownerKey = typeof state.identity.ownerKey === 'string' ? state.identity.ownerKey : '';
+  state.assistants = normalizeAssistantTable(raw.assistants, ownerKey);
+  state.tasks = normalizeTasks(raw.tasks, defaultAssistantId(ownerKey));
   state.peers = raw.peers && typeof raw.peers === 'object' ? raw.peers : {};
   state.outbox = Array.isArray(raw.outbox) ? raw.outbox : [];
   state.busy = raw.busy === true;
@@ -99,6 +161,57 @@ function normalize(raw) {
   return state;
 }
 
+/**
+ * Schema v1 → v2: one single-assistant state becomes the `default` assistant.
+ *
+ * Failure is explicit (I20): a v1 file whose tasks cannot be carried over must raise instead of
+ * being quarantined into an empty state, because "quarantine and start fresh" looks identical to
+ * "the user never had anything".
+ */
+export function migrateStateV1(raw, now = Date.now()) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw pactiveError('STATE_MIGRATION_FAILED', 'schema v1 state is not an object');
+  }
+  if (raw.tasks !== undefined && !Array.isArray(raw.tasks)) {
+    throw pactiveError('STATE_MIGRATION_FAILED', 'schema v1 state has a non-array tasks field; refusing to drop it');
+  }
+  const tasks = Array.isArray(raw.tasks) ? raw.tasks : [];
+  const ownerKey = typeof raw.identity?.ownerKey === 'string' ? raw.identity.ownerKey : '';
+  const id = defaultAssistantId(ownerKey);
+  const assistant = makeAssistant(
+    {
+      assistantId: id,
+      name: DEFAULT_ASSISTANT_NAME,
+      title: DEFAULT_ASSISTANT_NAME,
+      // I15: "installed" is not "enabled" — the migrated assistant inherits the old switch.
+      enabled: raw.idle?.enabled === true,
+      createdAt: Number.isFinite(raw.createdAt) ? raw.createdAt : now,
+    },
+    ownerKey,
+    now,
+  );
+  const migratedTasks = tasks.map((task) => {
+    if (!task || typeof task !== 'object') return task;
+    return { ...task, assistantId: id };
+  });
+  if (migratedTasks.length !== tasks.length) {
+    throw pactiveError('STATE_MIGRATION_FAILED', 'schema v1 tasks could not be carried over without loss');
+  }
+  return {
+    ...raw,
+    schemaVersion: SCHEMA_VERSION,
+    assistants: { [id]: assistant },
+    tasks: migratedTasks,
+    guardByAssistant: {},
+    globalGuard: defaultGlobalGuard(),
+  };
+}
+
+/** True when the state file on disk still speaks schema v1 (the CLI reports it). */
+export function needsMigration(parsed) {
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) && parsed.schemaVersion === LEGACY_SCHEMA_VERSION;
+}
+
 export function loadState(target) {
   const paths = toPaths(target);
   let raw;
@@ -108,16 +221,25 @@ export function loadState(target) {
     if (err.code === 'ENOENT') return defaultState();
     throw err;
   }
+  let parsed;
   try {
-    const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || parsed.schemaVersion !== SCHEMA_VERSION) {
-      throw pactiveError('STATE_SCHEMA_UNSUPPORTED', `unsupported schemaVersion in ${paths.stateFile}`);
-    }
-    return normalize(parsed);
+    parsed = JSON.parse(raw);
   } catch (err) {
     quarantine(paths, err);
     return defaultState();
   }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    quarantine(paths, { code: 'STATE_SCHEMA_UNSUPPORTED' });
+    return defaultState();
+  }
+  if (parsed.schemaVersion === SCHEMA_VERSION) return normalize(parsed);
+  if (needsMigration(parsed)) {
+    // Migration happens on read (read-only callers such as `status`/`doctor` never write);
+    // the next write persists v2 through saveState.
+    return normalize(migrateStateV1(parsed));
+  }
+  quarantine(paths, { code: 'STATE_SCHEMA_UNSUPPORTED' });
+  return defaultState();
 }
 
 function quarantine(paths, cause) {

package/src/core/tick.mjs

@@ -0,0 +1,128 @@
+import { defaultAssistantId } from './assistants.mjs';
+import { reserveTrigger } from './guard.mjs';
+import { evaluateIdle } from './idle.mjs';
+import { ledger } from './lineage.mjs';
+
+/** Reasons that mean "this really was going to fire but the throttle held it back". */
+export const THROTTLE_REASONS = ['quiet', 'hourly-limit', 'global-limit', 'min-interval', 'cooldown'];
+
+/**
+ * One drive round: due tasks + one idle sweep per enabled assistant,结果落 ledger。
+ *
+ * This is the minimal closed loop before a daemon exists: `pactive tick` runs it once, so the
+ * fleet is testable unattended. A blocked task stays active (retried next tick) — losing a
+ * reminder because the guard was closed would be silent data loss.
+ *
+ * ledger events (append-only, per assistantId): `triggered` + `delivered`, or `blocked`+reason.
+ */
+export function runTick(state, now = Date.now(), options = {}) {
+  const ts = Number.isFinite(now) ? now : Date.now();
+  const ledgerFile = typeof options.ledgerFile === 'string' && options.ledgerFile ? options.ledgerFile : null;
+  const only = typeof options.assistantId === 'string' && options.assistantId !== '' ? options.assistantId : null;
+  const record = (event) => {
+    if (ledgerFile) ledger.append(ledgerFile, event);
+    return event;
+  };
+
+  const delivered = [];
+  const blocked = [];
+  const fallbackId = defaultAssistantId(state.identity?.ownerKey ?? '');
+  const table = state.assistants && typeof state.assistants === 'object' ? state.assistants : {};
+  const tasks = Array.isArray(state.tasks) ? state.tasks : [];
+
+  const queued = [];
+  const unreachable = [];
+  /**
+   * Deliver one prompt and let the receipt decide the ledger event (contract §2.2):
+   * a bound pane that only *admitted* the text is `queued`, never `delivered` (I77).
+   */
+  const deliverOne = (base) => {
+    const assistant = table[base.assistantId] ?? null;
+    const pane = assistant?.pane ?? null;
+    if (pane && typeof options.paneDeliver === 'function') {
+      const receipt = options.paneDeliver({ ...base, pane }) ?? { state: 'queued', reason: 'no-receipt' };
+      const common = { assistantId: base.assistantId, paneId: pane.paneId, agentName: pane.agentName ?? null, ...base };
+      if (receipt.state === 'accepted') {
+        return delivered.push(record({
+          event: 'delivered',
+          ...common,
+          surface: 'herdr',
+          status: receipt.status ?? null,
+        }));
+      }
+      if (receipt.state === 'unreachable') {
+        // The pane is gone: drop the binding so the next `fleet up` can rebuild it. The
+        // assistant, its tasks and its history stay (I75).
+        assistant.pane = null;
+        return unreachable.push(record({ event: 'unreachable', ...common, reason: receipt.reason ?? 'unreachable' }));
+      }
+      return queued.push(record({ event: 'queued', ...common, reason: receipt.reason ?? 'queued' }));
+    }
+    // No pane: the in-process/outbox path (unchanged), but `paneId` is always present.
+    return delivered.push(record({ event: 'delivered', paneId: null, ...base }));
+  };
+
+  // ① Due tasks (explicit user reminders): min-interval/cooldown do not apply, the user asked.
+  for (const task of tasks) {
+    if (!task || typeof task !== 'object' || task.active === false) continue;
+    if (!Number.isFinite(task.dueAt) || task.dueAt > ts) continue;
+    const assistantId = typeof task.assistantId === 'string' && task.assistantId ? task.assistantId : fallbackId;
+    if (only && assistantId !== only) continue;
+    const res = reserveTrigger(state, ts, assistantId, { ignoreEpoch: true, skipIntervalGates: true });
+    if (res.reserved) {
+      task.lastRunAt = ts;
+      if (task.kind === 'every') task.dueAt = ts + (Number.isFinite(task.everyMs) ? task.everyMs : 0);
+      else task.active = false;
+      const assistant = table[assistantId];
+      if (assistant) {
+        assistant.lastFiredAt = ts;
+        assistant.firedCount = (Number.isFinite(assistant.firedCount) ? assistant.firedCount : 0) + 1;
+      }
+      record({ event: 'triggered', assistantId, taskId: task.id, taskKind: task.kind, source: 'tick' });
+      deliverOne({
+        assistantId,
+        taskId: task.id,
+        taskKind: task.kind,
+        source: 'tick',
+        prompt: task.prompt ?? null,
+      });
+    } else {
+      blocked.push(record({ event: 'blocked', assistantId, taskId: task.id, source: 'tick', reason: res.reason }));
+    }
+  }
+
+  // ② Idle sweep: only enabled assistants, only throttle reasons are recorded (no ledger spam).
+  for (const [assistantId, assistant] of Object.entries(table)) {
+    if (!assistant || assistant.enabled !== true) continue;
+    if (only && assistantId !== only) continue;
+    const result = evaluateIdle(state, ts, {}, assistantId);
+    if (result.idle) {
+      const res = reserveTrigger(state, ts, assistantId);
+      if (res.reserved) {
+        assistant.lastFiredAt = ts;
+        assistant.firedCount = (Number.isFinite(assistant.firedCount) ? assistant.firedCount : 0) + 1;
+        record({ event: 'triggered', assistantId, source: 'tick', reason: 'idle' });
+        deliverOne({ assistantId, source: 'tick', reason: 'idle' });
+      } else {
+        blocked.push(record({ event: 'blocked', assistantId, source: 'tick', reason: res.reason }));
+      }
+    } else if (THROTTLE_REASONS.includes(result.reason)) {
+      blocked.push(record({ event: 'blocked', assistantId, source: 'tick', reason: result.reason }));
+    }
+  }
+
+  return {
+    now: ts,
+    assistantId: only,
+    assistants: Object.keys(table).length,
+    delivered: delivered.length,
+    blocked: blocked.length,
+    queued: queued.length,
+    unreachable: unreachable.length,
+    deliveries: delivered,
+    queued_events: queued,
+    unreachable_events: unreachable,
+    blocks: blocked,
+    pending: tasks.filter((t) => t && t.active !== false).length,
+  };
+}

package/src/hosts/herdr/fleet-view.mjs

@@ -0,0 +1,31 @@
+// The fleet view shared by every tool surface (MCP / Pi / DSH) and the CLI.
+//
+// It is a thin join: the *binding* comes from pactive state (I76), the *status* comes from herdr
+// (`agent list`). When herdr cannot be asked, the status is `null` → rendered as "unobserved";
+// it is never guessed (I78).
+import * as herdr from './index.mjs';
+
+/** herdr `agent list` → `{available, ok, reason, map: agentName → agent_status}`. */
+export function herdrStatus(env = process.env) {
+  const probe = herdr.available({ env });
+  const map = new Map();
+  if (!probe.ok) return { available: false, ok: false, reason: probe.reason, map };
+  const listed = herdr.list({ env });
+  if (listed.ok) for (const agent of listed.agents) if (agent.agentName) map.set(agent.agentName, agent.status);
+  return { available: true, ok: listed.ok, reason: listed.ok ? null : listed.reason, map };
+}
+
+/** `{ok, count, herdr, rows}` — one row per assistant: identity ↔ pane ↔ status ↔ last delivery. */
+export function fleetPayload(core, state, paths, env = process.env) {
+  const status = herdrStatus(env);
+  const rows = core.fleet.view(state, {
+    ledgerFile: paths.ledgerFile,
+    statusOf: (pane) => (pane.agentName ? status.map.get(pane.agentName) ?? null : null),
+  });
+  return {
+    ok: true,
+    count: rows.length,
+    herdr: { available: status.available, reason: status.reason },
+    rows,
+  };
+}