@trayai/helix-sdk 1.8.0 → 1.13.0

package/CHANGELOG.md

@@ -8,6 +8,29 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The SDK and [`@trayai/helix-cli`](https://www.npmjs.com/package/@trayai/helix-cli) are
 released together and share a version — install matching versions.
 
+## 1.9.0
+
+### Added
+
+- **Agents and tools are now a documented, public part of the SDK.** Define a tool with
+  `defineTool` (`functions/_tools/`) and an agent with `defineAgent` (`functions/_agents/`),
+  then run it from any handler with `ctx.agent(name).generate()` / `.stream()`. An agent's
+  `model`/`auth` use the same `aiProviders` aliases as `ctx.ai` (every provider, including
+  Amazon Bedrock), can declare `fallbacks`, and can delegate to other agents. Conversations
+  persist as **sessions** (the full record, not just the model window) — read them with
+  `session(id).messages()` / `.page()` and clear them with `session(id).clear()`; cap the model
+  window with `memory.maxSessionMessages`, scope sessions per user with `memory.scope: 'user'`.
+  Choose a session store with the new `agentSessions` field in `helix.config.ts`
+  (`{ store: 'managed' }` by default, or a bring-your-own `{ store: 'dynamodb', … }`). See the
+  README's "Agents and tools" section; try them locally with `helix agent list` / `helix agent
+  chat`. (These APIs shipped earlier marked beta; the beta label has been removed.)
+
+### Changed
+
+- Removed the `@beta` labels from `defineAgent`, `defineTool`, `ctx.agent`, `HelixAgent`, and
+  `AgentClient` — the agent harness is now covered by the SDK's semantic-versioning contract
+  like the rest of the public API.
+
 ## 1.8.0
 
 ### Added

package/README.md

@@ -15,6 +15,7 @@ The runtime SDK for **Helix** — a TypeScript-first platform for building integ
 - [Scheduled functions](#scheduled-functions)
 - [Async function calls](#async-function-calls)
 - [AI — `ctx.ai`](#ai--ctxai)
+- [Agents and tools — `ctx.agent`](#agents-and-tools--ctxagent)
 - [Authentication](#authentication)
 - [Configuration](#configuration)
 - [Logging](#logging)
@@ -83,6 +84,7 @@ Every HTTP handler receives a `ctx` (`TrayContext`); scheduled handlers receive
 | `ctx.kv()` | Key-value store |
 | `ctx.files()` | File storage |
 | `ctx.ai(alias)` | AI provider access — credentials are injected by the platform, same as `ctx.http.authed` |
+| `ctx.agent(name)` | Run an agent defined with `defineAgent` — `generate`/`stream`, with persisted conversation sessions |
 | `ctx.log.info/warn/error/debug` | Structured logging |
 | `ctx.config` | The `config` block from `helix.config.ts` |
 | `ctx.state` | Per-request scratch space |
@@ -383,6 +385,125 @@ export default defineFunction(async (ctx) => {
   and passing a model instance built directly against a third-party AI SDK provider (bypassing
   `ctx.ai`) throws `SdkError.aiForeignModelRejected`.
 
+## Agents and tools — `ctx.agent`
+
+An **agent** is an AI loop you define once and run from any handler: it calls a model, decides
+when to use the **tools** you gave it, and keeps a conversation **session** across turns. You
+write agents and tools as files; `ctx.agent(name)` runs them.
+
+- **Tools** (`defineTool`) live under `functions/_tools/` — a name, description, Zod `input`
+  schema, and a handler. A tool is a normal module you can also call in-process; when an agent
+  calls it, the same validation and handler run.
+- **Agents** (`defineAgent`) live under `functions/_agents/`, one file per agent. The agent
+  declares its `model` and `auth` (an `aiProviders`/`authentications` alias, exactly like
+  `ctx.ai`), its `instructions`, and the `tools` it may call.
+
+```typescript
+// functions/_tools/lookup_order.ts
+import { defineTool } from '@trayai/helix-sdk';
+import { z } from 'zod';
+
+export default defineTool({
+  name: 'lookup_order',
+  description: 'Look up an order by its id.',
+  input: z.object({ orderId: z.string() }),
+  async handler(ctx) {
+    const res = await ctx.http.authed('shop').get(`https://api.shop.example/orders/${ctx.input.orderId}`);
+    return res.body;   // { status, body?, headers } — see Authenticated HTTP
+  },
+});
+```
+
+```typescript
+// functions/_agents/support-agent.ts
+import { defineAgent } from '@trayai/helix-sdk';
+import lookupOrder from '../_tools/lookup_order.js';
+
+export default defineAgent({
+  name: 'support-agent',
+  description: 'Answers customer support questions.',
+  model: 'claude-sonnet-4-5',
+  auth: 'anthropicKey',        // an aiProviders alias, like ctx.ai
+  instructions: 'You are a helpful support agent. Use tools to look up real data.',
+  tools: [lookupOrder],
+});
+```
+
+Run it from any function:
+
+```typescript
+import { defineFunction } from '@trayai/helix-sdk';
+import { z } from 'zod';
+import '../_agents/support-agent.js';   // register the agent (see note below)
+
+export const input = z.object({
+  message: z.string(),
+  sessionId: z.string().optional(),
+});
+
+export default defineFunction<typeof input>(async (ctx) => {
+  const result = await ctx.agent('support-agent').generate({
+    prompt: ctx.input.message,
+    sessionId: ctx.input.sessionId,   // omit to start a new conversation
+  });
+  return { text: result.text, sessionId: result.sessionId };
+});
+```
+
+- **`generate(options)`** runs the loop to completion and resolves with the model result plus
+  the `sessionId` it used. **`stream(options)`** returns the AI SDK stream result (with its
+  `sessionId`) for token-by-token responses. Both accept a `prompt` (or `messages`) and an
+  optional `sessionId`.
+- **Deployed functions must import the agent module** (e.g. `import '../_agents/support-agent.js'`)
+  so it registers before `ctx.agent(name)` runs — only `helix dev` auto-loads `_agents/`; an
+  unknown name throws `Unknown agent "<name>"`.
+- **`model` / `auth`** reference the same `aiProviders` + `authentications` aliases as
+  `ctx.ai`, so every provider works — including **Amazon Bedrock** (`auth` pointing at a
+  Bedrock authentication and a Bedrock model id). Declare one or more `fallbacks`
+  (`{ model, auth }` pairs) and the agent retries the next on a model error.
+- **Tools** passed to `defineAgent` are given to the model automatically. Set
+  `needsApproval: true` (or a predicate of the input) on a tool and the loop pauses for human
+  approval before that tool runs.
+- **Delegation** — list other agents' names in `agents: [...]` and the agent can hand work to
+  them as sub-agents (each keeps its own session; nesting is capped).
+
+### Sessions
+
+A session is the **full record of a conversation**, not just the model's context window —
+appends never delete, and there is no default expiry, so an app can always show a user their
+earlier conversations. `ctx.agent(name).session(sessionId)` reads and manages one:
+
+```typescript
+const agent = ctx.agent('support-agent');
+const history = await agent.session(sessionId).messages();        // whole conversation
+const page = await agent.session(sessionId).page({ limit: 50, order: 'desc' }); // newest first
+await agent.session(sessionId).clear();                            // delete the conversation
+```
+
+- **`memory.maxSessionMessages`** (default 200) caps only what the **model** is sent each turn
+  — never what is stored. **`memory.ttl`** (seconds) is opt-in idle retention; omit it and
+  sessions are kept until you `clear()` them.
+- **`memory.scope: 'user'`** keys sessions by the invoking user (`ctx.identity`), so each user
+  only sees their own; `agent.sessions({ first, cursor })` then lists the calling user's recent
+  sessions, newest first. The default scope is `'project'` (sessions shared across the
+  project's executions). `agent.sessions()` requires the **managed** store (below) and a
+  `'user'`-scoped agent — it is not supported on the bring-your-own DynamoDB store.
+
+Choose where sessions are stored with the `agentSessions` field in `helix.config.ts`:
+
+```typescript
+export default defineConfig({
+  // ...
+  // Managed by Helix (the default — nothing to configure):
+  agentSessions: { store: 'managed' },
+  // …or bring your own DynamoDB table (credentials injected by the platform):
+  // agentSessions: { store: 'dynamodb', auth: '<aws-alias>', table: 'agent-sessions', region: 'us-east-1' },
+});
+```
+
+Try agents locally with `helix dev`, then `helix agent list` and `helix agent chat <name>`
+(see the `@trayai/helix-cli` README).
+
 ## Authentication
 
 Authenticated features (`ctx.http.authed`, `ctx.kv`, `ctx.files`, `ctx.ai`) require you to be logged in during local development:

package/dist/{define-agent-Cc6mFat1.d.ts → define-agent-DXV_nHvs.d.ts}

@@ -1,5 +1,5 @@
 import { z, ZodType } from 'zod';
-import { P as PlatformContext } from './types-CRUtefiq.js';
+import { P as PlatformContext } from './types-CVW_-1wh.js';
 
 interface SdkRuntimeConfig {
     /**
@@ -652,9 +652,6 @@ declare function requireWorkspaceId(config: LoadedTrayConfig): string;
 /**
  * `defineTool` (helix-spec 12) — the subset agents consume (helix-spec 14).
  *
- * **Beta.** Agents and tools are in beta: this API may change in a future
- * release without a major version bump.
- *
  * A tool is a *definition*: name, description, input schema, approval policy,
  * and handler together in one default export. Tools are:
  *
@@ -714,8 +711,6 @@ interface HelixToolLike {
 }
 /**
  * Define a tool an agent can call (or that your code can invoke in-process).
- *
- * @beta Agents and tools are in beta and may change in a future release.
  */
 declare function defineTool<TSchema extends ZodType>(config: DefineToolConfig<TSchema>): HelixTool<TSchema>;
 /** Structural check for defineTool output — see TOOL_DEFINITION_KIND. */
@@ -726,9 +721,6 @@ declare function isToolDefinition(value: unknown): value is HelixTool;
  * `functions/_agents/`, definitions in code, the file system as the source of
  * truth.
  *
- * **Beta.** Agents and tools are in beta: this API may change in a future
- * release without a major version bump.
- *
  * Like `defineSchedule`, the SDK owns the definition + runtime and the
  * host (dev server, lambda router) owns discovery: importing the module
  * registers the agent by name.
@@ -897,8 +889,6 @@ interface AgentDefinition extends z.output<typeof agentConfigSchema> {
 }
 /**
  * Define an agent (default export of a file under `functions/_agents/`).
- *
- * @beta Agents and tools are in beta and may change in a future release.
  */
 declare function defineAgent(config: AgentDefinitionConfig): AgentDefinition;
 /** Structural check for defineAgent output — see AGENT_DEFINITION_KIND. */

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as h3 from 'h3';
 import { ZodType } from 'zod';
-import { F as FunctionHandler, D as DefineFunctionOptions, a as DefineScheduleConfig, S as ScheduleDefinition, P as PlatformContext } from './types-CRUtefiq.js';
-export { A as AgentApprovalDecision, b as AgentCallOptions, c as AgentClient, d as AgentPendingApproval, e as AgentResult, f as AgentSession, g as AgentSessionPage, h as AgentSessionPageOptions, i as AgentSessionSummary, j as AgentSessionsList, k as AgentStreamResult, l as AiEmbeddingModelInstance, m as AiImageModelInstance, n as AiLanguageModelInstance, o as AiSpeechModelInstance, p as AiTranscriptionModelInstance, B as BrokerAuthedClient, q as BrokerCallOptions, r as BrokerCallResult, C as CallFunctionAsync, s as DbCallParameters, t as DbClient, u as FileSystemClient, H as HelixAI, v as HelixAIProvider, w as HelixAgent, x as HelixCost, y as HelixResultMeta, z as HttpClient, K as KeyValueStore, L as Logger, E as S3SignOptions, G as S3SignResult, I as ScheduleContext, J as ScheduleHandler, M as ScheduleTrigger, N as SqlBuilder, T as TrayContext, U as UnvalidatedInput } from './types-CRUtefiq.js';
-import { T as TrayConfig, L as LoadedTrayConfig, W as WatchErrorPhase } from './define-agent-Cc6mFat1.js';
-export { A as AGENT_DEFINITION_KIND, a as AI_SERVICES, b as AgentDefinition, c as AgentDefinitionConfig, d as AgentSessionsConfig, e as AiProviderEntry, f as AiService, C as ConfigFileOptions, D as DefineToolConfig, H as HELIX_CONFIG_ENV, g as HelixTool, h as HelixToolLike, P as ProvisionedTrayConfig, S as SdkRuntimeConfig, i as TOOL_DEFINITION_KIND, U as UnprovisionedTrayConfig, j as WORKSPACE_ID_REQUIRED_CODE, k as WorkspaceIdRequiredError, l as agentSessionsSchema, m as aiProviderEntrySchema, n as defineAgent, o as defineTool, p as getSdkConfig, q as isAgentDefinition, r as isToolDefinition, s as loadConfig, t as loadedTrayConfigSchema, u as projectIdSchema, v as requireWorkspaceId, w as resolveConfigFile, x as resolveConfigOverride, y as workspaceIdSchema } from './define-agent-Cc6mFat1.js';
+import { F as FunctionHandler, D as DefineFunctionOptions, a as DefineScheduleConfig, S as ScheduleDefinition, P as PlatformContext } from './types-CVW_-1wh.js';
+export { A as AgentApprovalDecision, b as AgentCallOptions, c as AgentClient, d as AgentPendingApproval, e as AgentResult, f as AgentSession, g as AgentSessionPage, h as AgentSessionPageOptions, i as AgentSessionSummary, j as AgentSessionsList, k as AgentStreamResult, l as AiEmbeddingModelInstance, m as AiImageModelInstance, n as AiLanguageModelInstance, o as AiSpeechModelInstance, p as AiTranscriptionModelInstance, B as BrokerAuthedClient, q as BrokerCallOptions, r as BrokerCallResult, C as CallFunctionAsync, s as DbCallParameters, t as DbClient, u as FileSystemClient, H as HelixAI, v as HelixAIProvider, w as HelixAgent, x as HelixCost, y as HelixResultMeta, z as HttpClient, K as KeyValueStore, L as Logger, E as S3SignOptions, G as S3SignResult, I as ScheduleContext, J as ScheduleHandler, M as ScheduleTrigger, N as SqlBuilder, T as TrayContext, U as UnvalidatedInput } from './types-CVW_-1wh.js';
+import { T as TrayConfig, L as LoadedTrayConfig, W as WatchErrorPhase } from './define-agent-DXV_nHvs.js';
+export { A as AGENT_DEFINITION_KIND, a as AI_SERVICES, b as AgentDefinition, c as AgentDefinitionConfig, d as AgentSessionsConfig, e as AiProviderEntry, f as AiService, C as ConfigFileOptions, D as DefineToolConfig, H as HELIX_CONFIG_ENV, g as HelixTool, h as HelixToolLike, P as ProvisionedTrayConfig, S as SdkRuntimeConfig, i as TOOL_DEFINITION_KIND, U as UnprovisionedTrayConfig, j as WORKSPACE_ID_REQUIRED_CODE, k as WorkspaceIdRequiredError, l as agentSessionsSchema, m as aiProviderEntrySchema, n as defineAgent, o as defineTool, p as getSdkConfig, q as isAgentDefinition, r as isToolDefinition, s as loadConfig, t as loadedTrayConfigSchema, u as projectIdSchema, v as requireWorkspaceId, w as resolveConfigFile, x as resolveConfigOverride, y as workspaceIdSchema } from './define-agent-DXV_nHvs.js';
 export { a as REGION_VALUES, R as Region, r as regionSchema } from './region-schema-COfWyGI9.js';
 import { StopCondition, ToolSet } from 'ai';
 export { EmbedManyResult, EmbedResult, EmbeddingModel, FinishReason, GenerateImageResult, GenerateObjectResult, GenerateTextResult, ImageModel, LanguageModel, LanguageModelUsage, ModelMessage, Output, PrepareStepFunction, SpeechModel, SpeechResult, StopCondition, StreamObjectResult, StreamTextResult, TextStreamPart, ToolChoice, ToolSet, TranscriptionModel, TranscriptionResult, UIMessage, convertToModelMessages, cosineSimilarity, dynamicTool, hasToolCall, jsonSchema, smoothStream, stepCountIs, tool, zodSchema } from 'ai';

package/dist/internal/index.d.ts

@@ -1,7 +1,7 @@
-import { L as LoadedTrayConfig, b as AgentDefinition } from '../define-agent-Cc6mFat1.js';
-export { z as SdkConfigInput, B as setSdkConfig } from '../define-agent-Cc6mFat1.js';
-import { j as AgentSessionsList, b as AgentCallOptions, e as AgentResult } from '../types-CRUtefiq.js';
-export { O as SessionExpiredError, Q as clearAgentSessions } from '../types-CRUtefiq.js';
+import { L as LoadedTrayConfig, b as AgentDefinition } from '../define-agent-DXV_nHvs.js';
+export { z as SdkConfigInput, B as setSdkConfig } from '../define-agent-DXV_nHvs.js';
+import { j as AgentSessionsList, b as AgentCallOptions, e as AgentResult } from '../types-CVW_-1wh.js';
+export { O as SessionExpiredError, Q as clearAgentSessions } from '../types-CVW_-1wh.js';
 import 'zod';
 import 'h3';
 import 'ky';

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { P as PlatformContext } from '../types-CRUtefiq.js';
+import { P as PlatformContext } from '../types-CVW_-1wh.js';
 import 'h3';
 import 'ky';
 import 'zod';

package/dist/{types-CRUtefiq.d.ts → types-CVW_-1wh.d.ts}

@@ -392,8 +392,6 @@ type AgentStreamResult = StreamTextReturn & {
 };
 /**
  * What `ctx.agent(name)` returns.
- *
- * @beta Agents and tools are in beta and may change in a future release.
  */
 interface HelixAgent {
     /** The AI SDK loop + session handling. */
@@ -422,8 +420,6 @@ interface HelixAgent {
 }
 /**
  * `ctx.agent` — look up a registered agent by name.
- *
- * @beta Agents and tools are in beta and may change in a future release.
  */
 type AgentClient = (name: string) => HelixAgent;
 
@@ -517,8 +513,6 @@ interface ContextCore {
     ai: HelixAI;
     /**
      * Agent client (helix-spec 14): `ctx.agent(name).generate()/.stream()`.
-     *
-     * @beta Agents and tools are in beta and may change in a future release.
      */
     agent: AgentClient;
     log: Logger;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trayai/helix-sdk",
-  "version": "1.8.0",
+  "version": "1.13.0",
   "description": "Helix SDK runtime — defineFunction, ctx, defineConfig, authed HTTP",
   "license": "Apache-2.0",
   "author": "trayio",