agentsdk-agent 0.1.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory.ts","../src/runtime.ts","../src/handoff.ts"],"names":["AgentSDKError"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * AgentSDK Agent Runtime — Memory strategies\n * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.\n *\n * Reduces the message history between steps according to the agent's\n * `memoryStrategy`. Each function returns the (possibly trimmed) history.\n */\n\nimport type { MemoryStrategy } from './types';\nimport type { Message } from 'agentsdk-core';\n\n/** Apply the memory strategy to a message history. */\nexport function applyMemory(\n  messages: Message[],\n  strategy: MemoryStrategy,\n  windowSize = 8\n): Message[] {\n  switch (strategy) {\n    case 'none':\n      // Keep only the system prompt + the last user message.\n      return keepHeadAndLastUser(messages);\n    case 'full':\n      return messages;\n    case 'summary':\n      // 'summary' is not yet implemented. Rather than silently degrading to\n      // 'window' (which would surprise users whose prompts relied on full\n      // history being summarised), we fall back to 'window' behaviour and\n      // emit a one-time warning so they know to switch strategies.\n      warnSummaryDeprecated();\n      return applyWindow(messages, windowSize);\n    case 'window':\n    default:\n      return applyWindow(messages, windowSize);\n  }\n}\n\nfunction applyWindow(messages: Message[], windowSize: number): Message[] {\n  // Always keep the system message(s) at the head.\n  const system: Message[] = [];\n  const rest: Message[] = [];\n  for (const m of messages) {\n    (m.role === 'system' ? system : rest).push(m);\n  }\n  const tail = rest.slice(-Math.max(1, windowSize));\n  return [...system, ...tail];\n}\n\nfunction keepHeadAndLastUser(messages: Message[]): Message[] {\n  const system = messages.filter((m) => m.role === 'system');\n  const lastUser = [...messages].reverse().find((m) => m.role === 'user');\n  return [...system, ...(lastUser ? [lastUser] : [])];\n}\n\nlet summaryWarned = false;\nfunction warnSummaryDeprecated() {\n  if (summaryWarned) return;\n  summaryWarned = true;\n  console.warn(\n    '[agentsdk:agent] memoryStrategy \"summary\" is not yet implemented; ' +\n      'falling back to \"window\" behaviour. Use \"window\" or \"full\" to silence this warning.'\n  );\n}\n","/**\n * AgentSDK Agent Runtime — Step loop\n * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.\n *\n * The core agent execution loop:\n *   1. Seed history with the agent's system prompt + the input messages.\n *   2. Call the provider's generateText (with automatic retry on transient errors).\n *   3. If the model emitted tool calls, execute them in PARALLEL and append\n *      tool results.\n *   4. Otherwise, the agent is done — return the final text.\n *   5. Apply the memory strategy before each step to bound history size.\n *   6. Stop when maxSteps is hit or the model stops calling tools.\n */\n\nimport { addCost, addUsage } from 'agentsdk-core';\nimport { generateText } from 'agentsdk-core';\nimport { AgentSDKError, normalizeError } from 'agentsdk-core';\nimport type {\n  Cost,\n  Message,\n  ToolCall,\n  ToolResult,\n  Usage,\n} from 'agentsdk-core';\nimport type {\n  AgentConfig,\n  AgentRunOptions,\n  AgentRunResult,\n  StepEvent,\n  StepHook,\n} from './types';\nimport { applyMemory } from './memory';\n\nconst DEFAULT_MAX_STEPS = 10;\nconst DEFAULT_MAX_RETRIES = 2;\nconst RETRYABLE_TYPES = new Set(['rate_limit', 'server', 'timeout']);\nconst RETRY_BASE_DELAY_MS = 800;\n\nexport async function runAgent(\n  config: AgentConfig,\n  options: AgentRunOptions\n): Promise<AgentRunResult> {\n  const maxSteps = options.maxSteps ?? config.maxSteps ?? DEFAULT_MAX_STEPS;\n  const runId = options.runId ?? makeRunId();\n  const onStep = options.onStepFinish;\n\n  // Seed history.\n  let history: Message[] = [\n    { role: 'system', content: config.systemPrompt },\n    ...options.messages,\n  ];\n\n  const steps: StepEvent[] = [];\n  let totalUsage: Usage = {\n    promptTokens: 0,\n    completionTokens: 0,\n    totalTokens: 0,\n  };\n  let totalCost: Cost = { input: 0, output: 0, total: 0, currency: 'USD' };\n  let finalText = '';\n  let truncated = false;\n\n  for (let step = 1; step <= maxSteps; step++) {\n    // Apply memory strategy before the call.\n    const memStrategy = config.memoryStrategy ?? 'full';\n    const windowSize = config.memoryWindow ?? 8;\n    const visible = applyMemory(history, memStrategy, windowSize);\n\n    let event: StepEvent;\n    try {\n      const result = await generateTextWithRetry(\n        {\n          model: config.model,\n          messages: visible,\n          tools: config.tools,\n          temperature: config.temperature,\n          maxTokens: config.maxTokens,\n          thinking: config.thinking,\n          providerOptions: config.providerOptions,\n        },\n        { provider: config.provider }\n      );\n\n      totalUsage = addUsage(totalUsage, result.usage);\n      totalCost = addCost(totalCost, result.cost);\n\n      // Append the assistant turn to history.\n      const assistantMsg: Message = {\n        role: 'assistant',\n        content: result.text,\n        toolCalls: result.toolCalls.length ? result.toolCalls : undefined,\n      };\n      history.push(assistantMsg);\n\n      if (result.toolCalls.length === 0) {\n        // Pure text answer — done.\n        finalText = result.text;\n        event = {\n          step,\n          kind: 'text',\n          text: result.text,\n          usage: result.usage,\n          cost: result.cost,\n          timestamp: new Date().toISOString(),\n        };\n        steps.push(event);\n        await onStep?.(event);\n        break;\n      }\n\n      // Execute tool calls IN PARALLEL. Tools are independent of each other\n      // (the model emitted them all in one turn) so running them concurrently\n      // is safe and dramatically speeds up agents that call multiple tools\n      // (e.g. several web searches in one step).\n      const toolResults = await Promise.all(\n        result.toolCalls.map((tc) => executeToolCall(tc, config, step, runId))\n      );\n\n      // Append tool results to history in the SAME ORDER as the model emitted\n      // them — order matters for the next LLM turn's context.\n      for (const toolResult of toolResults) {\n        history.push({\n          role: 'tool',\n          content: stringifyToolResult(toolResult.result),\n          name: toolResult.name,\n          toolCallId: toolResult.toolCallId,\n        });\n      }\n\n      event = {\n        step,\n        kind: 'tool_call',\n        text: result.text,\n        toolCalls: result.toolCalls,\n        toolResults,\n        usage: result.usage,\n        cost: result.cost,\n        timestamp: new Date().toISOString(),\n      };\n      steps.push(event);\n      await onStep?.(event);\n\n      // If this was the last allowed step and we still called tools, mark truncated.\n      if (step === maxSteps) truncated = true;\n    } catch (err) {\n      const norm = normalizeError(err, config.provider);\n      event = {\n        step,\n        kind: 'error',\n        error: norm.message,\n        timestamp: new Date().toISOString(),\n      };\n      steps.push(event);\n      await onStep?.(event);\n      // Re-throw after the hook has had a chance to log.\n      throw norm;\n    }\n  }\n\n  // If the loop ended without a final text (e.g. hit maxSteps mid-tool-call),\n  // synthesise a final answer by running one more non-tool generation.\n  if (!finalText && steps.length > 0) {\n    const last = await generateTextWithRetry(\n      {\n        model: config.model,\n        messages: [\n          ...applyMemory(history, config.memoryStrategy ?? 'full', config.memoryWindow ?? 8),\n          {\n            role: 'system',\n            content:\n              'Summarise the result of the previous tool calls in a concise final answer for the user.',\n          },\n        ],\n        temperature: config.temperature,\n        maxTokens: config.maxTokens,\n        providerOptions: config.providerOptions,\n      },\n      { provider: config.provider }\n    );\n    finalText = last.text;\n    totalUsage = addUsage(totalUsage, last.usage);\n    totalCost = addCost(totalCost, last.cost);\n  }\n\n  return {\n    agentId: config.id,\n    text: finalText,\n    messages: history,\n    steps,\n    usage: totalUsage,\n    cost: totalCost,\n    stepsExecuted: steps.length,\n    truncated,\n  };\n}\n\n/**\n * Wrap generateText with automatic retry on rate_limit / server / timeout\n * errors. Uses exponential backoff with jitter. Non-retryable errors are\n * re-thrown immediately.\n */\nasync function generateTextWithRetry(\n  params: Parameters<typeof generateText>[0],\n  opts: Parameters<typeof generateText>[1]\n): ReturnType<typeof generateText> {\n  const maxRetries = DEFAULT_MAX_RETRIES;\n  let lastError: unknown;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      return await generateText(params, opts);\n    } catch (err) {\n      lastError = err;\n      const providerId = opts?.provider;\n      const norm = err instanceof AgentSDKError\n        ? err\n        : normalizeError(err, providerId);\n\n      // Don't retry on the last attempt or non-retryable errors.\n      if (attempt === maxRetries || !RETRYABLE_TYPES.has(norm.type)) {\n        throw norm;\n      }\n\n      // Exponential backoff with jitter: 800ms, 1600ms, ... +/- 20% jitter.\n      const baseDelay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);\n      const jitter = baseDelay * (0.8 + Math.random() * 0.4);\n      await new Promise((resolve) => setTimeout(resolve, jitter));\n    }\n  }\n\n  // Should be unreachable, but keeps TS happy.\n  throw lastError;\n}\n\nasync function executeToolCall(\n  call: ToolCall,\n  config: AgentConfig,\n  step: number,\n  runId: string\n): Promise<ToolResult> {\n  const tool = config.tools?.find((t) => t.name === call.name);\n  if (!tool || typeof tool.execute !== 'function') {\n    return {\n      toolCallId: call.id,\n      name: call.name,\n      result: { error: `Tool \"${call.name}\" is not defined or has no executor.` },\n      isError: true,\n    };\n  }\n  try {\n    const out = await tool.execute(call.arguments, { runId, step });\n    return { toolCallId: call.id, name: call.name, result: out };\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    return {\n      toolCallId: call.id,\n      name: call.name,\n      result: { error: msg },\n      isError: true,\n    };\n  }\n}\n\nfunction stringifyToolResult(result: unknown): string {\n  if (typeof result === 'string') return result;\n  try {\n    return JSON.stringify(result);\n  } catch {\n    return String(result);\n  }\n}\n\nfunction makeRunId(): string {\n  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;\n}\n\nexport type { StepHook };\n","/**\n * AgentSDK Agent Runtime — Agent-as-tool handoff\n * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.\n *\n * The core differentiator vs Vercel AI SDK: an agent can be exposed as a\n * callable \"tool\" to another agent. When the parent agent invokes the tool,\n * the child agent runs to completion and its final text is returned as the\n * tool result — the parent then continues with that context.\n *\n * This enables true multi-agent orchestration: a \"router\" agent can hand off\n * to specialised agents (researcher, writer, critic) as if they were tools.\n */\n\nimport { AgentSDKError } from 'agentsdk-core';\nimport type { ResolvedTool } from 'agentsdk-core';\nimport type { AgentConfig, AgentRunOptions } from './types';\nimport { runAgent } from './runtime';\n\nexport interface HandoffOptions {\n  /** Description the parent agent sees for this \"tool\". */\n  description?: string;\n  /** Input schema describing what the parent should pass. Defaults to a single `input` string. */\n  parameters?: Record<string, unknown>;\n  /** The argument key that becomes the user message to the child agent. Default: \"input\". */\n  inputKey?: string;\n  /** Extra seed messages to prepend for the child agent (beyond the input). */\n  seedMessages?: import('agentsdk-core').Message[];\n  /** Hook fired for every child step (for live UI updates). */\n  onChildStep?: AgentRunOptions['onStepFinish'];\n  /** Maximum handoff depth before recursion is rejected. Default: 5. */\n  maxDepth?: number;\n}\n\n/**\n * Wrap an agent as a tool that another agent can call. The resulting tool can\n * be appended to a parent agent's `tools` array.\n *\n * Includes a recursion guard: if the same child agent appears more than\n * `maxDepth` times in the call chain (e.g. A→B→A→B→...), the tool throws\n * instead of looping forever.\n */\nexport function asTool(\n  child: AgentConfig,\n  opts: HandoffOptions = {}\n): ResolvedTool {\n  const inputKey = opts.inputKey ?? 'input';\n  const maxDepth = opts.maxDepth ?? 5;\n\n  return {\n    name: child.id,\n    description:\n      opts.description ??\n      `Hand off to the \"${child.name}\" agent. Pass a natural-language ${inputKey} describing what the child agent should do.`,\n    parameters:\n      opts.parameters ?? {\n        type: 'object',\n        properties: {\n          [inputKey]: {\n            type: 'string',\n            description: 'The task or question to delegate to this agent.',\n          },\n        },\n        required: [inputKey],\n        additionalProperties: false,\n      },\n    async execute(args, ctx) {\n      // Recursion guard: the runId encodes the agent call chain as\n      // \"run_xxx:childA:childB:...\". Count how many times `child.id` already\n      // appears — if it exceeds maxDepth, we're in a cycle.\n      const chain = ctx.runId.split(':');\n      const occurrences = chain.filter((x) => x === child.id).length;\n      if (occurrences > maxDepth) {\n        throw new AgentSDKError(\n          `Handoff recursion limit exceeded: agent \"${child.id}\" appears ${occurrences} times ` +\n            `in the call chain (max ${maxDepth}). This usually means two agents are handing off ` +\n            `to each other in a loop. Check your agent tool lists for cycles.`,\n          { type: 'invalid_request' }\n        );\n      }\n\n      const input = String(args?.[inputKey] ?? '');\n      const messages = [\n        ...(opts.seedMessages ?? []),\n        { role: 'user' as const, content: input },\n      ];\n      const result = await runAgent(child, {\n        messages,\n        runId: `${ctx.runId}:${child.id}`,\n        onStepFinish: opts.onChildStep,\n      });\n      // Return a structured payload so the parent agent has rich context.\n      return {\n        text: result.text,\n        agentId: result.agentId,\n        stepsExecuted: result.stepsExecuted,\n        usage: result.usage,\n        cost: result.cost,\n        truncated: result.truncated,\n      };\n    },\n  };\n}\n\n/**\n * Convenience: build a parent agent's tool list by mixing ordinary tools with\n * a set of child agents (each converted to a tool via `asTool`).\n */\nexport function withHandoffs(\n  baseTools: ResolvedTool[],\n  children: Array<{ agent: AgentConfig; opts?: HandoffOptions }>\n): ResolvedTool[] {\n  return [\n    ...baseTools,\n    ...children.map(({ agent, opts }) => asTool(agent, opts)),\n  ];\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+import { ResolvedTool, Message, ToolCall, ToolResult, Usage, Cost } from 'agentsdk-core';
+
+/**
+ * AgentSDK Agent Runtime — Types
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ *
+ * An "agent" is a model + system prompt + tools + a step loop. Each step the
+ * model may emit text or tool calls; tool calls are executed and their results
+ * fed back, until the model stops calling tools or maxSteps is reached.
+ */
+
+type MemoryStrategy = 'none' | 'full' | 'summary' | 'window';
+interface AgentConfig {
+    /** Stable id for this agent within a graph. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Provider id, defaults to "glm". */
+    provider?: string;
+    /** Model id, e.g. "glm-4.6". */
+    model: string;
+    /** System prompt. */
+    systemPrompt: string;
+    /** Tools available to the agent. */
+    tools?: ResolvedTool[];
+    /** Max number of LLM round-trips before the loop is forced to stop. */
+    maxSteps?: number;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Max tokens per step. */
+    maxTokens?: number;
+    /** Enable thinking/reasoning mode if the provider supports it. */
+    thinking?: boolean;
+    /** How conversation history is carried between steps. */
+    memoryStrategy?: MemoryStrategy;
+    /** For 'window' strategy: how many most-recent messages to keep. */
+    memoryWindow?: number;
+    /** Extra provider-specific options. */
+    providerOptions?: Record<string, unknown>;
+}
+type StepKind = 'text' | 'tool_call' | 'tool_result' | 'error';
+interface StepEvent {
+    /** 1-indexed step number. */
+    step: number;
+    kind: StepKind;
+    /** The assistant message produced at this step (if any). */
+    text?: string;
+    /** Tool calls requested by the model at this step (if any). */
+    toolCalls?: ToolCall[];
+    /** Tool results produced this step (if any). */
+    toolResults?: ToolResult[];
+    /** Error message, if kind === 'error'. */
+    error?: string;
+    /** Token usage for this step's LLM call. */
+    usage?: Usage;
+    /** Cost for this step's LLM call. */
+    cost?: Cost;
+    /** ISO timestamp. */
+    timestamp: string;
+}
+interface AgentRunResult {
+    agentId: string;
+    /** Final text answer from the agent. */
+    text: string;
+    /** Full message history (post-run). */
+    messages: Message[];
+    /** Every step event, in order. */
+    steps: StepEvent[];
+    /** Aggregated token usage across all steps. */
+    usage: Usage;
+    /** Aggregated cost across all steps. */
+    cost: Cost;
+    /** Number of steps actually executed. */
+    stepsExecuted: number;
+    /** True if the loop hit maxSteps without a clean stop. */
+    truncated: boolean;
+}
+type StepHook = (event: StepEvent) => void | Promise<void>;
+interface AgentRunOptions {
+    /** The user/input message(s) to seed the run. */
+    messages: Message[];
+    /** Called after each step completes. */
+    onStepFinish?: StepHook;
+    /** Optional run id (auto-generated if omitted). */
+    runId?: string;
+    /** Override maxSteps for this run only. */
+    maxSteps?: number;
+}
+
+export type { AgentConfig, AgentRunOptions, AgentRunResult, MemoryStrategy, StepEvent, StepHook, StepKind };

