@ziggs-ai/agent-sdk 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0 — 2026-07-23
+
+### Added
+
+- New exports: `createStaleBacklogGate`, `resolveReplayPolicy`, `newestActionableAt`, `parseReplayMaxAge` (stale-backlog gating), and `decodeOperatorKeyClaims`, `boundKeyFleetWarning` (operator-key claims).
+
+### Changed (breaking)
+
+- Removed legacy socket-frame aliases; wire frames use canonical names only (ZIG-913, ZIG-915).
+- Delivery-law: classify inbound messages from the `service` wire shape (ZIG-936).
+- Bumped `@ziggs-ai/api-client` to `^0.3.0`.
+
+## 0.3.0 — 2026-07-22
+
+### Changed (breaking)
+
+- Agent delivery law: backend targeting policy, idempotent writes, and long-poll / multiplexed inbox.
+
 ## 0.2.0 — 2026-07-16
 
 ### Added (ZIG-784)

package/dist/AgentHost.js

@@ -306,14 +306,17 @@ export class AgentHost {
         }
         if (messageId)
             this.seenMessages.mark(messageId);
-        const ownAgentId = this._resolveOwnAgentId(metadata);
+        const ownAgentId = this._resolveOwnAgentId();
         if (!ownAgentId) {
             runtimeLog.warn('AgentHost', 'handleMessage: ownAgentId missing — dropping event');
             return;
         }
         let enrichedText = typeof text === 'string' ? text : '';
         if (!enrichedText.trim()) {
-            const agreement = metadata.agreement;
+            // ZIG-936: agreement rides under `service` on the inbox-pull wire; fall
+            // back to top-level for hand-built metadata.
+            const svc = metadata.service;
+            const agreement = (svc?.agreement ?? metadata.agreement);
             const terms = agreement?.terms;
             if (terms?.description) {
                 enrichedText = String(terms.description);
@@ -449,10 +452,11 @@ export class AgentHost {
             return;
         this.stateTimers.arm(laneKey, stateName, sd.timeoutMs);
     }
-    _resolveOwnAgentId(metadata = {}) {
-        const self = metadata.self;
-        const agent = metadata.agent;
-        return this.options.agentId || self?.id || agent?.id || metadata.ziggsAgentId || null;
+    _resolveOwnAgentId() {
+        // The host is constructed for exactly one agent; its own id is the only
+        // source. (The socket-frame-era metadata fallbacks — self/agent/ziggsAgentId
+        // — are gone: nothing on the inbox wire ever carried them.)
+        return this.options.agentId || null;
     }
     async connectAsync(_timeout) {
         // Bootstrap active assigned tasks once (HTTP pull → lane), then start the

package/dist/index.d.ts

@@ -40,6 +40,8 @@ export { default } from './AgentHost.js';
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
 export { ConnectionPool } from './server/ConnectionPool.js';
+export { createStaleBacklogGate, resolveReplayPolicy, newestActionableAt, parseReplayMaxAge, } from './server/staleBacklogGate.js';
+export { decodeOperatorKeyClaims, boundKeyFleetWarning } from './shared/operatorKeyClaims.js';
 export { createHealthServer } from './server/createHealthServer.js';
 export { TaskService } from './server/tasks/TaskService.js';
 export { AgreementService } from './server/agreements/AgreementService.js';

package/dist/index.js

@@ -34,6 +34,8 @@ export { default } from './AgentHost.js';
 export { validateContext, ContextWarning } from './cognition/validateContext.js';
 export { runLauncher } from './server/runLauncher.js';
 export { ConnectionPool } from './server/ConnectionPool.js';
+export { createStaleBacklogGate, resolveReplayPolicy, newestActionableAt, parseReplayMaxAge, } from './server/staleBacklogGate.js';
+export { decodeOperatorKeyClaims, boundKeyFleetWarning } from './shared/operatorKeyClaims.js';
 export { createHealthServer } from './server/createHealthServer.js';
 export { TaskService } from './server/tasks/TaskService.js';
 export { AgreementService } from './server/agreements/AgreementService.js';

package/dist/ingress/normalizeIncoming.d.ts

@@ -40,12 +40,10 @@ interface WireTask {
 }
 interface WireMetadata {
     chatId?: string;
-    chat_id?: string;
     messageId?: string;
     entryType?: string;
     content_type?: string;
     contentType?: string;
-    receiverId?: string;
     operation?: string;
     agreementId?: string;
     sender?: {
@@ -55,10 +53,13 @@ interface WireMetadata {
     receiver?: {
         id?: string;
     };
-    to?: {
-        id?: string;
-    };
     task?: WireTask;
+    service?: {
+        task?: WireTask;
+        operation?: string;
+        agreement?: unknown;
+        agreementId?: string;
+    };
     [key: string]: unknown;
 }
 interface NormalizeArgs {

package/dist/ingress/normalizeIncoming.js

@@ -5,10 +5,10 @@ const PROPOSAL_RESOLVED_OPERATIONS = new Set([
     'proposal_approved_execute',
 ]);
 function normalizeChatId(metadata) {
-    return metadata.chatId || metadata.chat_id || null;
+    return metadata.chatId || null;
 }
 function normalizeReceiverId(metadata, taskData) {
-    return metadata.receiver?.id || metadata.receiverId || metadata.to?.id || taskData?.executorId || taskData?.proposedTo || null;
+    return metadata.receiver?.id || taskData?.executorId || taskData?.proposedTo || null;
 }
 function isTaskRelated(metadata, taskData) {
     if (!taskData?.taskId)
@@ -21,7 +21,7 @@ function isTaskRelated(metadata, taskData) {
 }
 function isAgreementLifecycleNotification(metadata) {
     const entryType = metadata.entryType || 'message';
-    const operation = metadata.operation;
+    const operation = metadata.service?.operation ?? metadata.operation;
     return (entryType === 'notification' &&
         typeof operation === 'string' &&
         PROPOSAL_RESOLVED_OPERATIONS.has(operation));
@@ -36,7 +36,9 @@ function isAgreementLifecycleNotification(metadata) {
  * but no longer gates anything.
  */
 export function normalizeIncomingEvent({ text, metadata = {} }) {
-    const taskData = metadata.task || null;
+    // ZIG-936: classifier data lives under `service` on the inbox-pull wire;
+    // fall back to top-level for hand-built (direct-injection) metadata.
+    const taskData = (metadata.service?.task ?? metadata.task) || null;
     const chatId = normalizeChatId(metadata);
     const receiverId = normalizeReceiverId(metadata, taskData);
     const senderType = metadata.sender?.type ? String(metadata.sender.type).toUpperCase() : undefined;
@@ -48,13 +50,15 @@ export function normalizeIncomingEvent({ text, metadata = {} }) {
         timestamp: Date.now(),
     };
     if (isAgreementLifecycleNotification(metadata)) {
-        const agreementId = typeof metadata.agreementId === 'string' ? metadata.agreementId : '';
+        const operation = metadata.service?.operation ?? metadata.operation;
+        const rawAgreementId = metadata.service?.agreementId ?? metadata.agreementId;
+        const agreementId = typeof rawAgreementId === 'string' ? rawAgreementId : '';
         return {
             chatId,
             event: {
                 ...base,
                 type: 'agreement_lifecycle',
-                operation: metadata.operation,
+                operation,
                 agreementId,
                 text,
             },

package/dist/runtime/PromptBuilder.js

@@ -421,8 +421,8 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
             for (let i = history.length - 1; i >= 0; i--) {
                 const row = history[i];
                 const sender = row.sender;
-                const id = String(sender?.id || row.senderId || '');
-                const type = String(sender?.type || row.senderType || '').toUpperCase();
+                const id = String(sender?.id || '');
+                const type = String(sender?.type || '').toUpperCase();
                 if (id && id !== myId && !isNonRoutableSenderType(type)) {
                     defaultReplyReceiverId = id;
                     break;

package/dist/runtime/runTurn.js

@@ -809,8 +809,8 @@ function pickPrimaryUserIdFromContext(context) {
     for (let i = hist.length - 1; i >= 0; i--) {
         const row = hist[i];
         const sender = row?.sender;
-        const type = String(sender?.type || row?.senderType || '').toUpperCase();
-        const id = (sender?.id ?? row?.senderId);
+        const type = String(sender?.type || '').toUpperCase();
+        const id = sender?.id;
         if (type === 'USER' && id)
             return id;
     }

package/dist/server/ConnectionPool.d.ts

@@ -1,3 +1,17 @@
+/**
+ * ConnectionPool — multi-agent fleet manager.
+ *
+ * Holds N `AgentHostOptions` configs but only constructs/wakes an
+ * `AgentHost` (one WS connection) when needed. Idle hosts are slept after
+ * `idleTimeoutMs`. At most `maxActive` hosts are connected at a time; LRU
+ * eviction drops the oldest if the cap is reached. With `startControl`, a
+ * separate "launcher" socket receives backend-driven wake hints so the pool
+ * spins up the right host on demand.
+ *
+ * This is how a single Node process serves a fleet of agents without
+ * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
+ */
+import { type InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
 import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
 interface ConnectionManagerMeta {
     domain?: string;
@@ -13,6 +27,11 @@ interface QueryFilter {
 export interface PoolOptions {
     maxActive?: number;
     idleTimeoutMs?: number;
+    /**
+     * Gate on the operator-poll lazy start (ZIG-910): return false to leave an
+     * actionable agent's host down this pass. Explicit startAgent()s are not gated.
+     */
+    shouldLazyStart?: (entry: InboxOperatorAgentEntry) => boolean;
 }
 export interface SendToOptions {
     timeoutMs?: number;
@@ -25,17 +44,17 @@ export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
     private readonly responseListeners;
-    constructor({ maxActive, idleTimeoutMs }?: PoolOptions);
+    constructor({ maxActive, idleTimeoutMs, shouldLazyStart }?: PoolOptions);
     /**
-     * Register N agent configs. Each will be lazily woken (a fresh
+     * Register N agent configs. Each will be lazily started (a fresh
      * `AgentHost` constructed + connected) the first time it's referenced.
      */
     register(configs: AgentHostOptions[], metaArr?: ConnectionManagerMeta[]): void;
-    wake(agentId: string): Promise<AgentHost>;
+    startAgent(agentId: string): Promise<AgentHost>;
     sleep(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
     /**
-     * Wake the named agent, deliver a message, and wait for its first outbound
+     * Start the named agent, deliver a message, and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.
      *
      * The effectTap injected in `register` drains a per-agent listener queue;
@@ -44,7 +63,7 @@ export declare class ConnectionPool {
      */
     requestFrom(agentId: string, text: string, metadata?: Record<string, unknown>, { timeoutMs }?: SendToOptions): Promise<string>;
     /**
-     * Wake the named agent and deliver one wire frame to it. Returns once the
+     * Start the named agent and deliver one wire frame to it. Returns once the
      * host has finished processing.
      *
      * Note: does not return the agent's response. For request/response

package/dist/server/ConnectionPool.js

@@ -19,11 +19,11 @@ export class ConnectionPool {
     configs = new Map();
     // Listeners enqueued by requestFrom — drained on outbound send-message effects.
     responseListeners = new Map();
-    constructor({ maxActive = 50, idleTimeoutMs = 60_000 } = {}) {
-        this.manager = new ConnectionManager({ maxActive, idleTimeoutMs });
+    constructor({ maxActive = 50, idleTimeoutMs = 60_000, shouldLazyStart } = {}) {
+        this.manager = new ConnectionManager({ maxActive, idleTimeoutMs, shouldLazyStart });
     }
     /**
-     * Register N agent configs. Each will be lazily woken (a fresh
+     * Register N agent configs. Each will be lazily started (a fresh
      * `AgentHost` constructed + connected) the first time it's referenced.
      */
     register(configs, metaArr = []) {
@@ -56,7 +56,7 @@ export class ConnectionPool {
                     },
                 });
                 await host.connectAsync();
-                runtimeLog.debug('ConnectionPool', `woke "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`);
+                runtimeLog.debug('ConnectionPool', `started "${agentId}" (active: ${this.manager.listActive().length}/${this.maxActive})`);
                 return host;
             }, async (host) => {
                 host.disconnect();
@@ -64,8 +64,8 @@ export class ConnectionPool {
             }, metaByAgentId.get(agentId));
         }
     }
-    async wake(agentId) {
-        return await this.manager.wake(agentId);
+    async startAgent(agentId) {
+        return await this.manager.startAgent(agentId);
     }
     async sleep(agentId) {
         return this.manager.sleep(agentId);
@@ -74,7 +74,7 @@ export class ConnectionPool {
         return this.manager.sleepAll();
     }
     /**
-     * Wake the named agent, deliver a message, and wait for its first outbound
+     * Start the named agent, deliver a message, and wait for its first outbound
      * `send-message` effect — i.e. the agent's reply. Returns the reply text.
      *
      * The effectTap injected in `register` drains a per-agent listener queue;
@@ -82,7 +82,7 @@ export class ConnectionPool {
      * does not reply within `timeoutMs` (default 60 s for LLM agents).
      */
     async requestFrom(agentId, text, metadata = {}, { timeoutMs = 60_000 } = {}) {
-        const host = await this.wake(agentId);
+        const host = await this.startAgent(agentId);
         return new Promise((resolve, reject) => {
             let settled = false;
             const timer = setTimeout(() => {
@@ -123,14 +123,14 @@ export class ConnectionPool {
         });
     }
     /**
-     * Wake the named agent and deliver one wire frame to it. Returns once the
+     * Start the named agent and deliver one wire frame to it. Returns once the
      * host has finished processing.
      *
      * Note: does not return the agent's response. For request/response
      * semantics use `requestFrom`.
      */
     async sendTo(agentId, text, metadata = {}, { timeoutMs = 30_000 } = {}) {
-        const host = await this.wake(agentId);
+        const host = await this.startAgent(agentId);
         const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`sendTo timeout for "${agentId}" after ${timeoutMs}ms`)), timeoutMs));
         await Promise.race([host.handleMessage(text, metadata), timeoutPromise]);
         this.manager.touch(agentId);

package/dist/server/agreements/AgreementService.d.ts

@@ -22,6 +22,12 @@ export declare class AgreementService {
     counter(agreementId: string, counter: CounterAgreementData): Promise<Agreement>;
     getStatus(agreementId: string): Promise<unknown | null>;
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
+    /**
+     * ZIG-942: despite the name, the default returns every agreement the
+     * caller's grant can read in the active org — including ones the caller is
+     * not a party to (`isYou` all-false). Pass `{ partyOnly: true }` for only
+     * agreements where the caller is a party.
+     */
     mine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(agreementId: string): Promise<Agreement | null>;
     create(body: CreateAgreementBody): Promise<{

package/dist/server/agreements/AgreementService.js

@@ -46,6 +46,12 @@ export class AgreementService {
     list(filters = {}) {
         return listAgreements(filters, this.creds);
     }
+    /**
+     * ZIG-942: despite the name, the default returns every agreement the
+     * caller's grant can read in the active org — including ones the caller is
+     * not a party to (`isYou` all-false). Pass `{ partyOnly: true }` for only
+     * agreements where the caller is a party.
+     */
     mine(filters = {}) {
         return getMyAgreements(filters, this.creds);
     }

package/dist/server/createHealthServer.js

@@ -19,11 +19,11 @@ function readJsonBody(req) {
 export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents', pool, } = {}) {
     const server = createServer(async (req, res) => {
         const url = req.url ?? '/';
-        const wakeMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
-        if (req.method === 'POST' && wakeMatch && pool) {
-            const agentId = decodeURIComponent(wakeMatch[1]);
+        const startMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
+        if (req.method === 'POST' && startMatch && pool) {
+            const agentId = decodeURIComponent(startMatch[1]);
             try {
-                await pool.wake(agentId);
+                await pool.startAgent(agentId);
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ ok: true, agentId, active: pool.listActive().includes(agentId) }));
             }
@@ -45,7 +45,7 @@ export function createHealthServer({ port = Number(process.env.PORT) || 8080, la
                     res.end(JSON.stringify({ ok: false, error: 'agentId, chatId, text, senderId required' }));
                     return;
                 }
-                const host = (await pool.wake(agentId));
+                const host = (await pool.startAgent(agentId));
                 await host.handleMessage(text, {
                     chatId,
                     entryType: 'message',

package/dist/server/inboxLoop.js

@@ -7,33 +7,6 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
-/** Map Mongo message row → wire metadata for normalizeIncomingEvent. */
-function rowToMetadata(row, chatId) {
-    const senderRaw = row.sender;
-    const senderId = String(senderRaw?.agentId ?? senderRaw?.id ?? '');
-    const receiver = row.receiver;
-    const senderType = senderRaw?.type ??
-        (receiver?.type === 'agent' ? 'agent' : 'user');
-    return {
-        chatId,
-        chat_id: chatId,
-        messageId: row.messageId,
-        sender: { id: senderId, type: senderType },
-        senderId,
-        senderType: String(senderType).toUpperCase(),
-        receiver: receiver ?? null,
-        receiverId: receiver?.id ?? null,
-        entryType: row.entryType ?? 'message',
-        content_type: row.content_type ?? row.contentType ?? 'text',
-        contentType: row.content_type ?? row.contentType ?? 'text',
-        task: row.task ?? null,
-        agreement: row.agreement ?? null,
-        operation: row.operation ?? null,
-        agreementId: row.agreementId ?? null,
-        timestamp: row.timestamp,
-        text: row.text,
-    };
-}
 async function chatIdsForScope(scope, creds, grants) {
     const { kind, id } = scope.scope;
     switch (kind) {
@@ -82,8 +55,7 @@ async function deliverMessagesForScope(deps, scope, chatIds, reader, countCap) {
                 const text = typeof row.text === 'string' ? row.text : '';
                 if (!text.trim())
                     continue;
-                const metadata = rowToMetadata(row, chatId);
-                await deps.onMessage(text, metadata);
+                await deps.onMessage(text, { ...row, chatId });
                 delivered++;
                 if (remaining !== Number.POSITIVE_INFINITY)
                     remaining--;

package/dist/server/runLauncher.d.ts

@@ -18,7 +18,7 @@ interface FleetOptions extends SingleOptions {
     wsUrl?: string;
     agentMeta?: Record<string, unknown>[];
     primary?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
-    preWake?: string[];
+    preStart?: string[];
     poolOptions?: {
         maxActive?: number;
         idleTimeoutMs?: number;

package/dist/server/runLauncher.js

@@ -1,6 +1,8 @@
 import { ConnectionPool } from './ConnectionPool.js';
 import { AgentHost } from '../AgentHost.js';
 import { createHealthServer } from './createHealthServer.js';
+import { createStaleBacklogGate, resolveReplayPolicy } from './staleBacklogGate.js';
+import { boundKeyFleetWarning } from '../shared/operatorKeyClaims.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 export async function runLauncher(configOrConfigs, opts = {}) {
     if (Array.isArray(configOrConfigs))
@@ -34,8 +36,14 @@ async function runSingle(config, { operatorKey, label = 'agent', port = process.
     });
     return { agent, healthServer: server ?? undefined };
 }
-async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, preWake = [], poolOptions, onShutdown, } = {}) {
-    const pool = new ConnectionPool(poolOptions);
+async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080, healthServer = true, label = 'launcher', agentMeta, primary: primaryConfig, preStart = [], poolOptions, onShutdown, } = {}) {
+    // ZIG-910: don't resurrect stale backlogs at bootstrap. Env-driven default
+    // (FLEET_REPLAY_MAX_AGE / FLEET_REPLAY_STALE); an explicit
+    // poolOptions.shouldLazyStart wins.
+    const pool = new ConnectionPool({
+        shouldLazyStart: createStaleBacklogGate({ ...resolveReplayPolicy(), label }),
+        ...poolOptions,
+    });
     const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
     const decoratedConfigs = effectiveKey
         ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
@@ -50,6 +58,11 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
     }
     const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? resolvedPrimaryConfig?.operatorKey;
     if (controlKey) {
+        // ZIG-911: an agent-bound key half-works in a confusing way — say the big
+        // thing once at startup instead of letting N-1 per-agent loops 403.
+        const boundWarning = boundKeyFleetWarning(controlKey, pool.size);
+        if (boundWarning)
+            runtimeLog.warn(label, boundWarning);
         pool.startControl({ wsUrl, operatorKey: controlKey });
     }
     else {
@@ -68,10 +81,10 @@ async function runFleet(configs, { operatorKey, wsUrl = process.env.WS_URL, port
             runtimeLog.warn(label, `Primary agent "${resolvedPrimaryConfig.name || resolvedPrimaryConfig.ownAgentId || 'primary'}" failed to connect at startup: ${err.message} — will retry`);
         }
     }
-    if (preWake.length > 0) {
-        await Promise.all(preWake.map(id => pool.wake(id)
-            .then(() => runtimeLog.debug(label, `Pre-woke "${id}"`))
-            .catch(err => runtimeLog.warn(label, `Could not pre-wake "${id}": ${err.message}`))));
+    if (preStart.length > 0) {
+        await Promise.all(preStart.map(id => pool.startAgent(id)
+            .then(() => runtimeLog.debug(label, `Pre-started "${id}"`))
+            .catch(err => runtimeLog.warn(label, `Could not pre-start "${id}": ${err.message}`))));
     }
     runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
     process.on('SIGTERM', async () => {

package/dist/server/staleBacklogGate.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Launcher startup backlog policy (ZIG-910).
+ *
+ * "Work waits" has no statute of limitations on the backend — the inbox never
+ * expires anything. But when a fleet comes up after a dark period, replaying
+ * every weeks-old actionable slice means a mass of LLM turns on stale work at
+ * real token cost. The consumer chooses what to pick up: this gate keeps the
+ * operator-poll lazy start from resurrecting agents whose newest actionable
+ * item is older than a cutoff. Skips are never silent — one loud aggregated
+ * summary line announces what was left down and how to opt back in.
+ *
+ * Env:
+ *   FLEET_REPLAY_MAX_AGE  cutoff, e.g. "3d" | "12h" | "30m" | bare number =
+ *                         days (default "3d")
+ *   FLEET_REPLAY_STALE=1  replay everything (disable the gate)
+ *
+ * Scope is the launcher only. The backend inbox is untouched, explicit
+ * `pool.startAgent()` / preStart are untouched, and an agent with ANY fresh item
+ * starts normally (its own inbox loop then drains the stale backlog too).
+ */
+import type { InboxEnvelope, InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
+export declare const DEFAULT_REPLAY_MAX_AGE_MS: number;
+export interface ReplayPolicy {
+    /** Skip slices whose newest actionable item is older than this. */
+    maxAgeMs: number;
+    /** FLEET_REPLAY_STALE=1 — replay everything, gate disabled. */
+    replayAll: boolean;
+}
+/**
+ * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
+ * granularity). Returns null on garbage so the caller can warn and fall back.
+ */
+export declare function parseReplayMaxAge(raw: string): number | null;
+export declare function resolveReplayPolicy(env?: NodeJS.ProcessEnv): ReplayPolicy;
+/**
+ * Newest actionable timestamp across an agent's slice: scope activity,
+ * proposals, and connection/MCP requests. Null when nothing carries a
+ * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ */
+export declare function newestActionableAt(inbox: InboxEnvelope): number | null;
+export declare function formatAge(ms: number): string;
+export interface StaleBacklogGateOptions extends ReplayPolicy {
+    label?: string;
+    now?: () => number;
+    log?: (line: string) => void;
+}
+/**
+ * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
+ * resurface in every envelope (reading never acks), so announcements are
+ * per-agent-once: each poll pass that skips agents not yet announced emits one
+ * aggregated warn line covering them.
+ */
+export declare function createStaleBacklogGate({ maxAgeMs, replayAll, label, now, log, }: StaleBacklogGateOptions): (entry: InboxOperatorAgentEntry) => boolean;

package/dist/server/staleBacklogGate.js

@@ -0,0 +1,120 @@
+import { runtimeLog } from '../shared/runtimeLog.js';
+export const DEFAULT_REPLAY_MAX_AGE_MS = 3 * 24 * 60 * 60 * 1000;
+/**
+ * "3d" | "12h" | "30m" | "45s"; a bare number means days (the knob's natural
+ * granularity). Returns null on garbage so the caller can warn and fall back.
+ */
+export function parseReplayMaxAge(raw) {
+    const m = /^\s*(\d+(?:\.\d+)?)\s*([dhms]?)\s*$/i.exec(raw);
+    if (!m)
+        return null;
+    const value = Number(m[1]);
+    if (!Number.isFinite(value) || value <= 0)
+        return null;
+    const unitMs = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1_000 }[(m[2] || 'd').toLowerCase()];
+    return value * unitMs;
+}
+export function resolveReplayPolicy(env = process.env) {
+    const replayAll = env.FLEET_REPLAY_STALE === '1' || env.FLEET_REPLAY_STALE === 'true';
+    const raw = env.FLEET_REPLAY_MAX_AGE?.trim();
+    let maxAgeMs = DEFAULT_REPLAY_MAX_AGE_MS;
+    if (raw) {
+        const parsed = parseReplayMaxAge(raw);
+        if (parsed == null) {
+            runtimeLog.warn('staleBacklogGate', `FLEET_REPLAY_MAX_AGE="${raw}" is not a duration (use e.g. "3d", "12h", "30m") — using default ${formatAge(DEFAULT_REPLAY_MAX_AGE_MS)}`);
+        }
+        else {
+            maxAgeMs = parsed;
+        }
+    }
+    return { maxAgeMs, replayAll };
+}
+/**
+ * Newest actionable timestamp across an agent's slice: scope activity,
+ * proposals, and connection/MCP requests. Null when nothing carries a
+ * timestamp (e.g. a joined-but-idle chat) — age unprovable, treated as fresh.
+ */
+export function newestActionableAt(inbox) {
+    let newest = null;
+    const consider = (iso) => {
+        if (!iso)
+            return;
+        const t = Date.parse(iso);
+        if (!Number.isNaN(t) && (newest == null || t > newest))
+            newest = t;
+    };
+    for (const scope of inbox.scopes ?? [])
+        consider(scope.latestAt);
+    for (const p of inbox.proposalsAwaitingMe ?? [])
+        consider(p.proposedAt);
+    for (const r of inbox.connectionRequestsAwaitingMe ?? [])
+        consider(r.requestedAt);
+    for (const r of inbox.mcpServerRequestsAwaitingMe ?? [])
+        consider(r.requestedAt);
+    return newest;
+}
+/** Unread items in a slice, for the summary line. Counts are backend-capped. */
+function countItems(inbox) {
+    let items = 0;
+    for (const scope of inbox.scopes ?? []) {
+        items += (scope.newMessages ?? 0) + (scope.newArtifacts ?? 0);
+    }
+    items += (inbox.proposalsAwaitingMe ?? []).length;
+    items += (inbox.connectionRequestsAwaitingMe ?? []).length;
+    items += (inbox.mcpServerRequestsAwaitingMe ?? []).length;
+    return items;
+}
+export function formatAge(ms) {
+    if (ms >= 86_400_000)
+        return `${trimNum(ms / 86_400_000)}d`;
+    if (ms >= 3_600_000)
+        return `${trimNum(ms / 3_600_000)}h`;
+    if (ms >= 60_000)
+        return `${trimNum(ms / 60_000)}m`;
+    return `${trimNum(ms / 1_000)}s`;
+}
+function trimNum(n) {
+    return Number(n.toFixed(1)).toString();
+}
+/**
+ * Build the `shouldLazyStart` gate for the operator poll. Skipped agents
+ * resurface in every envelope (reading never acks), so announcements are
+ * per-agent-once: each poll pass that skips agents not yet announced emits one
+ * aggregated warn line covering them.
+ */
+export function createStaleBacklogGate({ maxAgeMs, replayAll, label = 'launcher', now = Date.now, log, }) {
+    const emit = log ?? ((line) => runtimeLog.warn(label, line));
+    const announced = new Set();
+    let pendingAgents = [];
+    let pendingItems = 0;
+    let flushScheduled = false;
+    // One envelope's entries are gated synchronously; a microtask-deferred
+    // flush turns a whole boot flood into a single summary line.
+    const flush = () => {
+        flushScheduled = false;
+        if (pendingAgents.length === 0)
+            return;
+        const preview = pendingAgents.slice(0, 5).join(', ');
+        const more = pendingAgents.length > 5 ? `, +${pendingAgents.length - 5} more` : '';
+        emit(`startup backlog policy: skipped ${pendingItems} stale item(s) across ${pendingAgents.length} agent(s) older than ${formatAge(maxAgeMs)} (${preview}${more}) — set FLEET_REPLAY_STALE=1 to replay them`);
+        pendingAgents = [];
+        pendingItems = 0;
+    };
+    return (entry) => {
+        if (replayAll)
+            return true;
+        const newest = newestActionableAt(entry.inbox);
+        if (newest == null || now() - newest <= maxAgeMs)
+            return true;
+        if (!announced.has(entry.agentId)) {
+            announced.add(entry.agentId);
+            pendingAgents.push(entry.agentId);
+            pendingItems += countItems(entry.inbox);
+            if (!flushScheduled) {
+                flushScheduled = true;
+                queueMicrotask(flush);
+            }
+        }
+        return false;
+    };
+}

package/dist/server/tools/tier2/contextTools.js

@@ -129,7 +129,7 @@ export const contextDiscoverGrantableTool = defineTool('context_discover_grantab
     const items = await new ContextDiscoveryClient(operatorKey, agentId).discoverGrantable();
     return { count: items.length, items };
 }, {
-    description: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
+    description: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Covers chats, agreements, and connections (type is one of "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only ({ type, label, scopeRef, orgId } per item), never content, member names, tokens, or money. Bounded to orgs you have an active agreement in, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
 });
 export const CONTEXT_TOOLS = [
     contextReadTool,

package/dist/shared/operatorKeyClaims.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Client-side peek at an operator key's JWT payload (signature NOT verified —
+ * identity hint only, the backend remains the authority). Used by the fleet
+ * launcher to warn when the key is agent-bound (ZIG-911): a bound key
+ * collapses the operator multiplex to its one agent and 403s every other
+ * per-agent loop, so a large fleet quietly watches a single agent.
+ */
+export interface OperatorKeyClaims {
+    type?: string;
+    keyId?: string;
+    ownerId?: string;
+    boundAgentId?: string | null;
+    exp?: number;
+}
+export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
+/**
+ * The ZIG-911 startup check: warn (never refuse — a one-agent launcher on a
+ * bound key is legitimate) when the fleet's control key is bound to a single
+ * agent while more than one agent is registered. Returns the warning line, or
+ * null when the setup is coherent.
+ */
+export declare function boundKeyFleetWarning(operatorKey: string, registeredAgents: number): string | null;

package/dist/shared/operatorKeyClaims.js

@@ -0,0 +1,35 @@
+export function decodeOperatorKeyClaims(token) {
+    const parts = token.trim().split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const payload = JSON.parse(json);
+        return {
+            type: payload.type,
+            keyId: payload.keyId,
+            ownerId: payload.ownerId,
+            boundAgentId: payload.boundAgentId ?? null,
+            exp: payload.exp,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The ZIG-911 startup check: warn (never refuse — a one-agent launcher on a
+ * bound key is legitimate) when the fleet's control key is bound to a single
+ * agent while more than one agent is registered. Returns the warning line, or
+ * null when the setup is coherent.
+ */
+export function boundKeyFleetWarning(operatorKey, registeredAgents) {
+    if (registeredAgents <= 1)
+        return null;
+    const bound = decodeOperatorKeyClaims(operatorKey)?.boundAgentId;
+    if (!bound)
+        return null;
+    return (`fleet key is bound to agent "${bound}": the operator multiplex covers 1 of ${registeredAgents} registered agents, ` +
+        `and per-agent inbox loops for the rest will 403 ("cannot impersonate"). ` +
+        `Use an unbound owner key with agents:impersonate to run a fleet.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.2.0",
+    "@ziggs-ai/api-client": "^0.3.1",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",