@meistrari/tela-sdk-js 2.13.1 → 2.14.0

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.
@@ -928,6 +928,7 @@ type SchemaFunction<T> = (schema: SchemaBuilder) => T;
 type Output<T> = T extends z$1.ZodType ? z$1.infer<T> : T;
 type ZodTypeOrRecord = z$1.ZodType | Record<string, unknown>;
 
+type EnvironmentName = 'production' | (string & {});
 interface BaseExecutionParams {
     /**
      * The version ID of the canvas to use for this chat completion.
@@ -1003,6 +1004,12 @@ interface BaseExecutionParams {
      * Tags can be used for filtering, categorization, and analytics.
      */
     tags?: string[];
+    /**
+     * Optional environment name to use for this execution.
+     * The default production environment is always available, and custom
+     * environment names can be configured in Tela.
+     */
+    environmentName?: EnvironmentName;
     /**
      * Custom HTTP headers to include in the request.
      * Useful for passing canvas event IDs.
@@ -1960,7 +1967,7 @@ interface BatchItem<TInput> {
 /**
  * Parameters excluded from batch execution (managed internally).
  */
-type ExcludedParams = 'versionId' | 'canvasId' | 'applicationId' | 'async' | 'stream' | 'webhookUrl' | 'skipResultValidation';
+type ExcludedParams = 'versionId' | 'canvasId' | 'applicationId' | 'async' | 'stream' | 'webhookUrl' | 'environmentName' | 'skipResultValidation';
 /**
  * Webhook configuration for batch completion notifications.
  *
@@ -4166,18 +4173,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 +4246,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 +4342,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 +4381,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 +4435,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`).
+     * 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.
      */
-    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 +4458,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 +4614,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 +4687,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, type EnvironmentName, 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.
@@ -928,6 +928,7 @@ type SchemaFunction<T> = (schema: SchemaBuilder) => T;
 type Output<T> = T extends z$1.ZodType ? z$1.infer<T> : T;
 type ZodTypeOrRecord = z$1.ZodType | Record<string, unknown>;
 
+type EnvironmentName = 'production' | (string & {});
 interface BaseExecutionParams {
     /**
      * The version ID of the canvas to use for this chat completion.
@@ -1003,6 +1004,12 @@ interface BaseExecutionParams {
      * Tags can be used for filtering, categorization, and analytics.
      */
     tags?: string[];
+    /**
+     * Optional environment name to use for this execution.
+     * The default production environment is always available, and custom
+     * environment names can be configured in Tela.
+     */
+    environmentName?: EnvironmentName;
     /**
      * Custom HTTP headers to include in the request.
      * Useful for passing canvas event IDs.
@@ -1960,7 +1967,7 @@ interface BatchItem<TInput> {
 /**
  * Parameters excluded from batch execution (managed internally).
  */
-type ExcludedParams = 'versionId' | 'canvasId' | 'applicationId' | 'async' | 'stream' | 'webhookUrl' | 'skipResultValidation';
+type ExcludedParams = 'versionId' | 'canvasId' | 'applicationId' | 'async' | 'stream' | 'webhookUrl' | 'environmentName' | 'skipResultValidation';
 /**
  * Webhook configuration for batch completion notifications.
  *
@@ -4166,18 +4173,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 +4246,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 +4342,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 +4381,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 +4435,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`).
+     * 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.
      */
-    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 +4458,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 +4614,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 +4687,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, type EnvironmentName, 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 };