@proteos/sdk 0.54.1 → 0.55.0

package/src/agent/index.ts

@@ -1,6 +1,7 @@
 import type { ProteosClient } from '../client.js'
 import { type AgentService, AgentServiceImpl } from './agents.js'
 import { type McpServerService, McpServerServiceImpl } from './mcp-servers.js'
+import { type ModelService, ModelServiceImpl } from './models.js'
 import { type PromptService, PromptServiceImpl } from './prompts.js'
 import { type SessionService, SessionServiceImpl } from './sessions.js'
 import { type SkillService, SkillServiceImpl } from './skills.js'
@@ -12,7 +13,8 @@ import { type ToolsetService, ToolsetServiceImpl } from './toolsets.js'
  *
  * Manages the AI-agent configuration domain: Agents, Prompts (versioned),
  * Skills (versioned bundles), Tools, and MCP Servers — all org-scoped and keyed
- * by an immutable kebab-case `key`.
+ * by an immutable kebab-case `key` — plus the stateless model calls
+ * (`models.generate`, `models.decide`) and chat sessions.
  *
  * @example
  * ```ts
@@ -23,6 +25,15 @@ import { type ToolsetService, ToolsetServiceImpl } from './toolsets.js'
  *
  * const agents = await agent.agents.list().all();
  * const prompt = await agent.prompts.get('revenue-brief');
+ *
+ * const { answers } = await agent.models.decide({
+ *   state: { message: 'My card was charged twice!' },
+ *   questions: {
+ *     refund_requested: { type: 'boolean', instructions: 'Does the customer ask for money back?' },
+ *     topic: { type: 'choice', instructions: 'Topic?', criteria: { billing: 'charges', other: 'else' } },
+ *   },
+ * });
+ * if (answers.topic.confidence > 0.8) route(answers.topic.choice);
  * ```
  */
 export class AgentClient {
@@ -38,6 +49,8 @@ export class AgentClient {
   readonly toolsets: ToolsetService
   /** Service for managing MCP server registrations. */
   readonly mcpServers: McpServerService
+  /** Service for stateless model calls: `generate` (one message out) and `decide` (calibrated typed answers). */
+  readonly models: ModelService
   /** Service for managing chat sessions (conversations + event log + stream). */
   readonly sessions: SessionService
 
@@ -53,6 +66,7 @@ export class AgentClient {
     this.tools = new ToolServiceImpl(client)
     this.toolsets = new ToolsetServiceImpl(client)
     this.mcpServers = new McpServerServiceImpl(client)
+    this.models = new ModelServiceImpl(client)
     this.sessions = new SessionServiceImpl(client)
   }
 }
@@ -60,6 +74,28 @@ export class AgentClient {
 // Re-export service interfaces
 export type { AgentService } from './agents.js'
 export type { McpServerService } from './mcp-servers.js'
+// Re-export model-call types (generate + decide)
+export type {
+  BooleanAnswer,
+  BooleanCriteria,
+  BooleanQuestion,
+  ChoiceAnswer,
+  ChoiceQuestion,
+  DecideRequest,
+  DecisionAnswer,
+  DecisionAnswerFor,
+  DecisionQuestion,
+  DecisionQuestions,
+  DecisionQuestionType,
+  DecisionResult,
+  GenerateRequest,
+  GenerationResult,
+  ModelStopReason,
+  ScoreAnswer,
+  ScoreQuestion,
+  StructuredText,
+} from './model-types.js'
+export type { ModelService } from './models.js'
 export type { PromptService } from './prompts.js'
 // Re-export session types
 export type {
@@ -110,12 +146,14 @@ export type {
   CreateMcpServerRequest,
   CreatePromptRequest,
   CreateToolRequest,
+  CreateToolsetRequest,
   DependentAgent,
   DependentSyncResult,
   ListAgentsOptions,
   ListMcpServersOptions,
   ListPromptsOptions,
   ListSkillsOptions,
+  ListToolsetsOptions,
   ListToolsOptions,
   McpBinding,
   McpConnectionState,
@@ -125,25 +163,23 @@ export type {
   McpServerOAuth,
   McpToolSummary,
   ModelConfig,
+  PlatformBinding,
   Prompt,
   PromptVersion,
+  QueryBinding,
   Skill,
   SkillBundle,
   SkillVersion,
   StartMcpOAuthResponse,
-  PlatformBinding,
-  QueryBinding,
   Tool,
   ToolBinding,
   ToolKind,
   Toolset,
   ToolsetKind,
   ToolsetToolSummary,
-  CreateToolsetRequest,
-  UpdateToolsetRequest,
-  ListToolsetsOptions,
   UpdateAgentRequest,
   UpdateMcpServerRequest,
   UpdatePromptRequest,
   UpdateToolRequest,
+  UpdateToolsetRequest,
 } from './types.js'

package/src/agent/model-types.ts

@@ -0,0 +1,193 @@
+/**
+ * Types for the stateless model endpoints of the Proteos Agent Service API —
+ * `POST /agents/v1/models/generate` and `POST /agents/v1/models/decide`.
+ *
+ * Hand-written mirror of the Go models in `go.proteos.ai/model/agent`
+ * (`generation.go`, `decision.go` + `api/generation-requests.go`,
+ * `api/decision-requests.go`). Field names match the snake_case wire format
+ * exactly, including enum values.
+ */
+
+import type { ContentBlock, ModelUsage, TextBlock } from './session-types.js'
+import type { ModelConfig } from './types.js'
+
+// ---------------------------------------------------------------------------
+// Generation (one message out)
+// ---------------------------------------------------------------------------
+
+/**
+ * Why the model stopped generating. An open string so a new provider reason
+ * never breaks decoding; the key distinction is `end_turn` (complete) vs
+ * `max_tokens` (truncated).
+ */
+export type ModelStopReason = 'end_turn' | 'max_tokens' | 'stop_sequence' | (string & {})
+
+/**
+ * Body of `POST /agents/v1/models/generate` — a single, stateless model call:
+ * content blocks in, one assistant message out. No event log, no tools, no
+ * multi-turn state.
+ */
+export interface GenerateRequest {
+  /** Model id + sampling knobs. Omitted (or an empty `model_id`) resolves to the service default. */
+  model?: Partial<ModelConfig>
+  /** Optional system prompt steering the response. */
+  system?: string
+  /** The message body the model answers — text and file blocks (a file-only body is valid). */
+  content: ContentBlock[]
+  /**
+   * JSON Schema of the structured reply. When set, generation is forced through a
+   * schema-constrained tool and the structured value comes back as `output`.
+   */
+  output_schema?: Record<string, unknown>
+}
+
+/** The assistant's reply to a {@link GenerateRequest}. */
+export interface GenerationResult {
+  /** The returned text blocks (usually empty on a schema-constrained call). */
+  content: TextBlock[]
+  stop_reason?: ModelStopReason
+  /** The model that produced the reply (resolved id). */
+  model_id: string
+  usage: ModelUsage
+  /** The structured value of a schema-constrained generation; absent otherwise. */
+  output?: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Decisions (typed, calibrated answers out — no prose)
+// ---------------------------------------------------------------------------
+
+/**
+ * The text shape a decision provider reads: a string, a JSON object, or an
+ * array — never `null`, a number, or a boolean. Carries the state under
+ * judgment, a question's instructions, every criteria description, and the
+ * legend echoed back on a score. Structure passes through verbatim, so
+ * instructions can be structured guidance (named fields such as `what` /
+ * `not_for` / `examples`, backtick paths into the state like
+ * `` `ticket.messages[0].text` ``).
+ */
+export type StructuredText = string | Record<string, unknown> | unknown[]
+
+/** Discriminates a {@link DecisionQuestion} and its {@link DecisionAnswer}. */
+export type DecisionQuestionType = 'boolean' | 'choice' | 'score'
+
+/** Describes the two outcomes of a {@link BooleanQuestion}. */
+export interface BooleanCriteria {
+  true: StructuredText
+  false: StructuredText
+}
+
+/**
+ * "Is this statement true?" — answered with the calibrated probability that it
+ * is. `criteria` optionally spells out what makes the statement hold (true) or
+ * not (false) when the boundary is subtle.
+ */
+export interface BooleanQuestion {
+  type: 'boolean'
+  instructions: StructuredText
+  criteria?: BooleanCriteria
+}
+
+/**
+ * "Which one of these?" — `criteria` maps each option name to its description;
+ * options are unordered. Option-count limits are the provider's.
+ */
+export interface ChoiceQuestion<Option extends string = string> {
+  type: 'choice'
+  instructions: StructuredText
+  criteria: Record<Option, StructuredText>
+}
+
+/**
+ * "Where on this scale?" — `criteria` is the ordered list of level
+ * descriptions; the level number is the position (0-based). Every level must
+ * be described. Level-count limits are the provider's.
+ */
+export interface ScoreQuestion {
+  type: 'score'
+  instructions: StructuredText
+  criteria: StructuredText[]
+}
+
+/** One atomic question over the shared state, discriminated by `type`. */
+export type DecisionQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion
+
+/** Caller-keyed questions; answers come back under the same keys. */
+export type DecisionQuestions = Record<string, DecisionQuestion>
+
+/**
+ * Body of `POST /agents/v1/models/decide` — one text-only state and a map of
+ * atomic questions answered in parallel with calibrated probabilities.
+ *
+ * Only `model.model_id` is meaningful for a decision; the sampling knobs of
+ * {@link ModelConfig} are rejected with `invalid_decision_request`.
+ */
+export interface DecideRequest<Questions extends DecisionQuestions = DecisionQuestions> {
+  model?: Partial<Pick<ModelConfig, 'model_id'>>
+  state: StructuredText
+  questions: Questions
+}
+
+/**
+ * Answer to a {@link BooleanQuestion}: `probability` is P(true); `boolean` is
+ * the argmax (probability > 0.5); `confidence` is |2p − 1|.
+ */
+export interface BooleanAnswer {
+  type: 'boolean'
+  boolean: boolean
+  probability: number
+  confidence: number
+}
+
+/**
+ * Answer to a {@link ChoiceQuestion}: `choice` is the highest-probability
+ * option; `probabilities` is the full distribution keyed by option name.
+ */
+export interface ChoiceAnswer<Option extends string = string> {
+  type: 'choice'
+  choice: Option
+  probabilities: Record<Option, number>
+  confidence: number
+}
+
+/**
+ * Answer to a {@link ScoreQuestion}: `score` is the probability-weighted mean
+ * of the level numbers (so it can fall between levels); `legend` echoes the
+ * level descriptions and `probabilities` the distribution, both indexed by
+ * level.
+ */
+export interface ScoreAnswer {
+  type: 'score'
+  score: number
+  legend: StructuredText[]
+  probabilities: number[]
+  confidence: number
+}
+
+/**
+ * The calibrated answer to one question, discriminated by `type`. Every
+ * variant carries `confidence` = (n·peak − 1)/(n − 1) over its distribution,
+ * so gating code can threshold without switching on the type.
+ */
+export type DecisionAnswer = BooleanAnswer | ChoiceAnswer | ScoreAnswer
+
+/** The answer type a given question produces (drives typed `answers`). */
+export type DecisionAnswerFor<Question extends DecisionQuestion> = Question extends BooleanQuestion
+  ? BooleanAnswer
+  : Question extends ChoiceQuestion<infer Option>
+    ? ChoiceAnswer<Option>
+    : Question extends ScoreQuestion
+      ? ScoreAnswer
+      : never
+
+/**
+ * The provider's reply to a {@link DecideRequest}: one answer per question key
+ * (typed from the questions you sent), the model that produced them, and token
+ * usage.
+ */
+export interface DecisionResult<Questions extends DecisionQuestions = DecisionQuestions> {
+  /** The model that produced the answers (resolved id, e.g. `jev-1.13.0`). */
+  model_id: string
+  answers: { [Key in keyof Questions]: DecisionAnswerFor<Questions[Key]> }
+  usage: ModelUsage
+}

package/src/agent/models.ts

@@ -0,0 +1,67 @@
+import type { ProteosClient } from '../client.js'
+import type {
+  DecideRequest,
+  DecisionQuestions,
+  DecisionResult,
+  GenerateRequest,
+  GenerationResult,
+} from './model-types.js'
+
+const MODELS_BASE_PATH = '/agents/v1/models'
+
+/**
+ * Service for the stateless model calls — one request in, one reply out, no
+ * session, no event log:
+ *
+ * - `generate` — free text or schema-constrained structured output from an LLM.
+ * - `decide` — calibrated typed answers (boolean | choice | score) with
+ *   probabilities and confidence, for snap judgments inside code paths
+ *   (routing, triage, classification, gates). No prose comes back; compose the
+ *   answers in code and threshold on `confidence`.
+ *
+ * Both need the `agent-sessions:write` permission.
+ */
+export interface ModelService {
+  /**
+   * Runs a single model call and returns the assistant message.
+   * @throws {ProteosError} 400 `invalid_generation_request` / `unsupported_file_type` /
+   *   `model_provider_rejected_request`; 429 `model_provider_rate_limited`;
+   *   502 `model_provider_failed`.
+   */
+  generate(request: GenerateRequest): Promise<GenerationResult>
+  /**
+   * Answers typed questions about a text state with calibrated probabilities.
+   * `answers` is typed from the `questions` you pass, so
+   * `result.answers.topic.choice` narrows to the option names you declared.
+   *
+   * Semantic limits (option / level counts, empty questions, unknown model ids)
+   * are the provider's and surface as `decision_provider_rejected_request` with
+   * its message.
+   * @throws {ProteosError} 400 `invalid_decision_request` (shape) /
+   *   `decision_provider_rejected_request` (provider rule); 429
+   *   `decision_provider_rate_limited`; 502 `decision_provider_failed` /
+   *   `decision_provider_invalid_response`; 503 `decision_provider_unavailable`
+   *   when the provider key is not configured.
+   */
+  decide<Questions extends DecisionQuestions>(
+    request: DecideRequest<Questions>,
+  ): Promise<DecisionResult<Questions>>
+}
+
+export class ModelServiceImpl implements ModelService {
+  constructor(private readonly client: ProteosClient) {}
+
+  async generate(request: GenerateRequest): Promise<GenerationResult> {
+    return this.client.request<GenerationResult>('POST', `${MODELS_BASE_PATH}/generate`, request)
+  }
+
+  async decide<Questions extends DecisionQuestions>(
+    request: DecideRequest<Questions>,
+  ): Promise<DecisionResult<Questions>> {
+    return this.client.request<DecisionResult<Questions>>(
+      'POST',
+      `${MODELS_BASE_PATH}/decide`,
+      request,
+    )
+  }
+}

package/src/index.ts

@@ -34,7 +34,7 @@
  * @packageDocumentation
  */
 
-// Agent client (agent-service: agents, prompts, skills, tools, mcp-servers, sessions)
+// Agent client (agent-service: agents, prompts, skills, tools, mcp-servers, models, sessions)
 export type {
   ActionBinding,
   Agent,
@@ -43,6 +43,11 @@ export type {
   AgentResourceListOptions,
   AgentService,
   AppendEventRequest,
+  BooleanAnswer,
+  BooleanCriteria,
+  BooleanQuestion,
+  ChoiceAnswer,
+  ChoiceQuestion,
   ClientEventType,
   ClientToolSchema,
   ContentBlock,
@@ -53,12 +58,21 @@ export type {
   CreateSessionRequest,
   CreateToolRequest,
   CreateToolsetRequest,
+  DecideRequest,
+  DecisionAnswer,
+  DecisionAnswerFor,
+  DecisionQuestion,
+  DecisionQuestions,
+  DecisionQuestionType,
+  DecisionResult,
   DependentAgent,
   DependentSyncResult,
   EmptyPayload,
   ErrorPayload,
   EventType,
   FileBlock,
+  GenerateRequest,
+  GenerationResult,
   ListAgentsOptions,
   ListMcpServersOptions,
   ListPromptsOptions,
@@ -77,6 +91,8 @@ export type {
   ModelConfig,
   ModelRequestEndPayload,
   ModelRequestStartPayload,
+  ModelService,
+  ModelStopReason,
   ModelUsage,
   PlatformBinding,
   Prompt,
@@ -85,6 +101,8 @@ export type {
   QueryBinding,
   ReasoningPayload,
   ResultBlock,
+  ScoreAnswer,
+  ScoreQuestion,
   Session,
   SessionEvent,
   SessionEventEnvelope,
@@ -100,6 +118,7 @@ export type {
   SkillVersion,
   StartMcpOAuthResponse,
   StopReason,
+  StructuredText,
   TextBlock,
   Tool,
   ToolBinding,

package/src/meta/index.ts

@@ -164,6 +164,12 @@ export type { MenuConfigurationService } from './menu-configurations.js'
 export type { ModuleService } from './modules.js'
 export type { PageExtensionService } from './page-extensions.js'
 export type { PageService } from './pages.js'
+export {
+  isReservedAttributeName,
+  isTitleQueryable,
+  RECORD_TITLE_FIELD,
+  titleTemplateVariables,
+} from './record-title.js'
 // Re-export types
 export type {
   // App types

package/src/meta/record-title.ts

@@ -0,0 +1,50 @@
+/**
+ * The virtual column that stands for a record's rendered title — the entity's
+ * Liquid `title_template` evaluated against the row. Lists show it, and the
+ * records query sorts and filters on it when the template is "simple". No
+ * attribute backs it, so the name is reserved: the backend rejects an
+ * attribute called `record_title` (mirror of `metamodel.RecordTitleField`).
+ */
+export const RECORD_TITLE_FIELD = 'record_title'
+
+/** True when `name` is taken by a virtual column and unavailable to attributes. */
+export function isReservedAttributeName(name: string): boolean {
+  return name === RECORD_TITLE_FIELD
+}
+
+/**
+ * A simple template is literal text plus `{{ attribute }}` references and
+ * nothing else — no filters (`| upcase`), no tags (`{% if %}`), no dotted
+ * references. Only those compile to SQL, so only those make `record_title`
+ * sortable and filterable. Mirror of the Go `titletemplate.ParseSimple`
+ * grammar; the backend stays the authority and answers 400 when the two
+ * ever disagree.
+ */
+export function isTitleQueryable(template: string | undefined): boolean {
+  // Nothing to order or match on without at least one attribute reference.
+  if (!template?.includes('{{')) return false
+  if (template.includes('{%') || template.includes('%}')) return false
+  let rest = template
+  while (rest !== '') {
+    const open = rest.indexOf('{{')
+    if (open < 0) return !rest.includes('}}')
+    if (rest.slice(0, open).includes('}}')) return false
+    rest = rest.slice(open + 2)
+    const close = rest.indexOf('}}')
+    if (close < 0) return false
+    if (!/^[a-z][a-z0-9_]*$/.test(rest.slice(0, close).trim())) return false
+    rest = rest.slice(close + 2)
+  }
+  return true
+}
+
+/** The attributes a simple template references, in order of first use; `[]` otherwise. */
+export function titleTemplateVariables(template: string | undefined): string[] {
+  if (!template || !isTitleQueryable(template)) return []
+  const out: string[] = []
+  for (const match of template.matchAll(/\{\{\s*([a-z][a-z0-9_]*)\s*\}\}/g)) {
+    const name = match[1]
+    if (name && !out.includes(name)) out.push(name)
+  }
+  return out
+}

package/src/workflow/types.ts

@@ -165,7 +165,9 @@ export type PropertyType =
   | 'credentials_select'
   | 'button'
   /** Edits a platform attribute list (`Attribute[]`) via the shared attribute schema builder. */
-  | 'attribute_schema'
+    /** Edits a decision-question map (model-decide `questions`) via the questions builder, with a raw-JSON mode. */
+  | 'decision_questions'
+| 'attribute_schema'
   // Wave 2 (editor support lands with Phase 3):
   | 'resource_locator'
   | 'resource_mapper'