diff --git a/README.md b/README.md index bcaec707d1..6d6dd16e4b 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Prefer clicking? Author the same metadata visually in **Studio** — objects, re - **AI-native, not retrofitted** — Objects, permissions, flows, APIs, and UI are declarative typed metadata, small enough for an agent to load end-to-end. That metadata generates an automatic tool surface — REST APIs, client SDKs, UI views, and an [MCP](packages/mcp) server — so agents inspect and act through the same contracts you defined. - **Protocol-first runtime** — Every definition starts as a Zod schema (`z.infer<>` types), compiles into versioned, self-describing JSON artifacts, and runs on a microkernel plugin system (DI container, EventBus, `init → start → destroy` lifecycle). - **Data & framework reach** — In-memory, PostgreSQL, MySQL, SQLite, and MongoDB drivers; 7 framework adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit); a client SDK with React hooks (`useQuery` / `useMutation` / `usePagination`). -- **Governance & built-ins** — better-auth, RBAC / RLS / FLS, a DAG-based automation engine, an AI service (Agent / Tool / Skill on the Vercel AI SDK), the ObjectUI Console, and a full CLI (`os init` / `dev` / `compile` / `validate` / …). +- **Governance & built-ins** — better-auth, RBAC / RLS / FLS, a DAG-based automation engine, an [MCP](packages/mcp) server that exposes the app to your own AI (BYO-AI), the ObjectUI Console, and a full CLI (`os init` / `dev` / `compile` / `validate` / …). ## Why AI-native? @@ -252,7 +252,6 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation | Package | Description | | :--- | :--- | -| [`@objectstack/service-ai`](packages/services/service-ai) | AI service — Agent, Tool, Skill, Vercel AI SDK integration | | [`@objectstack/service-analytics`](packages/services/service-analytics) | Analytics — aggregations, time series, funnels, dashboards | | [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, and workflow state machines | | [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory, Redis, multi-tier | diff --git a/content/docs/concepts/implementation-status.mdx b/content/docs/concepts/implementation-status.mdx index 1cc4d7db0a..d6b8bba732 100644 --- a/content/docs/concepts/implementation-status.mdx +++ b/content/docs/concepts/implementation-status.mdx @@ -294,6 +294,15 @@ The `auth` service in `CoreServiceName` covers both **authentication** (identity ## AI Layer + +The in-UI AI **runtime** below (`@objectstack/service-ai`) moved to the **cloud / +Enterprise** distribution — see cloud ADR-0025 (`service-ai → cloud; open = +MCP-only`). The agent / skill / tool **schemas** stay open in `@objectstack/spec/ai`; +the **open edition** exposes AI via [`@objectstack/mcp`](../guides/ai-capabilities) +(BYO-AI). The Implementation / Status columns describe the runtime as it ships in +cloud / EE. + + | Protocol | @objectstack/spec | Implementation | Status | |:---------|:-----------------:|:-------------:|:------:| | **Agent** | ✅ | @objectstack/service-ai | ✅ Agent runtime (`agent-runtime.ts`, `agents/`) | diff --git a/content/docs/guides/ai-capabilities.mdx b/content/docs/guides/ai-capabilities.mdx index 1f06be69f1..41fcb24d37 100644 --- a/content/docs/guides/ai-capabilities.mdx +++ b/content/docs/guides/ai-capabilities.mdx @@ -7,7 +7,18 @@ description: "Complete guide to leveraging AI agents, RAG pipelines, and intelli Complete guide to leveraging AI agents, knowledge retrieval, and intelligent automation in ObjectStack. -> **Note — the open edition exposes AI via MCP (BYO-AI).** Per ADR-0025, the in-UI AI runtime (`@objectstack/service-ai`: agents, the `ask`/`build` assistants, in-product chat) ships in the **cloud / Enterprise** distribution, not the open framework. A self-hosted **open** runtime instead exposes its objects, queries, and business actions to *your own* AI — Claude, Cursor, any MCP client, or a local model — through **`@objectstack/mcp`** (bring-your-own-AI, zero platform AI cost). The `@objectstack/service-ai` examples below therefore describe the cloud/EE distribution. + +**This guide describes the cloud / Enterprise AI tier. The open edition exposes AI only via MCP (BYO-AI).** + +Per **cloud ADR-0025** (`service-ai → cloud; open = MCP-only` — [`cloud/docs/adr/0025`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md)), the in-UI AI runtime — `@objectstack/service-ai`: both the **`ask`** data-query assistant and the **`build`** Studio authoring assistant, plus all in-product chat — ships in the **cloud / Enterprise** distribution. It is **not** in the open framework, and no open distribution (cloud free tier, Docker, desktop, on-prem) has a built-in `ask` / `build` chat. + +The **open edition** does AI two ways instead — both bring-your-own-AI, zero platform AI cost: + +- **Data query → `@objectstack/mcp`** (BYO-AI). Point your own AI — Claude, Cursor, any MCP client, or a local model — at the app's objects, queries, and business **actions**, governed by the same RLS. With a local model, data *and* inference stay inside your boundary. +- **Metadata authoring → source mode.** Author typed metadata as source (`*.object.ts`, `*.flow.ts`, …) with your own AI coding agent (Claude Code, Cursor), aided by the ObjectStack [skills](./skills) and MCP introspection. There is no in-product Builder chat in the open edition. + +Everything below (agents, the `ask` / `build` personas, `@objectstack/service-ai` wiring, the `/api/v1/ai/*` routes) therefore describes the **cloud / Enterprise** distribution. + ## Table of Contents @@ -50,12 +61,17 @@ is in — the user never picks from a roster: | Agent | Surface | Does | Edition | |---|---|---|---| -| **`ask`** | data console | Read / query / explore records + run the business **actions** the app exposes. RLS-bounded. | open-source · free | -| **`build`** | Studio | Author *metadata* (objects, fields, views, flows) via plan → draft → verify → publish. | cloud · paid | +| **`ask`** | data console | Read / query / explore records + run the business **actions** the app exposes. RLS-bounded. | cloud · Enterprise | +| **`build`** | Studio | Author *metadata* (objects, fields, views, flows) via plan → draft → verify → publish. | cloud · Enterprise | + +Both agents are part of the **cloud / Enterprise** in-UI AI runtime (cloud ADR-0025). +The **open edition** ships neither — it uses `@objectstack/mcp` (BYO-AI) for data +query and source-mode authoring instead (see the note above). -There is no per-turn intent classifier and no agent dropdown: the surface binds -the agent (data console → `ask`, Studio → `build`). A `build`-shaped request that -reaches `ask` is declined and redirected to the Builder, never silently re-routed. +Within the cloud / EE runtime there is no per-turn intent classifier and no agent +dropdown: the surface binds the agent (data console → `ask`, Studio → `build`). A +`build`-shaped request that reaches `ask` is declined and redirected to the +Builder, never silently re-routed. ### You extend the platform with **skills**, not agents @@ -68,8 +84,10 @@ Actions / Flows / queries; it then attaches to `ask`. Every skill declares surface-compatible skills' tools** — there is no global fall-through, so a skill reaches an agent only when their surfaces match ([ADR-0064](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0064-tool-scoping-to-agent.md)). -`surface:'build'` skills are inert on the open-source framework (the `build` agent -is cloud-only) — intentional tiering, not a bug. +Both `surface:'ask'` and `surface:'build'` skills run only where the in-UI AI +runtime exists — the **cloud / Enterprise** distribution. On the open framework +there is no in-product agent to attach them to (cloud ADR-0025); author capability +as Actions / Flows and reach it through `@objectstack/mcp` instead. ### The shape of an agent diff --git a/content/docs/guides/environment-variables.mdx b/content/docs/guides/environment-variables.mdx index 2f057f4368..8813d25dac 100644 --- a/content/docs/guides/environment-variables.mdx +++ b/content/docs/guides/environment-variables.mdx @@ -125,6 +125,15 @@ Auth settings precedence: ## AI + +These variables configure the **cloud / Enterprise** in-UI AI runtime +(`@objectstack/service-ai`), which moved out of the open framework — see cloud +ADR-0025 (`service-ai → cloud; open = MCP-only`). The **open edition** has no +in-UI AI runtime to configure: it exposes AI through `@objectstack/mcp` (BYO-AI), +where the model and provider are configured in your own MCP client (Claude, +Cursor, a local model, …). See the [AI Capabilities guide](./ai-capabilities). + + | Variable | Type | Default | Description | |:---|:---|:---|:---| | `AI_GATEWAY_MODEL` | string | — | Vercel AI Gateway model id (for example `openai/gpt-4.1-mini` or `anthropic/claude-sonnet-4-5`). When set, the AI service boots with the gateway adapter before trying direct providers. | diff --git a/content/docs/guides/plugin-chatbot-integration.mdx b/content/docs/guides/plugin-chatbot-integration.mdx index ece7220273..e276a60508 100644 --- a/content/docs/guides/plugin-chatbot-integration.mdx +++ b/content/docs/guides/plugin-chatbot-integration.mdx @@ -5,6 +5,17 @@ description: Wire @object-ui/plugin-chatbot in Console (or any frontend) to the # Connecting plugin-chatbot to a framework AI backend + +**Cloud / Enterprise tier.** The in-UI AI backend this guide wires up — the +`/api/v1/ai/*` routes, the `ask` / `build` assistants, the models picker, and the +HITL inbox (`@objectstack/service-ai`) — ships in the **cloud / Enterprise** +distribution, not the open framework (cloud ADR-0025: `service-ai → cloud; open = +MCP-only`). On the **open edition** there is no in-product chat backend; expose +the app to your own AI through `@objectstack/mcp` (BYO-AI) instead — see the +[AI Capabilities guide](./ai-capabilities). Follow this guide when you run against +a cloud / EE host (or a dev server with the AI tier mounted). + + `@object-ui/plugin-chatbot` (a React component shipped from the `objectui` monorepo) is the canonical chat UI for ObjectStack Console. It speaks the Vercel AI Data Stream protocol, so it pairs natively with the AI routes diff --git a/content/docs/protocol/knowledge.mdx b/content/docs/protocol/knowledge.mdx index 182c1d5ece..bd6923f7a1 100644 --- a/content/docs/protocol/knowledge.mdx +++ b/content/docs/protocol/knowledge.mdx @@ -17,6 +17,15 @@ service that orchestrates them — and ships individual adapters as `IDataEngine` / driver plugins (`driver-sql`, `driver-turso`, `driver-memory`) and `IStorageService` / S3 + local FS adapters. + +The Knowledge Protocol contract and the `service-knowledge` orchestrator are open +framework mechanisms. The AI **consumer** that wires the `search_knowledge` tool +into an in-product chat loop (`@objectstack/service-ai`, shown below) ships in the +**cloud / Enterprise** distribution — see cloud ADR-0025 (`service-ai → cloud; +open = MCP-only`). On the open edition, reach your data through `@objectstack/mcp` +(BYO-AI) instead. + + This document describes the **why**, the **contract**, the **plugin model**, and the **MVP scope** that ships in Phase 1. diff --git a/docs/adr/0033-ai-assisted-metadata-authoring.md b/docs/adr/0033-ai-assisted-metadata-authoring.md index bcc0134dd1..fc3de8b214 100644 --- a/docs/adr/0033-ai-assisted-metadata-authoring.md +++ b/docs/adr/0033-ai-assisted-metadata-authoring.md @@ -1,5 +1,7 @@ # ADR-0033: AI-assisted metadata authoring — one agent brain, draft-gated review, type-agnostic apply, open-core boundary +> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md). + **Status**: Accepted (2026-06-02) **Deciders**: ObjectStack Protocol Architects **Builds on**: [ADR-0005](./0005-metadata-customization-overlay.md) (one Zod source per type + org overlay), [ADR-0010 (protection)](./0010-metadata-protection-model.md) (L1/L2/L3 protection), [ADR-0010 (NL→flow)](./0010-nl-to-flow-authoring.md) + [ADR-0011](./0011-actions-as-ai-tools.md) (AI authoring of metadata / actions-as-tools — **the design center**), [ADR-0019](./0019-approval-as-flow-node.md) (approvals as a flow node), [ADR-0027](./0027-metadata-authoring-lifecycle.md) (**staged authoring · draft · publish · promote** — *this ADR routes every AI write through its draft workspace*), [ADR-0032](./0032-unified-expression-layer.md) (validate-by-default, AI-authored expressions) diff --git a/docs/adr/0038-build-verification-loop.md b/docs/adr/0038-build-verification-loop.md index 4955110ec5..0d478a6e2c 100644 --- a/docs/adr/0038-build-verification-loop.md +++ b/docs/adr/0038-build-verification-loop.md @@ -1,5 +1,7 @@ # ADR-0038: Build Verification Loop — the agent builds, verifies, and corrects itself +> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md). + **Status**: Proposed (2026-06-11) **Deciders**: ObjectStack Protocol Architects **Builds on**: [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (drafts as the staging layer — this ADR **replaces its human-approval assumption for AI builds** with a machine gate; HITL stays for destructive actions), [ADR-0021](./0021-analytics-dataset-semantic-layer.md) (datasets — what most verification probes exercise), ADR-0037 / [framework#1694](https://github.com/objectstack-ai/framework/pull/1694) (Live Canvas — the *human-visibility* complement to this ADR's *machine-verification*) diff --git a/docs/adr/0040-unified-assistant-and-agent-binding.md b/docs/adr/0040-unified-assistant-and-agent-binding.md index 44795ba486..3511b09b60 100644 --- a/docs/adr/0040-unified-assistant-and-agent-binding.md +++ b/docs/adr/0040-unified-assistant-and-agent-binding.md @@ -1,5 +1,7 @@ # ADR-0040: Unified Assistant — the end user never picks an agent +> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md). + > **⚠️ Superseded by [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md)** (2026-06-22). Its core decision — a *single* unified assistant carrying all skills, switched by a per-turn intent classifier — was **reversed**: the kernel now ships two agents (`ask` / `build`) bound by *surface*, and `*.agent.ts` is closed to third parties (skills are the extension primitive). The UX win it established (the user never picks from a roster) is kept, re-grounded as surface binding. Kept below as a historical record of the decision and the incident that motivated it. **Status**: **Superseded by [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md)** — original: Proposed (2026-06-11) diff --git a/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md b/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md index 88bb3d67d0..6c3de063fa 100644 --- a/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md +++ b/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md @@ -1,5 +1,7 @@ # ADR-0063: Two agents (`ask` / `build`), bound by surface; skills are the only third-party extension primitive +> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md). + **Status**: Proposed (2026-06-22) **Deciders**: ObjectStack Protocol Architects **Supersedes**: [ADR-0040](./0040-unified-assistant-and-agent-binding.md) — its core decision (a *single* unified assistant selected by *per-turn intent classification*) is **reversed**. ADR-0040's UX win ("the end user never picks from a roster") is **kept** but re-grounded: the *surface* binds the agent, not a classifier and not a dropdown. §3 (custom tenant agents) is withdrawn; §4 (tool-scoping) is handed to [ADR-0064](./0064-tool-scoping-to-agent.md). diff --git a/docs/adr/0064-tool-scoping-to-agent.md b/docs/adr/0064-tool-scoping-to-agent.md index 68ed4db636..4cd8522829 100644 --- a/docs/adr/0064-tool-scoping-to-agent.md +++ b/docs/adr/0064-tool-scoping-to-agent.md @@ -1,5 +1,7 @@ # ADR-0064: Tool scoping — an agent's tools are exactly its skills' tools +> **🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25).** The in-UI AI runtime and the `ask` / `build` agents described here moved to the **cloud / Enterprise** distribution (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed); the open framework exposes AI only via `@objectstack/mcp` (BYO-AI) and ships no in-product `ask` / `build` chat. Retained as historical design context, now **cloud-owned** — see [`cloud/docs/adr/0025-service-ai-to-cloud-open-mcp-only`](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md). + **Status**: Proposed (2026-06-22) **Deciders**: ObjectStack Protocol Architects **Builds on**: [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md) (two agents bound by surface; skill ↔ agent affinity), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (draft-gated authoring tools) diff --git a/skills/objectstack-ai/SKILL.md b/skills/objectstack-ai/SKILL.md index ae1b768271..2694dd3650 100644 --- a/skills/objectstack-ai/SKILL.md +++ b/skills/objectstack-ai/SKILL.md @@ -23,6 +23,16 @@ pipelines using the ObjectStack specification. This skill covers the Agent → Skill → Tool three-tier architecture aligned with Salesforce Agentforce, Microsoft Copilot Studio, and ServiceNow Now Assist patterns. +> **Edition boundary (cloud ADR-0025 — `service-ai → cloud; open = MCP-only`).** +> The in-UI AI **runtime** — the `ask` / `build` agents, in-product chat, and the +> `/api/v1/ai/*` routes (`@objectstack/service-ai`) — ships in the **cloud / +> Enterprise** distribution, not the open framework. The agent / skill / tool +> **schemas** in `@objectstack/spec/ai` stay open, so you author `*.agent.ts` / +> `*.skill.ts` / `*.tool.ts` as source either way — but they only execute in a +> cloud / EE host. On the **open edition** there is no in-product agent: expose the +> app to your own AI via `@objectstack/mcp` (BYO-AI) for data query, and author +> metadata in **source mode** with an AI coding agent (Claude Code, Cursor). + --- ## When to Use This Skill @@ -65,8 +75,10 @@ never picks from a roster; the surface they are in selects the agent: - **`ask`** — the **data product** (≈ Claude Chat). Conversational read / query / explore over records, plus running the business **actions** the app already exposes. End-user audience, RLS-bounded. Canonical id `ask` (`ASK_AGENT_NAME`). - Open-source · free — ships in `@objectstack/service-ai`, and is the implicit - copilot for any app that does not pin `app.defaultAgent`. + **Cloud / Enterprise** — the `ask` runtime moved from the open framework into the + cloud AI runtime (`@objectstack/service-ai` → `cloud/packages/service-ai`, closed) + per cloud ADR-0025; it is the implicit copilot for any cloud / EE app that does + not pin `app.defaultAgent`. (Open editions have no in-product `ask`; use MCP.) - **`build`** — the **authoring product** (≈ Claude Code). Agentic authoring of *metadata* (objects, fields, views, flows) through plan → draft → verify → publish. Builder audience, governance-gated. Canonical id `build`. Cloud-only · diff --git a/skills/objectstack-platform/SKILL.md b/skills/objectstack-platform/SKILL.md index d63546741a..440cc7601a 100644 --- a/skills/objectstack-platform/SKILL.md +++ b/skills/objectstack-platform/SKILL.md @@ -428,7 +428,7 @@ CLI: `os serve` / `os dev` ├── HonoServerPlugin ├── RESTPlugin (auto-generated API) ├── DispatcherPlugin - └── AIServicePlugin (if available) + └── AIServicePlugin (cloud / EE only — reverse-mounted by a cloud host; absent in the open framework per cloud ADR-0025) 5. Runtime.start() → init + start all plugins 6. Server listens on the resolved port (see "Ports & networking" in Part 3) ``` @@ -449,7 +449,7 @@ Plugins initialize in registration order. Key dependencies: | AppPlugin | ObjectQLPlugin | Registers objects/metadata with engine | | AuthPlugin | ObjectQLPlugin | Needs user/session objects | | RESTPlugin | ObjectQLPlugin, AppPlugin | Generates routes from registered objects | -| AIServicePlugin | ObjectQLPlugin, AppPlugin | Needs metadata for tool generation | +| AIServicePlugin | ObjectQLPlugin, AppPlugin | Needs metadata for tool generation. **Cloud / EE only** — `@objectstack/service-ai` moved to cloud (cloud ADR-0025); the open edition has no in-UI AI plugin and uses `@objectstack/mcp` (BYO-AI) | ### Programmatic Bootstrap (Without CLI)