Skip to content

docs(generator): fix reference $ref links and opaque Object types #3126

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-zhuang merged 1 commit into from
Jul 17, 2026
Merged

docs(generator): fix reference $ref links and opaque Object types #3126

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions content/docs/references/ai/agent.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,22 +74,22 @@ const result = AIKnowledge.parse(data);
| **avatar** | `string` | optional | |
| **role** | `string` | ✅ | The persona/role (e.g. "Senior Support Engineer") |
| **instructions** | `string` | ✅ | System Prompt / Prime Directives |
| **model** | `Object` | optional | |
| **lifecycle** | `Object` | optional | State machine defining the agent conversation follow and constraints |
| **model** | `{ provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'local'>; model: string; temperature: number; maxTokens?: number; … }` | optional | |
| **lifecycle** | `{ id: string; description?: string; contextSchema?: Record<string, any>; initial: string; … }` | optional | State machine defining the agent conversation follow and constraints |
| **surface** | `Enum<'ask' \| 'build'>` | ✅ | Product surface this agent binds ('ask' \| 'build') — ADR-0063 §1 |
| **skills** | `string[]` | optional | Skill names to attach (Agent→Skill→Tool architecture) |
| **tools** | `Object[]` | optional | Direct tool references (legacy fallback) |
| **knowledge** | `Object` | optional | RAG access |
| **tools** | `{ type: Enum<'action' \| 'flow' \| 'query' \| 'vector_search'>; name: string; description?: string }[]` | optional | Direct tool references (legacy fallback) |
| **knowledge** | `{ topics: string[]; indexes: string[] }` | optional | RAG access |
| **active** | `boolean` | ✅ | |
| **access** | `string[]` | optional | Who can chat with this agent |
| **permissions** | `string[]` | optional | Required permission-set capabilities |
| **tenantId** | `string` | optional | Tenant/Organization ID |
| **visibility** | `Enum<'global' \| 'organization' \| 'private'>` | ✅ | [EXPERIMENTAL — NOT ENFORCED, #1901] Intended listing scope. No runtime consumer yet; use access/permissions for real gating. |
| **planning** | `Object` | optional | Autonomous reasoning and planning configuration |
| **memory** | `Object` | optional | Agent memory management |
| **guardrails** | `Object` | optional | Safety guardrails for the agent |
| **structuredOutput** | `Object` | optional | Structured output format and validation configuration |
| **protection** | `Object` | optional | Package author protection block — lock policy for this agent. |
| **planning** | `{ strategy: Enum<'react' \| 'plan_and_execute' \| 'reflexion' \| 'tree_of_thought'>; maxIterations: integer; allowReplan: boolean }` | optional | Autonomous reasoning and planning configuration |
| **memory** | `{ longTerm?: object; reflectionInterval?: integer }` | optional | Agent memory management |
| **guardrails** | `{ maxTokensPerInvocation?: integer; maxExecutionTimeSec?: integer; blockedTopics?: string[] }` | optional | Safety guardrails for the agent |
| **structuredOutput** | `{ format: Enum<'json_object' \| 'json_schema' \| 'regex' \| 'grammar' \| 'xml'>; schema?: Record<string, any>; strict: boolean; retryOnValidationFailure: boolean; … }` | optional | Structured output format and validation configuration |
| **protection** | `{ lock: Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>; reason: string; docsUrl?: string }` | optional | Package author protection block — lock policy for this agent. |
| **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
| **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
| **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
Expand Down
40 changes: 20 additions & 20 deletions content/docs/references/ai/conversation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ const result = CodeContent.parse(data);

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'code'` | ✅ | |
| **text** | `string` | ✅ | Code snippet |
| **language** | `string` | ✅ | |
| **metadata** | `Record<string, any>` | optional | |
Expand Down Expand Up @@ -93,12 +93,12 @@ const result = CodeContent.parse(data);
| **id** | `string` | ✅ | Unique message ID |
| **timestamp** | `string` | ✅ | ISO 8601 timestamp |
| **role** | `Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>` | ✅ | |
| **content** | `Object \| Object \| Object \| Object[]` | ✅ | Message content (multimodal array) |
| **functionCall** | `Object` | optional | Legacy function call |
| **toolCalls** | `Object[]` | optional | Tool calls |
| **content** | `{ type: 'text'; text: string; metadata?: Record<string, any> } \| { type: 'image'; imageUrl: string; detail: Enum<'low' \| 'high' \| 'auto'>; metadata?: Record<string, any> } \| { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } \| { type: 'code'; text: string; language: string; metadata?: Record<string, any> }[]` | ✅ | Message content (multimodal array) |
| **functionCall** | `{ name: string; arguments: string; result?: string }` | optional | Legacy function call |
| **toolCalls** | `{ id: string; type: Enum<'function'>; function: object }[]` | optional | Tool calls |
| **toolCallId** | `string` | optional | Tool call ID this message responds to |
| **name** | `string` | optional | Name of the function/user |
| **tokens** | `Object` | optional | Token usage for this message |
| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Token usage for this message |
| **cost** | `number` | optional | Cost for this message in USD |
| **pinned** | `boolean` | ✅ | Prevent removal during pruning |
| **importance** | `number` | optional | Importance score for pruning |
Expand All @@ -116,12 +116,12 @@ const result = CodeContent.parse(data);
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Unique session ID |
| **name** | `string` | optional | Session name/title |
| **context** | `Object` | ✅ | |
| **context** | `{ sessionId: string; userId?: string; agentId?: string; object?: string; … }` | ✅ | |
| **modelId** | `string` | optional | AI model ID |
| **tokenBudget** | `Object` | ✅ | |
| **messages** | `Object[]` | ✅ | |
| **tokens** | `Object` | optional | |
| **totalTokens** | `Object` | optional | Total tokens across all messages |
| **tokenBudget** | `{ maxTokens: integer; maxPromptTokens?: integer; maxCompletionTokens?: integer; reserveTokens: integer; … }` | ✅ | |
| **messages** | `{ id: string; timestamp: string; role: Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>; content: { type: 'text'; text: string; metadata?: Record<string, any> } \| { type: 'image'; imageUrl: string; detail: Enum<'low' \| 'high' \| 'auto'>; metadata?: Record<string, any> } \| { type: 'file'; fileUrl: string; mimeType: string; fileName?: string; … } \| { type: 'code'; text: string; language: string; metadata?: Record<string, any> }[]; … }[]` | ✅ | |
| **tokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer; budgetLimit: integer; … }` | optional | |
| **totalTokens** | `{ promptTokens: integer; completionTokens: integer; totalTokens: integer }` | optional | Total tokens across all messages |
| **totalCost** | `number` | optional | Total cost for this session in USD |
| **status** | `Enum<'active' \| 'paused' \| 'completed' \| 'archived'>` | ✅ | |
| **createdAt** | `string` | ✅ | ISO 8601 timestamp |
Expand All @@ -143,7 +143,7 @@ const result = CodeContent.parse(data);
| **originalTokens** | `integer` | ✅ | Original token count |
| **summaryTokens** | `integer` | ✅ | Summary token count |
| **tokensSaved** | `integer` | ✅ | Tokens saved |
| **messageRange** | `Object` | ✅ | Range of messages summarized |
| **messageRange** | `{ startIndex: integer; endIndex: integer }` | ✅ | Range of messages summarized |
| **generatedAt** | `string` | ✅ | ISO 8601 timestamp |
| **modelId** | `string` | optional | Model used for summarization |

Expand All @@ -156,7 +156,7 @@ const result = CodeContent.parse(data);

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'file'` | ✅ | |
| **fileUrl** | `string` | ✅ | File attachment URL |
| **mimeType** | `string` | ✅ | MIME type |
| **fileName** | `string` | optional | |
Expand Down Expand Up @@ -184,7 +184,7 @@ const result = CodeContent.parse(data);

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'image'` | ✅ | |
| **imageUrl** | `string` | ✅ | Image URL |
| **detail** | `Enum<'low' \| 'high' \| 'auto'>` | ✅ | |
| **metadata** | `Record<string, any>` | optional | |
Expand All @@ -206,7 +206,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'text'` | ✅ | |
| **text** | `string` | ✅ | Text content |
| **metadata** | `Record<string, any>` | optional | |

Expand All @@ -220,7 +220,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'image'` | ✅ | |
| **imageUrl** | `string` | ✅ | Image URL |
| **detail** | `Enum<'low' \| 'high' \| 'auto'>` | ✅ | |
| **metadata** | `Record<string, any>` | optional | |
Expand All @@ -235,7 +235,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'file'` | ✅ | |
| **fileUrl** | `string` | ✅ | File attachment URL |
| **mimeType** | `string` | ✅ | MIME type |
| **fileName** | `string` | optional | |
Expand All @@ -251,7 +251,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'code'` | ✅ | |
| **text** | `string` | ✅ | Code snippet |
| **language** | `string` | ✅ | |
| **metadata** | `Record<string, any>` | optional | |
Expand Down Expand Up @@ -281,7 +281,7 @@ This schema accepts one of the following structures:
| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **timestamp** | `string` | ✅ | Event timestamp |
| **prunedMessages** | `Object[]` | ✅ | |
| **prunedMessages** | `{ messageId: string; role: Enum<'system' \| 'user' \| 'assistant' \| 'function' \| 'tool'>; tokens: integer; importance?: number }[]` | ✅ | |
| **tokensFreed** | `integer` | ✅ | |
| **messagesRemoved** | `integer` | ✅ | |
| **remainingTokens** | `integer` | ✅ | |
Expand Down Expand Up @@ -309,7 +309,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **type** | `string` | ✅ | |
| **type** | `'text'` | ✅ | |
| **text** | `string` | ✅ | Text content |
| **metadata** | `Record<string, any>` | optional | |

Expand Down Expand Up @@ -380,7 +380,7 @@ This schema accepts one of the following structures:
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Tool call ID |
| **type** | `Enum<'function'>` | ✅ | |
| **function** | `Object` | ✅ | |
| **function** | `{ name: string; arguments: string; result?: string }` | ✅ | |


---
Expand Down
20 changes: 10 additions & 10 deletions content/docs/references/ai/knowledge-source.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ const result = FileKnowledgeSource.parse(data);

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ | |
| **kind** | `'file'` | ✅ | |
| **prefix** | `string` | ✅ | Storage prefix |
| **mimeTypes** | `string[]` | optional | |

Expand All @@ -56,7 +56,7 @@ const result = FileKnowledgeSource.parse(data);

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ | |
| **kind** | `'http'` | ✅ | |
| **urls** | `string[]` | ✅ | |
| **userAgent** | `string` | optional | |

Expand Down Expand Up @@ -86,10 +86,10 @@ const result = FileKnowledgeSource.parse(data);
| **description** | `string` | optional | |
| **adapter** | `string` | ✅ | Adapter id |
| **adapterConfig** | `Record<string, any>` | optional | |
| **source** | `Object \| Object \| Object` | ✅ | |
| **embedding** | `Object` | optional | |
| **vectorStore** | `Object` | optional | |
| **refresh** | `Object` | optional | |
| **source** | `{ kind: 'object'; object: string; contentFields: string[]; metadataFields?: string[]; … } \| { kind: 'file'; prefix: string; mimeTypes?: string[] } \| { kind: 'http'; urls: string[]; userAgent?: string }` | ✅ | |
| **embedding** | `{ provider: Enum<'openai' \| 'cohere' \| 'azure_openai' \| 'huggingface' \| 'local' \| 'custom'>; model: string; dimensions: integer; endpoint?: string; … }` | optional | |
| **vectorStore** | `{ provider: Enum<'pgvector' \| 'chroma' \| 'qdrant' \| 'pinecone' \| 'weaviate' \| 'milvus' \| 'redis' \| 'opensearch' \| 'elasticsearch' \| 'custom'>; collection: string; endpoint?: string; secretRef?: string; … }` | optional | |
| **refresh** | `{ onRecordChange?: boolean; cron?: string }` | optional | |
| **aiExposed** | `boolean` | optional | |


Expand All @@ -107,7 +107,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ | |
| **kind** | `'object'` | ✅ | |
| **object** | `string` | ✅ | Short object name to index |
| **contentFields** | `string[]` | ✅ | Fields contributing to document content |
| **metadataFields** | `string[]` | optional | |
Expand All @@ -121,7 +121,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ | |
| **kind** | `'file'` | ✅ | |
| **prefix** | `string` | ✅ | Storage prefix |
| **mimeTypes** | `string[]` | optional | |

Expand All @@ -133,7 +133,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ | |
| **kind** | `'http'` | ✅ | |
| **urls** | `string[]` | ✅ | |
| **userAgent** | `string` | optional | |

Expand All @@ -148,7 +148,7 @@ This schema accepts one of the following structures:

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **kind** | `string` | ✅ | |
| **kind** | `'object'` | ✅ | |
| **object** | `string` | ✅ | Short object name to index |
| **contentFields** | `string[]` | ✅ | Fields contributing to document content |
| **metadataFields** | `string[]` | optional | |
Expand Down
2 changes: 1 addition & 1 deletion content/docs/references/ai/mcp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ server (so an agent can mount its tools).

2. **MCPToolBinding** — how an MCP tool from a referenced server

is exposed as an ObjectStack [AIToolDefinition](AIToolDefinition) (alias,
is exposed as an ObjectStack `AIToolDefinition` (alias,

visibility, approval policy).

Expand Down
26 changes: 13 additions & 13 deletions content/docs/references/ai/model-registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ const result = ModelCapability.parse(data);
| **name** | `string` | ✅ | Model display name |
| **version** | `string` | ✅ | Model version (e.g., "gpt-4-turbo-2024-04-09") |
| **provider** | `Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>` | ✅ | |
| **capabilities** | `Object` | ✅ | |
| **limits** | `Object` | ✅ | |
| **pricing** | `Object` | optional | |
| **capabilities** | `{ textGeneration: boolean; textEmbedding: boolean; imageGeneration: boolean; imageUnderstanding: boolean; … }` | ✅ | |
| **limits** | `{ maxTokens: integer; contextWindow: integer; maxOutputTokens?: integer; rateLimit?: object }` | ✅ | |
| **pricing** | `{ currency: string; inputCostPer1kTokens?: number; outputCostPer1kTokens?: number; embeddingCostPer1kTokens?: number }` | optional | |
| **endpoint** | `string` | optional | Custom API endpoint |
| **apiKey** | `string` | optional | API key (Warning: Prefer secretRef) |
| **secretRef** | `string` | optional | Reference to stored secret (e.g. system:openai_api_key) |
Expand All @@ -78,7 +78,7 @@ const result = ModelCapability.parse(data);
| **maxTokens** | `integer` | ✅ | Maximum tokens per request |
| **contextWindow** | `integer` | ✅ | Context window size |
| **maxOutputTokens** | `integer` | optional | Maximum output tokens |
| **rateLimit** | `Object` | optional | |
| **rateLimit** | `{ requestsPerMinute?: integer; tokensPerMinute?: integer }` | optional | |


---
Expand Down Expand Up @@ -120,8 +120,8 @@ const result = ModelCapability.parse(data);
| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Registry name |
| **models** | `Record<string, Object>` | ✅ | Model entries by ID |
| **promptTemplates** | `Record<string, Object>` | optional | Prompt templates by name |
| **models** | `Record<string, { model: object; status?: Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>; priority?: integer; fallbackModels?: string[]; … }>` | ✅ | Model entries by ID |
| **promptTemplates** | `Record<string, { id: string; name: string; label: string; system?: string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }; … }>` | optional | Prompt templates by name |
| **defaultModel** | `string` | optional | Default model ID |
| **enableAutoFallback** | `boolean` | optional | Auto-fallback on errors |

Expand All @@ -134,11 +134,11 @@ const result = ModelCapability.parse(data);

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **model** | `Object` | ✅ | |
| **model** | `{ id: string; name: string; version: string; provider: Enum<'openai' \| 'azure_openai' \| 'anthropic' \| 'google' \| 'cohere' \| 'huggingface' \| 'local' \| 'custom'>; … }` | ✅ | |
| **status** | `Enum<'active' \| 'deprecated' \| 'experimental' \| 'disabled'>` | ✅ | |
| **priority** | `integer` | ✅ | Priority for model selection |
| **fallbackModels** | `string[]` | optional | Fallback model IDs |
| **healthCheck** | `Object` | optional | |
| **healthCheck** | `{ enabled: boolean; intervalSeconds: integer; lastChecked?: string; status: Enum<'healthy' \| 'unhealthy' \| 'unknown'> }` | optional | |


---
Expand Down Expand Up @@ -168,10 +168,10 @@ const result = ModelCapability.parse(data);
| **id** | `string` | ✅ | Unique template identifier |
| **name** | `string` | ✅ | Template name (snake_case) |
| **label** | `string` | ✅ | Display name |
| **system** | `string \| Object` | optional | System prompt — supports `{{var}`} interpolation |
| **user** | `string \| Object` | ✅ | User prompt template — supports `{{var}`} interpolation |
| **system** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | optional | System prompt — supports `{{var}`} interpolation |
| **user** | `string \| { dialect: Enum<'cel' \| 'js' \| 'cron' \| 'template'>; source?: string; ast?: any; meta?: object }` | ✅ | User prompt template — supports `{{var}`} interpolation |
| **assistant** | `string` | optional | Assistant message prefix |
| **variables** | `Object[]` | optional | Template variables |
| **variables** | `{ name: string; type?: Enum<'string' \| 'number' \| 'boolean' \| 'object' \| 'array'>; required?: boolean; defaultValue?: any; … }[]` | optional | Template variables |
| **modelId** | `string` | optional | Recommended model ID |
| **temperature** | `number` | optional | |
| **maxTokens** | `number` | optional | |
Expand All @@ -183,7 +183,7 @@ const result = ModelCapability.parse(data);
| **description** | `string` | optional | |
| **category** | `string` | optional | Template category (e.g., "code_generation", "support") |
| **tags** | `string[]` | optional | |
| **examples** | `Object[]` | optional | |
| **examples** | `{ input: Record<string, any>; output: string }[]` | optional | |


---
Expand All @@ -199,7 +199,7 @@ const result = ModelCapability.parse(data);
| **required** | `boolean` | ✅ | |
| **defaultValue** | `any` | optional | |
| **description** | `string` | optional | |
| **validation** | `Object` | optional | |
| **validation** | `{ minLength?: number; maxLength?: number; pattern?: string; enum?: any[] }` | optional | |


---
Expand Down
Loading