graphjin 3.18.41 → 3.18.43

package/README.md

@@ -15,10 +15,12 @@ Works with PostgreSQL, MySQL, MongoDB, SQLite, Oracle, MSSQL, Snowflake, Redshif
 
 ## Why GraphJin For Agents
 
+- **A built-in agent, one call away** - POST one instruction to `/api/v1/agent` (or call the `ask_graphjin_agent` MCP tool) and GraphJin runs the discovery loop itself - as the caller, under the caller's permissions - and returns a typed, evidence-backed answer. See [Server-Side Agent](#server-side-agent).
 - **One governed surface for many systems** - Query operational databases, warehouses, MongoDB, object stores, local files, CodeSQL source indexes, workflows, and GraphJin system roots through GraphQL and MCP.
 - **Smart discovery before action** - Agents start with `query_catalog(search: "<user instruction>")`, `graphql_help`, relationship evidence, examples, config recipes, and safety notes before writing or running queries.
 - **Guarded action, not raw access** - Source-mode access, query allow-lists, read-only boundaries, policy-aware MCP tools, local encrypted secrets, and `gj_config` preview/apply keep changes auditable.
 - **Operational awareness** - `gj_security`, `gj_runtime`, and the built-in console expose policy and bounded runtime status so agents can check what is safe before they act.
+- **Durable memory and standing questions** - Saved queries, fragments, and workflows live in the owner-scoped `gj_artifacts` store; cursor-backed watches (`gj_watch`) run standing questions under the owner's permissions, resume from persisted subscription cursors, and deliver fired events to a durable inbox (`gj_watch_event`), webhooks, or workflows. Normal watches are durable by default; explicit ephemeral watches use TTL leases.
 
 ## Installation
 
@@ -72,6 +74,12 @@ executable workflows:
 graphjin serve --demo --path examples/coffee-roastery
 ```
 
+More demo verticals — a MySQL corrugated-box plant with JWT roles, a PCB fab
+spanning Postgres + Snowflake-emu + MongoDB + a file source + an OpenAPI
+supplier API, and a zero-Docker SQLite clinic scheduler — live in
+[examples/](examples/README.md), each with an end-to-end smoke suite
+(`make smoke-all` runs them all).
+
 You'll see output like this:
 ```
 GraphJin started