package/dist/types.js

@@ -0,0 +1,3 @@
+import './chunk-55J6XMHW.js';
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"types.js"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "agentsdk-agent",
+  "version": "0.1.0",
+  "description": "Multi-step agent runtime for AgentSDK — step loop, hooks, memory strategies, agent-as-tool handoff.",
+  "license": "MIT",
+  "author": "shetanmehra (https://github.com/shetanmehra)",
+  "homepage": "https://github.com/shetanmehra/agentsdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shetanmehra/agentsdk.git",
+    "directory": "packages/agent"
+  },
+  "bugs": {
+    "url": "https://github.com/shetanmehra/agentsdk/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "sdk",
+    "orchestration"
+  ],
+  "dependencies": {
+    "agentsdk-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/handoff.ts

@@ -0,0 +1,116 @@
+/**
+ * AgentSDK Agent Runtime — Agent-as-tool handoff
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ *
+ * The core differentiator vs Vercel AI SDK: an agent can be exposed as a
+ * callable "tool" to another agent. When the parent agent invokes the tool,
+ * the child agent runs to completion and its final text is returned as the
+ * tool result — the parent then continues with that context.
+ *
+ * This enables true multi-agent orchestration: a "router" agent can hand off
+ * to specialised agents (researcher, writer, critic) as if they were tools.
+ */
+
+import { AgentSDKError } from 'agentsdk-core';
+import type { ResolvedTool } from 'agentsdk-core';
+import type { AgentConfig, AgentRunOptions } from './types';
+import { runAgent } from './runtime';
+
+export interface HandoffOptions {
+  /** Description the parent agent sees for this "tool". */
+  description?: string;
+  /** Input schema describing what the parent should pass. Defaults to a single `input` string. */
+  parameters?: Record<string, unknown>;
+  /** The argument key that becomes the user message to the child agent. Default: "input". */
+  inputKey?: string;
+  /** Extra seed messages to prepend for the child agent (beyond the input). */
+  seedMessages?: import('agentsdk-core').Message[];
+  /** Hook fired for every child step (for live UI updates). */
+  onChildStep?: AgentRunOptions['onStepFinish'];
+  /** Maximum handoff depth before recursion is rejected. Default: 5. */
+  maxDepth?: number;
+}
+
+/**
+ * Wrap an agent as a tool that another agent can call. The resulting tool can
+ * be appended to a parent agent's `tools` array.
+ *
+ * Includes a recursion guard: if the same child agent appears more than
+ * `maxDepth` times in the call chain (e.g. A→B→A→B→...), the tool throws
+ * instead of looping forever.
+ */
+export function asTool(
+  child: AgentConfig,
+  opts: HandoffOptions = {}
+): ResolvedTool {
+  const inputKey = opts.inputKey ?? 'input';
+  const maxDepth = opts.maxDepth ?? 5;
+
+  return {
+    name: child.id,
+    description:
+      opts.description ??
+      `Hand off to the "${child.name}" agent. Pass a natural-language ${inputKey} describing what the child agent should do.`,
+    parameters:
+      opts.parameters ?? {
+        type: 'object',
+        properties: {
+          [inputKey]: {
+            type: 'string',
+            description: 'The task or question to delegate to this agent.',
+          },
+        },
+        required: [inputKey],
+        additionalProperties: false,
+      },
+    async execute(args, ctx) {
+      // Recursion guard: the runId encodes the agent call chain as
+      // "run_xxx:childA:childB:...". Count how many times `child.id` already
+      // appears — if it exceeds maxDepth, we're in a cycle.
+      const chain = ctx.runId.split(':');
+      const occurrences = chain.filter((x) => x === child.id).length;
+      if (occurrences > maxDepth) {
+        throw new AgentSDKError(
+          `Handoff recursion limit exceeded: agent "${child.id}" appears ${occurrences} times ` +
+            `in the call chain (max ${maxDepth}). This usually means two agents are handing off ` +
+            `to each other in a loop. Check your agent tool lists for cycles.`,
+          { type: 'invalid_request' }
+        );
+      }
+
+      const input = String(args?.[inputKey] ?? '');
+      const messages = [
+        ...(opts.seedMessages ?? []),
+        { role: 'user' as const, content: input },
+      ];
+      const result = await runAgent(child, {
+        messages,
+        runId: `${ctx.runId}:${child.id}`,
+        onStepFinish: opts.onChildStep,
+      });
+      // Return a structured payload so the parent agent has rich context.
+      return {
+        text: result.text,
+        agentId: result.agentId,
+        stepsExecuted: result.stepsExecuted,
+        usage: result.usage,
+        cost: result.cost,
+        truncated: result.truncated,
+      };
+    },
+  };
+}
+
+/**
+ * Convenience: build a parent agent's tool list by mixing ordinary tools with
+ * a set of child agents (each converted to a tool via `asTool`).
+ */
+export function withHandoffs(
+  baseTools: ResolvedTool[],
+  children: Array<{ agent: AgentConfig; opts?: HandoffOptions }>
+): ResolvedTool[] {
+  return [
+    ...baseTools,
+    ...children.map(({ agent, opts }) => asTool(agent, opts)),
+  ];
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * AgentSDK Agent Runtime — barrel
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ */
+
+export * from './types';
+export * from './runtime';
+export * from './memory';
+export * from './handoff';

package/src/memory.ts

@@ -0,0 +1,62 @@
+/**
+ * AgentSDK Agent Runtime — Memory strategies
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ *
+ * Reduces the message history between steps according to the agent's
+ * `memoryStrategy`. Each function returns the (possibly trimmed) history.
+ */
+
+import type { MemoryStrategy } from './types';
+import type { Message } from 'agentsdk-core';
+
+/** Apply the memory strategy to a message history. */
+export function applyMemory(
+  messages: Message[],
+  strategy: MemoryStrategy,
+  windowSize = 8
+): Message[] {
+  switch (strategy) {
+    case 'none':
+      // Keep only the system prompt + the last user message.
+      return keepHeadAndLastUser(messages);
+    case 'full':
+      return messages;
+    case 'summary':
+      // 'summary' is not yet implemented. Rather than silently degrading to
+      // 'window' (which would surprise users whose prompts relied on full
+      // history being summarised), we fall back to 'window' behaviour and
+      // emit a one-time warning so they know to switch strategies.
+      warnSummaryDeprecated();
+      return applyWindow(messages, windowSize);
+    case 'window':
+    default:
+      return applyWindow(messages, windowSize);
+  }
+}
+
+function applyWindow(messages: Message[], windowSize: number): Message[] {
+  // Always keep the system message(s) at the head.
+  const system: Message[] = [];
+  const rest: Message[] = [];
+  for (const m of messages) {
+    (m.role === 'system' ? system : rest).push(m);
+  }
+  const tail = rest.slice(-Math.max(1, windowSize));
+  return [...system, ...tail];
+}
+
+function keepHeadAndLastUser(messages: Message[]): Message[] {
+  const system = messages.filter((m) => m.role === 'system');
+  const lastUser = [...messages].reverse().find((m) => m.role === 'user');
+  return [...system, ...(lastUser ? [lastUser] : [])];
+}
+
+let summaryWarned = false;
+function warnSummaryDeprecated() {
+  if (summaryWarned) return;
+  summaryWarned = true;
+  console.warn(
+    '[agentsdk:agent] memoryStrategy "summary" is not yet implemented; ' +
+      'falling back to "window" behaviour. Use "window" or "full" to silence this warning.'
+  );
+}

package/src/runtime.ts

@@ -0,0 +1,277 @@
+/**
+ * AgentSDK Agent Runtime — Step loop
+ * MIT License — see LICENSE. Copyright (c) 2026 Shetan Mehra.
+ *
+ * The core agent execution loop:
+ *   1. Seed history with the agent's system prompt + the input messages.
+ *   2. Call the provider's generateText (with automatic retry on transient errors).
+ *   3. If the model emitted tool calls, execute them in PARALLEL and append
+ *      tool results.
+ *   4. Otherwise, the agent is done — return the final text.
+ *   5. Apply the memory strategy before each step to bound history size.
+ *   6. Stop when maxSteps is hit or the model stops calling tools.
+ */
+
+import { addCost, addUsage } from 'agentsdk-core';
+import { generateText } from 'agentsdk-core';
+import { AgentSDKError, normalizeError } from 'agentsdk-core';
+import type {
+  Cost,
+  Message,
+  ToolCall,
+  ToolResult,
+  Usage,
+} from 'agentsdk-core';
+import type {
+  AgentConfig,
+  AgentRunOptions,
+  AgentRunResult,
+  StepEvent,
+  StepHook,
+} from './types';
+import { applyMemory } from './memory';
+
+const DEFAULT_MAX_STEPS = 10;
+const DEFAULT_MAX_RETRIES = 2;
+const RETRYABLE_TYPES = new Set(['rate_limit', 'server', 'timeout']);
+const RETRY_BASE_DELAY_MS = 800;
+
+export async function runAgent(
+  config: AgentConfig,
+  options: AgentRunOptions
+): Promise<AgentRunResult> {
+  const maxSteps = options.maxSteps ?? config.maxSteps ?? DEFAULT_MAX_STEPS;
+  const runId = options.runId ?? makeRunId();
+  const onStep = options.onStepFinish;
+
+  // Seed history.
+  let history: Message[] = [
+    { role: 'system', content: config.systemPrompt },
+    ...options.messages,
+  ];
+
+  const steps: StepEvent[] = [];
+  let totalUsage: Usage = {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0,
+  };
+  let totalCost: Cost = { input: 0, output: 0, total: 0, currency: 'USD' };
+  let finalText = '';
+  let truncated = false;
+
+  for (let step = 1; step <= maxSteps; step++) {
+    // Apply memory strategy before the call.
+    const memStrategy = config.memoryStrategy ?? 'full';
+    const windowSize = config.memoryWindow ?? 8;
+    const visible = applyMemory(history, memStrategy, windowSize);
+
+    let event: StepEvent;
+    try {
+      const result = await generateTextWithRetry(
+        {
+          model: config.model,
+          messages: visible,
+          tools: config.tools,
+          temperature: config.temperature,
+          maxTokens: config.maxTokens,
+          thinking: config.thinking,
+          providerOptions: config.providerOptions,
+        },
+        { provider: config.provider }
+      );
+
+      totalUsage = addUsage(totalUsage, result.usage);
+      totalCost = addCost(totalCost, result.cost);
+
+      // Append the assistant turn to history.
+      const assistantMsg: Message = {
+        role: 'assistant',
+        content: result.text,
+        toolCalls: result.toolCalls.length ? result.toolCalls : undefined,
+      };
+      history.push(assistantMsg);
+
+      if (result.toolCalls.length === 0) {
+        // Pure text answer — done.
+        finalText = result.text;
+        event = {
+          step,
+          kind: 'text',
+          text: result.text,
+          usage: result.usage,
+          cost: result.cost,
+          timestamp: new Date().toISOString(),
+        };
+        steps.push(event);
+        await onStep?.(event);
+        break;
+      }
+
+      // Execute tool calls IN PARALLEL. Tools are independent of each other
+      // (the model emitted them all in one turn) so running them concurrently
+      // is safe and dramatically speeds up agents that call multiple tools
+      // (e.g. several web searches in one step).
+      const toolResults = await Promise.all(
+        result.toolCalls.map((tc) => executeToolCall(tc, config, step, runId))
+      );
+
+      // Append tool results to history in the SAME ORDER as the model emitted
+      // them — order matters for the next LLM turn's context.
+      for (const toolResult of toolResults) {
+        history.push({
+          role: 'tool',
+          content: stringifyToolResult(toolResult.result),
+          name: toolResult.name,
+          toolCallId: toolResult.toolCallId,
+        });
+      }
+
+      event = {
+        step,
+        kind: 'tool_call',
+        text: result.text,
+        toolCalls: result.toolCalls,
+        toolResults,
+        usage: result.usage,
+        cost: result.cost,
+        timestamp: new Date().toISOString(),
+      };
+      steps.push(event);
+      await onStep?.(event);
+
+      // If this was the last allowed step and we still called tools, mark truncated.
+      if (step === maxSteps) truncated = true;
+    } catch (err) {
+      const norm = normalizeError(err, config.provider);
+      event = {
+        step,
+        kind: 'error',
+        error: norm.message,
+        timestamp: new Date().toISOString(),
+      };
+      steps.push(event);
+      await onStep?.(event);
+      // Re-throw after the hook has had a chance to log.
+      throw norm;
+    }
+  }
+
+  // If the loop ended without a final text (e.g. hit maxSteps mid-tool-call),
+  // synthesise a final answer by running one more non-tool generation.
+  if (!finalText && steps.length > 0) {
+    const last = await generateTextWithRetry(
+      {
+        model: config.model,
+        messages: [
+          ...applyMemory(history, config.memoryStrategy ?? 'full', config.memoryWindow ?? 8),
+          {
+            role: 'system',
+            content:
+              'Summarise the result of the previous tool calls in a concise final answer for the user.',
+          },
+        ],
+        temperature: config.temperature,
+        maxTokens: config.maxTokens,
+        providerOptions: config.providerOptions,
+      },
+      { provider: config.provider }
+    );
+    finalText = last.text;
+    totalUsage = addUsage(totalUsage, last.usage);
+    totalCost = addCost(totalCost, last.cost);
+  }
+
+  return {
+    agentId: config.id,
+    text: finalText,
+    messages: history,
+    steps,
+    usage: totalUsage,
+    cost: totalCost,
+    stepsExecuted: steps.length,
+    truncated,
+  };
+}
+
+/**
+ * Wrap generateText with automatic retry on rate_limit / server / timeout
+ * errors. Uses exponential backoff with jitter. Non-retryable errors are
+ * re-thrown immediately.
+ */
+async function generateTextWithRetry(
+  params: Parameters<typeof generateText>[0],
+  opts: Parameters<typeof generateText>[1]
+): ReturnType<typeof generateText> {
+  const maxRetries = DEFAULT_MAX_RETRIES;
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await generateText(params, opts);
+    } catch (err) {
+      lastError = err;
+      const providerId = opts?.provider;
+      const norm = err instanceof AgentSDKError
+        ? err
+        : normalizeError(err, providerId);
+
+      // Don't retry on the last attempt or non-retryable errors.
+      if (attempt === maxRetries || !RETRYABLE_TYPES.has(norm.type)) {
+        throw norm;
+      }
+
+      // Exponential backoff with jitter: 800ms, 1600ms, ... +/- 20% jitter.
+      const baseDelay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+      const jitter = baseDelay * (0.8 + Math.random() * 0.4);
+      await new Promise((resolve) => setTimeout(resolve, jitter));
+    }
+  }
+
+  // Should be unreachable, but keeps TS happy.
+  throw lastError;
+}
+
+async function executeToolCall(
+  call: ToolCall,
+  config: AgentConfig,
+  step: number,
+  runId: string
+): Promise<ToolResult> {
+  const tool = config.tools?.find((t) => t.name === call.name);
+  if (!tool || typeof tool.execute !== 'function') {
+    return {
+      toolCallId: call.id,
+      name: call.name,
+      result: { error: `Tool "${call.name}" is not defined or has no executor.` },
+      isError: true,
+    };
+  }
+  try {
+    const out = await tool.execute(call.arguments, { runId, step });
+    return { toolCallId: call.id, name: call.name, result: out };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      toolCallId: call.id,
+      name: call.name,
+      result: { error: msg },
+      isError: true,
+    };
+  }
+}
+
+function stringifyToolResult(result: unknown): string {
+  if (typeof result === 'string') return result;
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+}
+
+function makeRunId(): string {
+  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+export type { StepHook };