The Open Framework for Building Agents
fix(docs): links - honor frontmatter URL overrides (#138)
Andrew Barba156aae727c16
diff --git a/docs/concepts/default-harness.md b/docs/concepts/default-harness.mdindex 7225fb4b2..20f75de3f 100644--- a/docs/concepts/default-harness.md+++ b/docs/concepts/default-harness.md@@ -24,20 +24,20 @@ Compaction also preserves the framework's own tool state automatically. It resetThese ship with every agent, no imports. The harness shows the model the tool descriptors first, then executes only what the model actually calls; discovery never runs them. The shell and file tools (`bash`, `read_file`, `write_file`, `glob`, `grep`) live in the app runtime and proxy their work into the agent's single [sandbox](../sandbox); the rest run in the app runtime. The "Where it runs" column below names where each tool's effect lands.-| Tool | Does | Where it runs |-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |-| `bash` | Run a shell command. | Sandbox |-| `read_file` | Read a text file with line-numbered output (enables read-before-write). | Sandbox FS |-| `write_file` | Write a complete file; enforces read-before-write and stale-read detection. | Sandbox FS |-| `glob` | Find files by glob pattern. | Sandbox FS |-| `grep` | Search file contents by regex. | Sandbox FS |-| `web_fetch` | Fetch a URL. | App runtime |-| `web_search` | Search the web (provider-managed; resolved from the model provider). | Provider |-| `todo` | Maintain a durable per-session todo list. | App runtime |-| `ask_question` | Ask the user a clarifying question or a choice mid-turn and park until they answer. No `execute`; the model calls it with `{ prompt, options?, allowFreeform? }`. See [Human-in-the-loop](../tools/human-in-the-loop). | App runtime |-| `agent` | Delegate a subtask to a copy of itself (shares the parent sandbox + tools, fresh history/state). | App runtime |-| `load_skill` | Pull an on-demand [skill](../skills)'s instructions into the current turn. Present only when the agent declares skills. | App runtime |-| `connection_search` | Discover tools across declared [connections](../connections); matched tools become directly callable. Present only when the agent declares connections. | App runtime |+| Tool | Does | Where it runs |+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |+| `bash` | Run a shell command. | Sandbox |+| `read_file` | Read a text file with line-numbered output (enables read-before-write). | Sandbox FS |+| `write_file` | Write a complete file; enforces read-before-write and stale-read detection. | Sandbox FS |+| `glob` | Find files by glob pattern. | Sandbox FS |+| `grep` | Search file contents by regex. | Sandbox FS |+| `web_fetch` | Fetch a URL. | App runtime |+| `web_search` | Search the web (provider-managed; resolved from the model provider). | Provider |+| `todo` | Maintain a durable per-session todo list. | App runtime |+| `ask_question` | Ask the user a clarifying question or a choice mid-turn and park until they answer. No `execute`; the model calls it with `{ prompt, options?, allowFreeform? }`. See [Human-in-the-loop](/docs/human-in-the-loop). | App runtime |+| `agent` | Delegate a subtask to a copy of itself (shares the parent sandbox + tools, fresh history/state). | App runtime |+| `load_skill` | Pull an on-demand [skill](../skills)'s instructions into the current turn. Present only when the agent declares skills. | App runtime |+| `connection_search` | Discover tools across declared [connections](../connections); matched tools become directly callable. Present only when the agent declares connections. | App runtime |Notes:diff --git a/docs/concepts/sessions-runs-and-streaming.md b/docs/concepts/sessions-runs-and-streaming.mdindex 823604f5b..9d464f0f8 100644--- a/docs/concepts/sessions-runs-and-streaming.md+++ b/docs/concepts/sessions-runs-and-streaming.md@@ -34,33 +34,33 @@ curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/streamThe stream is newline-delimited JSON (NDJSON), one event per line:-| Event | Meaning |-| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |-| `session.started` | A durable session was created. |-| `turn.started` | A new turn began. |-| `message.received` | An inbound user message was accepted. |-| `step.started` | A model step began. |-| `actions.requested` | The model requested tool calls. |-| `action.result` | A tool call returned. |-| `input.requested` | The run paused for human input ([HITL](../tools/human-in-the-loop) approval or `ask_question`); carries `requests`. |-| `subagent.called` | A subagent was delegated; carries `childSessionId` to attach to. |-| `subagent.completed` | A delegated subagent finished. |-| `reasoning.appended` | A reasoning delta (incremental, with cumulative text so far). |-| `reasoning.completed` | The finalized reasoning block. |-| `message.appended` | An assistant text delta (incremental, with cumulative text so far). |-| `message.completed` | A finalized assistant text block. |-| `result.completed` | The finalized structured result for a turn that requested an output schema; carries `result`. |-| `compaction.requested` | Context-window compaction began; carries `modelId`, `sessionId`, `turnId`, `usageInputTokens`. |-| `compaction.completed` | A compaction checkpoint was written to durable history. |-| `authorization.required` | A connection needs OAuth; carries `name`, `description`, and an `authorization` challenge. |-| `authorization.completed` | A connection's authorization resolved; carries `outcome`. |-| `step.completed` | A model step finished; carries `finishReason` and usage. |-| `step.failed` | A model step failed; carries `{ code, message, details? }`. |-| `turn.completed` | The turn finished. |-| `turn.failed` | The turn failed; carries `{ code, message, details? }`. |-| `session.waiting` | The session parked, waiting for the next input (a message, an answer). |-| `session.failed` | The session failed. |-| `session.completed` | The session reached a terminal end. |+| Event | Meaning |+| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |+| `session.started` | A durable session was created. |+| `turn.started` | A new turn began. |+| `message.received` | An inbound user message was accepted. |+| `step.started` | A model step began. |+| `actions.requested` | The model requested tool calls. |+| `action.result` | A tool call returned. |+| `input.requested` | The run paused for human input ([HITL](/docs/human-in-the-loop) approval or `ask_question`); carries `requests`. |+| `subagent.called` | A subagent was delegated; carries `childSessionId` to attach to. |+| `subagent.completed` | A delegated subagent finished. |+| `reasoning.appended` | A reasoning delta (incremental, with cumulative text so far). |+| `reasoning.completed` | The finalized reasoning block. |+| `message.appended` | An assistant text delta (incremental, with cumulative text so far). |+| `message.completed` | A finalized assistant text block. |+| `result.completed` | The finalized structured result for a turn that requested an output schema; carries `result`. |+| `compaction.requested` | Context-window compaction began; carries `modelId`, `sessionId`, `turnId`, `usageInputTokens`. |+| `compaction.completed` | A compaction checkpoint was written to durable history. |+| `authorization.required` | A connection needs OAuth; carries `name`, `description`, and an `authorization` challenge. |+| `authorization.completed` | A connection's authorization resolved; carries `outcome`. |+| `step.completed` | A model step finished; carries `finishReason` and usage. |+| `step.failed` | A model step failed; carries `{ code, message, details? }`. |+| `turn.completed` | The turn finished. |+| `turn.failed` | The turn failed; carries `{ code, message, details? }`. |+| `session.waiting` | The session parked, waiting for the next input (a message, an answer). |+| `session.failed` | The session failed. |+| `session.completed` | The session reached a terminal end. |`reasoning.appended` and `message.appended` stream deltas as they arrive, and each one carries both the new delta and the cumulative text for the current block. The finalized block shows up on `message.completed` and `reasoning.completed`, which is the compatibility path for clients that don't render incremental streaming.diff --git a/docs/guides/frontend/overview.mdx b/docs/guides/frontend/overview.mdxindex 95a586491..63dc4c589 100644--- a/docs/guides/frontend/overview.mdx+++ b/docs/guides/frontend/overview.mdx@@ -100,7 +100,7 @@ Assistant text, reasoning, tool calls, and tool results stream into `data` as th## Human-in-the-loop prompts-Tools opt into approval with `needsApproval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](../../tools/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:+Tools opt into approval with `needsApproval`, and the model can also ask a question with `ask_question` — see [Human-in-the-loop](/docs/human-in-the-loop) for the server-side model. Either way the stream emits an `input.requested` event, and the pending request rides on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `send()`:```tsxconst request = agent.data.messagesdiff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjsindex 0e8bfcaef..bc3b02aef 100755--- a/scripts/check-docs.mjs+++ b/scripts/check-docs.mjs@@ -188,27 +188,36 @@ for (const root of ROOTS) {}// 3. Internal links resolve. Every relative (./ ../) or site-absolute (/docs/)-// markdown link in a doc page must point at a real doc page or folder.+// markdown link in a doc page must point at a rendered doc URL or folder.// fumadocs renders broken links as dead clicks; CI should catch them.+function renderedUrl(relPath, source) {+ const slug = relPath.replace(/\.mdx?$/, "").replace(/(^|\/)index$/, "");+ const override = parseFrontmatter(source)?.url;+ const route = override || `/${slug}`;+ return `/docs${route}`.replace(/\/$/, "");+}+function checkLinks(rootDir) {const files = walkMarkdown(rootDir);- const slugs = new Set();- const dirs = new Set();+ const renderedUrls = new Set();+ const renderedDirs = new Set();for (const abs of files) {const rel = relative(rootDir, abs).split("\\").join("/");- slugs.add(rel.replace(/\.mdx?$/, ""));- let d = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";- while (d) {- dirs.add(d);- d = d.includes("/") ? d.slice(0, d.lastIndexOf("/")) : "";+ if (isExcluded(rel)) continue;+ const source = readFileSync(abs, "utf8");+ renderedUrls.add(renderedUrl(rel, source));+ let dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";+ while (dir) {+ renderedDirs.add(`/docs/${dir}`);+ dir = dir.includes("/") ? dir.slice(0, dir.lastIndexOf("/")) : "";}}const linkRe = /\]\((\s*[^)]+?)\s*\)/g;for (const abs of files) {const rel = relative(rootDir, abs).split("\\").join("/");if (isExcluded(rel)) continue;- const dirOfFile = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";const source = readFileSync(abs, "utf8");+ const sourceUrl = renderedUrl(rel, source);let m;while ((m = linkRe.exec(source)) !== null) {let target = m[1].trim();@@ -219,22 +228,16 @@ function checkLinks(rootDir) {if (!isRel && !isSite) continue; // external, mailto, #anchor, bare /eve/* runtime route, etc.target = target.split("#")[0].split("?")[0];if (!target) continue; // pure in-page anchor- let resolvedSlug;- if (isSite) {- resolvedSlug = target.replace(/^\/docs\/?/, "");- } else {- const base = dirOfFile ? `${rootDir}/${dirOfFile}` : rootDir;- resolvedSlug = relative(rootDir, resolve(base, target)).split("\\").join("/");- }- resolvedSlug = resolvedSlug.replace(/\/$/, "").replace(/\.mdx?$/, "");- if (resolvedSlug === "" || resolvedSlug === ".") continue; // docs root / index- if (slugs.has(resolvedSlug)) continue;- if (slugs.has(`${resolvedSlug}/index`)) continue;- if (dirs.has(resolvedSlug)) continue; // folder link (sidebar group)+ const resolvedUrl = new URL(target, `https://eve.dev${sourceUrl}`).pathname+ .replace(/\/$/, "")+ .replace(/\.mdx?$/, "");+ if (resolvedUrl === "/docs") continue; // docs root / index+ if (renderedUrls.has(resolvedUrl)) continue;+ if (renderedDirs.has(resolvedUrl)) continue; // folder link (sidebar group)failures.push({root: "docs",file: rel,- issue: `broken internal link → \`${m[1].trim()}\` (resolves to \`${resolvedSlug}\`, no such page)`,+ issue: `broken internal link → \`${m[1].trim()}\` (resolves to \`${resolvedUrl}\`, no such page)`,});}}