@triggerlink/sdk 0.4.5 → 0.4.6

package/README.md

@@ -130,6 +130,29 @@ Notes:
   turns, tool results), each element carrying `role`/`content` — same field name and shape as
   AgentKit's `result.output`, so helpers like `findLastIndex((m) => m.role === "assistant")`
   port directly. `lastAssistantTextMessageContent(result)` is the built-in shortcut.
+- **`lifecycle.onResponse`**: fired once per *actual* LLM call (inside the durable step, after
+  redaction) with `{ result, iteration }`; `result` is an `AgentIterationResult`
+  (`{ text, output, toolCalls, usage }` for that iteration) and works directly with
+  `lastAssistantTextMessageContent(result)`. Memo-hit replays do not re-fire it, so hook side
+  effects run exactly once per LLM call; a throwing hook fails the step (platform retries).
+  There is no `network.state` — because function code is the router, extract results after
+  `agent.run` returns (via `result.output` / `result.toolCalls`), or write to your own storage
+  inside the hook (closure variables don't survive platform re-invocations):
+
+  ```ts
+  const codeAgent = createAgent({
+    name: "code-agent",
+    model: openai("gpt-4.1"),
+    lifecycle: {
+      onResponse: async ({ result }) => {
+        const lastAssistantText = lastAssistantTextMessageContent(result);
+        if (lastAssistantText?.includes("<task_summary>")) {
+          await db.runs.update(runId, { summary: lastAssistantText }); // your own storage
+        }
+      },
+    },
+  });
+  ```
 - **`redact` hook** (optional): transforms each step's output inside `step.run` before
   persistence, e.g. to strip secrets or PII from memos. It must be deterministic and
   replay-safe — the memo is what the model sees of its own prior turns after a crash-resume:

package/dist/agent.d.ts

@@ -36,6 +36,36 @@ export interface RedactCtx {
  * responseMessages）不得破坏，否则抛错（见 assertLlmMemoShape）。
  */
 export type RedactHook = (output: unknown, ctx: RedactCtx) => unknown;
+/** 单轮 LLM 调用的结果（lifecycle.onResponse 的入参）。 */
+export interface AgentIterationResult {
+    /** 本轮 assistant 文本 */
+    text: string;
+    /** 本轮 assistant 消息（与 lastAssistantTextMessageContent 兼容） */
+    output: TextMessage[];
+    /** 本轮模型发起的工具调用（尚未执行） */
+    toolCalls: Array<{
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }>;
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+export interface AgentLifecycle {
+    /**
+     * 每次 LLM 调用真实执行后触发一次（memo 命中/恢复重放不触发），
+     * 看到的是 redact 之后的最终内容（与落库 memo、模型历史一致）。
+     * 抛错视同 step 失败：StepError → 平台退避重试（LLM 会被重新调用）。
+     * 注意：函数会被平台反复重入，闭包变量不可靠；要保留 hook 产出请写自己的存储，
+     * 或在 agent.run 返回后从 AgentResult 收尾提取。
+     */
+    onResponse?: (args: {
+        result: AgentIterationResult;
+        iteration: number;
+    }) => void | Promise<void>;
+}
 export interface AgentOpts {
     /** 稳定标识，用作 memo 键前缀（agent/<name>/...）；同一函数内不同 Agent 必须不同名（§5.2） */
     name: string;
@@ -46,6 +76,7 @@ export interface AgentOpts {
     /** 迭代上限（一次迭代 = 一次 LLM 调用 + 其全部工具执行），默认 10；超限抛错使 run 失败 */
     maxIterations?: number;
     redact?: RedactHook;
+    lifecycle?: AgentLifecycle;
 }
 export interface AgentResult {
     /** 最终一条 assistant 文本 */

package/dist/agent.js

@@ -115,6 +115,17 @@ export function createAgent(opts) {
                     };
                     const out = redact ? redact(memo, { kind: "llm", iteration: i }) : memo;
                     assertLlmMemoShape(out, agent.name); // 落库前拦截坏结构
+                    // onResponse 在 step 回调内触发：只在 LLM 真实执行时跑一次，
+                    // memo 命中/恢复重放不重复触发；抛错视同 step 失败走重试。
+                    await opts.lifecycle?.onResponse?.({
+                        result: {
+                            text: out.text,
+                            output: out.responseMessages,
+                            toolCalls: out.toolCalls,
+                            usage: out.usage,
+                        },
+                        iteration: i,
+                    });
                     return out;
                 });
                 assertLlmMemoShape(llmMemo, agent.name); // memo 命中路径同样校验（防御脏数据）

package/dist/serve.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from "./client.js";
 import type { TriggerFunction } from "./function.js";
-export declare const sdkVersion = "triggerlink-ts/0.4.5";
+export declare const sdkVersion = "triggerlink-ts/0.4.6";
 export declare const SIGNATURE_HEADER = "x-triggerlink-signature";
 export interface ServeOptions {
     client: Client;

package/dist/serve.js

@@ -1,7 +1,7 @@
 import { ExecCtx, StepInterrupt } from "./execx.js";
 import { createStepTool, errMessage } from "./step.js";
 import { verifySignature } from "./sign.js";
-export const sdkVersion = "triggerlink-ts/0.4.5";
+export const sdkVersion = "triggerlink-ts/0.4.6";
 export const SIGNATURE_HEADER = "x-triggerlink-signature";
 const MAX_BODY = 10 << 20; // 10 MB，与平台一致
 function json(data, status = 200) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triggerlink/sdk",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "TriggerLink TypeScript SDK: durable, crash-recoverable functions for Next.js / Node.js",
   "keywords": [
     "triggerlink",