@meistrari/tela-sdk-js 2.13.0 → 2.13.2

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 { SessionStatus, SessionStreamEvent } from '@meistrari/agent-sdk';
-export { SessionStatus, SessionStreamEvent } 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.
@@ -4164,58 +4164,42 @@ declare class Vault {
 }
 
 /**
- * Types for the Agents API (Phase 1: execution).
+ * Types for the Agents API.
  *
- * Agents are executed through the Tela API's `/agent/*` routes (which proxy to
- * the agent runtime). An agent is identified by its **agentId**; the Tela API
- * resolves it to the underlying repository and runs it. These routes are
- * camelCase-native, so every agent request opts out of the SDK's case
- * transformation.
+ * 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 **session/event contract** (`SessionStreamEvent`, `SessionStatus`, …) is
- * re-exported from `@meistrari/agent-sdk` — the single source of truth for the
- * agent contract. Only the Tela-layer types (agent records, execute params,
- * the `/agent` timeline shape) live here.
+ * 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
  */
 
-/**
- * A typed view of a single execution step (the wire payload is a loose object;
- * these are the fields commonly present, with token/cost accounting).
- */
-interface AgentStep {
-    id: string;
-    stepIndex: number;
-    eventId?: string;
-    inputTokens: number | null;
-    outputTokens: number | null;
-    cacheReadInputTokens?: number | null;
-    cacheCreationInputTokens?: number | null;
-    calculatedCostUsd: number | null;
-    [key: string]: unknown;
-}
-/**
- * A typed view of the session's final result payload (the wire payload is a
- * loose object; these are the fields commonly present).
- */
-interface AgentSessionResult {
-    usage: {
-        duration: number;
-        turns: number;
-        completionTokens: number;
-        promptTokens: number;
-        totalTokens: number;
-        completionCost: number;
-        promptCost: number;
-        totalCost: number;
-        [key: string]: unknown;
-    };
-    content?: string;
-    structuredContent?: Record<string, unknown>;
-    childEventIds?: string[];
-    [key: string]: unknown;
-}
+/** A `status` session event. */
+type SessionStatusEvent = Extract<SessionStreamEvent, {
+    kind: 'status';
+}>;
+/** A `steps` session event. */
+type SessionStepsEvent = Extract<SessionStreamEvent, {
+    kind: 'steps';
+}>;
+/** A `result` session event. */
+type SessionResultEvent = Extract<SessionStreamEvent, {
+    kind: 'result';
+}>;
+/** An `error` session event. */
+type SessionErrorEvent = Extract<SessionStreamEvent, {
+    kind: 'error';
+}>;
+/** A `timeline-finalize` session event. */
+type SessionTimelineFinalizeEvent = Extract<SessionStreamEvent, {
+    kind: 'timeline-finalize';
+}>;
 /** A declared input variable on an agent (from the agent record). */
 interface AgentInputVariable {
     id?: string;
@@ -4226,6 +4210,9 @@ interface AgentInputVariable {
 }
 /**
  * An agent record as returned by `GET /agent` and `GET /agent/:id`.
+ *
+ * Carries the `organizationName`/`repository` the agent-sdk addresses agents by;
+ * the wrapper resolves an `agentId` to these before delegating an execution.
  */
 interface AgentRecord {
     id: string;
@@ -4252,11 +4239,50 @@ 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;
+}
+/**
+ * One input value for a variable. A bare {@link TelaFile} is sugar for
+ * `{ file }` — it is uploaded to the vault automatically.
+ */
+type AgentRunInputEntry = AgentFileEntry | AgentUploadEntry | AgentTextEntry | TelaFile;
 /**
- * A resolved execution input item (the value form sent to the agent), keyed by
- * the agent's declared input variable name.
+ * 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 AgentInputItem = {
+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;
@@ -4267,293 +4293,78 @@ type AgentInputItem = {
     name: string;
     content: string;
 };
-/** An ad-hoc file attachment (a vault reference + filename). */
-interface AgentAttachment {
-    vaultRef: string;
-    filename: string;
-}
-/**
- * Session timeline summary from `GET /agent/sessions/:id/timeline`.
- */
-interface AgentTimeline {
-    durationMs?: number;
-    toolCalls?: number;
-    apiCalls?: number;
-    tokensIn?: number;
-    tokensOut?: number;
-    cachedTokens?: number;
-    totalCostUsd?: number;
-    cacheSavingsUsd?: number;
-    prompt?: Record<string, unknown>;
-    spans?: Array<Record<string, unknown>>;
-    events?: Array<Record<string, unknown>>;
-    continuation?: Record<string, unknown>;
-    [key: string]: unknown;
-}
 /**
- * Parameters for executing (or continuing) an agent session.
+ * Parameters for {@link Agents.run} — starting or continuing an agent session via
+ * the Tela gateway (`POST /agent/:id/run`).
+ *
+ * Start a new session with just `agentId` (+ `message`); continue an existing one
+ * by also passing its `sessionId`.
  */
-interface AgentExecuteParams {
-    /** The natural-language instruction for the agent (sent as `message` on the wire). */
-    prompt?: string;
-    /**
-     * Alias for {@link AgentExecuteParams.prompt}, matching the raw wire field
-     * name. Provide either `prompt` or `message`, not both.
-     */
-    message?: string;
-    /**
-     * Values for the agent's declared input variables, keyed by name.
-     * `TelaFile`s are uploaded to the vault automatically; strings are sent as text.
-     */
-    inputs?: Record<string, TelaFile | string>;
-    /** Ad-hoc file attachments — `TelaFile`s are uploaded; `AgentAttachment`s pass through. */
-    attachments?: Array<TelaFile | AgentAttachment>;
-    /** Environment variables made available to the agent run. */
+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;
     /**
-     * Run the **draft** version (`POST /agent/:id/test`) instead of the
-     * published one (`POST /agent/:id/run`, the default).
+     * Optional session webhook registrations. On continuation, passing this
+     * replaces the existing set; omitting it keeps the current registration.
      */
-    draft?: boolean;
-    /** Git ref (branch/tag/commit) to run. Draft mode only. */
-    ref?: string;
-    /** Enable multi-turn. Draft mode only. */
-    isMultiturn?: boolean;
-    /** Extra headers to attach to the execute request. */
-    headers?: Record<string, string>;
+    webhooks?: AgentRunWebhooks;
 }
-
+/** Response of `POST /agent/:id/run`, matching the agent-sdk execute response union. */
+type RunAgentResponse = ExecuteAgentResponse;
 /**
- * Agent execution lifecycle.
- *
- * `AgentExecution` drives a single agent session through the Tela API: it
- * creates (or continues) the session via `POST /agent/:id/run` (or `/test` for
- * the draft), then streams the session's events from `GET /agent/sessions/:id`
- * (SSE). It mirrors the promise-like + event-emitter ergonomics of
- * {@link CanvasExecution}: you can `await execution.result`, iterate
- * `execution.stream`, or subscribe to `status`/`step`/`result`/`error` events.
- *
- * @module Resources
- */
-
-/** The execution mode: the published version (`/run`) or the draft (`/test`). */
-type AgentExecutionMode = 'run' | 'test';
-/**
- * Events emitted by {@link AgentExecution} during a session's lifecycle.
- *
- * @property status - Emitted when the session status changes.
- * @property step - Emitted for each `steps` event, with the newly produced steps.
- * @property result - Emitted when the session produces a result payload.
- * @property error - Emitted when the session fails (an `error` event or `failed` status).
+ * Parameters for updating an agent's model — mirrors the agent-sdk
+ * `UpdateAgentModelRequest`, with `agentId` in place of `repository`.
  */
-interface AgentExecutionEvents {
-    status: SessionStatus;
-    step: AgentStep[];
-    result: AgentSessionResult;
-    error: AgentExecutionFailedError;
-}
-/**
- * Construction context for an {@link AgentExecution}.
- */
-interface AgentExecutionContext {
-    client: BaseClient;
-    /** The agent id. Omitted for executions resumed from an existing session. */
-    agentId?: string;
-    /** Execution mode. Defaults to `run` (published). */
-    mode?: AgentExecutionMode;
-    /** An existing session id to resume. */
-    sessionId?: string;
-    /** Delay (ms) between session-stream reconnects. Defaults to 2000. */
-    reconnectDelayMs?: number;
-}
-/**
- * A promise-like handle returned by `Agent.execute()` / `AgentExecution.continue()`.
- *
- * - `await` it to get the started {@link AgentExecution} (after the session is created).
- * - `.result` resolves with the session's result payload.
- * - `.stream` is a live, typed async iterator of session events.
- *
- * Consume **either** `.result` **or** `.stream` for a given execution — they
- * share a single underlying generator and cannot both be read.
- */
-type AgentExecutionPromiseLike = PromiseLike<AgentExecution> & {
-    result: Promise<AgentSessionResult>;
-    stream: AsyncGenerator<SessionStreamEvent>;
-};
-/**
- * Manages the lifecycle of a single agent session.
- *
- * @fires status - When the session status transitions.
- * @fires step - For each batch of steps produced.
- * @fires result - When the session yields a result payload.
- * @fires error - When the session fails.
- *
- * @example
- * ```typescript
- * const agent = await tela.agents.get('agent-id')
- * const execution = agent.execute({ prompt: 'Summarize the latest tickets' })
- *
- * execution.on('step', steps => console.log(steps))
- * const result = await execution.result
- * ```
- */
-declare class AgentExecution extends Emittery<AgentExecutionEvents> {
-    private _sessionId;
-    private _status;
-    private _cursor;
-    private _resultPromise;
-    private _stream;
-    private _abortController;
-    private readonly _client;
-    private readonly _agentId;
-    private readonly _mode;
-    private readonly _reconnectDelayMs;
-    constructor(context: AgentExecutionContext);
-    /**
-     * Builds a resumable execution bound to an existing session id.
-     *
-     * Used by `tela.agents.getSession()`. The returned execution can `.stream`,
-     * `.result`, `.cancel`, or `.recover` — but not `.continue` (a new turn
-     * needs the agent id).
-     */
-    static fromSession(sessionId: string, client: BaseClient): AgentExecution;
-    /**
-     * The session id assigned by the server.
-     *
-     * @throws {ExecutionNotStartedError} If the execution has not started yet.
-     */
-    get sessionId(): string;
-    /**
-     * The latest known session status.
-     *
-     * @throws {ExecutionNotStartedError} If no status has been observed yet.
-     */
-    get status(): SessionStatus;
-    private set status(value);
-    /**
-     * Starts (or continues) the session by POSTing to `/agent/:id/run`
-     * (or `/agent/:id/test` in draft mode). Resets any in-flight stream/result
-     * so the next read re-opens.
-     *
-     * @throws {AgentExecutionFailedError} If the server rejects the execution.
-     */
-    start(params: AgentExecuteParams): Promise<this>;
-    /**
-     * Continues this session with another turn (same `sessionId`).
-     *
-     * @returns A promise-like handle for the new turn (`.result` / `.stream`).
-     */
-    continue(params: AgentExecuteParams): AgentExecutionPromiseLike;
-    /**
-     * Recovers a failed/terminal session (`POST /agent/sessions/:id/recover`),
-     * then re-opens the stream from the current cursor.
-     *
-     * @throws {ExecutionNotStartedError} If there is no session to recover.
-     * @throws {AgentExecutionFailedError} If recovery is rejected.
-     */
-    recover(): Promise<this>;
-    /**
-     * A live, typed stream of session events. Memoized: repeated access returns
-     * the same generator. Updates `status` and the resume cursor as it goes.
-     *
-     * @throws {ExecutionNotStartedError} If the session has no id yet.
-     */
-    get stream(): AsyncGenerator<SessionStreamEvent>;
-    private openStream;
-    private fail;
-    /**
-     * Resolves with the session's result payload, lazily consuming the stream.
-     *
-     * Memoized: repeated access returns the same promise. Resolves on the first
-     * `result` event — for `completed` *or* `waiting_messages`. Inspect
-     * `.status` to tell them apart, and `.continue()` from a paused turn.
-     *
-     * @throws {AgentExecutionFailedError} If the session fails or the stream
-     * ends without producing a result.
-     */
-    get result(): Promise<AgentSessionResult>;
-    /**
-     * Cancels the session: aborts the open stream immediately, then requests a
-     * server-side cancel (`POST /agent/sessions/:id/cancel`).
-     */
-    cancel(): Promise<void>;
-    /**
-     * Resolves the agent's input values into {@link AgentInputItem}s, uploading
-     * any `TelaFile`s to the vault and passing strings through as text.
-     */
-    private resolveInputs;
-    /**
-     * Resolves attachments to {@link AgentAttachment}s, uploading any `TelaFile`s.
-     */
-    private resolveAttachments;
+interface UpdateAgentModelParams {
+    /** The Tela agent id, resolved to the underlying repository. */
+    agentId: string;
+    /** The model to set, as accepted by the agent-sdk model contract. */
+    model: UpdateAgentModelRequest['model'];
+    /** Optional commit message recorded for the change. */
+    commitMessage?: string;
 }
 
 /**
- * Agent handle — a fetched reference to an agent, identified by its id.
+ * Agents API resource (`tela.agents`).
  *
- * Created via `tela.agents.get(agentId)`, mirroring how `tela.canvas.get()`
- * returns a {@link Canvas}. From a handle you `execute()` the agent and read its
- * metadata (title, declared inputs, published version, etc.).
+ * 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:
  *
- * @module Resources
- */
-
-/**
- * A handle to an agent. Use `agent.execute()` to run it.
- *
- * @category Resources
+ *  - **`agentId` resolution** — a Tela agent is addressed by id; the wrapper
+ *    resolves it to the underlying `organizationName`/`repository` via the Tela
+ *    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`.
  *
- * @example
- * ```typescript
- * const agent = await tela.agents.get('agent-id')
- * const result = await agent.execute({ prompt: 'Hello' }).result
- * ```
+ * @module Resources
  */
-declare class Agent {
-    private readonly _client;
-    private readonly _record;
-    constructor(client: BaseClient, record: AgentRecord);
-    /** The agent id. */
-    get id(): string;
-    /** The agent's display title. */
-    get title(): string;
-    /** The organization that owns the agent's repository. */
-    get organizationName(): string;
-    /** The agent's repository name. */
-    get repository(): string;
-    /** The agent's declared input variables. */
-    get inputSchema(): AgentInputVariable[];
-    /** The published commit id, or `null` if the agent has never been published. */
-    get publishedId(): string | null;
-    /** Whether the agent supports multi-turn sessions. */
-    get isMultiturn(): boolean;
-    /** The full agent record as returned by the API. */
-    get record(): AgentRecord;
-    /**
-     * Executes the agent. By default this runs the **published** version
-     * (`POST /agent/:id/run`); pass `{ draft: true }` to run the current draft
-     * (`POST /agent/:id/test`).
-     *
-     * Returns a promise-like handle: `await` it for the {@link AgentExecution},
-     * read `.result` for the final payload, or iterate `.stream` for live events.
-     *
-     * @param params - Execution parameters (notably `prompt`, `inputs`, `draft`).
-     */
-    execute(params?: AgentExecuteParams): AgentExecutionPromiseLike;
-}
 
 /**
- * Agents API resource (`tela.agents`).
- *
- * Phase 1 covers the execution lifecycle: discovering agents, getting a handle,
- * running them by id, and reading/controlling session state. All calls go to
- * the Tela API's `/agent/*` routes (which proxy to the agent runtime), reusing
- * the SDK's existing baseURL and authentication. The routes are camelCase-native,
- * so every request opts out of case transformation.
+ * Configuration for the {@link Agents} resource.
  *
- * @module Resources
+ * Provide either a pre-built agent-sdk `client` (used for testing/advanced use),
+ * or the pieces needed to build one (`agentBaseURL`, `authStrategy`, and an
+ * optional `vaultURL` for reference resolution).
  */
-
+type AgentsConfig = {
+    client: AgentClient;
+} | {
+    agentBaseURL: string;
+    vaultURL?: string;
+    authStrategy: AuthStrategy;
+};
 /**
  * Agents API resource.
  *
@@ -4563,62 +4374,93 @@ declare class Agent {
  * ```typescript
  * const tela = new TelaSDK({ apiKey: '...' })
  *
- * const agents = await tela.agents.list()                 // discover agent ids
- * const agent = await tela.agents.get(agents[0].id)        // get a handle
- * const result = await agent.execute({ prompt: 'Summarize the latest tickets' }).result
+ * // Start a session by agent id (`POST /agent/:id/run`).
+ * const { sessionId } = await tela.agents.run({
+ *   agentId: 'agent-123',
+ *   message: 'Summarize the latest tickets',
+ *   inputs: {
+ *     report: tela.createFile('https://example.com/q3.pdf'),
+ *     notes: { type: 'text', content: 'Focus on churn.' },
+ *   },
+ * })
  *
- * // Resume / inspect a session by id
- * const exec = await tela.agents.getSession('session-uuid')
- * const timeline = await tela.agents.getTimeline('session-uuid')
+ * // 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)
  * ```
  */
 declare class Agents {
+    /** The delegated agent-sdk client (the `/v4/*` execution backend). */
     private readonly client;
-    constructor(client: BaseClient);
+    /** The Tela gateway client (`/agent` discovery + vault upload). */
+    private readonly gateway;
+    /** Memoized `agentId` → `{ organizationName, repository }` resolutions. */
+    private readonly resolved;
     /**
-     * Lists the agents available in the workspace (optionally filtered by project).
+     * Streams a session's events. Pass-through to the agent-sdk client
+     * (`GET /v4/sessions/:id`).
      */
-    list(query?: ListAgentsQuery): Promise<AgentRecord[]>;
+    readonly streamSession: AgentClient['streamSession'];
     /**
-     * Fetches an agent by id and returns a handle for running it.
+     * Fetches the session timeline summary. Pass-through to the agent-sdk client
+     * (`GET /v4/sessions/:id/timeline`).
      */
-    get(agentId: string): Promise<Agent>;
+    readonly fetchTimeline: AgentClient['fetchTimeline'];
     /**
-     * Executes an agent by id without first fetching its record.
-     *
-     * Convenience shortcut equivalent to `(await get(id)).execute(params)` but
-     * skipping the metadata fetch. Defaults to the published version; pass
-     * `{ draft: true }` to run the draft.
+     * Cancels a running session. Pass-through to the agent-sdk client
+     * (`POST /v4/sessions/:id/cancel`).
      */
-    execute(agentId: string, params?: AgentExecuteParams): AgentExecutionPromiseLike;
+    readonly cancelSession: AgentClient['cancelSession'];
     /**
-     * Returns a resumable execution bound to an existing session id. Use it to
-     * monitor (`.stream` / `.result`), `.cancel()`, or `.recover()` a session
-     * that was started elsewhere.
+     * Resolves a `vault://` reference to bytes/stream/json. Pass-through to the
+     * agent-sdk client.
      */
-    getSession(sessionId: string): Promise<AgentExecution>;
+    readonly resolveReference: AgentClient['resolveReference'];
+    constructor(gateway: BaseClient, config: AgentsConfig);
     /**
-     * Fetches the session timeline summary (`GET /agent/sessions/:id/timeline`):
-     * duration, token/cost metrics, prompt, and spans.
+     * Lists the agents available in the workspace (optionally filtered by
+     * project) via the Tela gateway (`GET /agent`).
      */
-    getTimeline(sessionId: string): Promise<AgentTimeline>;
+    list(query?: ListAgentsQuery): Promise<AgentRecord[]>;
     /**
-     * Cancels a running session (`POST /agent/sessions/:id/cancel`).
+     * Fetches an agent record by id via the Tela gateway (`GET /agent/:id`).
      */
-    cancel(sessionId: string): Promise<{
-        success?: boolean;
-    }>;
+    get(agentId: string): Promise<AgentRecord>;
     /**
-     * Recovers a failed/terminal session and returns a resumable execution for
-     * the new turn.
+     * Starts (or continues) an agent session via the Tela gateway
+     * (`POST /agent/:id/run`).
+     *
+     * - **New session**: pass `agentId` (+ `message`).
+     * - **Continue**: pass `agentId` and the existing `sessionId`.
+     *
+     * 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.
      */
-    recover(sessionId: string): Promise<AgentExecution>;
+    run(params: RunAgentParams): Promise<RunAgentResponse>;
     /**
-     * Ends a session (`DELETE /agent/sessions/:id`), marking it finished.
+     * Updates an agent's model, delegating to the agent-sdk client
+     * (`PUT /v4/agents/:repository/model`). The `agentId` is resolved to the
+     * underlying repository first.
      */
-    endSession(sessionId: string): Promise<{
-        success?: boolean;
-    }>;
+    updateAgentModel(params: UpdateAgentModelParams): Promise<UpdateAgentModelResponse>;
+    /**
+     * Resolves an `agentId` to its `organizationName`/`repository`, memoizing the
+     * lookup. Backed by the Tela gateway `GET /agent/:id`.
+     */
+    private resolveAgent;
+    /**
+     * 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 resolveEntry;
 }
 
 /**
@@ -4656,6 +4498,20 @@ interface TelaSDKOptions extends Omit<BaseClientOptions, 'baseURL'> {
      * The base URL for the Tela API. Defaults to 'https://api.tela.com'.
      */
     baseURL?: string;
+    /**
+     * Base URL for the agent execution backend (the agent-sdk `/v4/*` service)
+     * that `tela.agents` delegates to. Defaults to `baseURL`.
+     *
+     * Set this to the reachable v4 service URL when it differs from the main Tela
+     * API host — the agent-sdk client calls fixed `/v4/agents` and `/v4/sessions`
+     * paths.
+     */
+    agentBaseURL?: string;
+    /**
+     * Vault service URL used by `tela.agents.resolveReference`. Defaults to
+     * `` `${baseURL}/_services/vault` ``.
+     */
+    vaultURL?: string;
 }
 /**
  * The main class for interacting with the Tela API.
@@ -4681,7 +4537,7 @@ declare class TelaSDK extends BaseClient {
     /**
      * Creates a new instance of the TelaSDK.
      */
-    constructor({ baseURL, apiKey, jwt, dataToken, ...rest }: TelaSDKOptions);
+    constructor({ baseURL, apiKey, jwt, dataToken, agentBaseURL, vaultURL, ...rest }: TelaSDKOptions);
     get authToken(): string;
     private validateAuth;
     protected getAuthHeaders(): Record<string, string>;
@@ -4751,13 +4607,18 @@ declare class TelaSDK extends BaseClient {
      */
     vault: Vault;
     /**
-     * Agents API resource for running agent sessions by `agentId` — execute,
-     * stream events, multi-turn, cancel — and reading session state.
+     * 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 agent = await tela.agents.get('agent-id')
-     * const result = await agent.execute({ prompt: 'Hello' }).result
+     * const { sessionId } = await tela.agents.run({
+     *   agentId: 'agent-id',
+     *   message: 'Hello',
+     * })
+     * for await (const event of await tela.agents.streamSession(sessionId))
+     *   console.log(event.kind)
      * ```
      */
     agents: Agents;
@@ -4819,4 +4680,4 @@ declare class TelaSDK extends BaseClient {
  */
 declare function createTelaClient(opts: TelaSDKOptions): TelaSDK;
 
-export { APIError, Agent, type AgentAttachment, type AgentExecuteParams, AgentExecution, type AgentExecutionEvents, AgentExecutionFailedError, type AgentExecutionPromiseLike, type AgentInputItem, type AgentInputVariable, type AgentRecord, type AgentSessionResult, type AgentStep, type AgentTimeline, Agents, 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 SchemaBuilder, 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, 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 };