@agentfield/sdk 0.1.137-rc.4 → 0.1.137-rc.6

package/README.md

@@ -1,5 +1,9 @@
 # AgentField TypeScript SDK
 
+## Graceful shutdown
+
+`serve()` installs SIGTERM and SIGINT handlers that notify the control plane and drain detached executions. Host processes that own signal handling can use `serve({ handleSignals: false })` and call the idempotent `shutdown()` method themselves. `AGENTFIELD_SHUTDOWN_TIMEOUT` accepts bare seconds (`30`) or durations (`30s`, `5m`) and defaults to 30 seconds. In Kubernetes, set `terminationGracePeriodSeconds` higher than this timeout.
+
 The TypeScript SDK provides an idiomatic Node.js interface for building and running AgentField agents. It mirrors the Python SDK APIs, including AI, memory, discovery, and MCP tooling.
 
 ## Installing

package/dist/index.d.ts

@@ -792,6 +792,7 @@ declare class AgentFieldClient {
     constructor(config: AgentConfig);
     register(payload: any): Promise<any>;
     getNode(nodeId: string): Promise<any>;
+    shutdown(nodeId: string): Promise<any>;
     heartbeat(status?: 'starting' | 'ready' | 'degraded' | 'offline'): Promise<HealthStatus>;
     execute<T = any>(target: string, input: any, metadata?: {
         runId?: string;
@@ -1949,6 +1950,10 @@ declare class RealtimeSession {
 }
 declare function buildSessionDefinition(name: string, options: SessionOptions): SessionDefinition;
 
+interface ServeOptions {
+    handleSignals?: boolean;
+}
+
 declare class Agent {
     readonly config: AgentConfig;
     readonly app: express.Express;
@@ -1956,6 +1961,10 @@ declare class Agent {
     readonly skills: SkillRegistry;
     private server?;
     private heartbeatTimer?;
+    private shutdownPromise?;
+    private readonly inFlightExecutions;
+    private shuttingDown;
+    private signalHandlers?;
     private readonly aiClient;
     private readonly agentFieldClient;
     private readonly memoryClient;
@@ -2074,8 +2083,10 @@ declare class Agent {
         executionId?: string;
     }): Promise<ApprovalResult>;
     private buildExecutionLogContext;
-    serve(): Promise<void>;
+    serve(options?: ServeOptions): Promise<void>;
     shutdown(): Promise<void>;
+    private performShutdown;
+    private installSignalHandlers;
     call(target: string, input: any): Promise<any>;
     /**
      * Remote call variant that submits the execution asynchronously and polls for

package/dist/index.js

@@ -4161,6 +4161,14 @@ var AgentFieldClient = class {
     });
     return res.data;
   }
+  async shutdown(nodeId) {
+    const bodyStr = JSON.stringify({ reason: "shutdown", version: this.config.version ?? "" });
+    const authHeaders = this.didAuthenticator.signRequest(Buffer.from(bodyStr));
+    const res = await this.http.post(`/api/v1/nodes/${encodeURIComponent(nodeId)}/shutdown`, bodyStr, {
+      headers: this.mergeHeaders({ "Content-Type": "application/json", ...authHeaders })
+    });
+    return res.data;
+  }
   async heartbeat(status = "ready") {
     const nodeId = this.config.nodeId;
     const bodyStr = JSON.stringify({ status, version: this.config.version ?? "", timestamp: (/* @__PURE__ */ new Date()).toISOString() });
@@ -6041,10 +6049,26 @@ function buildSessionDefinition(name, options) {
   };
 }
 
+// src/agent/signals.ts
+var DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
+function parseShutdownTimeout(value, warn = console.warn) {
+  if (!value?.trim()) return DEFAULT_SHUTDOWN_TIMEOUT_MS;
+  const text2 = value.trim();
+  if (/^\d+$/.test(text2)) return Number(text2) * 1e3;
+  const match = text2.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)$/);
+  if (match) {
+    const factors = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+    return Number(match[1]) * factors[match[2]];
+  }
+  warn(`invalid AGENTFIELD_SHUTDOWN_TIMEOUT ${JSON.stringify(value)}; using 30s`);
+  return DEFAULT_SHUTDOWN_TIMEOUT_MS;
+}
+
 // src/agent/Agent.ts
 var TargetNotFoundError = class extends Error {
 };
 var AGENTFIELD_TS_SDK_VERSION = "0.1.82";
