@triggerlink/sdk 0.3.2 → 0.4.0

package/README.md

@@ -3,7 +3,8 @@
 Lets Next.js / Node.js applications integrate with the TriggerLink platform using an
 Inngest-style DX. See the protocol spec at
 [`docs/protocol.md`](../docs/protocol.md). Currently supports the `step.run`,
-`step.sleep` / `step.sleepUntil`, and `step.sendEvent` primitives.
+`step.sleep` / `step.sleepUntil`, and `step.sendEvent` primitives, plus a native
+AI agent primitive via the `@triggerlink/sdk/agent` subpath.
 
 ## Integrating with Next.js (App Router)
 
@@ -62,6 +63,68 @@ Note: for local development, point the serve URL at `http://localhost:3000/api/t
 - The step call sequence must be deterministic: branches/loops may only depend on event data and the outputs of completed steps;
 - A single step's duration must be shorter than both the deployment platform's function limit and the platform callback timeout (5 minutes by default).
 
+## AI Agents (`@triggerlink/sdk/agent`)
+
+A native agent primitive: a single agent (system prompt + tools + model) whose
+LLM/tool loop is decomposed into ordinary durable steps. **Each LLM call and each
+tool execution is individually memoized** — on crash recovery, completed calls are
+injected from memo and only the failed call re-runs (no re-billed LLM tokens).
+Built on the [Vercel AI SDK](https://github.com/vercel/ai) for multi-provider
+support; design details in [`docs/agent-design.md`](../docs/agent-design.md).
+
+```bash
+npm install @triggerlink/sdk ai zod @ai-sdk/anthropic   # or another AI SDK provider
+```
+
+```ts
+import { createFunction } from "@triggerlink/sdk";
+import { createAgent } from "@triggerlink/sdk/agent";   // subpath import, not the main entry
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const researcher = createAgent({
+  name: "researcher",                    // stable ID, used in memo keys — do not rename casually
+  model: anthropic("claude-sonnet-4-5"), // any AI SDK LanguageModel
+  system: "You are a research assistant. Answer concisely.",
+  tools: {
+    search: {
+      description: "Search the knowledge base",
+      parameters: z.object({ query: z.string() }),
+      handler: async ({ query }) => kb.search(query),
+    },
+  },
+  maxIterations: 10,                     // safety cap; the run fails when exceeded
+});
+
+const answerQuestion = createFunction(
+  { id: "answer-question", event: "question/asked" },
+  async ({ event, step }) => {
+    const { question } = event.data as { question: string };
+    const result = await researcher.run(step, question); // each LLM/tool call is a durable step
+
+    // Function code is the router: chain agents, branch, or fan out — no extra abstraction
+    await step.sendEvent("notify", { name: "question/answered", data: { answer: result.text } });
+    return result;
+  },
+);
+```
+
+Notes:
+
+- **Durability granularity**: an agent run with *L* LLM calls and *T* tool executions costs
+  *L + T* platform callbacks (one per step). Each step appears in the dashboard run detail
+  with its output — per-call tracing and token usage for free.
+- **Multi-tool responses** are executed sequentially in array order, one step each.
+- **`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:
+  `redact: (output, ctx) => ...` with `ctx = { kind: "llm" | "tool", iteration, toolName? }`.
+- **Constraints**: same as any function — a single LLM call must finish within the platform
+  callback timeout (5 minutes by default); two different agents in one function must have
+  different `name`s; changing the tool set or loop structure between retries of the same run
+  can misalign memo keys (changing prompt text is safe).
+- The `ai` and `zod` packages are optional peer dependencies — only agent users install them.
+
 ## Sending events (any TS code, modeled after Inngest's `inngest.send`)
 
 ```ts

package/dist/agent.d.ts

@@ -0,0 +1,53 @@
+import { type LanguageModel } from "ai";
+import type { ZodType } from "zod";
+import type { StepTool } from "./step.js";
+/** Agent 工具定义。parameters 为 zod schema；handler 入参是 schema parse 后的值。 */
+export interface AgentTool<P = unknown, R = unknown> {
+    description: string;
+    parameters: ZodType<P>;
+    handler: (params: P) => Promise<R> | R;
+}
+/** redact 钩子的上下文（§5.7）。 */
+export interface RedactCtx {
+    /** 产生输出的 step 类型 */
+    kind: "llm" | "tool";
+    /** Agent 循环迭代号（0 起） */
+    iteration: number;
+    /** kind === "tool" 时的工具名 */
+    toolName?: string;
+}
+/**
+ * 输出脱敏钩子：在 step.run 内部、输出被持久化之前调用。
+ * 必须 replay-safe 且确定（同输入同输出）——memo 是恢复时重建对话历史的唯一来源，
+ * 删改的字段会原样出现在恢复后的后续 LLM 调用里。llm 输出的结构（text/toolCalls/
+ * responseMessages）不得破坏，否则抛错（见 assertLlmMemoShape）。
+ */
+export type RedactHook = (output: unknown, ctx: RedactCtx) => unknown;
+export interface AgentOpts {
+    /** 稳定标识，用作 memo 键前缀（agent/<name>/...）；同一函数内不同 Agent 必须不同名（§5.2） */
+    name: string;
+    /** AI SDK 的 LanguageModel（用户自带 provider 包，如 @ai-sdk/anthropic） */
+    model: LanguageModel;
+    system?: string;
+    tools?: Record<string, AgentTool>;
+    /** 迭代上限（一次迭代 = 一次 LLM 调用 + 其全部工具执行），默认 10；超限抛错使 run 失败 */
+    maxIterations?: number;
+    redact?: RedactHook;
+}
+export interface AgentResult {
+    /** 最终一条 assistant 文本 */
+    text: string;
+    /** 实际执行的迭代次数 */
+    iterations: number;
+    /** 各迭代 token 用量合计（memo 命中时也照常累计） */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface Agent {
+    readonly name: string;
+    run(step: StepTool, input: string): Promise<AgentResult>;
+}
+/** 定义一个 Agent：system prompt + tools + 模型，循环直到模型不再调用工具。 */
+export declare function createAgent(opts: AgentOpts): Agent;

package/dist/agent.js

@@ -0,0 +1,119 @@
+// Agent 原语：把单 Agent 的 LLM/tool 循环分解为 durable step（设计文档 docs/agent-design.md）。
+// 每次 LLM 调用与每次工具执行各自 memo 化；崩溃恢复时从 memo 重建对话历史，只重跑失败的调用。
+// 本模块只通过子路径 @triggerlink/sdk/agent 导出——ai/zod 是 optional peer 依赖，
+// 主入口 index.ts 不得 import 本模块（§8.1），否则未装 ai 的普通用户会在 import 时崩溃。
+import { generateText, tool, } from "ai";
+/** redact 钩子可能破坏 llm memo 结构；此处 fail loud，不让坏 memo 落库或参与历史重建（§5.7）。 */
+function assertLlmMemoShape(m, name) {
+    const o = m;
+    if (!o ||
+        typeof o.text !== "string" ||
+        !Array.isArray(o.toolCalls) ||
+        !Array.isArray(o.responseMessages) ||
+        !o.usage ||
+        typeof o.usage !== "object") {
+        throw new Error(`agent "${name}": llm step memo has a damaged structure (must keep text/toolCalls/responseMessages/usage) — check the redact hook`);
+    }
+}
+// 同一函数调用（每次回调都是一个新 StepTool 实例）内 agent 名 → 实例的登记簿，
+// 用于拒绝两个不同 Agent 共用 name 造成的 memo 键前缀冲突（§5.2）。
+// 同一个 Agent 实例多次 run（如循环里）是合法的：ExecCtx 序号机制保证 memo 键确定。
+const claimedNames = new WeakMap();
+/** 定义一个 Agent：system prompt + tools + 模型，循环直到模型不再调用工具。 */
+export function createAgent(opts) {
+    if (!opts.name || opts.name.includes("/")) {
+        throw new Error('createAgent: name is required and must not contain "/"');
+    }
+    if (!opts.model)
+        throw new Error("createAgent: model is required");
+    const maxIterations = opts.maxIterations ?? 10;
+    if (!Number.isInteger(maxIterations) || maxIterations < 1) {
+        throw new Error("createAgent: maxIterations must be a positive integer");
+    }
+    const toolDefs = opts.tools ?? {};
+    // 以 schema-only 方式把工具交给 AI SDK（不传 execute）：
+    // 模型的 tool call 原样返回不执行，"决策"与"执行"之间就是我们的 step 边界（§4.1）。
+    const aiTools = {};
+    for (const [toolName, def] of Object.entries(toolDefs)) {
+        aiTools[toolName] = tool({ description: def.description, inputSchema: def.parameters });
+    }
+    const agent = {
+        name: opts.name,
+        async run(step, input) {
+            let registry = claimedNames.get(step);
+            if (!registry) {
+                registry = new Map();
+                claimedNames.set(step, registry);
+            }
+            const claimed = registry.get(agent.name);
+            if (claimed && claimed !== agent) {
+                throw new Error(`agent "${agent.name}": another agent with the same name already ran in this function; names must be unique per function (memo key prefix collision)`);
+            }
+            registry.set(agent.name, agent);
+            const redact = opts.redact;
+            const llmStepId = `agent/${agent.name}/llm`;
+            const toolStepId = `agent/${agent.name}/tool`;
+            const messages = [{ role: "user", content: input }];
+            const usage = { inputTokens: 0, outputTokens: 0 };
+            for (let i = 0;; i++) {
+                if (i >= maxIterations) {
+                    throw new Error(`agent "${agent.name}": maxIterations (${maxIterations}) exceeded`);
+                }
+                const llmMemo = await step.run(llmStepId, async () => {
+                    const res = await generateText({
+                        model: opts.model,
+                        system: opts.system,
+                        messages,
+                        tools: aiTools,
+                    });
+                    const memo = {
+                        text: res.text,
+                        toolCalls: res.toolCalls.map((c) => ({
+                            toolCallId: c.toolCallId,
+                            toolName: c.toolName,
+                            input: c.input,
+                        })),
+                        responseMessages: res.responseMessages,
+                        usage: { inputTokens: res.usage.inputTokens, outputTokens: res.usage.outputTokens },
+                    };
+                    const out = redact ? redact(memo, { kind: "llm", iteration: i }) : memo;
+                    assertLlmMemoShape(out, agent.name); // 落库前拦截坏结构
+                    return out;
+                });
+                assertLlmMemoShape(llmMemo, agent.name); // memo 命中路径同样校验（防御脏数据）
+                usage.inputTokens += llmMemo.usage.inputTokens ?? 0;
+                usage.outputTokens += llmMemo.usage.outputTokens ?? 0;
+                messages.push(...llmMemo.responseMessages);
+                if (llmMemo.toolCalls.length === 0) {
+                    return { text: llmMemo.text, iterations: i + 1, usage };
+                }
+                // 并行 tool call 顺序执行（数组序），每个一个 durable step（§5.3）
+                for (const call of llmMemo.toolCalls) {
+                    const def = toolDefs[call.toolName];
+                    if (!def) {
+                        throw new Error(`agent "${agent.name}": model called unknown tool "${call.toolName}"`);
+                    }
+                    const output = await step.run(toolStepId, async () => {
+                        const out = await def.handler(def.parameters.parse(call.input));
+                        return redact
+                            ? redact(out, { kind: "tool", iteration: i, toolName: call.toolName })
+                            : out;
+                    });
+                    const toolMsg = {
+                        role: "tool",
+                        content: [
+                            {
+                                type: "tool-result",
+                                toolCallId: call.toolCallId,
+                                toolName: call.toolName,
+                                output: { type: "json", value: (output ?? null) },
+                            },
+                        ],
+                    };
+                    messages.push(toolMsg);
+                }
+            }
+        },
+    };
+    return agent;
+}

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.3.0";
+export declare const sdkVersion = "triggerlink-ts/0.4.0";
 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.3.0";
+export const sdkVersion = "triggerlink-ts/0.4.0";
 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.3.2",
+  "version": "0.4.0",
   "description": "TriggerLink TypeScript SDK: durable, crash-recoverable functions for Next.js / Node.js",
   "keywords": [
     "triggerlink",
@@ -18,6 +18,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
     }
   },
   "files": [
@@ -39,6 +43,20 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.5.0"
+    "ai": "^7.0.66",
+    "typescript": "^5.5.0",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.0",
+    "zod": "^3.25.76 || ^4.1.8"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
   }
 }