@@ -83,6 +91,18 @@ GraphJin started
   MCP:         http://localhost:8080/api/v1/mcp
 ```
 
+**Ask the built-in agent**
+
+With a model API key in `./.env` (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GOOGLE_APIKEY`), `--demo` also switches into agentic mode and enables GraphJin's built-in agent - one instruction in, a typed, evidence-backed answer out. Against the coffee-roastery demo:
+
+```bash
+curl -sS localhost:8080/api/v1/agent \
+  -H 'content-type: application/json' \
+  -d '{"instruction": "What production work should we prioritize next?"}'
+```
+
+Answers come back as `{status, answer, data, evidence, actions, next}`, grounded by server-side protocol guards. See [Server-Side Agent](#server-side-agent) below, [AGENTIC.md](AGENTIC.md#server-side-agent), and [graphjin.com/agentic/server-agent](https://graphjin.com/agentic/server-agent/).
+
 ## Add GraphJin To Your AI Client
 
 ### Local / Dev
@@ -517,6 +537,7 @@ federation:
 | `/api/v1/openapi.json` | `GET` | OpenAPI 3 spec generated from your saved REST queries. |
 | `/api/v1/mcp` | `POST` | MCP (Model Context Protocol) HTTP transport — Streamable HTTP, stateless. |
 | `/api/v1/mcp/message` | `POST` | Legacy MCP message route for older local proxy/client integrations. New clients should use `/api/v1/mcp`. |
+| `/api/v1/agent` | `POST` | Server-side agent: send one instruction, get a typed evidence-backed answer (only when `agent.enabled`). See [Server-Side Agent](#server-side-agent). |
 | `/.well-known/oauth-protected-resource[/api/v1/mcp]` | `GET` | MCP OAuth protected-resource metadata (only when `mcp.oauth.enabled`). |
 | `/.well-known/oauth-authorization-server` | `GET` | Built-in MCP OAuth authorization-server metadata (only when `mcp.oauth.enabled`). |
 | `/api/v1/oauth/register` | `POST` | Built-in MCP OAuth dynamic client registration (only in builtin mode). |
@@ -547,6 +568,8 @@ GraphJin exposes a catalog-first MCP surface that guides AI models to discover b
 - Act through governed GraphQL roots such as `gj_workflow_execution(insert)`, `gj_workflow(insert/update/delete)`, and `gj_config(id: "current", update: ...)` only when policy exposes them.
 - In source mode, `gj_config` writes must run `mode: "preview"` with `expected_catalog_revision`, then resend the exact same payload with `mode: "apply"` and `preview_id`.
 - Source access and GraphJin root changes should use `source_patches` by exact source name instead of rewriting the full `sources` array.
+- Watches are managed through `gj_watch` / `gj_watch_event` and REST wrappers (`/api/v1/watches`, `/api/v1/watch-events/unseen`). MCP clients can subscribe to `graphjin://watch-events/unseen` for caller-scoped unseen-event notifications; unsubscribing does not pause or delete durable watches.
+- Use `/api/v1/watches/cleanup-preview` before `/api/v1/watches/cleanup-apply`. Expired ephemeral watches can be expired automatically, but durable watch deletion is always explicit.
 - Legacy discovery tools are migration shims and are disabled unless `mcp.legacy_discovery: true`.
 
 Schema reloads, schema changes, where-clause validation, and query repair remain MCP action tools.
@@ -566,6 +589,19 @@ For JS orchestration, use:
 
 Legacy prompts such as `write_query` and `fix_query_error` are available only when the caller's MCP surface lists them; in source mode their guidance lives in `graphql_help`, `query_catalog`, and GraphJin repair hints.
 
+## Server-Side Agent
+
+Optional: instead of your client chaining `query_catalog` → `validate_where_clause` → `execute_saved_query`, let GraphJin run the catalog-first discovery loop for you. When enabled, GraphJin exposes one MCP tool `ask_graphjin_agent` and one REST endpoint `POST /api/v1/agent` that take a single instruction and return a typed, evidence-backed answer (`status`, `answer`, `data`, `evidence`, `actions`, `next`).
+
+- **Enable** by loading `agentic.yml` (`GO_ENV=agentic`) with `agent.enabled: true` plus a provider, model, and `api_key_env`.
+- **Execution control:** there are no per-request agent modes. `agent.read_only: true` forces the server-side agent to reject mutations, including saved-query mutations; otherwise core roles, row-level security, source/table `read_only`, and Go protocol guards decide what can run.
+- **Caller-scoped:** the agent runs as the caller, so core roles + row-level security enforce access. The caller's role only changes which *guidance* the agent follows, never what it can read or write.
+- **Grounded:** Go protocol guards keep every answer backed by real catalog/validation/execution evidence and downgrade to `blocked` (with evidence) when a step is skipped.
+- **Machine-actionable refusals:** blocked responses carry a structured `refusal` (code, reasons, unblock steps, `policy_final`/`retryable`) so a calling agent can course-correct in one step instead of guessing.
+- **Model sampling:** with `agent.sampling: auto` (or `require`), the agent borrows the calling MCP client's model via MCP sampling — no server-side model key needed; caller identity and permissions are unchanged.
+
+It is an RLM loop — the model writes JavaScript that calls the discovery tools, and the typed result is parsed from `key: value` output. So it needs a model that is good at **code generation**, not provider tool-calling or structured-output modes; any OpenAI-compatible endpoint works via `agent.base_url`. See [AGENTIC.md](AGENTIC.md#server-side-agent) and [CONFIG.md](CONFIG.md#agent-configuration).
+
 ## JS Workflows (GraphQL + REST)
 
 Workflows let an LLM run multi-step logic in JavaScript while still using GraphJin MCP tools for DB-aware operations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphjin",
-  "version": "3.18.41",
+  "version": "3.18.43",
   "description": "GraphJin CLI - Build APIs in 5 minutes with GraphQL",
   "bin": {
     "graphjin": "bin/graphjin.js"