@meistrari/tela-sdk-js 2.13.1 → 2.13.2

package/README.md

@@ -718,9 +718,9 @@ This is particularly useful when reading task input files: `tela.tasks.getInputF
 
 ### Agents API
 
-`tela.agents` is a thin **pass-through wrapper** around [`@meistrari/agent-sdk`](https://www.npmjs.com/package/@meistrari/agent-sdk). Execution, streaming, timeline, cancellation, and model updates are delegated straight to the agent-sdk client; the SDK adds only the Tela-specific bits: addressing agents by **`agentId`** (resolved to the underlying `organizationName`/`repository`), uploading `TelaFile` inputs to the vault, and mapping your Tela credentials onto the agent-sdk auth strategy. Method names and shapes mirror the agent-sdk contract.
+`tela.agents` runs agents through the Tela gateway (`run` → `POST /agent/:id/run`). Streaming, timeline, cancellation, and model updates are delegated to [`@meistrari/agent-sdk`](https://www.npmjs.com/package/@meistrari/agent-sdk). The SDK adds the Tela-specific bits: addressing agents by **`agentId`**, flattening a per-variable `inputs` map into the wire `inputSchema` array, uploading `TelaFile` inputs to the vault, and mapping your Tela credentials onto the agent-sdk auth strategy.
 
-> **Transport:** the wrapper builds an agent-sdk client that calls the `/v4/agents` and `/v4/sessions` endpoints. It defaults to your `baseURL`; set `agentBaseURL` when the v4 agent service lives at a different host:
+> **Transport:** `run` posts to the Tela gateway and is authenticated by your SDK credentials. The delegated streaming/timeline/cancel calls use an agent-sdk client against `/v4/sessions`; it defaults to your `baseURL`, set `agentBaseURL` when the v4 agent service lives at a different host:
 >
 > ```typescript
 > const tela = new TelaSDK({ apiKey: 'your-api-key', agentBaseURL: 'https://agents.example.com' })
@@ -732,8 +732,8 @@ const tela = new TelaSDK({ apiKey: 'your-api-key' })
 // Discover agents (Tela gateway)
 const agents = await tela.agents.list()
 
