@ziggs-ai/agent-sdk 0.41.1 → 0.41.2

package/CHANGELOG.md

@@ -32,6 +32,8 @@
 
 ## Unreleased
 
+## 0.41.2
+
 ## 0.41.1
 
 - Publishing names a third audience, `company`: every team in your active organization's company. A listing posted to it counts as a listing when the agent reads its wakes. Built on `@ziggs-ai/api-client` 0.37.26.

package/dist/Agent.d.ts

@@ -258,6 +258,8 @@ export declare class Agent {
     private telemetryClient?;
     private seenMessages;
     private stateTimers;
+    /** The agent's own check-backs, kept so a restart re-arms them. */
+    private wakeLedger;
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     private inboxLoop;
     private inboxLoopEnabled;
@@ -435,6 +437,18 @@ export declare class Agent {
     private _armIfTimedParked;
     private _resolveOwnAgentId;
     connectAsync(_timeout?: number): Promise<this>;
+    /**
+     * Arm the lane's timer for the agent's own `wake_at`, and save it so a
+     * restart arms it again.
+     */
+    private armOwnWake;
+    /**
+     * Arm again the check-backs this agent asked for before the process went
+     * down. A wake whose time passed in the meantime fires on the next turn,
+     * once. The lane gets a session first, since a timer frame for a lane with
+     * no session is dropped.
+     */
+    private restoreWakes;
     /**
      * plain string compare against {@link AgentOptions.requestMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.

package/dist/Agent.js

@@ -20,6 +20,7 @@ import { contextReadTool, openTool, accessExplainTool } from './platform/tools/t
 import { EventQueue } from './platform/EventQueue.js';
 import { StateTimers } from './platform/StateTimers.js';
 import { laneKeyFor } from './platform/laneKey.js';
+import { WakeLedger } from './platform/WakeLedger.js';
 import { WAKE_TOOLS } from './platform/tools/tier1/wakeTools.js';
 import { createZiggsEffectHandler } from './platform/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
@@ -222,6 +223,8 @@ export class Agent {
     telemetryClient;
     seenMessages = new SeenMessages();
     stateTimers;
+    /** The agent's own check-backs, kept so a restart re-arms them. */
+    wakeLedger;
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     inboxLoop = null;
     inboxLoopEnabled;
@@ -304,6 +307,7 @@ export class Agent {
             operatorKey: options.operatorKey,
             agentId: options.agentId,
         });
+        this.wakeLedger = new WakeLedger(this.memory);
         this.sessionStore = options.sessionStore ?? null;
         this._validate();
         this.pollRunner = createDeclaredPollRunner(this.options, {
@@ -424,7 +428,7 @@ export class Agent {
             // is built once and has no laneKey, so it derives one the same way the
             // event queue does (see laneKeyFor).
             wakeScheduler: {
-                armWakeAt: (sessionId, at, reason) => this.stateTimers.armWakeAt(laneKeyFor(this.options.agentId, sessionId), at, reason, this.wakeEffects.getStore()?.scope),
+                armWakeAt: (sessionId, at, reason) => this.armOwnWake(sessionId, at, reason),
             },
         });
         this.brain = this.options.brain?.kind === 'handler'
@@ -466,6 +470,10 @@ export class Agent {
         // nothing to redeliver, so its failure is logged and dropped here rather
         // than left as an unhandled rejection (made enqueue reject).
         this.stateTimers = new StateTimers((ev, laneKey) => {
+            // A check-back that fired is no longer waiting: a restart from here on
+            // must not fire it again.
+            if (ev.type === 'wake-at')
+                this.wakeLedger.done(laneKey);
             void this.eventQueue.enqueue(ev, laneKey).catch((err) => {
                 runtimeLog.warn('Agent', `state-timer frame failed laneKey=${laneKey}: ${err?.message || err}`);
             });
@@ -1604,8 +1612,63 @@ export class Agent {
         }
         this.pollRunner?.start();
         this.started = true;
+        // Not awaited: starting stays synchronous, so a second connect in the
+        // same turn still sees `started`. A wake re-armed a moment later is fine.
+        void this.restoreWakes();
         return this;
     }
+    /**
+     * Arm the lane's timer for the agent's own `wake_at`, and save it so a
+     * restart arms it again.
+     */
+    armOwnWake(sessionId, at, reason) {
+        const laneKey = laneKeyFor(this.options.agentId, sessionId);
+        const scope = this.wakeEffects.getStore()?.scope;
+        const armed = this.stateTimers.armWakeAt(laneKey, at, reason, scope);
+        this.wakeLedger.arm({
+            laneKey,
+            sessionId,
+            firesAt: armed.firesAt,
+            reason,
+            ...(scope ? { scope } : {}),
+        });
+        return { ...armed, durable: this.wakeLedger.durable };
+    }
+    /**
+     * Arm again the check-backs this agent asked for before the process went
+     * down. A wake whose time passed in the meantime fires on the next turn,
+     * once. The lane gets a session first, since a timer frame for a lane with
+     * no session is dropped.
+     */
+    async restoreWakes() {
+        const agentId = this.options.agentId;
+        if (!agentId)
+            return;
+        let pending;
+        try {
+            pending = await this.wakeLedger.pending();
+        }
+        catch (err) {
+            runtimeLog.warn(this.options.name || 'agent', `could not read saved wakes; they will not be re-armed: ${err?.message || err}`);
+            return;
+        }
+        for (const wake of pending) {
+            if (wake.laneKey !== laneKeyFor(agentId, wake.sessionId))
+                continue;
+            if (this.stateTimers.peek(wake.laneKey))
+                continue;
+            if (!this.sessions.has(wake.laneKey)) {
+                this.sessions.set(wake.laneKey, { sessionId: wake.sessionId, ownAgentId: agentId });
+            }
+            try {
+                this.stateTimers.armWakeAt(wake.laneKey, wake.firesAt, wake.reason, wake.scope);
+                runtimeLog.info(this.options.name || 'agent', `re-armed a saved wake laneKey=${wake.laneKey} at=${new Date(wake.firesAt).toISOString()}`);
+            }
+            catch (err) {
+                runtimeLog.warn(this.options.name || 'agent', `could not re-arm a saved wake laneKey=${wake.laneKey}: ${err?.message || err}`);
+            }
+        }
+    }
     /**
      * plain string compare against {@link AgentOptions.requestMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.

package/dist/platform/StateTimers.d.ts

@@ -38,8 +38,10 @@ export declare const MAX_WAKE_DELAY_MS: number;
  * queued timeout frame whose epoch is not the lane's currently-armed epoch was
  * cancelled or replaced and must be dropped.
  *
- * In-memory only: process restart loses all timers; each lane re-arms on its
- * next real event (sessionStore persists { ctx, state } but not timers).
+ * The timers themselves live in memory. An agent's own `wake_at` is also
+ * written to its memory notes (`WakeLedger`), and the host arms those again
+ * when it starts; a host liveness timer is not, and re-arms on the lane's next
+ * real event.
  */
 export declare class StateTimers {
     private _timers;
@@ -67,10 +69,10 @@ export declare class StateTimers {
      * the agent changing its mind, which is allowed and is why this replaces
      * rather than adds.
      *
-     * In memory only. A restart loses it; recovery requires the agent to re-arm
-     * on its next real event. Returns what actually got armed so the caller
-     * can tell the agent, since "I will wake at X" is a promise the agent will
-     * otherwise make on its own.
+     * The timer is in memory; the Agent saves what it needs to arm it again
+     * after a restart. Returns what actually got armed so the caller can tell
+     * the agent, since "I will wake at X" is a promise the agent will otherwise
+     * make on its own.
      */
     armWakeAt(laneKey: string, at: Date | number, reason?: string | null, scope?: WorkScope): {
         firesAt: number;

package/dist/platform/StateTimers.js

@@ -14,8 +14,10 @@ export const MAX_WAKE_DELAY_MS = 2 ** 31 - 1;
  * queued timeout frame whose epoch is not the lane's currently-armed epoch was
  * cancelled or replaced and must be dropped.
  *
- * In-memory only: process restart loses all timers; each lane re-arms on its
- * next real event (sessionStore persists { ctx, state } but not timers).
+ * The timers themselves live in memory. An agent's own `wake_at` is also
+ * written to its memory notes (`WakeLedger`), and the host arms those again
+ * when it starts; a host liveness timer is not, and re-arms on the lane's next
+ * real event.
  */
 export class StateTimers {
     _timers = new Map();
@@ -68,10 +70,10 @@ export class StateTimers {
      * the agent changing its mind, which is allowed and is why this replaces
      * rather than adds.
      *
-     * In memory only. A restart loses it; recovery requires the agent to re-arm
-     * on its next real event. Returns what actually got armed so the caller
-     * can tell the agent, since "I will wake at X" is a promise the agent will
-     * otherwise make on its own.
+     * The timer is in memory; the Agent saves what it needs to arm it again
+     * after a restart. Returns what actually got armed so the caller can tell
+     * the agent, since "I will wake at X" is a promise the agent will otherwise
+     * make on its own.
      */
     armWakeAt(laneKey, at, reason = null, scope) {
         const firesAtRaw = at instanceof Date ? at.getTime() : Number(at);

package/dist/platform/WakeLedger.d.ts

@@ -0,0 +1,43 @@
+import { type MemoryStore } from '../memory/MemoryStore.js';
+import type { WorkScope } from '../runtime/wakeEffects.js';
+/** One check-back an agent asked for, as it is kept across a restart. */
+export interface SavedWake {
+    laneKey: string;
+    sessionId: string;
+    firesAt: number;
+    reason: string | null;
+    scope?: WorkScope;
+}
+/**
+ * Where an agent's own check-backs are kept, so a restart does not lose them.
+ *
+ * The timer itself stays in memory (`StateTimers`). This keeps the facts
+ * needed to arm it again: which lane, when, why, and under which work. A wake
+ * is written when it is armed and marked done when it fires, so on start the
+ * host re-arms exactly the ones still waiting, and one that passed while the
+ * host was down fires once.
+ *
+ * The notes live in the agent's own memory store under a prefix no memory
+ * section uses (sections are `hire:<id>`), so the agent's memory tools never
+ * see them. Writes are chained so a mark can never land before the arm it
+ * follows.
+ *
+ * Two hosts of the same agent running at once, as during a rolling deploy,
+ * can both re-arm a wake and both fire it. That costs one extra wake, and the
+ * agent checks for an answer before it chases anyone.
+ */
+export declare class WakeLedger {
+    private readonly store;
+    private writes;
+    constructor(store: MemoryStore);
+    /** False when the store is in memory: then a restart loses wakes anyway. */
+    get durable(): boolean;
+    arm(wake: SavedWake): void;
+    done(laneKey: string): void;
+    /** The wakes still waiting to fire, for the host to arm again on start. */
+    pending(): Promise<SavedWake[]>;
+    /** Resolves when every write so far has landed. For tests and shutdown. */
+    flushed(): Promise<void>;
+    private write;
+    private warn;
+}

package/dist/platform/WakeLedger.js

@@ -0,0 +1,79 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+import { InMemoryStore } from '../memory/MemoryStore.js';
+const PREFIX = 'host:wake-at:';
+/**
+ * Where an agent's own check-backs are kept, so a restart does not lose them.
+ *
+ * The timer itself stays in memory (`StateTimers`). This keeps the facts
+ * needed to arm it again: which lane, when, why, and under which work. A wake
+ * is written when it is armed and marked done when it fires, so on start the
+ * host re-arms exactly the ones still waiting, and one that passed while the
+ * host was down fires once.
+ *
+ * The notes live in the agent's own memory store under a prefix no memory
+ * section uses (sections are `hire:<id>`), so the agent's memory tools never
+ * see them. Writes are chained so a mark can never land before the arm it
+ * follows.
+ *
+ * Two hosts of the same agent running at once, as during a rolling deploy,
+ * can both re-arm a wake and both fire it. That costs one extra wake, and the
+ * agent checks for an answer before it chases anyone.
+ */
+export class WakeLedger {
+    store;
+    writes = Promise.resolve();
+    constructor(store) {
+        this.store = store;
+    }
+    /** False when the store is in memory: then a restart loses wakes anyway. */
+    get durable() {
+        return !(this.store instanceof InMemoryStore);
+    }
+    arm(wake) {
+        const { laneKey, ...rest } = wake;
+        this.write(laneKey, { ...rest, state: 'armed' });
+    }
+    done(laneKey) {
+        this.writes = this.writes
+            .then(async () => {
+            const saved = (await this.store.get(PREFIX + laneKey));
+            if (saved?.state === 'armed') {
+                await this.store.put(PREFIX + laneKey, { ...saved, state: 'done' });
+            }
+        })
+            .catch((err) => this.warn('mark done', laneKey, err));
+    }
+    /** The wakes still waiting to fire, for the host to arm again on start. */
+    async pending() {
+        await this.writes;
+        const rows = await this.store.list(PREFIX);
+        const out = [];
+        for (const { key, value } of rows) {
+            const saved = value;
+            if (saved?.state !== 'armed' || typeof saved.sessionId !== 'string')
+                continue;
+            if (!Number.isFinite(saved.firesAt))
+                continue;
+            out.push({
+                laneKey: key.slice(PREFIX.length),
+                sessionId: saved.sessionId,
+                firesAt: saved.firesAt,
+                reason: saved.reason ?? null,
+                ...(saved.scope ? { scope: saved.scope } : {}),
+            });
+        }
+        return out;
+    }
+    /** Resolves when every write so far has landed. For tests and shutdown. */
+    flushed() {
+        return this.writes;
+    }
+    write(laneKey, value) {
+        this.writes = this.writes
+            .then(() => this.store.put(PREFIX + laneKey, value))
+            .catch((err) => this.warn('save', laneKey, err));
+    }
+    warn(what, laneKey, err) {
+        runtimeLog.warn('WakeLedger', `could not ${what} the wake for laneKey=${laneKey}: ${err?.message || err}`);
+    }
+}

package/dist/platform/tools/tier1/wakeTools.d.ts

@@ -10,13 +10,15 @@ import { type ToolDefinition } from '../../../tools/defineTool.js';
  *
  * What the platform learns from this: nothing. The wake is the agent's own
  * business — it arrives on the agent's lane, behind any real event, and no
- * server-side schedule is created.
+ * server-side schedule is created. The host keeps it in the agent's own
+ * memory notes, so a restart arms it again.
  */
 export interface WakeSchedulerPort {
     /** Arm the lane's timer. Returns when it will actually fire. */
     armWakeAt(sessionId: string, at: Date | number, reason: string | null): {
         firesAt: number;
         delayMs: number;
+        durable?: boolean;
     };
 }
 export interface WakeToolContext {

package/dist/platform/tools/tier1/wakeTools.js

@@ -38,7 +38,9 @@ export const wakeAtTool = defineTool('wake_at', {
         wakeAt: new Date(armed.firesAt).toISOString(),
         inMs: armed.delayMs,
         reason,
-        note: 'One wake is armed per lane, and arming again replaces it. This wake is held in memory: if the process restarts before it fires it is lost, and you will pick up on your next real event instead.',
+        note: armed.durable
+            ? 'One wake is armed per lane, and arming again replaces it. It is saved, so a restart of your host arms it again; if its time passed while the host was down, it wakes you once when the host is back.'
+            : 'One wake is armed per lane, and arming again replaces it. This wake is held in memory: if the process restarts before it fires it is lost, and you will pick up on your next real event instead.',
     };
 }, {
     description: 'Ask to be woken at a time, to check back on something you are waiting for. The wake arrives on this conversation, behind anything real that happens first. Arming again replaces the previous wake — a check-back schedule is a series of single wakes, so re-arm the next one each time you wake. Counts against your wake budget like any other wake.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.41.1",
+  "version": "0.41.2",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -30,7 +30,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.26",
+    "@ziggs-ai/api-client": "0.37.27",
     "@ziggs-ai/contracts": "^0.31.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",