@to11ai/sdk 0.1.1 → 0.2.0

package/dist/projectEnvironments/resource.cjs

@@ -42,6 +42,8 @@ __export(exports_resource, {
   ProjectEnvironmentResource: () => ProjectEnvironmentResource
 });
 module.exports = __toCommonJS(exports_resource);
+var import_zod = require("zod");
+var import_zod2 = require("../generated/zod.gen");
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
     throw new Error("API returned success but data is null");
@@ -62,12 +64,15 @@ class ProjectEnvironmentResource {
   }
   async list(input) {
     const envelope = await this.transport.request("GET", projectEnvironmentsPath(input.projectId), {
-      query: input.includeArchived ? { includeArchived: "true" } : undefined
+      query: input.includeArchived ? { includeArchived: "true" } : undefined,
+      decode: (data) => import_zod.z.array(import_zod2.zProjectEnvironment).parse(data)
     });
     return unwrap(envelope);
   }
   async get(input) {
-    const envelope = await this.transport.request("GET", projectEnvironmentPath(input.projectId, input.slug));
+    const envelope = await this.transport.request("GET", projectEnvironmentPath(input.projectId, input.slug), {
+      decode: (data) => import_zod2.zProjectEnvironment.parse(data)
+    });
     return unwrap(envelope);
   }
   async create(input) {

package/dist/projectEnvironments/resource.js

@@ -1,4 +1,6 @@
 // src/projectEnvironments/resource.ts
+import { z } from "zod";
+import { zProjectEnvironment } from "../generated/zod.gen";
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
     throw new Error("API returned success but data is null");
@@ -19,12 +21,15 @@ class ProjectEnvironmentResource {
   }
   async list(input) {
     const envelope = await this.transport.request("GET", projectEnvironmentsPath(input.projectId), {
-      query: input.includeArchived ? { includeArchived: "true" } : undefined
+      query: input.includeArchived ? { includeArchived: "true" } : undefined,
+      decode: (data) => z.array(zProjectEnvironment).parse(data)
     });
     return unwrap(envelope);
   }
   async get(input) {
-    const envelope = await this.transport.request("GET", projectEnvironmentPath(input.projectId, input.slug));
+    const envelope = await this.transport.request("GET", projectEnvironmentPath(input.projectId, input.slug), {
+      decode: (data) => zProjectEnvironment.parse(data)
+    });
     return unwrap(envelope);
   }
   async create(input) {

package/dist/projectEnvironments/types.d.ts

@@ -1,62 +1,9 @@
-/**
- * Project-scoped environment row as returned by
- * `GET /v1/projects/:projectId/environments/:slug`.
- *
- * Notes:
- *  - `isSystem: true` for the seeded `prod` / `staging` rows. Those rows
- *    cannot be renamed, archived, or have their `slug`/`isSystem` mutated.
- *  - `isGatewayFallback: true` marks the env the gateway routes to when no
- *    `x-to11-env` header is supplied. At most one env per project may carry
- *    this flag; clearing the only fallback is rejected with 409
- *    `CANNOT_CLEAR_ONLY_GATEWAY_FALLBACK`.
- *  - `archivedAt` is `null` for live envs and an ISO-8601 timestamp for
- *    soft-archived ones.
- */
-export interface ProjectEnvironment {
-    id: string;
-    projectId: string;
-    slug: string;
-    name: string;
-    color: string | null;
-    description: string | null;
-    isPointer: boolean;
-    requiresApproval: boolean;
-    isDefault: boolean;
-    isGatewayFallback: boolean;
-    sortOrder: number;
-    isSystem: boolean;
-    archivedAt: string | null;
-    createdBy: string;
-    updatedBy: string;
-    createdAt: string;
-    updatedAt: string;
-}
-/**
- * Pointer-count payload attached to archive responses. `prompts` is real
- * today; `rules` / `providers` are 0 in v1 (reserved for Wave 6+ specs to
- * keep the response shape stable when those domains land).
- */
-export interface LivePointerCounts {
-    prompts: number;
-    rules: number;
-    providers: number;
-}
-/**
- * Response body for `POST /v1/projects/:projectId/environments/:slug/archive`.
- * Carries the soft-archived environment plus the count of live pointers
- * cascade-cleared by the archive operation (informational, for the
- * confirmation modal in the web UI).
- */
-export interface ArchiveProjectEnvironmentResult {
-    environment: ProjectEnvironment;
-    livePointerCounts: LivePointerCounts;
-}
+import type { ArchiveProjectEnvironmentResult as GenArchiveProjectEnvironmentResult, LivePointerCounts as GenLivePointerCounts, ProjectEnvironment as GenProjectEnvironment } from "../generated/types.gen";
+export type ProjectEnvironment = GenProjectEnvironment;
+export type LivePointerCounts = GenLivePointerCounts;
+export type ArchiveProjectEnvironmentResult = GenArchiveProjectEnvironmentResult;
 export interface ListProjectEnvironmentsInput {
     projectId: string;
-    /**
-     * When `true`, the response includes archived envs (those with a
-     * non-null `archivedAt`). Default behavior excludes them.
-     */
     includeArchived?: boolean;
 }
 export type ListProjectEnvironmentsResult = ProjectEnvironment[];
@@ -65,15 +12,6 @@ export interface GetProjectEnvironmentInput {
     slug: string;
 }
 export type GetProjectEnvironmentResult = ProjectEnvironment;
-/**
- * Create input — must specify a unique `slug` matching lowercase-kebab
- * (a-z, 0-9, hyphen, 1..63 chars). Reserved system slugs (`prod`,
- * `staging`) are rejected by the API with `ENVIRONMENT_SLUG_TAKEN`.
- *
- * Setting `isGatewayFallback: true` here additionally requires the
- * `project:manage_default_environment` capability; the create use case
- * atomically clears the flag on any other env in the same project.
- */
 export interface CreateProjectEnvironmentInput {
     projectId: string;
     slug: string;
@@ -87,15 +25,6 @@ export interface CreateProjectEnvironmentInput {
     sortOrder?: number;
 }
 export type CreateProjectEnvironmentResult = ProjectEnvironment;
-/**
- * PATCH input — every field is optional. `slug` rename triggers a 7-day
- * alias row server-side. System envs (`isSystem: true`) reject `slug`,
- * `isSystem`, and other immutable-field mutations with
- * `SYSTEM_ENV_IMMUTABLE`.
- *
- * As with `create`, mutating `isGatewayFallback` requires the additional
- * `project:manage_default_environment` capability.
- */
 export interface UpdateProjectEnvironmentInput {
     projectId: string;
     slug: string;

package/dist/prompts/cache.d.ts

@@ -1,10 +1,15 @@
-import type { ResolvedPrompt } from "./types";
+import type { FetchedPrompt, PromptContext, ResolvedPrompt } from "./types";
 export interface CacheConfig {
     /** Time-to-live in seconds. Default: 300 (5 minutes) */
     ttlSeconds?: number;
     /** Maximum number of entries. Default: 100 */
     maxEntries?: number;
 }
+/**
+ * The cache stores either a legacy `resolve()` result or an enriched
+ * `fetch()` result. Both are JSON-cloneable; the cache is shape-agnostic.
+ */
+export type CacheableResolved = ResolvedPrompt | FetchedPrompt;
 /**
  * Build a canonical cache key for a resolve() call.
  *
@@ -18,6 +23,22 @@ export interface CacheConfig {
  *   values cannot cause key collisions (e.g. a slug containing "|" or ",").
  */
 export declare function buildCacheKey(projectId: string, slug: string, labels: string[], variables?: Record<string, unknown>): string;
+/**
+ * Build a cache key for an env-aware `fetch()` call.
+ *
+ * Folds in `env`, `context`, and `subject` ON TOP of the base
+ * project/slug/labels/variables key so two calls that differ only by
+ * env/context/subject do not return a stale cross-env / cross-cohort hit
+ * (spec §3 "Caching key changes"). The env slug is also forwarded as the
+ * single resolution label (env→label mapping, correction #3), so it appears
+ * in the `labels` segment too; including it explicitly here keeps the key
+ * unambiguous and self-documenting.
+ *
+ * `subject` participates in the key so a `subject`-keyed weighted assignment
+ * caches as the same deterministic variant on repeat (D8); the
+ * weighted-no-subject bypass is handled in the resource, not here.
+ */
+export declare function buildFetchCacheKey(projectId: string, slug: string, env: string, context?: PromptContext, subject?: string, variables?: Record<string, unknown>): string;
 /**
  * In-memory LRU cache for ResolvedPrompt objects.
  *
@@ -30,8 +51,8 @@ export declare class PromptCache {
     private readonly maxEntries;
     private readonly store;
     constructor(config?: CacheConfig);
-    get(key: string): ResolvedPrompt | undefined;
-    set(key: string, value: ResolvedPrompt): void;
+    get(key: string): CacheableResolved | undefined;
+    set(key: string, value: CacheableResolved): void;
     delete(key: string): void;
     clear(): void;
     get size(): number;

package/dist/prompts/resource.cjs

@@ -42,8 +42,20 @@ __export(exports_resource, {
   PromptResource: () => PromptResource
 });
 module.exports = __toCommonJS(exports_resource);
+var import_zod = require("zod");
 var import_errors = require("../errors");
+var import_zod2 = require("../generated/zod.gen");
 var import_cache = require("./cache");
+var import_types = require("./types");
+var zResolvedPromptLegacy = import_zod2.zResolvedPrompt.pick({
+  promptId: true,
+  versionId: true,
+  version: true,
+  labels: true,
+  contentHash: true,
+  rendered: true
+});
+var zResolvedPromptEnvelope = import_zod2.zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: import_zod.z.enum(["single", "weighted"]).optional() });
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
     throw new Error("API returned success but data is null");
@@ -53,6 +65,36 @@ function unwrap(envelope) {
 function getProjectPromptsPath(projectId) {
   return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
 }
+function renderedToMessages(rendered) {
+  if (rendered.format === "chat") {
+    return rendered.messages;
+  }
+  return [{ role: "user", content: rendered.text }];
+}
+function normalizeResolvedEnvelope(raw) {
+  const provenance = raw;
+  const result = {
+    messages: renderedToMessages(raw.rendered),
+    version: raw.version,
+    releaseId: provenance.releaseId ?? null,
+    blockRenderRecord: provenance.blockRenderRecord ?? {},
+    promptId: raw.promptId,
+    versionId: raw.versionId,
+    contentHash: raw.contentHash,
+    labels: raw.labels,
+    rendered: raw.rendered
+  };
+  if (typeof provenance.variantName === "string" && provenance.variantName.length > 0) {
+    result.variantName = provenance.variantName;
+  }
+  return result;
+}
+function liftFallbackToFetched(fallback) {
+  if ("messages" in fallback) {
+    return structuredClone(fallback);
+  }
+  return normalizeResolvedEnvelope(fallback);
+}
 function getProjectPromptPath(projectId, promptId) {
   return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
 }
@@ -87,9 +129,13 @@ function buildLabelEventsQuery(input) {
 class PromptResource {
   transport;
   cache;
-  constructor(transport, cacheConfig) {
+  projectId;
+  env;
+  constructor(transport, cacheConfig, config) {
     this.transport = transport;
     this.cache = new import_cache.PromptCache(cacheConfig);
+    this.projectId = config?.projectId;
+    this.env = config?.env;
   }
   async create(input) {
     const { projectId, ...body } = input;
@@ -153,6 +199,57 @@ class PromptResource {
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
     return unwrap(envelope);
   }
+  async fetch(slug, options = {}) {
+    if (this.projectId === undefined || this.projectId.trim() === "") {
+      throw new Error("[to11ai/sdk] `prompts.fetch()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).");
+    }
+    const env = options.env ?? this.env;
+    if (env === undefined) {
+      throw import_errors.EnvNotFoundError.missing();
+    }
+    if (!import_types.ENV_SLUG_REGEX.test(env)) {
+      throw new Error(`[to11ai/sdk] \`env\` must match ${import_types.ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`);
+    }
+    const {
+      context,
+      subject,
+      variables,
+      cache: useCache = true,
+      fallback
+    } = options;
+    const cacheKey = import_cache.buildFetchCacheKey(this.projectId, slug, env, context, subject, variables);
+    if (useCache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached && "messages" in cached)
+        return structuredClone(cached);
+    }
+    const body = { slug, labels: [env] };
+    if (context !== undefined)
+      body.context = context;
+    if (subject !== undefined)
+      body.subject = subject;
+    if (variables !== undefined)
+      body.variables = variables;
+    try {
+      const envelope = await this.transport.request("POST", `${getProjectPromptsPath(this.projectId)}:resolve`, {
+        body,
+        decode: (data) => zResolvedPromptEnvelope.parse(data)
+      });
+      const raw = unwrap(envelope);
+      const result = normalizeResolvedEnvelope(raw);
+      const isWeighted = raw.strategy === "weighted" || result.variantName !== undefined;
+      const cacheable = !(isWeighted && subject === undefined);
+      if (useCache && cacheable) {
+        this.cache.set(cacheKey, structuredClone(result));
+      }
+      return result;
+    } catch (err) {
+      if (err instanceof import_errors.To11aiNetworkError && fallback !== undefined) {
+        return liftFallbackToFetched(fallback);
+      }
+      throw err;
+    }
+  }
   async resolve(input) {
     const {
       projectId,
@@ -165,12 +262,13 @@ class PromptResource {
     const cacheKey = import_cache.buildCacheKey(projectId, slug, labels, variables);
     if (useCache) {
       const cached = this.cache.get(cacheKey);
-      if (cached)
+      if (cached && !("messages" in cached))
         return structuredClone(cached);
     }
     try {
       const envelope = await this.transport.request("POST", `${getProjectPromptsPath(projectId)}:resolve`, {
-        body: { slug, labels, variables }
+        body: { slug, labels, variables },
+        decode: (data) => zResolvedPromptLegacy.parse(data)
       });
       const result = unwrap(envelope);
       if (useCache) {

package/dist/prompts/resource.d.ts

@@ -1,12 +1,27 @@
 import type { Transport } from "../transport";
 import type { CacheConfig } from "./cache";
-import type { ArchivePromptInput, ArchivePromptResult, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, ResolvePromptInput, ResolvePromptResult, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult } from "./types";
+import type { ArchivePromptInput, ArchivePromptResult, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, FetchedPrompt, FetchPromptOptions, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, ResolvePromptInput, ResolvePromptResult, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult } from "./types";
 export type { CacheConfig } from "./cache";
-export type { ArchivePromptInput, ArchivePromptResult, ChatMessage, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, PaginationInfo, PaletteToken, ProjectPromptLabel, ProjectPromptLabelUsage, Prompt, PromptFormat, PromptLabelEvent, PromptLabelPointer, PromptStatus, PromptVersion, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvePromptInput, ResolvePromptResult, RowError, TextChatMessage, TextChatRole, ToolChatMessage, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult, } from "./types";
+export type { ArchivePromptInput, ArchivePromptResult, BlockRenderRecord, ChatMessage, CreateProjectPromptLabelInput, CreateProjectPromptLabelResult, CreatePromptInput, CreatePromptResult, CreatePromptVersionInput, CreatePromptVersionResult, DeleteProjectPromptLabelInput, DeleteProjectPromptLabelResult, FetchedPrompt, FetchPromptOptions, GetProjectPromptLabelInput, GetProjectPromptLabelResult, GetPromptInput, GetPromptResult, GetPromptVersionInput, GetPromptVersionResult, ListLabelEventsInput, ListLabelEventsResult, ListProjectPromptLabelsInput, ListProjectPromptLabelsResult, ListProjectPromptLabelUsagesInput, ListProjectPromptLabelUsagesResult, ListPromptLabelsInput, ListPromptLabelsResult, ListPromptsInput, ListPromptsResult, ListPromptVersionsInput, ListPromptVersionsResult, MovePromptLabelInput, MovePromptLabelResult, PaginatedResult, PaginationInfo, PaletteToken, ProjectPromptLabel, ProjectPromptLabelUsage, Prompt, PromptContext, PromptFormat, PromptLabelEvent, PromptLabelPointer, PromptStatus, PromptVersion, RenderedChatMessage, RenderedPrompt, ResolvedPrompt, ResolvedPromptEnvelope, ResolvePromptInput, ResolvePromptResult, RowError, TextChatMessage, TextChatRole, ToolChatMessage, UpdateProjectPromptLabelInput, UpdateProjectPromptLabelResult, UpdatePromptInput, UpdatePromptResult, } from "./types";
+/**
+ * Init-time config for the env-aware `fetch()` surface (TO11-980 / S9).
+ *
+ * `projectId` and `env` come from `createClient`. `projectId` is required for
+ * `fetch()` (it builds the project-scoped resolve path); `env` is the default
+ * serving environment inherited by every `fetch(slug)` call.
+ */
+export interface PromptResourceConfig {
+    /** Project the client is bound to. Required for `fetch()`; validated at createClient. */
+    projectId?: string;
+    /** Default serving env for `fetch()`. Validated against ENV_SLUG_REGEX at createClient. */
+    env?: string;
+}
 export declare class PromptResource {
     private readonly transport;
     private readonly cache;
-    constructor(transport: Transport, cacheConfig?: CacheConfig);
+    private readonly projectId;
+    private readonly env;
+    constructor(transport: Transport, cacheConfig?: CacheConfig, config?: PromptResourceConfig);
     create(input: CreatePromptInput): Promise<CreatePromptResult>;
     list(input: ListPromptsInput): Promise<PaginatedResult<ListPromptsResult>>;
     get(input: GetPromptInput): Promise<GetPromptResult>;
@@ -17,6 +32,35 @@ export declare class PromptResource {
     getVersion(input: GetPromptVersionInput): Promise<GetPromptVersionResult>;
     moveLabel(input: MovePromptLabelInput): Promise<MovePromptLabelResult>;
     listLabels(input: ListPromptLabelsInput): Promise<ListPromptLabelsResult>;
+    /**
+     * Resolve a prompt for the client's configured `projectId` + `env`
+     * (Style-A). The ergonomic slug-first surface: env is configured once at
+     * `createClient` and inherited here, with an optional per-call override.
+     *
+     * - **env→label wire mapping (correction #3):** the resolve route is
+     *   label-based (`/v1/projects/:projectId/prompts:resolve`, body
+     *   `labels[]`); it does NOT accept a top-level `env` field. The resolved
+     *   env slug (lowercase-kebab — a valid label name) is therefore sent as
+     *   the single resolution label: body `{ slug, labels: [env], context?,
+     *   subject?, variables? }`.
+     * - **No silent fallback (R4):** if no env is resolvable (none at init AND
+     *   none per call) this throws `EnvNotFoundError` (`reason.source =
+     *   "missing"`) CLIENT-side, eagerly, before any transport call.
+     * - **Cache (D8):** caches `single`-strategy releases and weighted releases
+     *   WITH a `subject`; BYPASSES the cache for weighted releases with NO
+     *   `subject` (a uniform-random assignment must not be pinned for the TTL).
+     *
+     * Prefer this over the deprecated `resolve()`.
+     */
+    fetch(slug: string, options?: FetchPromptOptions): Promise<FetchedPrompt>;
+    /**
+     * @deprecated Use {@link PromptResource.fetch | `prompts.fetch(slug,
+     * options?)`} instead. `resolve()` is env-agnostic (no `env` / `context` /
+     * `subject`, no enriched release/variant provenance, no typed-env errors)
+     * and is retained only for back-compat. It is NOT subject to the R4
+     * no-silent-fallback env gate (it has no env concept). New code should
+     * configure `projectId` + `env` at `createClient` and call `fetch()`.
+     */
     resolve(input: ResolvePromptInput): Promise<ResolvePromptResult>;
     /**
      * List the project-level label registry.

package/dist/prompts/resource.js

@@ -1,6 +1,18 @@
 // src/prompts/resource.ts
-import { To11aiNetworkError } from "../errors";
-import { buildCacheKey, PromptCache } from "./cache";
+import { z } from "zod";
+import { EnvNotFoundError, To11aiNetworkError } from "../errors";
+import { zResolvedPrompt } from "../generated/zod.gen";
+import { buildCacheKey, buildFetchCacheKey, PromptCache } from "./cache";
+import { ENV_SLUG_REGEX } from "./types";
+var zResolvedPromptLegacy = zResolvedPrompt.pick({
+  promptId: true,
+  versionId: true,
+  version: true,
+  labels: true,
+  contentHash: true,
+  rendered: true
+});
+var zResolvedPromptEnvelope = zResolvedPrompt.partial({ releaseId: true }).extend({ strategy: z.enum(["single", "weighted"]).optional() });
 function unwrap(envelope) {
   if (envelope.data === null || envelope.data === undefined) {
     throw new Error("API returned success but data is null");
@@ -10,6 +22,36 @@ function unwrap(envelope) {
 function getProjectPromptsPath(projectId) {
   return `/v1/projects/${encodeURIComponent(projectId)}/prompts`;
 }
+function renderedToMessages(rendered) {
+  if (rendered.format === "chat") {
+    return rendered.messages;
+  }
+  return [{ role: "user", content: rendered.text }];
+}
+function normalizeResolvedEnvelope(raw) {
+  const provenance = raw;
+  const result = {
+    messages: renderedToMessages(raw.rendered),
+    version: raw.version,
+    releaseId: provenance.releaseId ?? null,
+    blockRenderRecord: provenance.blockRenderRecord ?? {},
+    promptId: raw.promptId,
+    versionId: raw.versionId,
+    contentHash: raw.contentHash,
+    labels: raw.labels,
+    rendered: raw.rendered
+  };
+  if (typeof provenance.variantName === "string" && provenance.variantName.length > 0) {
+    result.variantName = provenance.variantName;
+  }
+  return result;
+}
+function liftFallbackToFetched(fallback) {
+  if ("messages" in fallback) {
+    return structuredClone(fallback);
+  }
+  return normalizeResolvedEnvelope(fallback);
+}
 function getProjectPromptPath(projectId, promptId) {
   return `${getProjectPromptsPath(projectId)}/${encodeURIComponent(promptId)}`;
 }
@@ -44,9 +86,13 @@ function buildLabelEventsQuery(input) {
 class PromptResource {
   transport;
   cache;
-  constructor(transport, cacheConfig) {
+  projectId;
+  env;
+  constructor(transport, cacheConfig, config) {
     this.transport = transport;
     this.cache = new PromptCache(cacheConfig);
+    this.projectId = config?.projectId;
+    this.env = config?.env;
   }
   async create(input) {
     const { projectId, ...body } = input;
@@ -110,6 +156,57 @@ class PromptResource {
     const envelope = await this.transport.request("GET", `${getProjectPromptPath(projectId, promptId)}/labels`);
     return unwrap(envelope);
   }
+  async fetch(slug, options = {}) {
+    if (this.projectId === undefined || this.projectId.trim() === "") {
+      throw new Error("[to11ai/sdk] `prompts.fetch()` requires a `projectId` on the client — pass it to createClient({ projectId, ... }).");
+    }
+    const env = options.env ?? this.env;
+    if (env === undefined) {
+      throw EnvNotFoundError.missing();
+    }
+    if (!ENV_SLUG_REGEX.test(env)) {
+      throw new Error(`[to11ai/sdk] \`env\` must match ${ENV_SLUG_REGEX} (lowercase-kebab, 1-63 chars). Received: ${JSON.stringify(env)}`);
+    }
+    const {
+      context,
+      subject,
+      variables,
+      cache: useCache = true,
+      fallback
+    } = options;
+    const cacheKey = buildFetchCacheKey(this.projectId, slug, env, context, subject, variables);
+    if (useCache) {
+      const cached = this.cache.get(cacheKey);
+      if (cached && "messages" in cached)
+        return structuredClone(cached);
+    }
+    const body = { slug, labels: [env] };
+    if (context !== undefined)
+      body.context = context;
+    if (subject !== undefined)
+      body.subject = subject;
+    if (variables !== undefined)
+      body.variables = variables;
+    try {
+      const envelope = await this.transport.request("POST", `${getProjectPromptsPath(this.projectId)}:resolve`, {
+        body,
+        decode: (data) => zResolvedPromptEnvelope.parse(data)
+      });
+      const raw = unwrap(envelope);
+      const result = normalizeResolvedEnvelope(raw);
+      const isWeighted = raw.strategy === "weighted" || result.variantName !== undefined;
+      const cacheable = !(isWeighted && subject === undefined);
+      if (useCache && cacheable) {
+        this.cache.set(cacheKey, structuredClone(result));
+      }
+      return result;
+    } catch (err) {
+      if (err instanceof To11aiNetworkError && fallback !== undefined) {
+        return liftFallbackToFetched(fallback);
+      }
+      throw err;
+    }
+  }
   async resolve(input) {
     const {
       projectId,
@@ -122,12 +219,13 @@ class PromptResource {
     const cacheKey = buildCacheKey(projectId, slug, labels, variables);
     if (useCache) {
       const cached = this.cache.get(cacheKey);
-      if (cached)
+      if (cached && !("messages" in cached))
         return structuredClone(cached);
     }
     try {
       const envelope = await this.transport.request("POST", `${getProjectPromptsPath(projectId)}:resolve`, {
-        body: { slug, labels, variables }
+        body: { slug, labels, variables },
+        decode: (data) => zResolvedPromptLegacy.parse(data)
       });
       const result = unwrap(envelope);
       if (useCache) {