-// Start a session by agentId — resolved to org/repo under the hood.
-const started = await tela.agents.executeAgent({
+// Start a session by agentId.
+const started = await tela.agents.run({
     agentId: agents[0].id,
     message: 'Summarize the latest tickets',
 })
@@ -743,7 +743,7 @@ if (!started.success)
 const { sessionId } = started
 ```
 
-`executeAgent` returns the agent-sdk `ExecuteAgentResponse` (`{ success: true, sessionId } | { success: false, error }`). Stream the session's events by id:
+`run` returns `{ success, sessionId }` — execution is async, so stream the session's events by id:
 
 ```typescript
 for await (const event of await tela.agents.streamSession(sessionId)) {
@@ -767,60 +767,68 @@ const timeline = await tela.agents.fetchTimeline(sessionId)
 await tela.agents.cancelSession(sessionId)
 ```
 
-**Inputs** — pass file inputs as `TelaFile`s (uploaded to the vault automatically) or ready `vault://` references:
+**Inputs** — `inputs` is a map keyed by variable name. Each value is a single entry or an array of entries; an entry can be a `TelaFile` (uploaded to the vault automatically), a ready `vault://` reference, or a text entry — each optionally carrying `metadata`. The SDK flattens this into the wire `inputSchema` array, tagging every entry with its variable name.
 
 ```typescript
-await tela.agents.executeAgent({
+await tela.agents.run({
     agentId,
-    message: 'Review this contract',
-    inputs: [
-        tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
-        { vaultRef: 'vault://...', filename: 'reference.txt' },
-    ],
+    message: 'Review this contract against the references',
+    inputs: {
+        // a TelaFile — uploaded to the vault for you
+        contract: tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
+        // multiple entries for one variable; ready vault refs with metadata
+        references: [
+            { vaultRef: 'vault://...', filename: 'reference.txt', metadata: 'prior version' },
+        ],
+        // a text input
+        notes: { type: 'text', content: 'Focus on the indemnity clauses.' },
+    },
+    environmentVariables: { LOCALE: 'en-US' },
 })
 ```
 
-**Multi-turn / recover** — continue or recover an existing session by `sessionId` (omit `agentId`):
+**Multi-turn** — continue an existing session by passing its `sessionId` alongside the `agentId`:
 
 ```typescript
-await tela.agents.executeAgent({ sessionId, message: 'Now implement step 1' }) // continue
-await tela.agents.executeAgent({ sessionId, recover: true }) // recover a failed/terminal session
+await tela.agents.run({ agentId, sessionId, message: 'Now implement step 1' })
 ```
 
-**Webhooks** — register up to 5 HTTPS endpoints to receive session lifecycle callbacks instead of (or alongside) streaming. Passing `webhooks` on a continuation **replaces** the set.
+**Webhooks** — register session lifecycle callbacks by passing `webhooks` to `run`. The gateway forwards the webhook config to the agent execution service unchanged. Passing `webhooks` on a continuation replaces the session's registration; omitting it keeps the existing registration.
 
 ```typescript
-import { verifyWebhookSignature } from '@meistrari/tela-sdk-js'
-import type { SessionWebhookEventPayload } from '@meistrari/tela-sdk-js'
-
-await tela.agents.executeAgent({
+await tela.agents.run({
     agentId,
-    message: 'Audit the README for typos',
+    message: 'Summarize the latest tickets',
     webhooks: [{
-        url: 'https://example.com/hooks/agent',
-        events: ['session.completed', 'session.failed'], // defaults to all session.* events
-        secret: 'whsec_…', // optional HMAC-SHA256 signing secret
+        url: 'https://example.com/hooks/agent-session',
+        events: ['session.completed', 'session.failed', 'session.cancelled'],
+        secret: 'whsec_a-long-random-string',
     }],
 })
-
-// On your endpoint, verify the signature before trusting the payload:
-const valid = await verifyWebhookSignature(
-    rawBody,
-    req.headers.get('x-tela-agent-webhook-signature'),
-    process.env.WEBHOOK_SECRET!,
-)
-if (!valid)
-    return res.status(401).end()
-const event = JSON.parse(rawBody) as SessionWebhookEventPayload
 ```
 
+Webhook URLs must be HTTPS and publicly reachable. Up to five webhooks can be registered per session. Use `verifyWebhookSignature` to verify signed deliveries.
+
 **Model updates** — set an agent's model by id:
 
 ```typescript
 await tela.agents.updateAgentModel({ agentId, model: 'claude-opus-4-8', commitMessage: 'bump model' })
 ```
 
-The contract types (`SessionStreamEvent`, `SessionTimelineResponse`, `SessionWebhookConfig`, …), `verifyWebhookSignature`, and `parseSessionStream` are re-exported from `@meistrari/tela-sdk-js` — the agent-sdk is the single source of truth.
+The contract types (`SessionStreamEvent`, `SessionTimelineResponse`, `AgentRunWebhooks`, `SessionWebhookConfig`, …), `verifyWebhookSignature`, and `parseSessionStream` are re-exported from `@meistrari/tela-sdk-js` — the agent-sdk is the single source of truth for the session/streaming/webhook contract.
+
+**Migration note** — replace `tela.agents.executeAgent(...)` with `tela.agents.run(...)`. `agentId` is now required, `inputs` is keyed by variable name instead of a flat array, and `webhooks` moves unchanged onto `run`. The Tela gateway run path does not support agent-sdk `recover` requests; start or continue a session with `message` instead.
+
+```typescript
+await tela.agents.run({
+    agentId,
+    message,
+    inputs: {
+        document: tela.createFile(file, { name: 'document.pdf' }),
+    },
+    webhooks,
+})
+```
 
 ## Migration Guide from v1.x to v2
 

package/dist/index.cjs

@@ -24,7 +24,7 @@ const changeCase__namespace = /*#__PURE__*/_interopNamespaceCompat(changeCase);
 const z__default = /*#__PURE__*/_interopDefaultCompat(z);
 const Emittery__default = /*#__PURE__*/_interopDefaultCompat(Emittery);
 
-const version = "2.13.1";
+const version = "2.13.2";
 
 var __defProp$b = Object.defineProperty;
 var __defNormalProp$b = (obj, key, value) => key in obj ? __defProp$b(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -4788,34 +4788,27 @@ class Agents {
     return response.data;
   }
   /**
-   * Starts (or continues/recovers) an agent session, delegating to the
-   * agent-sdk client (`POST /v4/agents/execute`).
+   * Starts (or continues) an agent session via the Tela gateway
+   * (`POST /agent/:id/run`).
    *
-   * - **New session**: pass `agentId` (+ `message`). It is resolved to the
-   *   underlying `organizationName`/`repository`.
-   * - **Continue / recover**: pass `sessionId` (omit `agentId`); `recover: true`
-   *   resumes without a new message.
+   * - **New session**: pass `agentId` (+ `message`).
+   * - **Continue**: pass `agentId` and the existing `sessionId`.
    *
-   * After the request shape is validated, `TelaFile` inputs are uploaded to
-   * the vault; `webhooks` pass through to register lifecycle callbacks.
-   *
-   * @throws {Error} If neither `agentId` nor `sessionId` is provided, or if
-   * both are provided.
+   * The per-variable `inputs` map is flattened into the wire `inputSchema`
+   * array (each entry tagged with its variable name); any `TelaFile` inputs are
+   * uploaded to the vault first. Returns the `sessionId` to stream/inspect.
    */
-  async executeAgent(params) {
-    const { agentId, inputs, ...rest } = params;
-    const hasSessionId = rest.sessionId !== void 0;
-    if (hasSessionId) {
-      if (agentId)
-        throw new Error("agents.executeAgent: pass either `agentId` to start a new session or `sessionId` to continue/recover an existing session, not both.");
-      const resolvedInputs2 = inputs ? await this.uploadInputs(inputs) : void 0;
-      return this.client.executeAgent({ ...rest, inputs: resolvedInputs2 });
-    }
-    if (!agentId)
-      throw new Error("agents.executeAgent: `agentId` is required to start a new session (omit it only when continuing an existing `sessionId`).");
-    const resolvedInputs = inputs ? await this.uploadInputs(inputs) : void 0;
-    const { organizationName, repository } = await this.resolveAgent(agentId);
-    return this.client.executeAgent({ ...rest, inputs: resolvedInputs, organizationName, repository });
+  async run(params) {
+    const { agentId, message, sessionId, environmentVariables, inputs, webhooks } = params;
+    const inputSchema = inputs ? await this.buildInputSchema(inputs) : void 0;
+    const response = await this.gateway.post(
+      `/agent/${agentId}/run`,
+      {
+        ...AGENT_NO_TRANSFORM,
+        body: { message, sessionId, inputSchema, environmentVariables, webhooks }
+      }
+    );
+    return response.data;
   }
   /**
    * Updates an agent's model, delegating to the agent-sdk client
@@ -4844,19 +4837,45 @@ class Agents {
     return resolution;
   }
   /**
-   * Uploads any {@link TelaFile} inputs to the vault, turning the input list
-   * into agent-sdk {@link AgentInput}s (`vault://` references pass through).
+   * Flattens the per-variable {@link AgentRunInputs} map into the wire
+   * `inputSchema` array, tagging each entry with its variable name and
+   * uploading any {@link TelaFile} entries to the vault.
    */
-  async uploadInputs(inputs) {
-    return Promise.all(
-      inputs.map(async (input) => {
-        if (isTelaFile(input)) {
-          const { fileUrl } = await uploadFile(input, this.gateway);
-          return { vaultRef: fileUrl, filename: input.name ?? "file" };
-        }
-        return input;
-      })
-    );
+  async buildInputSchema(inputs) {
+    const pairs = Object.entries(inputs).flatMap(([name, value]) => {
+      const entries = Array.isArray(value) ? value : [value];
+      return entries.map((entry) => ({ name, entry }));
+    });
+    return Promise.all(pairs.map(({ name, entry }) => this.resolveEntry(name, entry)));
+  }
+  /**
+   * Resolves a single {@link AgentRunInputEntry} into a wire
+   * {@link AgentRunInputItem}, uploading {@link TelaFile}s to the vault.
+   */
+  async resolveEntry(name, entry) {
+    if (isTelaFile(entry)) {
+      const { fileUrl } = await uploadFile(entry, this.gateway);
+      return { type: "file", name, vaultRef: fileUrl, filename: entry.name ?? "file" };
+    }
+    if ("type" in entry && entry.type === "text")
+      return { type: "text", name, content: entry.content };
+    if ("file" in entry) {
+      const { fileUrl } = await uploadFile(entry.file, this.gateway);
+      return {
+        type: "file",
+        name,
+        vaultRef: fileUrl,
+        filename: entry.filename ?? entry.file.name ?? "file",
+        ...entry.metadata ? { metadata: entry.metadata } : {}
+      };
+    }
+    return {
+      type: "file",
+      name,
+      vaultRef: entry.vaultRef,
+      filename: entry.filename,
+      ...entry.metadata ? { metadata: entry.metadata } : {}
+    };
   }
 }
 
@@ -4956,13 +4975,13 @@ const _TelaSDK = class _TelaSDK extends BaseClient {
      */
     __publicField(this, "vault", new Vault(this));
     /**
-     * Agents API resource — a thin pass-through wrapper around
-     * `@meistrari/agent-sdk`. Execute by `agentId`, then stream events, fetch the
-     * timeline, or cancel by `sessionId`.
+     * Agents API resource. Run an agent by `agentId` via the Tela gateway
+     * (`POST /agent/:id/run`), then stream events, fetch the timeline, or cancel
+     * by `sessionId` (delegated to `@meistrari/agent-sdk`).
      *
      * @example
      * ```typescript
-     * const { sessionId } = await tela.agents.executeAgent({
+     * const { sessionId } = await tela.agents.run({
      *   agentId: 'agent-id',
      *   message: 'Hello',
      * })

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import z, { z as z$1 } from 'zod';
 import Emittery from 'emittery';
 import { JSONSchema } from 'zod/v4/core';
-import { SessionStreamEvent, AgentInput, ExecuteAgentRequest, UpdateAgentModelRequest, AgentClient, AuthStrategy, ExecuteAgentResponse, UpdateAgentModelResponse } from '@meistrari/agent-sdk';
-export { AgentInput, CancelSessionResponse, ExecuteAgentResponse, FetchTimelineOptions, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, SessionTimelineResponse, SessionWebhookConfig, SessionWebhookEventPayload, SessionWebhookEventType, SessionWebhookSubagent, SessionWebhookUsage, StreamSessionOptions, UpdateAgentModelResponse, parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
+import { SessionStreamEvent, ExecuteAgentRequest, ExecuteAgentResponse, UpdateAgentModelRequest, AgentClient, AuthStrategy, UpdateAgentModelResponse } from '@meistrari/agent-sdk';
+export { CancelSessionResponse, FetchTimelineOptions, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, SessionTimelineResponse, SessionWebhookConfig, SessionWebhookEventPayload, SessionWebhookEventType, SessionWebhookSubagent, SessionWebhookUsage, StreamSessionOptions, UpdateAgentModelResponse, parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
 
 /**
  * Base HTTP client with retry logic, request/response transformation, and streaming support.
@@ -4166,18 +4166,16 @@ declare class Vault {
 /**
  * Types for the Agents API.
  *
- * `tela.agents` is a thin wrapper around `@meistrari/agent-sdk` — it delegates
- * execution, streaming, timeline, cancellation, and model updates straight to
- * the agent-sdk client. The session/agent **contract is the agent-sdk's**, so
- * those types are re-exported here (single source of truth) rather than
- * redefined.
+ * Execution runs through the Tela gateway (`POST /agent/:id/run`): {@link RunAgentParams}
+ * carries a per-variable {@link AgentRunInputs} map that the wrapper flattens into the
+ * wire `inputSchema` array (each entry tagged with its variable `name`), uploading any
+ * {@link TelaFile} inputs to the vault along the way.
  *
- * The only Tela-specific additions are:
- *  - the **`agentId` contract**: a Tela agent is addressed by id and resolved to
- *    the underlying `organizationName`/`repository` (via the gateway `/agent`
- *    routes); and
- *  - the **vault integration**: `inputs` may carry {@link TelaFile}s, which are
- *    uploaded to the vault and passed to the agent as `vault://` references.
+ * Streaming, timeline, cancellation, and model updates are still delegated to
+ * `@meistrari/agent-sdk`, so those session/agent contract types are re-exported here
+ * (single source of truth) rather than redefined. A Tela agent is addressed by id and
+ * resolved to the underlying `organizationName`/`repository` (via the gateway `/agent`
+ * routes) for those delegated calls.
  *
  * @module Resources
  */
@@ -4241,34 +4239,86 @@ interface ListAgentsQuery {
     projectId?: string;
     includeProjects?: boolean;
 }
+/** A file input whose vault reference is already known. */
+interface AgentFileEntry {
+    type?: 'file';
+    /** A `vault://` reference. */
+    vaultRef: string;
+    /** The user-facing filename. */
+    filename: string;
+    /** Optional metadata string forwarded to the agent (≤16,384 chars). */
+    metadata?: string;
+}
+/** A {@link TelaFile} to upload to the vault before the run, with optional metadata. */
+interface AgentUploadEntry {
+    type?: 'file';
+    /** The file to upload; its vault reference is derived automatically. */
+    file: TelaFile;
+    /** Overrides the uploaded filename; defaults to the {@link TelaFile}'s name. */
+    filename?: string;
+    /** Optional metadata string forwarded to the agent (≤16,384 chars). */
+    metadata?: string;
+}
+/** A text input. */
+interface AgentTextEntry {
+    type: 'text';
+    /** The text content (≤10MB). */
+    content: string;
+}
 /**
- * A single execution input: either a ready agent-sdk {@link AgentInput} (a
- * `vault://` reference) or a {@link TelaFile} that the wrapper uploads to the
- * vault automatically before delegating.
+ * One input value for a variable. A bare {@link TelaFile} is sugar for
+ * `{ file }` — it is uploaded to the vault automatically.
  */
-type AgentExecuteInput = AgentInput | TelaFile;
+type AgentRunInputEntry = AgentFileEntry | AgentUploadEntry | AgentTextEntry | TelaFile;
 /**
- * Parameters for executing (or continuing) an agent session.
- *
- * Mirrors the agent-sdk `ExecuteAgentRequest` verbatim, except:
- *  - `organizationName`/`repository` are replaced by **`agentId`** (resolved by
- *    the wrapper); and
- *  - `inputs` may include {@link TelaFile}s (uploaded to the vault for you).
+ * Per-variable inputs: the key is the variable `name`, the value is one entry or
+ * an array of entries. The wrapper flattens this into the wire `inputSchema`
+ * array, tagging every entry with its variable name.
+ */
+type AgentRunInputs = Record<string, AgentRunInputEntry | AgentRunInputEntry[]>;
+/** Webhook registrations accepted by {@link Agents.run}; forwarded to `/agent/:id/run` unchanged. */
+type AgentRunWebhooks = ExecuteAgentRequest['webhooks'];
+/**
+ * A single wire `inputSchema` entry as sent to `POST /agent/:id/run`. Produced by
+ * flattening {@link AgentRunInputs}.
+ */
+type AgentRunInputItem = {
+    type: 'file';
+    name: string;
+    vaultRef: string;
+    filename: string;
+    metadata?: string;
+} | {
+    type: 'text';
+    name: string;
+    content: string;
+};
+/**
+ * Parameters for {@link Agents.run} — starting or continuing an agent session via
+ * the Tela gateway (`POST /agent/:id/run`).
  *
- * Start a new session with `agentId`; continue or recover an existing one with
- * `sessionId` (omit `agentId`). Passing both is rejected to avoid ambiguous
- * agent-sdk delegation semantics.
+ * Start a new session with just `agentId` (+ `message`); continue an existing one
+ * by also passing its `sessionId`.
  */
-interface ExecuteAgentParams extends Omit<ExecuteAgentRequest, 'organizationName' | 'repository' | 'inputs'> {
-    /**
-     * The Tela agent id. Required to start a new session — it is resolved to the
-     * underlying `organizationName`/`repository`. Omit it when continuing or
-     * recovering an existing `sessionId`; do not pass both.
-     */
-    agentId?: string;
-    /** File inputs. `TelaFile`s are uploaded to the vault; `AgentInput`s pass through. */
-    inputs?: AgentExecuteInput[];
+interface RunAgentParams {
+    /** The Tela agent id (path param). Always required — `/agent/:id/run`. */
+    agentId: string;
+    /** The turn message (required by the API for both new and continued sessions). */
+    message: string;
+    /** Continue an existing session by id; omit to start a new one. */
+    sessionId?: string;
+    /** Key/value environment variables for the run. */
+    environmentVariables?: Record<string, string>;
+    /** Per-variable inputs, flattened into the wire `inputSchema` array. */
+    inputs?: AgentRunInputs;
+    /**
+     * Optional session webhook registrations. On continuation, passing this
+     * replaces the existing set; omitting it keeps the current registration.
+     */
+    webhooks?: AgentRunWebhooks;
 }
+/** Response of `POST /agent/:id/run`, matching the agent-sdk execute response union. */
+type RunAgentResponse = ExecuteAgentResponse;
 /**
  * Parameters for updating an agent's model — mirrors the agent-sdk
  * `UpdateAgentModelRequest`, with `agentId` in place of `repository`.
@@ -4285,21 +4335,19 @@ interface UpdateAgentModelParams {
 /**
  * Agents API resource (`tela.agents`).
  *
- * A thin **pass-through wrapper** around `@meistrari/agent-sdk`. Execution,
- * streaming, timeline, cancellation, and model updates are delegated straight to
- * the agent-sdk client (which talks to the `/v4/*` endpoints). The wrapper adds
- * only the Tela-specific bits:
+ * Execution runs through the Tela gateway (`run` → `POST /agent/:id/run`): the
+ * wrapper flattens the per-variable `inputs` map into the wire `inputSchema`
+ * array and uploads any `TelaFile` inputs to the vault first. Streaming,
+ * timeline, cancellation, and model updates are delegated to `@meistrari/agent-sdk`
+ * (which talks to the `/v4/*` endpoints). The wrapper adds the Tela-specific bits:
  *
  *  - **`agentId` resolution** — a Tela agent is addressed by id; the wrapper
  *    resolves it to the underlying `organizationName`/`repository` via the Tela
- *    gateway `/agent` routes before delegating an execution.
+ *    gateway `/agent` routes for the delegated agent-sdk calls.
  *  - **vault integration** — `TelaFile` inputs are uploaded to the vault and
  *    passed to the agent as `vault://` references.
  *  - **auth** — Tela credentials are mapped onto an agent-sdk `AuthStrategy`.
  *
- * Webhook registration comes for free: `webhooks` is part of the agent-sdk
- * execute contract and passes straight through.
- *
  * @module Resources
  */
 
@@ -4326,14 +4374,17 @@ type AgentsConfig = {
  * ```typescript
  * const tela = new TelaSDK({ apiKey: '...' })
  *
- * // Start a session by agent id (resolved to org/repo under the hood).
- * const { sessionId } = await tela.agents.executeAgent({
+ * // Start a session by agent id (`POST /agent/:id/run`).
+ * const { sessionId } = await tela.agents.run({
  *   agentId: 'agent-123',
  *   message: 'Summarize the latest tickets',
- *   webhooks: [{ url: 'https://example.com/hook', events: ['session.completed'] }],
+ *   inputs: {
+ *     report: tela.createFile('https://example.com/q3.pdf'),
+ *     notes: { type: 'text', content: 'Focus on churn.' },
+ *   },
  * })
  *
- * // Stream / inspect / cancel by session id (straight pass-through).
+ * // Stream / inspect / cancel by session id (agent-sdk pass-through).
  * for await (const event of await tela.agents.streamSession(sessionId))
  *   console.log(event.kind)
  * const timeline = await tela.agents.fetchTimeline(sessionId)
@@ -4377,21 +4428,17 @@ declare class Agents {
      */
     get(agentId: string): Promise<AgentRecord>;
     /**
-     * Starts (or continues/recovers) an agent session, delegating to the
-     * agent-sdk client (`POST /v4/agents/execute`).
-     *
-     * - **New session**: pass `agentId` (+ `message`). It is resolved to the
-     *   underlying `organizationName`/`repository`.
-     * - **Continue / recover**: pass `sessionId` (omit `agentId`); `recover: true`
-     *   resumes without a new message.
+     * Starts (or continues) an agent session via the Tela gateway
+     * (`POST /agent/:id/run`).
      *
-     * After the request shape is validated, `TelaFile` inputs are uploaded to
-     * the vault; `webhooks` pass through to register lifecycle callbacks.
+     * - **New session**: pass `agentId` (+ `message`).
+     * - **Continue**: pass `agentId` and the existing `sessionId`.
      *
-     * @throws {Error} If neither `agentId` nor `sessionId` is provided, or if
-     * both are provided.
+     * The per-variable `inputs` map is flattened into the wire `inputSchema`
+     * array (each entry tagged with its variable name); any `TelaFile` inputs are
+     * uploaded to the vault first. Returns the `sessionId` to stream/inspect.
      */
-    executeAgent(params: ExecuteAgentParams): Promise<ExecuteAgentResponse>;
+    run(params: RunAgentParams): Promise<RunAgentResponse>;
     /**
      * Updates an agent's model, delegating to the agent-sdk client
      * (`PUT /v4/agents/:repository/model`). The `agentId` is resolved to the
@@ -4404,10 +4451,16 @@ declare class Agents {
      */
     private resolveAgent;
     /**
-     * Uploads any {@link TelaFile} inputs to the vault, turning the input list
-     * into agent-sdk {@link AgentInput}s (`vault://` references pass through).
+     * Flattens the per-variable {@link AgentRunInputs} map into the wire
+     * `inputSchema` array, tagging each entry with its variable name and
+     * uploading any {@link TelaFile} entries to the vault.
+     */
+    private buildInputSchema;
+    /**
+     * Resolves a single {@link AgentRunInputEntry} into a wire
+     * {@link AgentRunInputItem}, uploading {@link TelaFile}s to the vault.
      */
-    private uploadInputs;
+    private resolveEntry;
 }
 
 /**
@@ -4554,13 +4607,13 @@ declare class TelaSDK extends BaseClient {
      */
     vault: Vault;
     /**
-     * Agents API resource — a thin pass-through wrapper around
-     * `@meistrari/agent-sdk`. Execute by `agentId`, then stream events, fetch the
-     * timeline, or cancel by `sessionId`.
+     * Agents API resource. Run an agent by `agentId` via the Tela gateway
+     * (`POST /agent/:id/run`), then stream events, fetch the timeline, or cancel
+     * by `sessionId` (delegated to `@meistrari/agent-sdk`).
      *
      * @example
      * ```typescript
-     * const { sessionId } = await tela.agents.executeAgent({
+     * const { sessionId } = await tela.agents.run({
      *   agentId: 'agent-id',
      *   message: 'Hello',
      * })
@@ -4627,4 +4680,4 @@ declare class TelaSDK extends BaseClient {
  */
 declare function createTelaClient(opts: TelaSDKOptions): TelaSDK;
 
-export { APIError, type AgentExecuteInput, AgentExecutionFailedError, type AgentInputVariable, type AgentRecord, Agents, type AgentsConfig, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, type BatchParams, type BatchQueueConfig, type BatchQueueType, type BatchWebhookConfig, ConflictApiKeyAndJWTError, ConflictAuthMethodsError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, type ExecuteAgentParams, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, type ListAgentsQuery, MissingApiKeyOrJWTError, MissingAuthError, type NormalizedTaskStatus, NotFoundError, RateLimitError, type RequestOptions, type SchemaBuilder, type SessionErrorEvent, type SessionResultEvent, type SessionStatusEvent, type SessionStepsEvent, type SessionTimelineFinalizeEvent, type Task, type TaskDeleteBulkResult, type TaskDeleteResult, TaskFailedError, type TaskInputContent, type TaskInputFile, type TaskListItem, type TaskListQuery, type TaskListResult, type TaskOrderBy, type TaskOutputContent, type TaskRerunResult, type TaskStatus, type TaskUndoApprovalBulkResult, type TaskUpdatePayload, Tasks, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, type UpdateAgentModelParams, UserAbortError, Vault, createTelaClient, extractTaskOutput, isTelaFile, isTelaFileArray, normalizeTaskStatus, toError };
+export { APIError, AgentExecutionFailedError, type AgentFileEntry, type AgentInputVariable, type AgentRecord, type AgentRunInputEntry, type AgentRunInputItem, type AgentRunInputs, type AgentRunWebhooks, type AgentTextEntry, type AgentUploadEntry, Agents, type AgentsConfig, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, type BatchParams, type BatchQueueConfig, type BatchQueueType, type BatchWebhookConfig, ConflictApiKeyAndJWTError, ConflictAuthMethodsError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, type ListAgentsQuery, MissingApiKeyOrJWTError, MissingAuthError, type NormalizedTaskStatus, NotFoundError, RateLimitError, type RequestOptions, type RunAgentParams, type RunAgentResponse, type SchemaBuilder, type SessionErrorEvent, type SessionResultEvent, type SessionStatusEvent, type SessionStepsEvent, type SessionTimelineFinalizeEvent, type Task, type TaskDeleteBulkResult, type TaskDeleteResult, TaskFailedError, type TaskInputContent, type TaskInputFile, type TaskListItem, type TaskListQuery, type TaskListResult, type TaskOrderBy, type TaskOutputContent, type TaskRerunResult, type TaskStatus, type TaskUndoApprovalBulkResult, type TaskUpdatePayload, Tasks, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, type UpdateAgentModelParams, UserAbortError, Vault, createTelaClient, extractTaskOutput, isTelaFile, isTelaFileArray, normalizeTaskStatus, toError };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 import z, { z as z$1 } from 'zod';
 import Emittery from 'emittery';
 import { JSONSchema } from 'zod/v4/core';
-import { SessionStreamEvent, AgentInput, ExecuteAgentRequest, UpdateAgentModelRequest, AgentClient, AuthStrategy, ExecuteAgentResponse, UpdateAgentModelResponse } from '@meistrari/agent-sdk';
-export { AgentInput, CancelSessionResponse, ExecuteAgentResponse, FetchTimelineOptions, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, SessionTimelineResponse, SessionWebhookConfig, SessionWebhookEventPayload, SessionWebhookEventType, SessionWebhookSubagent, SessionWebhookUsage, StreamSessionOptions, UpdateAgentModelResponse, parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
+import { SessionStreamEvent, ExecuteAgentRequest, ExecuteAgentResponse, UpdateAgentModelRequest, AgentClient, AuthStrategy, UpdateAgentModelResponse } from '@meistrari/agent-sdk';
+export { CancelSessionResponse, FetchTimelineOptions, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, SessionTimelineResponse, SessionWebhookConfig, SessionWebhookEventPayload, SessionWebhookEventType, SessionWebhookSubagent, SessionWebhookUsage, StreamSessionOptions, UpdateAgentModelResponse, parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
 
 /**
  * Base HTTP client with retry logic, request/response transformation, and streaming support.
@@ -4166,18 +4166,16 @@ declare class Vault {
 /**
  * Types for the Agents API.
  *
- * `tela.agents` is a thin wrapper around `@meistrari/agent-sdk` — it delegates
- * execution, streaming, timeline, cancellation, and model updates straight to
- * the agent-sdk client. The session/agent **contract is the agent-sdk's**, so
- * those types are re-exported here (single source of truth) rather than
- * redefined.
+ * Execution runs through the Tela gateway (`POST /agent/:id/run`): {@link RunAgentParams}
+ * carries a per-variable {@link AgentRunInputs} map that the wrapper flattens into the
+ * wire `inputSchema` array (each entry tagged with its variable `name`), uploading any
+ * {@link TelaFile} inputs to the vault along the way.
  *
- * The only Tela-specific additions are:
- *  - the **`agentId` contract**: a Tela agent is addressed by id and resolved to
- *    the underlying `organizationName`/`repository` (via the gateway `/agent`
- *    routes); and
- *  - the **vault integration**: `inputs` may carry {@link TelaFile}s, which are
- *    uploaded to the vault and passed to the agent as `vault://` references.
+ * Streaming, timeline, cancellation, and model updates are still delegated to
+ * `@meistrari/agent-sdk`, so those session/agent contract types are re-exported here
+ * (single source of truth) rather than redefined. A Tela agent is addressed by id and
+ * resolved to the underlying `organizationName`/`repository` (via the gateway `/agent`
+ * routes) for those delegated calls.
  *
  * @module Resources
  */
@@ -4241,34 +4239,86 @@ interface ListAgentsQuery {
     projectId?: string;
     includeProjects?: boolean;
 }
+/** A file input whose vault reference is already known. */
+interface AgentFileEntry {
+    type?: 'file';
+    /** A `vault://` reference. */
+    vaultRef: string;
+    /** The user-facing filename. */
+    filename: string;
+    /** Optional metadata string forwarded to the agent (≤16,384 chars). */
+    metadata?: string;
+}
+/** A {@link TelaFile} to upload to the vault before the run, with optional metadata. */
+interface AgentUploadEntry {
+    type?: 'file';
+    /** The file to upload; its vault reference is derived automatically. */
+    file: TelaFile;
+    /** Overrides the uploaded filename; defaults to the {@link TelaFile}'s name. */
+    filename?: string;
+    /** Optional metadata string forwarded to the agent (≤16,384 chars). */
+    metadata?: string;
+}
+/** A text input. */
+interface AgentTextEntry {
+    type: 'text';
+    /** The text content (≤10MB). */
+    content: string;
+}
 /**
- * A single execution input: either a ready agent-sdk {@link AgentInput} (a
- * `vault://` reference) or a {@link TelaFile} that the wrapper uploads to the
- * vault automatically before delegating.
+ * One input value for a variable. A bare {@link TelaFile} is sugar for
+ * `{ file }` — it is uploaded to the vault automatically.
  */
-type AgentExecuteInput = AgentInput | TelaFile;
+type AgentRunInputEntry = AgentFileEntry | AgentUploadEntry | AgentTextEntry | TelaFile;
 /**
- * Parameters for executing (or continuing) an agent session.
- *
- * Mirrors the agent-sdk `ExecuteAgentRequest` verbatim, except:
- *  - `organizationName`/`repository` are replaced by **`agentId`** (resolved by
- *    the wrapper); and
- *  - `inputs` may include {@link TelaFile}s (uploaded to the vault for you).
+ * Per-variable inputs: the key is the variable `name`, the value is one entry or
+ * an array of entries. The wrapper flattens this into the wire `inputSchema`
+ * array, tagging every entry with its variable name.
+ */
+type AgentRunInputs = Record<string, AgentRunInputEntry | AgentRunInputEntry[]>;
+/** Webhook registrations accepted by {@link Agents.run}; forwarded to `/agent/:id/run` unchanged. */
+type AgentRunWebhooks = ExecuteAgentRequest['webhooks'];
+/**
+ * A single wire `inputSchema` entry as sent to `POST /agent/:id/run`. Produced by
+ * flattening {@link AgentRunInputs}.
+ */
+type AgentRunInputItem = {
+    type: 'file';
+    name: string;
+    vaultRef: string;
+    filename: string;
+    metadata?: string;
+} | {
+    type: 'text';
+    name: string;
+    content: string;
+};
+/**
+ * Parameters for {@link Agents.run} — starting or continuing an agent session via
+ * the Tela gateway (`POST /agent/:id/run`).
  *
- * Start a new session with `agentId`; continue or recover an existing one with
- * `sessionId` (omit `agentId`). Passing both is rejected to avoid ambiguous
- * agent-sdk delegation semantics.
+ * Start a new session with just `agentId` (+ `message`); continue an existing one
+ * by also passing its `sessionId`.
  */
-interface ExecuteAgentParams extends Omit<ExecuteAgentRequest, 'organizationName' | 'repository' | 'inputs'> {
-    /**
-     * The Tela agent id. Required to start a new session — it is resolved to the
-     * underlying `organizationName`/`repository`. Omit it when continuing or
-     * recovering an existing `sessionId`; do not pass both.
-     */
-    agentId?: string;
-    /** File inputs. `TelaFile`s are uploaded to the vault; `AgentInput`s pass through. */
-    inputs?: AgentExecuteInput[];
+interface RunAgentParams {
+    /** The Tela agent id (path param). Always required — `/agent/:id/run`. */
+    agentId: string;
+    /** The turn message (required by the API for both new and continued sessions). */
+    message: string;
+    /** Continue an existing session by id; omit to start a new one. */
+    sessionId?: string;
+    /** Key/value environment variables for the run. */
+    environmentVariables?: Record<string, string>;
+    /** Per-variable inputs, flattened into the wire `inputSchema` array. */
+    inputs?: AgentRunInputs;
+    /**
+     * Optional session webhook registrations. On continuation, passing this
+     * replaces the existing set; omitting it keeps the current registration.
+     */
+    webhooks?: AgentRunWebhooks;
 }
+/** Response of `POST /agent/:id/run`, matching the agent-sdk execute response union. */
+type RunAgentResponse = ExecuteAgentResponse;
 /**
  * Parameters for updating an agent's model — mirrors the agent-sdk
  * `UpdateAgentModelRequest`, with `agentId` in place of `repository`.
@@ -4285,21 +4335,19 @@ interface UpdateAgentModelParams {
 /**
  * Agents API resource (`tela.agents`).
  *
- * A thin **pass-through wrapper** around `@meistrari/agent-sdk`. Execution,
- * streaming, timeline, cancellation, and model updates are delegated straight to
- * the agent-sdk client (which talks to the `/v4/*` endpoints). The wrapper adds
- * only the Tela-specific bits:
+ * Execution runs through the Tela gateway (`run` → `POST /agent/:id/run`): the
+ * wrapper flattens the per-variable `inputs` map into the wire `inputSchema`
+ * array and uploads any `TelaFile` inputs to the vault first. Streaming,
+ * timeline, cancellation, and model updates are delegated to `@meistrari/agent-sdk`
+ * (which talks to the `/v4/*` endpoints). The wrapper adds the Tela-specific bits:
  *
  *  - **`agentId` resolution** — a Tela agent is addressed by id; the wrapper
  *    resolves it to the underlying `organizationName`/`repository` via the Tela
- *    gateway `/agent` routes before delegating an execution.
+ *    gateway `/agent` routes for the delegated agent-sdk calls.
  *  - **vault integration** — `TelaFile` inputs are uploaded to the vault and
  *    passed to the agent as `vault://` references.
  *  - **auth** — Tela credentials are mapped onto an agent-sdk `AuthStrategy`.
  *
- * Webhook registration comes for free: `webhooks` is part of the agent-sdk
- * execute contract and passes straight through.
- *
  * @module Resources
  */
 
@@ -4326,14 +4374,17 @@ type AgentsConfig = {
  * ```typescript
  * const tela = new TelaSDK({ apiKey: '...' })
  *
- * // Start a session by agent id (resolved to org/repo under the hood).
- * const { sessionId } = await tela.agents.executeAgent({
+ * // Start a session by agent id (`POST /agent/:id/run`).
+ * const { sessionId } = await tela.agents.run({
  *   agentId: 'agent-123',
  *   message: 'Summarize the latest tickets',
- *   webhooks: [{ url: 'https://example.com/hook', events: ['session.completed'] }],
+ *   inputs: {
+ *     report: tela.createFile('https://example.com/q3.pdf'),
+ *     notes: { type: 'text', content: 'Focus on churn.' },
+ *   },
  * })
  *
- * // Stream / inspect / cancel by session id (straight pass-through).
+ * // Stream / inspect / cancel by session id (agent-sdk pass-through).
  * for await (const event of await tela.agents.streamSession(sessionId))
  *   console.log(event.kind)
  * const timeline = await tela.agents.fetchTimeline(sessionId)
@@ -4377,21 +4428,17 @@ declare class Agents {
      */
     get(agentId: string): Promise<AgentRecord>;
     /**
-     * Starts (or continues/recovers) an agent session, delegating to the
-     * agent-sdk client (`POST /v4/agents/execute`).
-     *
-     * - **New session**: pass `agentId` (+ `message`). It is resolved to the
-     *   underlying `organizationName`/`repository`.
-     * - **Continue / recover**: pass `sessionId` (omit `agentId`); `recover: true`
-     *   resumes without a new message.
+     * Starts (or continues) an agent session via the Tela gateway
+     * (`POST /agent/:id/run`).
      *
-     * After the request shape is validated, `TelaFile` inputs are uploaded to
-     * the vault; `webhooks` pass through to register lifecycle callbacks.
+     * - **New session**: pass `agentId` (+ `message`).
+     * - **Continue**: pass `agentId` and the existing `sessionId`.
      *
-     * @throws {Error} If neither `agentId` nor `sessionId` is provided, or if
-     * both are provided.
+     * The per-variable `inputs` map is flattened into the wire `inputSchema`
+     * array (each entry tagged with its variable name); any `TelaFile` inputs are
+     * uploaded to the vault first. Returns the `sessionId` to stream/inspect.
      */
-    executeAgent(params: ExecuteAgentParams): Promise<ExecuteAgentResponse>;
+    run(params: RunAgentParams): Promise<RunAgentResponse>;
     /**
      * Updates an agent's model, delegating to the agent-sdk client
      * (`PUT /v4/agents/:repository/model`). The `agentId` is resolved to the
@@ -4404,10 +4451,16 @@ declare class Agents {
      */
     private resolveAgent;
     /**
-     * Uploads any {@link TelaFile} inputs to the vault, turning the input list
-     * into agent-sdk {@link AgentInput}s (`vault://` references pass through).
+     * Flattens the per-variable {@link AgentRunInputs} map into the wire
+     * `inputSchema` array, tagging each entry with its variable name and
+     * uploading any {@link TelaFile} entries to the vault.
+     */
+    private buildInputSchema;
+    /**
+     * Resolves a single {@link AgentRunInputEntry} into a wire
+     * {@link AgentRunInputItem}, uploading {@link TelaFile}s to the vault.
      */
-    private uploadInputs;
+    private resolveEntry;
 }
 
 /**
@@ -4554,13 +4607,13 @@ declare class TelaSDK extends BaseClient {
      */
     vault: Vault;
     /**
-     * Agents API resource — a thin pass-through wrapper around
-     * `@meistrari/agent-sdk`. Execute by `agentId`, then stream events, fetch the
-     * timeline, or cancel by `sessionId`.
+     * Agents API resource. Run an agent by `agentId` via the Tela gateway
+     * (`POST /agent/:id/run`), then stream events, fetch the timeline, or cancel
+     * by `sessionId` (delegated to `@meistrari/agent-sdk`).
      *
      * @example
      * ```typescript
-     * const { sessionId } = await tela.agents.executeAgent({
+     * const { sessionId } = await tela.agents.run({
      *   agentId: 'agent-id',
      *   message: 'Hello',
      * })
@@ -4627,4 +4680,4 @@ declare class TelaSDK extends BaseClient {
  */
 declare function createTelaClient(opts: TelaSDKOptions): TelaSDK;
 
-export { APIError, type AgentExecuteInput, AgentExecutionFailedError, type AgentInputVariable, type AgentRecord, Agents, type AgentsConfig, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, type BatchParams, type BatchQueueConfig, type BatchQueueType, type BatchWebhookConfig, ConflictApiKeyAndJWTError, ConflictAuthMethodsError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, type ExecuteAgentParams, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, type ListAgentsQuery, MissingApiKeyOrJWTError, MissingAuthError, type NormalizedTaskStatus, NotFoundError, RateLimitError, type RequestOptions, type SchemaBuilder, type SessionErrorEvent, type SessionResultEvent, type SessionStatusEvent, type SessionStepsEvent, type SessionTimelineFinalizeEvent, type Task, type TaskDeleteBulkResult, type TaskDeleteResult, TaskFailedError, type TaskInputContent, type TaskInputFile, type TaskListItem, type TaskListQuery, type TaskListResult, type TaskOrderBy, type TaskOutputContent, type TaskRerunResult, type TaskStatus, type TaskUndoApprovalBulkResult, type TaskUpdatePayload, Tasks, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, type UpdateAgentModelParams, UserAbortError, Vault, createTelaClient, extractTaskOutput, isTelaFile, isTelaFileArray, normalizeTaskStatus, toError };
+export { APIError, AgentExecutionFailedError, type AgentFileEntry, type AgentInputVariable, type AgentRecord, type AgentRunInputEntry, type AgentRunInputItem, type AgentRunInputs, type AgentRunWebhooks, type AgentTextEntry, type AgentUploadEntry, Agents, type AgentsConfig, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, type BatchParams, type BatchQueueConfig, type BatchQueueType, type BatchWebhookConfig, ConflictApiKeyAndJWTError, ConflictAuthMethodsError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, type ListAgentsQuery, MissingApiKeyOrJWTError, MissingAuthError, type NormalizedTaskStatus, NotFoundError, RateLimitError, type RequestOptions, type RunAgentParams, type RunAgentResponse, type SchemaBuilder, type SessionErrorEvent, type SessionResultEvent, type SessionStatusEvent, type SessionStepsEvent, type SessionTimelineFinalizeEvent, type Task, type TaskDeleteBulkResult, type TaskDeleteResult, TaskFailedError, type TaskInputContent, type TaskInputFile, type TaskListItem, type TaskListQuery, type TaskListResult, type TaskOrderBy, type TaskOutputContent, type TaskRerunResult, type TaskStatus, type TaskUndoApprovalBulkResult, type TaskUpdatePayload, Tasks, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, type UpdateAgentModelParams, UserAbortError, Vault, createTelaClient, extractTaskOutput, isTelaFile, isTelaFileArray, normalizeTaskStatus, toError };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import z, { z as z$1 } from 'zod';
 import Emittery from 'emittery';
 import { JSONSchema } from 'zod/v4/core';
-import { SessionStreamEvent, AgentInput, ExecuteAgentRequest, UpdateAgentModelRequest, AgentClient, AuthStrategy, ExecuteAgentResponse, UpdateAgentModelResponse } from '@meistrari/agent-sdk';
-export { AgentInput, CancelSessionResponse, ExecuteAgentResponse, FetchTimelineOptions, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, SessionTimelineResponse, SessionWebhookConfig, SessionWebhookEventPayload, SessionWebhookEventType, SessionWebhookSubagent, SessionWebhookUsage, StreamSessionOptions, UpdateAgentModelResponse, parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
+import { SessionStreamEvent, ExecuteAgentRequest, ExecuteAgentResponse, UpdateAgentModelRequest, AgentClient, AuthStrategy, UpdateAgentModelResponse } from '@meistrari/agent-sdk';
+export { CancelSessionResponse, FetchTimelineOptions, ResolveReferenceOptions, SessionStatus, SessionStreamEvent, SessionTimelineResponse, SessionWebhookConfig, SessionWebhookEventPayload, SessionWebhookEventType, SessionWebhookSubagent, SessionWebhookUsage, StreamSessionOptions, UpdateAgentModelResponse, parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
 
 /**
  * Base HTTP client with retry logic, request/response transformation, and streaming support.
@@ -4166,18 +4166,16 @@ declare class Vault {
 /**
  * Types for the Agents API.
  *
- * `tela.agents` is a thin wrapper around `@meistrari/agent-sdk` — it delegates
- * execution, streaming, timeline, cancellation, and model updates straight to
- * the agent-sdk client. The session/agent **contract is the agent-sdk's**, so
- * those types are re-exported here (single source of truth) rather than
- * redefined.
+ * Execution runs through the Tela gateway (`POST /agent/:id/run`): {@link RunAgentParams}
+ * carries a per-variable {@link AgentRunInputs} map that the wrapper flattens into the
+ * wire `inputSchema` array (each entry tagged with its variable `name`), uploading any
+ * {@link TelaFile} inputs to the vault along the way.
  *
- * The only Tela-specific additions are:
- *  - the **`agentId` contract**: a Tela agent is addressed by id and resolved to
- *    the underlying `organizationName`/`repository` (via the gateway `/agent`
- *    routes); and
- *  - the **vault integration**: `inputs` may carry {@link TelaFile}s, which are
- *    uploaded to the vault and passed to the agent as `vault://` references.
+ * Streaming, timeline, cancellation, and model updates are still delegated to
+ * `@meistrari/agent-sdk`, so those session/agent contract types are re-exported here
+ * (single source of truth) rather than redefined. A Tela agent is addressed by id and
+ * resolved to the underlying `organizationName`/`repository` (via the gateway `/agent`
+ * routes) for those delegated calls.
  *
  * @module Resources
  */
@@ -4241,34 +4239,86 @@ interface ListAgentsQuery {
     projectId?: string;
     includeProjects?: boolean;
 }
+/** A file input whose vault reference is already known. */
+interface AgentFileEntry {
+    type?: 'file';
+    /** A `vault://` reference. */
+    vaultRef: string;
+    /** The user-facing filename. */
+    filename: string;
+    /** Optional metadata string forwarded to the agent (≤16,384 chars). */
+    metadata?: string;
+}
+/** A {@link TelaFile} to upload to the vault before the run, with optional metadata. */
+interface AgentUploadEntry {
+    type?: 'file';
+    /** The file to upload; its vault reference is derived automatically. */
+    file: TelaFile;
+    /** Overrides the uploaded filename; defaults to the {@link TelaFile}'s name. */
+    filename?: string;
+    /** Optional metadata string forwarded to the agent (≤16,384 chars). */
+    metadata?: string;
+}
+/** A text input. */
+interface AgentTextEntry {
+    type: 'text';
+    /** The text content (≤10MB). */
+    content: string;
+}
 /**
- * A single execution input: either a ready agent-sdk {@link AgentInput} (a
- * `vault://` reference) or a {@link TelaFile} that the wrapper uploads to the
- * vault automatically before delegating.
+ * One input value for a variable. A bare {@link TelaFile} is sugar for
+ * `{ file }` — it is uploaded to the vault automatically.
  */
-type AgentExecuteInput = AgentInput | TelaFile;
+type AgentRunInputEntry = AgentFileEntry | AgentUploadEntry | AgentTextEntry | TelaFile;
 /**
- * Parameters for executing (or continuing) an agent session.
- *
- * Mirrors the agent-sdk `ExecuteAgentRequest` verbatim, except:
- *  - `organizationName`/`repository` are replaced by **`agentId`** (resolved by
- *    the wrapper); and
- *  - `inputs` may include {@link TelaFile}s (uploaded to the vault for you).
+ * Per-variable inputs: the key is the variable `name`, the value is one entry or
+ * an array of entries. The wrapper flattens this into the wire `inputSchema`
+ * array, tagging every entry with its variable name.
+ */
+type AgentRunInputs = Record<string, AgentRunInputEntry | AgentRunInputEntry[]>;
+/** Webhook registrations accepted by {@link Agents.run}; forwarded to `/agent/:id/run` unchanged. */
+type AgentRunWebhooks = ExecuteAgentRequest['webhooks'];
+/**
+ * A single wire `inputSchema` entry as sent to `POST /agent/:id/run`. Produced by
+ * flattening {@link AgentRunInputs}.
+ */
+type AgentRunInputItem = {
+    type: 'file';
+    name: string;
+    vaultRef: string;
+    filename: string;
+    metadata?: string;
+} | {
+    type: 'text';
+    name: string;
+    content: string;
+};
+/**
+ * Parameters for {@link Agents.run} — starting or continuing an agent session via
+ * the Tela gateway (`POST /agent/:id/run`).
  *
- * Start a new session with `agentId`; continue or recover an existing one with
- * `sessionId` (omit `agentId`). Passing both is rejected to avoid ambiguous
- * agent-sdk delegation semantics.
+ * Start a new session with just `agentId` (+ `message`); continue an existing one
+ * by also passing its `sessionId`.
  */
-interface ExecuteAgentParams extends Omit<ExecuteAgentRequest, 'organizationName' | 'repository' | 'inputs'> {
-    /**
-     * The Tela agent id. Required to start a new session — it is resolved to the
-     * underlying `organizationName`/`repository`. Omit it when continuing or
-     * recovering an existing `sessionId`; do not pass both.
-     */
-    agentId?: string;
-    /** File inputs. `TelaFile`s are uploaded to the vault; `AgentInput`s pass through. */
-    inputs?: AgentExecuteInput[];
+interface RunAgentParams {
+    /** The Tela agent id (path param). Always required — `/agent/:id/run`. */
+    agentId: string;
+    /** The turn message (required by the API for both new and continued sessions). */
+    message: string;
+    /** Continue an existing session by id; omit to start a new one. */
+    sessionId?: string;
+    /** Key/value environment variables for the run. */
+    environmentVariables?: Record<string, string>;
+    /** Per-variable inputs, flattened into the wire `inputSchema` array. */
+    inputs?: AgentRunInputs;
+    /**
+     * Optional session webhook registrations. On continuation, passing this
+     * replaces the existing set; omitting it keeps the current registration.
+     */
+    webhooks?: AgentRunWebhooks;
 }
+/** Response of `POST /agent/:id/run`, matching the agent-sdk execute response union. */
+type RunAgentResponse = ExecuteAgentResponse;
 /**
  * Parameters for updating an agent's model — mirrors the agent-sdk
  * `UpdateAgentModelRequest`, with `agentId` in place of `repository`.
@@ -4285,21 +4335,19 @@ interface UpdateAgentModelParams {
 /**
  * Agents API resource (`tela.agents`).
  *
- * A thin **pass-through wrapper** around `@meistrari/agent-sdk`. Execution,
- * streaming, timeline, cancellation, and model updates are delegated straight to
- * the agent-sdk client (which talks to the `/v4/*` endpoints). The wrapper adds
- * only the Tela-specific bits:
+ * Execution runs through the Tela gateway (`run` → `POST /agent/:id/run`): the
+ * wrapper flattens the per-variable `inputs` map into the wire `inputSchema`
+ * array and uploads any `TelaFile` inputs to the vault first. Streaming,
+ * timeline, cancellation, and model updates are delegated to `@meistrari/agent-sdk`
+ * (which talks to the `/v4/*` endpoints). The wrapper adds the Tela-specific bits:
  *
  *  - **`agentId` resolution** — a Tela agent is addressed by id; the wrapper
  *    resolves it to the underlying `organizationName`/`repository` via the Tela
- *    gateway `/agent` routes before delegating an execution.
+ *    gateway `/agent` routes for the delegated agent-sdk calls.
  *  - **vault integration** — `TelaFile` inputs are uploaded to the vault and
  *    passed to the agent as `vault://` references.
  *  - **auth** — Tela credentials are mapped onto an agent-sdk `AuthStrategy`.
  *
- * Webhook registration comes for free: `webhooks` is part of the agent-sdk
- * execute contract and passes straight through.
- *
  * @module Resources
  */
 
@@ -4326,14 +4374,17 @@ type AgentsConfig = {
  * ```typescript
  * const tela = new TelaSDK({ apiKey: '...' })
  *
- * // Start a session by agent id (resolved to org/repo under the hood).
- * const { sessionId } = await tela.agents.executeAgent({
+ * // Start a session by agent id (`POST /agent/:id/run`).
+ * const { sessionId } = await tela.agents.run({
  *   agentId: 'agent-123',
  *   message: 'Summarize the latest tickets',
- *   webhooks: [{ url: 'https://example.com/hook', events: ['session.completed'] }],
+ *   inputs: {
+ *     report: tela.createFile('https://example.com/q3.pdf'),
+ *     notes: { type: 'text', content: 'Focus on churn.' },
+ *   },
  * })
  *
- * // Stream / inspect / cancel by session id (straight pass-through).
+ * // Stream / inspect / cancel by session id (agent-sdk pass-through).
  * for await (const event of await tela.agents.streamSession(sessionId))
  *   console.log(event.kind)
  * const timeline = await tela.agents.fetchTimeline(sessionId)
@@ -4377,21 +4428,17 @@ declare class Agents {
      */
     get(agentId: string): Promise<AgentRecord>;
     /**
-     * Starts (or continues/recovers) an agent session, delegating to the
-     * agent-sdk client (`POST /v4/agents/execute`).
-     *
-     * - **New session**: pass `agentId` (+ `message`). It is resolved to the
-     *   underlying `organizationName`/`repository`.
-     * - **Continue / recover**: pass `sessionId` (omit `agentId`); `recover: true`
-     *   resumes without a new message.
+     * Starts (or continues) an agent session via the Tela gateway
+     * (`POST /agent/:id/run`).
      *
-     * After the request shape is validated, `TelaFile` inputs are uploaded to
-     * the vault; `webhooks` pass through to register lifecycle callbacks.
+     * - **New session**: pass `agentId` (+ `message`).
+     * - **Continue**: pass `agentId` and the existing `sessionId`.
      *
-     * @throws {Error} If neither `agentId` nor `sessionId` is provided, or if
-     * both are provided.
+     * The per-variable `inputs` map is flattened into the wire `inputSchema`
+     * array (each entry tagged with its variable name); any `TelaFile` inputs are
+     * uploaded to the vault first. Returns the `sessionId` to stream/inspect.
      */
-    executeAgent(params: ExecuteAgentParams): Promise<ExecuteAgentResponse>;
+    run(params: RunAgentParams): Promise<RunAgentResponse>;
     /**
      * Updates an agent's model, delegating to the agent-sdk client
      * (`PUT /v4/agents/:repository/model`). The `agentId` is resolved to the
@@ -4404,10 +4451,16 @@ declare class Agents {
      */
     private resolveAgent;
     /**
-     * Uploads any {@link TelaFile} inputs to the vault, turning the input list
-     * into agent-sdk {@link AgentInput}s (`vault://` references pass through).
+     * Flattens the per-variable {@link AgentRunInputs} map into the wire
+     * `inputSchema` array, tagging each entry with its variable name and
+     * uploading any {@link TelaFile} entries to the vault.
+     */
+    private buildInputSchema;
+    /**
+     * Resolves a single {@link AgentRunInputEntry} into a wire
+     * {@link AgentRunInputItem}, uploading {@link TelaFile}s to the vault.
      */
-    private uploadInputs;
+    private resolveEntry;
 }
 
 /**
@@ -4554,13 +4607,13 @@ declare class TelaSDK extends BaseClient {
      */
     vault: Vault;
     /**
-     * Agents API resource — a thin pass-through wrapper around
-     * `@meistrari/agent-sdk`. Execute by `agentId`, then stream events, fetch the
-     * timeline, or cancel by `sessionId`.
+     * Agents API resource. Run an agent by `agentId` via the Tela gateway
+     * (`POST /agent/:id/run`), then stream events, fetch the timeline, or cancel
+     * by `sessionId` (delegated to `@meistrari/agent-sdk`).
      *
      * @example
      * ```typescript
-     * const { sessionId } = await tela.agents.executeAgent({
+     * const { sessionId } = await tela.agents.run({
      *   agentId: 'agent-id',
      *   message: 'Hello',
      * })
@@ -4627,4 +4680,4 @@ declare class TelaSDK extends BaseClient {
  */
 declare function createTelaClient(opts: TelaSDKOptions): TelaSDK;
 
-export { APIError, type AgentExecuteInput, AgentExecutionFailedError, type AgentInputVariable, type AgentRecord, Agents, type AgentsConfig, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, type BatchParams, type BatchQueueConfig, type BatchQueueType, type BatchWebhookConfig, ConflictApiKeyAndJWTError, ConflictAuthMethodsError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, type ExecuteAgentParams, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, type ListAgentsQuery, MissingApiKeyOrJWTError, MissingAuthError, type NormalizedTaskStatus, NotFoundError, RateLimitError, type RequestOptions, type SchemaBuilder, type SessionErrorEvent, type SessionResultEvent, type SessionStatusEvent, type SessionStepsEvent, type SessionTimelineFinalizeEvent, type Task, type TaskDeleteBulkResult, type TaskDeleteResult, TaskFailedError, type TaskInputContent, type TaskInputFile, type TaskListItem, type TaskListQuery, type TaskListResult, type TaskOrderBy, type TaskOutputContent, type TaskRerunResult, type TaskStatus, type TaskUndoApprovalBulkResult, type TaskUpdatePayload, Tasks, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, type UpdateAgentModelParams, UserAbortError, Vault, createTelaClient, extractTaskOutput, isTelaFile, isTelaFileArray, normalizeTaskStatus, toError };
+export { APIError, AgentExecutionFailedError, type AgentFileEntry, type AgentInputVariable, type AgentRecord, type AgentRunInputEntry, type AgentRunInputItem, type AgentRunInputs, type AgentRunWebhooks, type AgentTextEntry, type AgentUploadEntry, Agents, type AgentsConfig, AuthenticationError, AuthorizationError, BadRequestError, BaseClient, type BaseClientOptions, type BaseTelaFileOptions, BatchExecutionFailedError, type BatchParams, type BatchQueueConfig, type BatchQueueType, type BatchWebhookConfig, ConflictApiKeyAndJWTError, ConflictAuthMethodsError, ConflictError, ConnectionError, ConnectionTimeout, EmptyFileError, ExecutionFailedError, ExecutionNotStartedError, FileUploadError, type HTTPMethods, InternalServerError, InvalidExecutionModeError, InvalidFileURL, type ListAgentsQuery, MissingApiKeyOrJWTError, MissingAuthError, type NormalizedTaskStatus, NotFoundError, RateLimitError, type RequestOptions, type RunAgentParams, type RunAgentResponse, type SchemaBuilder, type SessionErrorEvent, type SessionResultEvent, type SessionStatusEvent, type SessionStepsEvent, type SessionTimelineFinalizeEvent, type Task, type TaskDeleteBulkResult, type TaskDeleteResult, TaskFailedError, type TaskInputContent, type TaskInputFile, type TaskListItem, type TaskListQuery, type TaskListResult, type TaskOrderBy, type TaskOutputContent, type TaskRerunResult, type TaskStatus, type TaskUndoApprovalBulkResult, type TaskUpdatePayload, Tasks, TelaError, TelaFile, type TelaFileInput, type TelaFileOptions, type TelaFileOptionsWithMimeType, TelaFileSchema, TelaSDK, type TelaSDKOptions, UnprocessableEntityError, type UpdateAgentModelParams, UserAbortError, Vault, createTelaClient, extractTaskOutput, isTelaFile, isTelaFileArray, normalizeTaskStatus, toError };

package/dist/index.mjs

@@ -5,7 +5,7 @@ import Emittery from 'emittery';
 import { agentClient, DataTokenAuthStrategy, APIKeyAuthStrategy } from '@meistrari/agent-sdk';
 export { parseSessionStream, verifyWebhookSignature } from '@meistrari/agent-sdk';
 
-const version = "2.13.1";
+const version = "2.13.2";
 
 var __defProp$b = Object.defineProperty;
 var __defNormalProp$b = (obj, key, value) => key in obj ? __defProp$b(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -4769,34 +4769,27 @@ class Agents {
     return response.data;
   }
   /**
-   * Starts (or continues/recovers) an agent session, delegating to the
-   * agent-sdk client (`POST /v4/agents/execute`).
+   * Starts (or continues) an agent session via the Tela gateway
+   * (`POST /agent/:id/run`).
    *
-   * - **New session**: pass `agentId` (+ `message`). It is resolved to the
-   *   underlying `organizationName`/`repository`.
-   * - **Continue / recover**: pass `sessionId` (omit `agentId`); `recover: true`
-   *   resumes without a new message.
+   * - **New session**: pass `agentId` (+ `message`).
+   * - **Continue**: pass `agentId` and the existing `sessionId`.
    *
-   * After the request shape is validated, `TelaFile` inputs are uploaded to
-   * the vault; `webhooks` pass through to register lifecycle callbacks.
-   *
-   * @throws {Error} If neither `agentId` nor `sessionId` is provided, or if
-   * both are provided.
+   * The per-variable `inputs` map is flattened into the wire `inputSchema`
+   * array (each entry tagged with its variable name); any `TelaFile` inputs are
+   * uploaded to the vault first. Returns the `sessionId` to stream/inspect.
    */
-  async executeAgent(params) {
-    const { agentId, inputs, ...rest } = params;
-    const hasSessionId = rest.sessionId !== void 0;
-    if (hasSessionId) {
-      if (agentId)
-        throw new Error("agents.executeAgent: pass either `agentId` to start a new session or `sessionId` to continue/recover an existing session, not both.");
-      const resolvedInputs2 = inputs ? await this.uploadInputs(inputs) : void 0;
-      return this.client.executeAgent({ ...rest, inputs: resolvedInputs2 });
-    }
-    if (!agentId)
-      throw new Error("agents.executeAgent: `agentId` is required to start a new session (omit it only when continuing an existing `sessionId`).");
-    const resolvedInputs = inputs ? await this.uploadInputs(inputs) : void 0;
-    const { organizationName, repository } = await this.resolveAgent(agentId);
-    return this.client.executeAgent({ ...rest, inputs: resolvedInputs, organizationName, repository });
+  async run(params) {
+    const { agentId, message, sessionId, environmentVariables, inputs, webhooks } = params;
+    const inputSchema = inputs ? await this.buildInputSchema(inputs) : void 0;
+    const response = await this.gateway.post(
+      `/agent/${agentId}/run`,
+      {
+        ...AGENT_NO_TRANSFORM,
+        body: { message, sessionId, inputSchema, environmentVariables, webhooks }
+      }
+    );
+    return response.data;
   }
   /**
    * Updates an agent's model, delegating to the agent-sdk client
@@ -4825,19 +4818,45 @@ class Agents {
     return resolution;
   }
   /**
-   * Uploads any {@link TelaFile} inputs to the vault, turning the input list
-   * into agent-sdk {@link AgentInput}s (`vault://` references pass through).
+   * Flattens the per-variable {@link AgentRunInputs} map into the wire
+   * `inputSchema` array, tagging each entry with its variable name and
+   * uploading any {@link TelaFile} entries to the vault.
    */
-  async uploadInputs(inputs) {
-    return Promise.all(
-      inputs.map(async (input) => {
-        if (isTelaFile(input)) {
-          const { fileUrl } = await uploadFile(input, this.gateway);
-          return { vaultRef: fileUrl, filename: input.name ?? "file" };
-        }
-        return input;
-      })
-    );
+  async buildInputSchema(inputs) {
+    const pairs = Object.entries(inputs).flatMap(([name, value]) => {
+      const entries = Array.isArray(value) ? value : [value];
+      return entries.map((entry) => ({ name, entry }));
+    });
+    return Promise.all(pairs.map(({ name, entry }) => this.resolveEntry(name, entry)));
+  }
+  /**
+   * Resolves a single {@link AgentRunInputEntry} into a wire
+   * {@link AgentRunInputItem}, uploading {@link TelaFile}s to the vault.
+   */
+  async resolveEntry(name, entry) {
+    if (isTelaFile(entry)) {
+      const { fileUrl } = await uploadFile(entry, this.gateway);
+      return { type: "file", name, vaultRef: fileUrl, filename: entry.name ?? "file" };
+    }
+    if ("type" in entry && entry.type === "text")
+      return { type: "text", name, content: entry.content };
+    if ("file" in entry) {
+      const { fileUrl } = await uploadFile(entry.file, this.gateway);
+      return {
+        type: "file",
+        name,
+        vaultRef: fileUrl,
+        filename: entry.filename ?? entry.file.name ?? "file",
+        ...entry.metadata ? { metadata: entry.metadata } : {}
+      };
+    }
+    return {
+      type: "file",
+      name,
+      vaultRef: entry.vaultRef,
+      filename: entry.filename,
+      ...entry.metadata ? { metadata: entry.metadata } : {}
+    };
   }
 }
 
@@ -4937,13 +4956,13 @@ const _TelaSDK = class _TelaSDK extends BaseClient {
      */
     __publicField(this, "vault", new Vault(this));
     /**
-     * Agents API resource — a thin pass-through wrapper around
-     * `@meistrari/agent-sdk`. Execute by `agentId`, then stream events, fetch the
-     * timeline, or cancel by `sessionId`.
+     * Agents API resource. Run an agent by `agentId` via the Tela gateway
+     * (`POST /agent/:id/run`), then stream events, fetch the timeline, or cancel
+     * by `sessionId` (delegated to `@meistrari/agent-sdk`).
      *
      * @example
      * ```typescript
-     * const { sessionId } = await tela.agents.executeAgent({
+     * const { sessionId } = await tela.agents.run({
      *   agentId: 'agent-id',
      *   message: 'Hello',
      * })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-sdk-js",
-  "version": "2.13.1",
+  "version": "2.13.2",
   "repository": {
     "type": "git",
     "url": "https://github.com/meistrari/tela-sdk-js.git"