+var POST_CANCEL_SETTLEMENT_MS = 5e3;
 var harnessRunners = /* @__PURE__ */ new WeakMap();
 function normalizeAcceptsWebhook(value) {
   if (value === true) return "true";
@@ -6074,6 +6098,10 @@ var Agent = class {
   skills = new SkillRegistry();
   server;
   heartbeatTimer;
+  shutdownPromise;
+  inFlightExecutions = /* @__PURE__ */ new Map();
+  shuttingDown = false;
+  signalHandlers;
   aiClient;
   agentFieldClient;
   memoryClient;
@@ -6473,7 +6501,7 @@ var Agent = class {
       agentNodeDid: current.agentNodeDid
     };
   }
-  async serve() {
+  async serve(options = {}) {
     await this.registerWithControlPlane();
     if (this.localVerifier) {
       try {
@@ -6493,19 +6521,70 @@ var Agent = class {
     });
     this.memoryEventClient.start();
     this.startHeartbeat();
-  }
-  async shutdown() {
-    if (this.heartbeatTimer) {
-      clearInterval(this.heartbeatTimer);
-    }
-    this.pauseManager.cancelAll();
-    await new Promise((resolve3, reject) => {
-      this.server?.close((err) => {
+    if (options.handleSignals !== false) this.installSignalHandlers();
+  }
+  shutdown() {
+    if (this.shutdownPromise) return this.shutdownPromise;
+    this.shuttingDown = true;
+    this.shutdownPromise = this.performShutdown();
+    return this.shutdownPromise;
+  }
+  async performShutdown() {
+    const listenerClosed = new Promise((resolve3, reject) => {
+      if (!this.server) return resolve3();
+      this.server.close((err) => {
         if (err) reject(err);
         else resolve3();
       });
     });
+    try {
+      await this.agentFieldClient.shutdown(this.config.nodeId);
+    } catch (err) {
+      console.warn("[Agent] Failed to notify control plane of shutdown:", err);
+    }
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+    }
+    await listenerClosed;
+    const timeoutMs = parseShutdownTimeout(process.env.AGENTFIELD_SHUTDOWN_TIMEOUT);
+    let timer;
+    const timeout = new Promise((resolve3) => {
+      timer = setTimeout(() => resolve3("timeout"), timeoutMs);
+    });
+    const drained = Promise.allSettled([...this.inFlightExecutions.values()]).then(() => "drained");
+    if (await Promise.race([drained, timeout]) === "timeout") {
+      for (const executionId of this.inFlightExecutions.keys()) {
+        this.cancelRegistry.cancel(executionId, "shutdown_timeout");
+      }
+      this.pauseManager.cancelAll();
+      let settlementTimer;
+      const settlementTimeout = new Promise((resolve3) => {
+        settlementTimer = setTimeout(resolve3, POST_CANCEL_SETTLEMENT_MS);
+      });
+      await Promise.race([
+        Promise.allSettled([...this.inFlightExecutions.values()]),
+        settlementTimeout
+      ]);
+      if (settlementTimer) clearTimeout(settlementTimer);
+    }
+    if (timer) clearTimeout(timer);
     this.memoryEventClient.stop();
+    if (this.signalHandlers) {
+      process.off("SIGTERM", this.signalHandlers.SIGTERM);
+      process.off("SIGINT", this.signalHandlers.SIGINT);
+      this.signalHandlers = void 0;
+    }
+  }
+  installSignalHandlers() {
+    if (this.signalHandlers) return;
+    const handle = (signal) => () => {
+      void this.shutdown().finally(() => {
+        process.exit(signal === "SIGTERM" ? 143 : 130);
+      });
+    };
+    this.signalHandlers = { SIGTERM: handle("SIGTERM"), SIGINT: handle("SIGINT") };
+    process.on("SIGTERM", this.signalHandlers.SIGTERM);
+    process.on("SIGINT", this.signalHandlers.SIGINT);
   }
   async call(target, input) {
     const { agentId, name } = this.parseTarget(target);
@@ -6927,11 +7006,17 @@ var Agent = class {
     this.app.post("/execute/:name", (req, res) => this.executeServerlessHttp(req, res, req.params.name));
   }
   async executeReasoner(req, res, name) {
+    if (this.shuttingDown) {
+      res.status(503).json({ error: "agent shutting down" });
+      return;
+    }
     const metadata = this.buildMetadata(req);
     const reasoner = this.reasoners.get(name);
     if (reasoner && this.shouldRunAsync(req)) {
       res.status(202).json({ status: "processing", execution_id: metadata.executionId });
-      void this.runReasonerAsync(reasoner, { targetName: name, input: req.body, metadata });
+      const execution = this.runReasonerAsync(reasoner, { targetName: name, input: req.body, metadata });
+      this.inFlightExecutions.set(metadata.executionId, execution);
+      void execution.finally(() => this.inFlightExecutions.delete(metadata.executionId));
       return;
     }
     try {
@@ -6981,6 +7066,10 @@ var Agent = class {
     return this.buildMetadataFromHeaders(req.headers);
   }
   async executeServerlessHttp(req, res, explicitName) {
+    if (this.shuttingDown) {
+      res.status(503).json({ error: "agent shutting down" });
+      return;
+    }
     const invocation = this.extractInvocationDetails({
       path: req.path,
       explicitTarget: explicitName,