@to11ai/sdk 0.6.0 → 0.8.1

package/src/prompts/resource.ts

@@ -104,12 +104,13 @@ export type {
 	RenderedPrompt,
 	ResolvedPrompt,
 	ResolvedPromptEnvelope,
+	ResolvedToolCall,
+	ResolvedToolDefinition,
 	ResolvePromptInput,
 	ResolvePromptResult,
 	RowError,
 	TextChatMessage,
 	TextChatRole,
-	ToolChatMessage,
 	UpdateProjectPromptLabelInput,
 	UpdateProjectPromptLabelResult,
 	UpdatePromptInput,
@@ -123,6 +124,8 @@ const zResolvedPromptLegacy = zResolvedPrompt.pick({
 	labels: true,
 	contentHash: true,
 	rendered: true,
+	tools: true,
+	toolChoice: true,
 });
 
 const zResolvedPromptEnvelope = zResolvedPrompt
@@ -178,6 +181,19 @@ function normalizeResolvedEnvelope(
 		labels: raw.labels,
 		rendered: raw.rendered,
 	};
+	// `tools` is present IFF the resolved version declares tool definitions; the
+	// wire may send `null` (or omit it) — normalize both to absent so callers
+	// can `?? []` once via the converters rather than guarding `null`.
+	if (raw.tools != null && raw.tools.length > 0) {
+		result.tools = raw.tools;
+	}
+	// `toolChoice` mirrors `tools`: present IFF the resolved version declares a
+	// directive. The wire may send `null` (or omit it); normalize both to absent
+	// so callers feed `toOpenAIToolChoice` / `toAnthropicToolChoice` (which map
+	// `null`/`undefined` → omit) without a separate guard.
+	if (raw.toolChoice != null) {
+		result.toolChoice = raw.toolChoice;
+	}
 	// Set `variantName` only when it is a non-empty string, so the key is
 	// genuinely absent for `single`-strategy releases (R5: present IFF weighted —
 	// never `null`, never `""`). A `null`/`""` from the wire is normalized to
@@ -477,6 +493,7 @@ export class PromptResource {
 			variables,
 			cache: useCache = true,
 			fallback,
+			developerRole,
 		} = options;
 
 		const cacheKey = buildFetchCacheKey(
@@ -486,6 +503,7 @@ export class PromptResource {
 			context,
 			subject,
 			variables,
+			developerRole,
 		);
 
 		if (useCache) {
@@ -500,6 +518,7 @@ export class PromptResource {
 		if (context !== undefined) body.context = context;
 		if (subject !== undefined) body.subject = subject;
 		if (variables !== undefined) body.variables = variables;
+		if (developerRole !== undefined) body.developerRole = developerRole;
 
 		try {
 			const envelope = await this.transport.request<ResolvedPromptEnvelope>(

package/src/prompts/types.ts

@@ -8,6 +8,8 @@ import type {
 	RenderedChatPrompt as GenRenderedChatPrompt,
 	RenderedPrompt as GenRenderedPrompt,
 	ResolvedPrompt as GenResolvedPrompt,
+	ResolvedToolCall as GenResolvedToolCall,
+	ResolvedToolDefinition as GenResolvedToolDefinition,
 } from "../generated/types.gen";
 
 export interface RowError {
@@ -30,23 +32,35 @@ export interface TextChatMessage {
 	disabled?: boolean;
 }
 
-export interface ToolChatMessage {
-	role: "tool";
-	name: string;
-	description?: string;
-	parameters: unknown;
-	disabled?: boolean;
-}
-
-export type ChatMessage = TextChatMessage | ToolChatMessage;
+export type ChatMessage = TextChatMessage;
 
 export type RenderedChatMessage = GenRenderedChatPrompt["messages"][number];
 
 export type RenderedPrompt = GenRenderedPrompt;
 
+/**
+ * A provider-neutral tool definition (`{ name, description?, parameters }`),
+ * sourced from authored tool-definition blocks. Surfaced on the resolved
+ * contract and shaped for a provider via `toOpenAITools` / `toAnthropicTools`.
+ */
+export type ResolvedToolDefinition = GenResolvedToolDefinition;
+
+/**
+ * A structured assistant tool call (`{ id, name, arguments }`) carried inline
+ * on a rendered `assistant` turn (few-shot multi-tool history).
+ */
+export type ResolvedToolCall = GenResolvedToolCall;
+
 export type ResolvedPrompt = Pick<
 	GenResolvedPrompt,
-	"promptId" | "versionId" | "version" | "labels" | "contentHash" | "rendered"
+	| "promptId"
+	| "versionId"
+	| "version"
+	| "labels"
+	| "contentHash"
+	| "rendered"
+	| "tools"
+	| "toolChoice"
 >;
 
 export interface PaginationInfo {
@@ -112,6 +126,9 @@ export interface CreatePromptVersionInput {
 	format: PromptFormat;
 	templateJson: unknown;
 	variablesSchema: unknown;
+	// TO11-2609: server-trusted, gating-only context schema (scalar/enum keys).
+	// Optional on write; omitted → no context keys.
+	contextSchema?: unknown;
 	modelConfig?: unknown;
 	changelog?: string;
 }
@@ -180,6 +197,22 @@ export interface FetchedPrompt {
 	contentHash: string;
 	labels: string[];
 	rendered: RenderedPrompt;
+	/**
+	 * Provider-neutral tool definitions lifted from authored tool-definition
+	 * blocks. Absent (rather than `[]`) when the resolved version declares no
+	 * tools. Shape for a provider with `toOpenAITools` / `toAnthropicTools`.
+	 */
+	tools?: ResolvedToolDefinition[];
+	/**
+	 * Provider-neutral tool-choice directive lifted from the resolved version.
+	 * Absent (rather than `null`) when the version declares none. Feed straight
+	 * into `toOpenAIToolChoice` / `toAnthropicToolChoice`.
+	 *
+	 * `NonNullable` because `normalizeResolvedEnvelope` maps wire-`null` to absent,
+	 * so a present `FetchedPrompt.toolChoice` is never `null` — callers get the
+	 * key or nothing, and never have to branch on `null`.
+	 */
+	toolChoice?: NonNullable<ResolvedPrompt["toolChoice"]>;
 }
 
 export type ResolvedPromptEnvelope = GenResolvedPrompt & {
@@ -187,6 +220,14 @@ export type ResolvedPromptEnvelope = GenResolvedPrompt & {
 	strategy?: "single" | "weighted";
 };
 
+/**
+ * How an authored `developer` block is rendered. The caller controls this
+ * per-call because it knows the upstream it targets. Omitted ⇒ `"user"`
+ * (back-compatible; safe for any upstream). `"developer"` preserves the role
+ * (OpenAI); `"system"` folds it into a system message.
+ */
+export type DeveloperRole = "user" | "developer" | "system";
+
 export interface FetchPromptOptions {
 	env?: string;
 	context?: PromptContext;
@@ -194,6 +235,12 @@ export interface FetchPromptOptions {
 	variables?: Record<string, unknown>;
 	cache?: boolean;
 	fallback?: ResolvedPrompt | FetchedPrompt;
+	/**
+	 * How authored `developer` blocks render. Default `"user"`. Forwarded on the
+	 * resolve request and folded into the cache key so two calls differing only
+	 * by `developerRole` never share a cached result.
+	 */
+	developerRole?: DeveloperRole;
 }
 
 export type PaletteToken = ProjectPromptLabel["displayColor"];