diff --git a/agents/.skill-lock.json b/agents/.skill-lock.json index d116e02..42e6a4f 100644 --- a/agents/.skill-lock.json +++ b/agents/.skill-lock.json @@ -1,24 +1,6 @@ { "version": 3, "skills": { - "nano-banana-pro": { - "source": "intellectronica/agent-skills", - "sourceType": "github", - "sourceUrl": "https://github.com/intellectronica/agent-skills.git", - "skillPath": "skills/nano-banana-pro/SKILL.md", - "skillFolderHash": "eea680c3ebf9b8ae10ed99ea457f27af2bc05b19", - "installedAt": "2026-02-16T03:27:31.287Z", - "updatedAt": "2026-02-16T03:27:31.287Z" - }, - "find-skills": { - "source": "vercel-labs/skills", - "sourceType": "github", - "sourceUrl": "https://github.com/vercel-labs/skills.git", - "skillPath": "skills/find-skills/SKILL.md", - "skillFolderHash": "76a98a285cb0434f3d39e1a873823556330e398b", - "installedAt": "2026-02-16T03:30:57.972Z", - "updatedAt": "2026-07-11T07:02:15.192Z" - }, "playwright-cli": { "source": "microsoft/playwright-cli", "sourceType": "github", @@ -28,15 +10,6 @@ "installedAt": "2026-02-16T03:32:31.689Z", "updatedAt": "2026-07-10T09:03:00.602Z" }, - "agent-browser": { - "source": "vercel-labs/agent-browser", - "sourceType": "github", - "sourceUrl": "https://github.com/vercel-labs/agent-browser.git", - "skillPath": "skills/agent-browser/SKILL.md", - "skillFolderHash": "037e8078db4b20b4aa25c04f21c6de7d335ec449", - "installedAt": "2026-02-16T03:36:08.769Z", - "updatedAt": "2026-07-20T04:40:56.062Z" - }, "git-commit": { "source": "krosdai/skills", "sourceType": "github", @@ -55,232 +28,230 @@ "installedAt": "2026-02-28T19:07:45.593Z", "updatedAt": "2026-05-18T07:00:54.549Z" }, - "llm-context": { - "source": "brave/brave-search-skills", - "sourceType": "github", - "sourceUrl": "https://github.com/brave/brave-search-skills.git", - "skillPath": "skills/llm-context/SKILL.md", - "skillFolderHash": "48021337e75124af614c546d0e86640dfb8e63c6", - "installedAt": "2026-03-12T01:00:32.899Z", - "updatedAt": "2026-08-18T00:41:42.376Z" - }, - "manus": { - "source": "krosdai/skills", - "sourceType": "github", - "sourceUrl": "https://github.com/krosdai/skills.git", - "skillPath": "skills/manus/SKILL.md", - "skillFolderHash": "40fcb57439bb648197efc2ec015b089cf190dfde", - "installedAt": "2026-03-12T01:30:38.946Z", - "updatedAt": "2026-03-13T12:55:35.183Z" - }, - "greploop": { - "source": "greptileai/skills", - "sourceType": "github", - "sourceUrl": "https://github.com/greptileai/skills.git", - "skillPath": "greploop/SKILL.md", - "skillFolderHash": "fbef5a8a22b222d14fad7cb4dcb5af37065eb257", - "installedAt": "2026-03-30T16:10:26.002Z", - "updatedAt": "2026-07-22T06:04:14.987Z" - }, "lark-base": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-base/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-base/SKILL.md", + "skillFolderHash": "62cd8fb60cddb0d23b8b687556dd8ba7f62a68b4", "installedAt": "2026-04-01T15:50:08.850Z", - "updatedAt": "2026-08-04T18:05:37.348Z" + "updatedAt": "2026-08-19T18:10:24.988Z" }, "lark-calendar": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-calendar/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-calendar/SKILL.md", + "skillFolderHash": "631bee2f0c891459808691e29203975568141e0b", "installedAt": "2026-04-01T15:50:10.125Z", - "updatedAt": "2026-08-04T18:05:37.348Z" + "updatedAt": "2026-08-19T18:10:24.989Z" }, "lark-contact": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-contact/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-contact/SKILL.md", + "skillFolderHash": "ce95e8f616fe3016906c25524ebf54068b4905ae", "installedAt": "2026-04-01T15:50:11.228Z", - "updatedAt": "2026-08-04T18:05:37.348Z" + "updatedAt": "2026-08-19T18:10:24.989Z" }, "lark-doc": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-doc/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-doc/SKILL.md", + "skillFolderHash": "af52e47ff848d67ceb576da306698a8639521187", "installedAt": "2026-04-01T15:50:12.644Z", - "updatedAt": "2026-08-04T18:05:37.349Z" + "updatedAt": "2026-08-19T18:10:24.989Z" }, "lark-drive": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-drive/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-drive/SKILL.md", + "skillFolderHash": "69a4c7cd55aa419aa2f53f3cf5f328f4f50f58d5", "installedAt": "2026-04-01T15:50:13.472Z", - "updatedAt": "2026-08-04T18:05:37.349Z" + "updatedAt": "2026-08-19T18:10:24.989Z" }, "lark-event": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-event/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-event/SKILL.md", + "skillFolderHash": "095e9b13951088f8ad733a6368f4d195bf325315", "installedAt": "2026-04-01T15:50:14.386Z", - "updatedAt": "2026-08-04T18:05:37.349Z" + "updatedAt": "2026-08-19T18:10:24.990Z" }, "lark-im": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-im/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-im/SKILL.md", + "skillFolderHash": "87d1f95bbfc6f3df9e416ca36a1b7d7a4c09fb83", "installedAt": "2026-04-01T15:50:15.279Z", - "updatedAt": "2026-08-04T18:05:37.349Z" + "updatedAt": "2026-08-19T18:10:24.990Z" }, "lark-mail": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-mail/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-mail/SKILL.md", + "skillFolderHash": "a442e4d945ca30a214f9268aabd849f766291043", "installedAt": "2026-04-01T15:50:16.722Z", - "updatedAt": "2026-08-04T18:05:37.349Z" + "updatedAt": "2026-08-19T18:10:24.990Z" }, "lark-minutes": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-minutes/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-minutes/SKILL.md", + "skillFolderHash": "ed0448c2a38cab2495af2ecdb2c43bdb9baa75a3", "installedAt": "2026-04-01T15:50:17.630Z", - "updatedAt": "2026-08-04T18:05:37.350Z" + "updatedAt": "2026-08-19T18:10:24.991Z" }, "lark-openapi-explorer": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-openapi-explorer/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-openapi-explorer/SKILL.md", + "skillFolderHash": "b403a77f10cf342a01792241a3e77231842c438c", "installedAt": "2026-04-01T15:50:19.016Z", - "updatedAt": "2026-08-04T18:05:37.350Z" + "updatedAt": "2026-08-19T18:10:24.991Z" }, "lark-shared": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-shared/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-shared/SKILL.md", + "skillFolderHash": "1ee7e9dce1377a7038ab798e1ac5813ed608f4e1", "installedAt": "2026-04-01T15:50:20.533Z", - "updatedAt": "2026-08-04T18:05:37.350Z" + "updatedAt": "2026-08-19T18:10:24.992Z" }, "lark-sheets": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-sheets/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-sheets/SKILL.md", + "skillFolderHash": "97a53977beb2218d27ae04586e79dbc84ebf63be", "installedAt": "2026-04-01T15:50:21.514Z", - "updatedAt": "2026-08-04T18:05:37.351Z" + "updatedAt": "2026-08-19T18:10:24.992Z" }, "lark-skill-maker": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-skill-maker/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-skill-maker/SKILL.md", + "skillFolderHash": "f1f0673f26a0b5d2b6cf12454dd47253587f181e", "installedAt": "2026-04-01T15:50:22.416Z", - "updatedAt": "2026-08-04T18:05:37.351Z" + "updatedAt": "2026-08-19T18:10:24.992Z" }, "lark-task": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-task/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-task/SKILL.md", + "skillFolderHash": "b0ac4195cf86f1bd34396e7e1fb423a3ad9e9267", "installedAt": "2026-04-01T15:50:23.342Z", - "updatedAt": "2026-08-04T18:05:37.351Z" + "updatedAt": "2026-08-19T18:10:24.993Z" }, "lark-vc": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-vc/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-vc/SKILL.md", + "skillFolderHash": "aeb8b3a9130bee92d78865aa4861095c3cca786d", "installedAt": "2026-04-01T15:50:24.784Z", - "updatedAt": "2026-08-04T18:05:37.351Z" + "updatedAt": "2026-08-19T18:10:24.993Z" }, "lark-whiteboard": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-whiteboard/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-whiteboard/SKILL.md", + "skillFolderHash": "dc5eae804df0a67dd9ea9cb7ebe7f197bc31663f", "installedAt": "2026-04-01T15:50:25.690Z", - "updatedAt": "2026-08-04T18:05:37.352Z" + "updatedAt": "2026-08-19T18:10:24.993Z" }, "lark-wiki": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-wiki/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-wiki/SKILL.md", + "skillFolderHash": "f414d0100e7afa397a1084a3a31f299b1ae5b7a3", "installedAt": "2026-04-01T15:50:26.570Z", - "updatedAt": "2026-08-04T18:05:37.352Z" + "updatedAt": "2026-08-19T18:10:24.994Z" }, "lark-workflow-meeting-summary": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-workflow-meeting-summary/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-workflow-meeting-summary/SKILL.md", + "skillFolderHash": "558d1e6776d7c453929e21e6f439ca2e9bd9e040", "installedAt": "2026-04-01T15:50:27.293Z", - "updatedAt": "2026-08-04T18:05:37.352Z" + "updatedAt": "2026-08-19T18:10:24.994Z" }, "lark-workflow-standup-report": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-workflow-standup-report/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-workflow-standup-report/SKILL.md", + "skillFolderHash": "6525c6f1b0be0c0ae2d2c1bf6ef67ecbd64269e0", "installedAt": "2026-04-01T15:50:28.173Z", - "updatedAt": "2026-08-04T18:05:37.352Z" + "updatedAt": "2026-08-19T18:10:24.994Z" }, "lark-approval": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-approval/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-approval/SKILL.md", + "skillFolderHash": "5b26e4871fbc94f39791847e6b4e5cfebbab40d7", "installedAt": "2026-05-18T04:34:00.070Z", - "updatedAt": "2026-08-04T18:05:37.347Z" + "updatedAt": "2026-08-19T18:10:24.987Z" }, "lark-attendance": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-attendance/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-attendance/SKILL.md", + "skillFolderHash": "4702032975fb1a4c50aa16a82cbb6db1e14c371c", "installedAt": "2026-05-18T04:34:00.074Z", - "updatedAt": "2026-08-04T18:05:37.348Z" + "updatedAt": "2026-08-19T18:10:24.988Z" }, "lark-markdown": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-markdown/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-markdown/SKILL.md", + "skillFolderHash": "0a74659f8148ed276290317074b50e225eadaa61", "installedAt": "2026-05-18T04:34:00.079Z", - "updatedAt": "2026-08-04T18:05:37.350Z" + "updatedAt": "2026-08-19T18:10:24.990Z" }, "lark-okr": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-okr/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-okr/SKILL.md", + "skillFolderHash": "588832ba72cc5405927bba76c1ba859fa228e3b1", "installedAt": "2026-05-18T04:34:00.079Z", - "updatedAt": "2026-08-04T18:05:37.350Z" + "updatedAt": "2026-08-19T18:10:24.991Z" }, "lark-slides": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-slides/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-slides/SKILL.md", + "skillFolderHash": "dddebdc4c9adb9800124d443499b32e7b6b12c91", "installedAt": "2026-05-18T04:34:00.082Z", - "updatedAt": "2026-08-04T18:05:37.351Z" + "updatedAt": "2026-08-19T18:10:24.992Z" }, "lark-vc-agent": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-vc-agent/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-vc-agent/SKILL.md", + "skillFolderHash": "fa130825ccee05681057d0a6e02814893af97254", "installedAt": "2026-05-18T04:34:00.083Z", - "updatedAt": "2026-08-04T18:05:37.351Z" + "updatedAt": "2026-08-19T18:10:24.993Z" }, "audience-aware-comms": { "source": "krosdai/skills", @@ -310,20 +281,22 @@ "updatedAt": "2026-06-26T14:54:22.111Z" }, "lark-apps": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-apps/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-apps/SKILL.md", + "skillFolderHash": "186f300ca6c54c65f5dcc704476872682edf1d64", "installedAt": "2026-06-25T16:46:17.631Z", - "updatedAt": "2026-08-04T18:05:37.347Z" + "updatedAt": "2026-08-19T18:10:24.988Z" }, "lark-note": { - "source": "open.feishu.cn", - "sourceType": "well-known", - "sourceUrl": "https://open.feishu.cn/.well-known/skills/lark-note/SKILL.md", - "skillFolderHash": "", + "source": "larksuite/cli", + "sourceType": "github", + "sourceUrl": "https://github.com/larksuite/cli.git", + "skillPath": "skills/lark-note/SKILL.md", + "skillFolderHash": "3cb4fe33cc1e03b283289f913cd38762ad780485", "installedAt": "2026-06-25T16:46:17.635Z", - "updatedAt": "2026-08-04T18:05:37.350Z" + "updatedAt": "2026-08-19T18:10:24.991Z" }, "steel-browser": { "source": "steel-dev/skills", @@ -375,9 +348,18 @@ "sourceType": "github", "sourceUrl": "https://github.com/herdrdev/herdr.git", "skillPath": "skills/herdr/SKILL.md", - "skillFolderHash": "4821f1d39ccae24b9b274b03184edaaf198a3994", + "skillFolderHash": "f8bb649bb92ddc99e6af463ab9a635da98c7b129", "installedAt": "2026-08-14T10:00:06.267Z", - "updatedAt": "2026-08-18T00:41:54.602Z" + "updatedAt": "2026-08-19T18:03:51.276Z" + }, + "wrangler": { + "source": "cloudflare/skills", + "sourceType": "github", + "sourceUrl": "https://github.com/cloudflare/skills.git", + "skillPath": "skills/wrangler/SKILL.md", + "skillFolderHash": "45cc198b2aad3f06e8abf91333f55fbe7579f659", + "installedAt": "2026-08-19T18:08:38.308Z", + "updatedAt": "2026-08-19T18:08:38.308Z" } }, "dismissed": { diff --git a/agents/skills/agent-browser/SKILL.md b/agents/skills/agent-browser/SKILL.md deleted file mode 100644 index bdd73cc..0000000 --- a/agents/skills/agent-browser/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: agent-browser -description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools. -allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*) -hidden: true ---- - -# agent-browser - -Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with accessibility-tree snapshots and compact `@eN` element refs. - -Install: `npm i -g agent-browser && agent-browser install` - -## Start here - -This file is a discovery stub, not the usage guide. Before running any `agent-browser` command, load the actual workflow content from the CLI: - -```bash -agent-browser skills get core # start here — workflows, common patterns, troubleshooting -agent-browser skills get core --full # include full command reference and templates -``` - -The CLI serves skill content that always matches the installed version, so instructions never go stale. The content in this stub cannot change between releases, which is why it just points at `skills get core`. - -## Specialized skills - -Load a specialized skill when the task falls outside browser web pages: - -```bash -agent-browser skills get electron # Electron desktop apps (VS Code, Slack, Discord, Figma, ...) -agent-browser skills get slack # Slack workspace automation -agent-browser skills get dogfood # Exploratory testing / QA / bug hunts -agent-browser skills get vercel-sandbox # agent-browser inside Vercel Sandbox microVMs -agent-browser skills get agentcore # AWS Bedrock AgentCore cloud browsers -``` - -Run `agent-browser skills list` to see everything available on the installed version. - -## Why agent-browser - -- Fast native Rust CLI, not a Node.js wrapper -- Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.) -- Chrome/Chromium via CDP with no Playwright or Puppeteer dependency -- Accessibility-tree snapshots with element refs for reliable interaction -- Sessions, authentication vault, state persistence, video recording -- Specialized skills for Electron apps, Slack, exploratory testing, cloud providers - -## Observability Dashboard - -The dashboard runs independently of browser sessions on port 4848 and can also be opened through a proxied or forwarded URL such as `https://dashboard.agent-browser.localhost`. Agents should stay on the dashboard origin: session tabs, status, and stream traffic are proxied internally, so session ports do not need to be exposed. diff --git a/agents/skills/agents-sdk/SKILL.md b/agents/skills/agents-sdk/SKILL.md deleted file mode 100644 index d9f1c8a..0000000 --- a/agents/skills/agents-sdk/SKILL.md +++ /dev/null @@ -1,221 +0,0 @@ ---- -name: agents-sdk -description: Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge. ---- - -# Cloudflare Agents SDK - -Your knowledge of the Agents SDK may be outdated. **Prefer retrieval over pre-training** for any Agents SDK task. - -## Retrieval Sources - -Cloudflare docs: https://developers.cloudflare.com/agents/ - -| Topic | Docs URL | Use for | -|-------|----------|---------| -| Getting started | [Quick start](https://developers.cloudflare.com/agents/getting-started/quick-start/) | First agent, project setup | -| Adding to existing project | [Add to existing project](https://developers.cloudflare.com/agents/getting-started/add-to-existing-project/) | Install into existing Workers app | -| Configuration | [Configuration](https://developers.cloudflare.com/agents/api-reference/configuration/) | `wrangler.jsonc`, bindings, assets, deployment | -| Agent class | [Agents API](https://developers.cloudflare.com/agents/api-reference/agents-api/) | Agent lifecycle, patterns, pitfalls | -| State | [Store and sync state](https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/) | `setState`, `validateStateChange`, persistence | -| Routing | [Routing](https://developers.cloudflare.com/agents/api-reference/routing/) | URL patterns, `routeAgentRequest` | -| Callable methods | [Callable methods](https://developers.cloudflare.com/agents/api-reference/callable-methods/) | `@callable`, RPC, streaming, timeouts | -| Scheduling | [Schedule tasks](https://developers.cloudflare.com/agents/api-reference/schedule-tasks/) | `schedule()`, `scheduleEvery()`, cron | -| Workflows | [Run workflows](https://developers.cloudflare.com/agents/api-reference/run-workflows/) | `AgentWorkflow`, durable multi-step tasks | -| HTTP/WebSockets | [WebSockets](https://developers.cloudflare.com/agents/api-reference/websockets/) | Lifecycle hooks, hibernation | -| Chat agents | [Chat agents](https://developers.cloudflare.com/agents/api-reference/chat-agents/) | `AIChatAgent`, streaming, tools, persistence | -| Client SDK | [Client SDK](https://developers.cloudflare.com/agents/api-reference/client-sdk/) | `useAgent`, `useAgentChat`, React hooks | -| Client tools | [Client tools](https://developers.cloudflare.com/agents/api-reference/client-tools/) | Client-side tools, `autoContinueAfterToolResult` | -| Server-driven messages | [Trigger patterns](https://developers.cloudflare.com/agents/api-reference/trigger-patterns/) | `saveMessages`, `waitUntilStable`, server-initiated turns | -| Resumable streaming | [Resumable streaming](https://developers.cloudflare.com/agents/api-reference/resumable-streaming/) | Stream recovery on disconnect | -| Email | [Email](https://developers.cloudflare.com/agents/api-reference/email/) | Email routing, secure reply resolver | -| MCP client | [MCP client](https://developers.cloudflare.com/agents/api-reference/mcp-client-api/) | Connecting to MCP servers | -| MCP server | [MCP server](https://developers.cloudflare.com/agents/api-reference/mcp-agent-api/) | Building MCP servers with `McpAgent` | -| MCP transports | [MCP transports](https://developers.cloudflare.com/agents/api-reference/mcp-transports/) | Streamable HTTP, SSE, RPC transport options | -| Securing MCP servers | [Securing MCP](https://developers.cloudflare.com/agents/api-reference/securing-mcp-servers/) | OAuth, proxy MCP, hardening | -| Human-in-the-loop | [Human-in-the-loop](https://developers.cloudflare.com/agents/concepts/human-in-the-loop/) | Approval flows, `needsApproval`, workflows | -| Durable execution | [Durable execution](https://developers.cloudflare.com/agents/api-reference/durable-execution/) | `runFiber()`, `stash()`, surviving DO eviction | -| Queue | [Queue](https://developers.cloudflare.com/agents/api-reference/queue-tasks/) | Built-in FIFO queue, `queue()` | -| Retries | [Retries](https://developers.cloudflare.com/agents/api-reference/retries/) | `this.retry()`, backoff/jitter | -| Observability | [Observability](https://developers.cloudflare.com/agents/api-reference/observability/) | Diagnostics-channel events | -| Push notifications | [Push notifications](https://developers.cloudflare.com/agents/api-reference/push-notifications/) | Web Push + VAPID from agents | -| Webhooks | [Webhooks](https://developers.cloudflare.com/agents/api-reference/webhooks/) | Receiving external webhooks | -| Cross-domain auth | [Cross-domain auth](https://developers.cloudflare.com/agents/api-reference/cross-domain-authentication/) | WebSocket auth, tokens, CORS | -| Readonly connections | [Readonly](https://developers.cloudflare.com/agents/api-reference/readonly-connections/) | `shouldConnectionBeReadonly` | -| Voice | [Voice](https://developers.cloudflare.com/agents/api-reference/voice/) | Experimental STT/TTS, `withVoice` | -| Browse the web | [Browser tools](https://developers.cloudflare.com/agents/api-reference/browse-the-web/) | Experimental CDP browser automation | -| Think | [Think](https://developers.cloudflare.com/agents/api-reference/think/) | Experimental higher-level chat agent class | -| Migrations | [AI SDK v5](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v5/), [AI SDK v6](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v6/) | Upgrading `@cloudflare/ai-chat` | - -## Capabilities - -The Agents SDK provides: - -- **Persistent state** — SQLite-backed, auto-synced to clients via `setState` -- **Callable RPC** — `@callable()` methods invoked over WebSocket -- **Scheduling** — One-time, recurring (`scheduleEvery`), and cron tasks -- **Workflows** — Durable multi-step background processing via `AgentWorkflow` -- **Durable execution** — `runFiber()` / `stash()` for work that survives DO eviction -- **Queue** — Built-in FIFO queue with retries via `queue()` -- **Retries** — `this.retry()` with exponential backoff and jitter -- **MCP integration** — Connect to MCP servers or build your own with `McpAgent` -- **Email handling** — Receive and reply to emails with secure routing -- **Streaming chat** — `AIChatAgent` with resumable streams, message persistence, tools -- **Server-driven messages** — `saveMessages`, `waitUntilStable` for proactive agent turns -- **React hooks** — `useAgent`, `useAgentChat` for client apps -- **Observability** — `diagnostics_channel` events for state, RPC, schedule, lifecycle -- **Push notifications** — Web Push + VAPID delivery from agents -- **Webhooks** — Receive and verify external webhooks -- **Voice** (experimental) — STT/TTS via `@cloudflare/voice` -- **Browser tools** (experimental) — CDP-powered browsing via `agents/browser` -- **Think** (experimental) — Higher-level chat agent via `@cloudflare/think` - -## FIRST: Verify Installation - -```bash -npm ls agents # Should show agents package -``` - -If not installed: -```bash -npm install agents -``` - -For chat agents: -```bash -npm install agents @cloudflare/ai-chat ai @ai-sdk/react -``` - -## Wrangler Configuration - -```jsonc -{ - "compatibility_flags": ["nodejs_compat"], - "durable_objects": { - "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }] - }, - "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }] -} -``` - -**Gotchas:** -- Do NOT enable `experimentalDecorators` in tsconfig (breaks `@callable`) -- Never edit old migrations — always add new tags -- Each agent class needs its own DO binding + migration entry -- Add `"ai": { "binding": "AI" }` for Workers AI - -## Agent Class - -```typescript -import { Agent, routeAgentRequest, callable } from "agents"; - -type State = { count: number }; - -export class Counter extends Agent { - initialState = { count: 0 }; - - validateStateChange(nextState: State, source: Connection | "server") { - if (nextState.count < 0) throw new Error("Count cannot be negative"); - } - - onStateUpdate(state: State, source: Connection | "server") { - console.log("State updated:", state); - } - - @callable() - increment() { - this.setState({ count: this.state.count + 1 }); - return this.state.count; - } -} - -export default { - fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 }) -}; -``` - -## Routing - -Requests route to `/agents/{agent-name}/{instance-name}`: - -| Class | URL | -|-------|-----| -| `Counter` | `/agents/counter/user-123` | -| `ChatRoom` | `/agents/chat-room/lobby` | - -Client: `useAgent({ agent: "Counter", name: "user-123" })` - -Custom routing: use `getAgentByName(env.MyAgent, "instance-id")` then `agent.fetch(request)`. - -## Core APIs - -| Task | API | -|------|-----| -| Read state | `this.state.count` | -| Write state | `this.setState({ count: 1 })` | -| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` | -| Schedule (delay) | `await this.schedule(60, "task", payload)` | -| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` | -| Schedule (interval) | `await this.scheduleEvery(30, "poll")` | -| RPC method | `@callable() myMethod() { ... }` | -| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` | -| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` | -| Durable fiber | `await this.runFiber("name", async (ctx) => { ... })` | -| Enqueue work | `this.queue("handler", payload)` | -| Retry with backoff | `await this.retry(fn, { maxAttempts: 5 })` | -| Broadcast to clients | `this.broadcast(message)` | -| Get connections | `this.getConnections(tag?)` | - -## React Client - -```tsx -import { useAgent } from "agents/react"; - -function App() { - const [state, setLocalState] = useState({ count: 0 }); - - const agent = useAgent({ - agent: "Counter", - name: "my-instance", - onStateUpdate: (newState) => setLocalState(newState), - onIdentity: (name, agentType) => console.log(`Connected to ${name}`) - }); - - return ( - - ); -} -``` - -## References - -### Core -- **[references/state-scheduling.md](references/state-scheduling.md)** — State persistence, scheduling, SQL -- **[references/callable.md](references/callable.md)** — RPC methods, streaming, timeouts -- **[references/routing.md](references/routing.md)** — URL patterns, custom routing, `getAgentByName` -- **[references/configuration.md](references/configuration.md)** — Wrangler config, bindings, Vite setup - -### Chat & Streaming -- **[references/streaming-chat.md](references/streaming-chat.md)** — AIChatAgent, resumable streams, tools -- **[references/client-sdk.md](references/client-sdk.md)** — `useAgent`, `useAgentChat`, `AgentClient` -- **[references/server-driven-messages.md](references/server-driven-messages.md)** — Trigger patterns, `saveMessages` -- **[references/human-in-the-loop.md](references/human-in-the-loop.md)** — Approval flows, `needsApproval` - -### Background Processing -- **[references/workflows.md](references/workflows.md)** — Durable Workflows integration -- **[references/durable-execution.md](references/durable-execution.md)** — `runFiber`, `stash`, surviving eviction -- **[references/queue-retries.md](references/queue-retries.md)** — Built-in queue, retry with backoff - -### Integrations -- **[references/mcp.md](references/mcp.md)** — MCP client and server, transports, securing -- **[references/email.md](references/email.md)** — Email routing and handling -- **[references/webhooks-push.md](references/webhooks-push.md)** — Webhooks, push notifications -- **[references/observability.md](references/observability.md)** — Diagnostics-channel events - -### Experimental -- **[references/think.md](references/think.md)** — `@cloudflare/think` higher-level chat agent -- **[references/voice.md](references/voice.md)** — `@cloudflare/voice` STT/TTS -- **[references/codemode.md](references/codemode.md)** — Code Mode for tool orchestration -- **[references/browse-the-web.md](references/browse-the-web.md)** — CDP browser tools diff --git a/agents/skills/agents-sdk/references/browse-the-web.md b/agents/skills/agents-sdk/references/browse-the-web.md deleted file mode 100644 index 115e74e..0000000 --- a/agents/skills/agents-sdk/references/browse-the-web.md +++ /dev/null @@ -1,63 +0,0 @@ -# Browse the Web (Experimental) - -Fetch https://developers.cloudflare.com/agents/api-reference/browse-the-web/ for complete documentation. - -CDP-powered browser tools that let agents scrape, screenshot, and interact with web pages. - -## Setup - -```jsonc -// wrangler.jsonc -{ - "browser": { "binding": "BROWSER" }, - "worker_loaders": [{ "binding": "LOADER" }], - "compatibility_flags": ["nodejs_compat"] -} -``` - -## Usage with AI SDK - -```typescript -import { createBrowserTools } from "agents/browser/ai"; - -export class MyAgent extends AIChatAgent { - async onChatMessage(onFinish) { - const browserTools = createBrowserTools({ - browser: this.env.BROWSER, - loader: this.env.LOADER - }); - - const result = streamText({ - model: openai("gpt-4o"), - messages: await convertToModelMessages(this.messages), - tools: { ...myTools, ...browserTools }, - onFinish - }); - return result.toUIMessageStreamResponse(); - } -} -``` - -## Available Tools - -| Tool | Purpose | -|------|---------| -| `browser_search` | Search the web and return results | -| `browser_execute` | Navigate to URL, execute JS, return results | - -The LLM writes async JavaScript IIFEs that run in a fresh browser session. - -## When to Use - -- Need a real browser (JS rendering, screenshots, interaction) → browser tools -- Just need HTML/API data → use `fetch()` instead (faster, cheaper) - -## Low-Level API - -```typescript -import { connectBrowser, CdpSession } from "agents/browser"; - -const browser = await connectBrowser(this.env.BROWSER); -const cdp = new CdpSession(browser); -await cdp.send("Page.navigate", { url: "https://example.com" }); -``` diff --git a/agents/skills/agents-sdk/references/callable.md b/agents/skills/agents-sdk/references/callable.md deleted file mode 100644 index 3c885c0..0000000 --- a/agents/skills/agents-sdk/references/callable.md +++ /dev/null @@ -1,92 +0,0 @@ -# Callable Methods - -Fetch https://developers.cloudflare.com/agents/api-reference/callable-methods/ for complete documentation. - -## Overview - -`@callable()` exposes agent methods to clients via WebSocket RPC. - -```typescript -import { Agent, callable } from "agents"; - -export class MyAgent extends Agent { - @callable() - async greet(name: string): Promise { - return `Hello, ${name}!`; - } - - @callable() - async processData(data: unknown): Promise { - // Long-running work - return result; - } -} -``` - -## Client Usage - -```typescript -// Basic call -const greeting = await agent.call("greet", ["World"]); - -// With timeout -const result = await agent.call("processData", [data], { - timeout: 5000 // 5 second timeout -}); -``` - -## Streaming Responses - -```typescript -import { Agent, callable, StreamingResponse } from "agents"; - -export class MyAgent extends Agent { - @callable({ streaming: true }) - async streamResults(stream: StreamingResponse, query: string) { - for await (const item of fetchResults(query)) { - stream.send(JSON.stringify(item)); - } - stream.close(); - } - - @callable({ streaming: true }) - async streamWithError(stream: StreamingResponse) { - try { - // ... work - } catch (error) { - stream.error(error.message); // Signal error to client - return; - } - stream.close(); - } -} -``` - -Client with streaming: - -```typescript -await agent.call("streamResults", ["search term"], { - stream: { - onChunk: (data) => console.log("Chunk:", data), - onDone: () => console.log("Complete"), - onError: (error) => console.error("Error:", error) - } -}); -``` - -## Introspection - -```typescript -// Get list of callable methods on an agent -const methods = await agent.call("getCallableMethods", []); -// Returns: ["greet", "processData", "streamResults", ...] -``` - -## When to Use - -| Scenario | Use | -|----------|-----| -| Browser/mobile calling agent | `@callable()` | -| External service calling agent | `@callable()` | -| Worker calling agent (same codebase) | DO RPC directly | -| Agent calling another agent | `getAgentByName()` + DO RPC | diff --git a/agents/skills/agents-sdk/references/client-sdk.md b/agents/skills/agents-sdk/references/client-sdk.md deleted file mode 100644 index b4abc53..0000000 --- a/agents/skills/agents-sdk/references/client-sdk.md +++ /dev/null @@ -1,110 +0,0 @@ -# Client SDK - -Fetch https://developers.cloudflare.com/agents/api-reference/client-sdk/ for complete documentation. - -## React: `useAgent` - -```tsx -import { useAgent } from "agents/react"; - -function App() { - const [state, setState] = useState({ count: 0 }); - - const agent = useAgent({ - agent: "Counter", - name: "my-instance", - onStateUpdate: (newState) => setState(newState), - onIdentity: (name, agentType) => console.log(`Connected to ${name}`) - }); - - return ; -} -``` - -### Typed RPC via `stub` - -```tsx -const agent = useAgent({ - agent: "MyAgent", - name: "default" -}); - -const result = await agent.stub.myMethod(arg1, arg2); -``` - -### Auth via Query Params - -```tsx -useAgent({ - agent: "MyAgent", - name: "default", - query: async () => `token=${await getToken()}`, - queryDeps: [tokenVersion] -}); -``` - -## React: `useAgentChat` - -```tsx -import { useAgent } from "agents/react"; -import { useAgentChat } from "@cloudflare/ai-chat/react"; - -function Chat() { - const agent = useAgent({ agent: "ChatAgent", name: "session-1" }); - - const { messages, input, handleInputChange, handleSubmit, status } = - useAgentChat({ agent }); - - return ( -
- {messages.map((m) =>
{m.role}: {m.content}
)} -
- -
-
- ); -} -``` - -## Vanilla JS: `AgentClient` - -```typescript -import { AgentClient } from "agents/client"; - -const client = new AgentClient({ - agent: "MyAgent", - name: "default", - host: "https://my-worker.workers.dev" -}); - -client.addEventListener("stateUpdate", (e) => console.log(e.state)); -const result = await client.call("myMethod", [arg]); -client.close(); -``` - -## `agentFetch` for HTTP-only - -```typescript -import { agentFetch } from "agents/client"; - -const response = await agentFetch({ - agent: "MyAgent", - name: "default", - host: "https://my-worker.workers.dev", - path: "/api/data" -}); -``` - -## Streaming RPC - -```typescript -await agent.call("streamResults", ["query"], { - stream: { - onChunk: (data) => console.log(data), - onDone: () => console.log("done"), - onError: (err) => console.error(err) - } -}); -``` diff --git a/agents/skills/agents-sdk/references/codemode.md b/agents/skills/agents-sdk/references/codemode.md deleted file mode 100644 index d5e5a85..0000000 --- a/agents/skills/agents-sdk/references/codemode.md +++ /dev/null @@ -1,110 +0,0 @@ -# Codemode (Experimental) - -Fetch https://developers.cloudflare.com/agents/api-reference/codemode/ for complete documentation. - -Codemode lets LLMs write and execute code that orchestrates your tools, instead of calling them one at a time. The LLM gets a single "write code" tool; generated JavaScript runs in an isolated Worker sandbox. - -## When to Use - -| Scenario | Use Codemode? | -|----------|---------------| -| Single tool call | No — standard tool calling is simpler | -| Chained tool calls with logic | Yes | -| Conditional logic across tools | Yes | -| MCP multi-server workflows | Yes | -| Simple Q&A chat | No | - -## Setup - -### Wrangler Config - -```jsonc -{ - "worker_loaders": [{ "binding": "LOADER" }], - "compatibility_flags": ["nodejs_compat"] -} -``` - -### Install - -```bash -npm install @cloudflare/codemode ai zod -``` - -## Usage - -```typescript -import { createCodeTool } from "@cloudflare/codemode/ai"; -import { DynamicWorkerExecutor } from "@cloudflare/codemode"; -import { streamText, tool, convertToModelMessages } from "ai"; -import { z } from "zod"; - -const tools = { - getWeather: tool({ - description: "Get weather for a location", - inputSchema: z.object({ location: z.string() }), - execute: async ({ location }) => `Weather: ${location} 72°F` - }), - sendEmail: tool({ - description: "Send an email", - inputSchema: z.object({ to: z.string(), subject: z.string(), body: z.string() }), - execute: async ({ to, subject, body }) => `Email sent to ${to}` - }) -}; - -export class MyAgent extends Agent { - async onChatMessage() { - const executor = new DynamicWorkerExecutor({ - loader: this.env.LOADER - }); - - const codemode = createCodeTool({ tools, executor }); - - const result = streamText({ - model, - system: "You are a helpful assistant.", - messages: await convertToModelMessages(this.messages), - tools: { codemode } - }); - - return result.toUIMessageStreamResponse(); - } -} -``` - -## With MCP Tools - -```typescript -const codemode = createCodeTool({ - tools: { - ...myTools, - ...this.mcp.getAITools() - }, - executor -}); -``` - -## How It Works - -1. `createCodeTool` generates TypeScript type definitions from your tools -2. The LLM writes an async arrow function calling `codemode.toolName(args)` -3. Code runs in an isolated Worker sandbox via `DynamicWorkerExecutor` -4. Tool calls route back to the host via Workers RPC -5. External `fetch()` is blocked by default — sandbox can only call your tools - -## Network Isolation - -```typescript -const executor = new DynamicWorkerExecutor({ - loader: env.LOADER, - globalOutbound: null // default — fully isolated - // globalOutbound: env.MY_SERVICE // route through a Fetcher -}); -``` - -## Limitations - -- Experimental — API may change -- `needsApproval` tools execute immediately in sandbox (no approval pause yet) -- JavaScript execution only -- Requires `worker_loaders` binding diff --git a/agents/skills/agents-sdk/references/configuration.md b/agents/skills/agents-sdk/references/configuration.md deleted file mode 100644 index 0dc9e82..0000000 --- a/agents/skills/agents-sdk/references/configuration.md +++ /dev/null @@ -1,72 +0,0 @@ -# Configuration - -Fetch https://developers.cloudflare.com/agents/api-reference/configuration/ for complete documentation. - -## Wrangler Config (`wrangler.jsonc`) - -```jsonc -{ - "name": "my-agent", - "main": "src/index.ts", - "compatibility_date": "2025-01-28", - "compatibility_flags": ["nodejs_compat"], - "durable_objects": { - "bindings": [ - { "name": "MyAgent", "class_name": "MyAgent" }, - { "name": "ChatAgent", "class_name": "ChatAgent" } - ] - }, - "migrations": [ - { "tag": "v1", "new_sqlite_classes": ["MyAgent", "ChatAgent"] } - ], - "ai": { "binding": "AI" }, - "assets": { - "directory": "./dist/client", - "binding": "ASSETS", - "not_found_handling": "single-page-application", - "run_worker_first": true - } -} -``` - -## Key Rules - -- Every agent class needs a DO binding AND a `new_sqlite_classes` migration entry -- `nodejs_compat` is required -- Never edit old migrations — add a new tag (e.g. `v2`) for new classes -- Do NOT enable `experimentalDecorators` in tsconfig — it breaks `@callable` -- For Workers AI locally, set `"ai": { "binding": "AI", "remote": true }` in `.dev.vars` or config -- Use `wrangler secret put` for secrets, never hardcode them - -## Vite Setup - -```typescript -import { defineConfig } from "vite"; -import react from "@vitejs/plugin-react"; -import { cloudflare } from "@cloudflare/vite-plugin"; -import { agents } from "agents/vite"; - -export default defineConfig({ - plugins: [react(), cloudflare(), agents()] -}); -``` - -## Type Generation - -```bash -npx wrangler types -``` - -This generates `env.d.ts` with typed bindings. Regenerate after changing `wrangler.jsonc`. - -## tsconfig - -Extend the agents tsconfig for correct settings: - -```jsonc -{ - "extends": ["agents/tsconfig"], - "include": ["src/**/*.ts", "src/**/*.tsx"], - "compilerOptions": { "paths": { "~/*": ["./src/*"] } } -} -``` diff --git a/agents/skills/agents-sdk/references/durable-execution.md b/agents/skills/agents-sdk/references/durable-execution.md deleted file mode 100644 index e75b5e8..0000000 --- a/agents/skills/agents-sdk/references/durable-execution.md +++ /dev/null @@ -1,51 +0,0 @@ -# Durable Execution - -Fetch https://developers.cloudflare.com/agents/api-reference/durable-execution/ for complete documentation. - -Fibers let agent work survive Durable Object eviction. Progress is checkpointed to SQLite; on recovery, you decide what to do. - -## `runFiber` - -```typescript -export class MyAgent extends Agent { - async onRequest(request: Request) { - await this.runFiber("process-data", async (ctx) => { - const step1 = await fetchData(); - ctx.stash({ step: 1, data: step1 }); - - const step2 = await transform(step1); - ctx.stash({ step: 2, result: step2 }); - - this.setState({ result: step2 }); - }); - return new Response("Started"); - } - - async onFiberRecovered(ctx) { - const checkpoint = ctx.stash; - if (checkpoint.step === 1) { - const step2 = await transform(checkpoint.data); - this.setState({ result: step2 }); - } - } -} -``` - -## Key APIs - -| API | Purpose | -|-----|---------| -| `this.runFiber(name, fn)` | Start a named fiber | -| `ctx.stash` / `this.stash` | Read latest checkpoint | -| `ctx.stash = data` | Write checkpoint (JSON-serializable) | -| `onFiberRecovered(ctx)` | Called on DO restart if fiber was in-flight | -| `keepAlive()` | Prevent hibernation while fiber runs | -| `keepAliveWhile(fn)` | Keep alive for duration of async function | - -## Important - -- `stash` replaces the entire checkpoint — not a merge -- The lambda is NOT restored on recovery — only the stash data is. You must re-derive what to do in `onFiberRecovered` -- No auto-retry on throw — handle errors yourself -- For long-running pipelines with automatic retries, use Workflows instead -- Filter concurrent fibers by `ctx.name` in `onFiberRecovered` diff --git a/agents/skills/agents-sdk/references/email.md b/agents/skills/agents-sdk/references/email.md deleted file mode 100644 index b7efaa5..0000000 --- a/agents/skills/agents-sdk/references/email.md +++ /dev/null @@ -1,146 +0,0 @@ -# Email Handling - -Fetch https://developers.cloudflare.com/agents/api-reference/email/ for complete documentation. - -## Overview - -Agents receive and reply to emails via Cloudflare Email Routing. - -## Wrangler Configuration - -```jsonc -{ - "durable_objects": { - "bindings": [{ "name": "EmailAgent", "class_name": "EmailAgent" }] - }, - "migrations": [{ "tag": "v1", "new_sqlite_classes": ["EmailAgent"] }], - "send_email": [ - { "name": "SEB", "destination_address": "reply@yourdomain.com" } - ] -} -``` - -## Basic Email Handler - -```typescript -import { Agent } from "agents"; -import { type AgentEmail } from "agents/email"; -import PostalMime from "postal-mime"; - -export class EmailAgent extends Agent { - async onEmail(email: AgentEmail) { - const raw = await email.getRaw(); - const parsed = await PostalMime.parse(raw); - - console.log("From:", email.from); - console.log("Subject:", parsed.subject); - - await this.replyToEmail(email, { - fromName: "My Agent", - subject: `Re: ${parsed.subject}`, - body: "Thanks for your email!" - }); - } -} -``` - -## Routing Emails - -```typescript -import { routeAgentRequest, routeAgentEmail } from "agents"; -import { createAddressBasedEmailResolver } from "agents/email"; - -export default { - async email(message, env) { - await routeAgentEmail(message, env, { - resolver: createAddressBasedEmailResolver("EmailAgent") - }); - }, - - async fetch(request, env) { - return routeAgentRequest(request, env) ?? new Response("Not found", { status: 404 }); - } -}; -``` - -## Resolvers - -### Address-Based (Inbound Mail) - -Routes based on recipient address: - -```typescript -import { createAddressBasedEmailResolver } from "agents/email"; - -const resolver = createAddressBasedEmailResolver("EmailAgent"); -// support@example.com → EmailAgent, instance "support" -// NotificationAgent+user123@example.com → NotificationAgent, instance "user123" -``` - -### Secure Reply (Reply Flows) - -Verifies replies are authentic using HMAC-SHA256 signatures: - -```typescript -import { createSecureReplyEmailResolver } from "agents/email"; - -const resolver = createSecureReplyEmailResolver(env.EMAIL_SECRET, { - maxAge: 7 * 24 * 60 * 60, // 7 days (default: 30 days) - onInvalidSignature: (email, reason) => { - console.warn(`Invalid signature from ${email.from}: ${reason}`); - } -}); -``` - -Sign outbound emails to enable secure reply routing: - -```typescript -await this.replyToEmail(email, { - fromName: "My Agent", - body: "Thanks!", - secret: this.env.EMAIL_SECRET // Signs headers for secure reply routing -}); -``` - -### Catch-All (Single Instance) - -Routes all emails to one agent instance: - -```typescript -import { createCatchAllEmailResolver } from "agents/email"; - -const resolver = createCatchAllEmailResolver("EmailAgent", "default"); -``` - -### Combining Resolvers - -```typescript -async email(message, env) { - const secureReply = createSecureReplyEmailResolver(env.EMAIL_SECRET); - const addressBased = createAddressBasedEmailResolver("EmailAgent"); - - await routeAgentEmail(message, env, { - resolver: async (email, env) => { - // Try secure reply first - const result = await secureReply(email, env); - if (result) return result; - // Fall back to address-based - return addressBased(email, env); - } - }); -} -``` - -## Utilities - -```typescript -import { isAutoReplyEmail } from "agents/email"; - -async onEmail(email: AgentEmail) { - if (isAutoReplyEmail(email.headers)) { - // Skip auto-replies (vacation, out-of-office, etc.) - return; - } - // Process email... -} -``` diff --git a/agents/skills/agents-sdk/references/human-in-the-loop.md b/agents/skills/agents-sdk/references/human-in-the-loop.md deleted file mode 100644 index 3e8ddb1..0000000 --- a/agents/skills/agents-sdk/references/human-in-the-loop.md +++ /dev/null @@ -1,67 +0,0 @@ -# Human-in-the-Loop - -Fetch https://developers.cloudflare.com/agents/concepts/human-in-the-loop/ for complete documentation. - -Multiple patterns for adding human approval to agent actions. - -## Decision Guide - -| Pattern | Best for | -|---------|----------| -| Workflows `waitForApproval` | Long-running background tasks | -| AI SDK `needsApproval` on tools | Chat tool calls requiring approval | -| Client tools (`onToolCall`) | Tools that execute in the browser | -| MCP `elicitInput` | Gathering structured input from MCP clients | - -## Workflow Approvals - -```typescript -// In AgentWorkflow: -const approved = await step.waitForEvent<{ approved: boolean }>("approval", { - timeout: "7d" -}); -if (!approved.approved) throw new Error("Rejected"); - -// From agent: -await this.approveWorkflow(workflowId); -await this.rejectWorkflow(workflowId); -``` - -## Chat Tool Approvals (`needsApproval`) - -```typescript -const tools = { - deleteItem: tool({ - description: "Delete an item", - parameters: z.object({ id: z.string() }), - execute: async ({ id }) => { /* delete */ }, - needsApproval: true // or a function: (toolCall) => boolean - }) -}; -``` - -Client handles approval: - -```tsx -const { addToolApprovalResponse, addToolOutput } = useAgentChat({ - agent, - onToolCall: async ({ toolCall }) => { - if (confirm(`Allow ${toolCall.toolName}?`)) { - return { approve: true }; - } - return { approve: false }; - } -}); -``` - -To deny with a custom message: - -```tsx -addToolOutput(toolCallId, "output-error", "User rejected this action"); -``` - -## Important - -- `waitForApproval` may return `undefined` on timeout — handle it -- `addToolOutput` with `output-error` does NOT auto-continue the LLM — you may need `sendMessage` after -- For OpenAI Agents SDK, use `needsApproval` on the tool definition (same pattern) diff --git a/agents/skills/agents-sdk/references/mcp.md b/agents/skills/agents-sdk/references/mcp.md deleted file mode 100644 index 3edf3dd..0000000 --- a/agents/skills/agents-sdk/references/mcp.md +++ /dev/null @@ -1,188 +0,0 @@ -# MCP Integration - -Fetch https://developers.cloudflare.com/agents/api-reference/mcp-client-api/ and https://developers.cloudflare.com/agents/api-reference/mcp-agent-api/ for complete documentation. - -Agents include a multi-server MCP client for connecting to external MCP servers, and `McpAgent` for building MCP servers. - -## Add an MCP Server - -```typescript -import { Agent, callable } from "agents"; - -export class MyAgent extends Agent { - @callable() - async addServer(name: string, url: string) { - // Options-based API (recommended) - const result = await this.addMcpServer(name, url, { - callbackHost: "https://my-worker.workers.dev", - transport: { headers: { Authorization: "Bearer ..." } } - }); - - if (result.state === "authenticating") { - // OAuth required - redirect user to result.authUrl - return { needsAuth: true, authUrl: result.authUrl }; - } - - return { ready: true, id: result.id }; - } -} -``` - -## Use MCP Tools - -```typescript -async onChatMessage() { - // Get AI-compatible tools from all connected MCP servers - const mcpTools = this.mcp.getAITools(); - - const allTools = { - ...localTools, - ...mcpTools - }; - - const result = streamText({ - model: openai("gpt-4o"), - messages: await convertToModelMessages(this.messages), - tools: allTools - }); - - return result.toUIMessageStreamResponse(); -} -``` - -## List MCP Resources - -```typescript -// List all registered servers -const servers = this.mcp.listServers(); - -// List tools from all servers -const tools = this.mcp.listTools(); - -// List resources -const resources = this.mcp.listResources(); - -// List prompts -const prompts = this.mcp.listPrompts(); -``` - -## Remove Server - -```typescript -await this.removeMcpServer(serverId); -``` - -## Building an MCP Server - -Use `McpAgent` from the SDK to create an MCP server. - -**Install dependencies:** -```bash -npm install @modelcontextprotocol/sdk zod -``` - -**Wrangler config:** -```jsonc -{ - "durable_objects": { - "bindings": [{ "name": "MyMCP", "class_name": "MyMCP" }] - }, - "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyMCP"] }] -} -``` - -**Server implementation:** -```typescript -import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; -import { McpAgent } from "agents/mcp"; -import { z } from "zod"; - -type State = { counter: number }; - -export class MyMCP extends McpAgent { - server = new McpServer({ - name: "MyMCPServer", - version: "1.0.0" - }); - - initialState = { counter: 0 }; - - async init() { - // Register a resource - this.server.resource("counter", "mcp://resource/counter", (uri) => ({ - contents: [{ text: String(this.state.counter), uri: uri.href }] - })); - - // Register a tool - this.server.registerTool( - "increment", - { - description: "Increment the counter", - inputSchema: { amount: z.number().default(1) } - }, - async ({ amount }) => { - this.setState({ counter: this.state.counter + amount }); - return { - content: [{ text: `Counter: ${this.state.counter}`, type: "text" }] - }; - } - ); - } -} -``` - -## Serve MCP Server - -```typescript -export default { - fetch(request: Request, env: Env, ctx: ExecutionContext) { - const url = new URL(request.url); - - // Streamable HTTP transport (recommended) - if (url.pathname.startsWith("/mcp")) { - return MyMCP.serve("/mcp", { binding: "MyMCP" }).fetch(request, env, ctx); - } - - // SSE transport (legacy, deprecated) - if (url.pathname.startsWith("/sse")) { - return MyMCP.serveSSE("/sse", { binding: "MyMCP" }).fetch(request, env, ctx); - } - - return new Response("Not found", { status: 404 }); - } -}; -``` - -## Transports - -Fetch https://developers.cloudflare.com/agents/api-reference/mcp-transports/ for complete documentation. - -| Transport | Use for | -|-----------|---------| -| Streamable HTTP (`serve`) | External/public clients (recommended) | -| SSE (`serveSSE`) | Legacy clients only (deprecated) | -| RPC (`addMcpServer(name, env.Binding)`) | Same-Worker internal calls (fastest) | - -### RPC Transport (Same Worker) - -```typescript -async onStart() { - await this.addMcpServer("internal-tools", this.env.MyMCPBinding, { - props: { userId: this.name } - }); -} -``` - -## Retry on MCP Connections - -```typescript -await this.addMcpServer("tools", url, { - retry: { maxAttempts: 3, baseDelayMs: 500 } -}); -``` - -## Securing MCP Servers - -Fetch https://developers.cloudflare.com/agents/api-reference/securing-mcp-servers/ for complete documentation. - -Use `@cloudflare/workers-oauth-provider` to add OAuth in front of your MCP server. See the securing docs for proxy patterns and `redirect_uri` validation. diff --git a/agents/skills/agents-sdk/references/observability.md b/agents/skills/agents-sdk/references/observability.md deleted file mode 100644 index a4e1963..0000000 --- a/agents/skills/agents-sdk/references/observability.md +++ /dev/null @@ -1,44 +0,0 @@ -# Observability - -Fetch https://developers.cloudflare.com/agents/api-reference/observability/ for complete documentation. - -Agents emit structured events via Node.js `diagnostics_channel`. Subscribe in development or forward via Tail Workers in production. - -## Subscribe to Events - -```typescript -import { subscribe } from "agents/observability"; - -subscribe("agents:rpc", (event) => { - console.log(`RPC call: ${event.payload.method}`); -}); - -subscribe("agents:state", (event) => { - console.log(`State change on ${event.agent}`); -}); -``` - -## Available Channels - -| Channel | Events | -|---------|--------| -| `agents:state` | State changes | -| `agents:rpc` | `@callable` invocations | -| `agents:message` | WebSocket messages | -| `agents:schedule` | Schedule triggers | -| `agents:lifecycle` | Agent start, connect, disconnect | -| `agents:workflow` | Workflow progress, completion, errors | -| `agents:mcp` | MCP server connections, tool calls | -| `agents:email` | Email received | - -## Per-Agent Override - -```typescript -export class MyAgent extends Agent { - observability = undefined; // disable for this agent -} -``` - -## Production: Tail Workers - -In production, events appear as `diagnosticsChannelEvents` on the Tail Worker `event` object. Attach a Tail Worker to your agent's Worker to forward events to your observability platform. diff --git a/agents/skills/agents-sdk/references/queue-retries.md b/agents/skills/agents-sdk/references/queue-retries.md deleted file mode 100644 index 7db1c67..0000000 --- a/agents/skills/agents-sdk/references/queue-retries.md +++ /dev/null @@ -1,79 +0,0 @@ -# Queue & Retries - -Fetch https://developers.cloudflare.com/agents/api-reference/queue-tasks/ and https://developers.cloudflare.com/agents/api-reference/retries/ for complete documentation. - -## Built-in Queue - -FIFO queue persisted in SQLite. Sequential processing, one item at a time. - -```typescript -export class MyAgent extends Agent { - async onRequest(request: Request) { - this.queue("processItem", { id: "abc", data: "..." }); - this.queue("processItem", { id: "def", data: "..." }, { retry: { maxAttempts: 5 } }); - return new Response("Queued"); - } - - async processItem(payload: { id: string; data: string }, queueItem: QueueItem) { - await doWork(payload); - } -} -``` - -### Queue Management - -```typescript -const items = this.getQueue(); -const byCallback = this.getQueues("processItem"); -this.dequeue(itemId); -this.dequeueAll(); -this.dequeueAllByCallback("processItem"); -``` - -## Retries - -Exponential backoff with full jitter. Defaults: 3 attempts, 100ms base, 3000ms max. - -```typescript -const result = await this.retry( - async () => { - const res = await fetch("https://api.example.com/data"); - if (!res.ok) throw new Error(`HTTP ${res.status}`); - return res.json(); - }, - { - maxAttempts: 5, - baseDelayMs: 200, - maxDelayMs: 5000, - shouldRetry: (err, nextAttempt) => { - if (err.message.includes("429")) return true; - if (err.message.includes("401")) return false; - return nextAttempt <= 3; - } - } -); -``` - -### Retry on Schedules and Queue - -```typescript -await this.schedule(60, "task", payload, { retry: { maxAttempts: 3 } }); -await this.scheduleEvery(30, "poll", undefined, { retry: { maxAttempts: 2 } }); -this.queue("handler", payload, { retry: { maxAttempts: 5 } }); -``` - -### Class-level Defaults - -```typescript -export class MyAgent extends Agent { - static options = { - retry: { maxAttempts: 5, baseDelayMs: 200, maxDelayMs: 10000 } - }; -} -``` - -## Important - -- `shouldRetry` only works on `this.retry()` — not on schedule/queue (callbacks aren't serializable) -- Queue retries block head-of-line; long delays keep the DO awake — use `schedule` for long waits instead -- No dead-letter queue — failed items are removed after retries exhausted diff --git a/agents/skills/agents-sdk/references/routing.md b/agents/skills/agents-sdk/references/routing.md deleted file mode 100644 index 9c31aa7..0000000 --- a/agents/skills/agents-sdk/references/routing.md +++ /dev/null @@ -1,75 +0,0 @@ -# Routing - -Fetch https://developers.cloudflare.com/agents/api-reference/routing/ for complete documentation. - -## Default URL Pattern - -`/agents/{kebab-class-name}/{instance-name}` - -```typescript -import { routeAgentRequest } from "agents"; - -export default { - fetch: (req, env) => - routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 }) -}; -``` - -| Class | URL | -|-------|-----| -| `Counter` | `/agents/counter/user-123` | -| `ChatRoom` | `/agents/chat-room/lobby` | -| `MyAgent` | `/agents/my-agent/default` | - -Subpaths after the instance name (e.g. `/agents/my-agent/default/api/data`) route to `onRequest`. - -## Custom Routing with `getAgentByName` - -```typescript -import { getAgentByName } from "agents"; - -export default { - async fetch(req, env) { - const url = new URL(req.url); - if (url.pathname.startsWith("/api/")) { - const agent = getAgentByName(env.MyAgent, "singleton"); - return agent.fetch(req); - } - return routeAgentRequest(req, env); - } -}; -``` - -## Options - -```typescript -routeAgentRequest(req, env, { - cors: true, - prefix: "/api/agents", - locationHint: "enam", - jurisdiction: "eu", - props: { userId: "123" }, - onBeforeConnect: async (req) => { /* auth check */ }, - onBeforeRequest: async (req) => { /* auth check */ } -}); -``` - -`props` are delivered to `onStart(props)` on first access. - -## Client Side - -```tsx -useAgent({ - agent: "MyAgent", - name: "instance-1", - host: "https://my-worker.workers.dev", - basePath: "/api/agents", - path: "/custom-subpath" -}); -``` - -## Common Mistakes - -- Class name `MyAgent` becomes kebab `my-agent` in URLs — match exactly -- "Namespace not found" error = the `class_name` in wrangler doesn't match your exported class -- If `sendIdentityOnConnect: false`, the `ready` promise on the client may never resolve — use state sync instead diff --git a/agents/skills/agents-sdk/references/server-driven-messages.md b/agents/skills/agents-sdk/references/server-driven-messages.md deleted file mode 100644 index a51ded5..0000000 --- a/agents/skills/agents-sdk/references/server-driven-messages.md +++ /dev/null @@ -1,63 +0,0 @@ -# Server-Driven Messages (Trigger Patterns) - -Fetch https://developers.cloudflare.com/agents/api-reference/trigger-patterns/ for complete documentation. - -Patterns for server-initiated LLM turns in `AIChatAgent` — from schedules, webhooks, email, or other agents. - -## `saveMessages` — Trigger an LLM Turn - -```typescript -await this.saveMessages((existingMessages) => [ - ...existingMessages, - { role: "user", content: "Check for new notifications" } -]); -``` - -`saveMessages` persists the messages AND triggers `onChatMessage`. - -## `persistMessages` — Save Without Triggering - -```typescript -await this.persistMessages([ - ...this.messages, - { role: "assistant", content: "System note: checked at " + new Date() } -]); -``` - -## `waitUntilStable` - -**Always call before `saveMessages` from non-chat contexts** (schedules, webhooks, email): - -```typescript -async checkNotifications(payload: unknown, schedule: Schedule) { - await this.waitUntilStable({ timeout: 30_000 }); - await this.saveMessages((msgs) => [ - ...msgs, - { role: "user", content: "Run scheduled notification check" } - ]); -} -``` - -## `onChatResponse` - -Runs after each LLM turn completes. Use for chaining: - -```typescript -async onChatResponse(result: ChatResponseResult) { - if (result.type === "finish" && needsFollowUp(result)) { - await this.saveMessages((msgs) => [ - ...msgs, - { role: "user", content: "Continue with next step" } - ]); - } -} -``` - -## Client Status - -```tsx -const { isStreaming, isServerStreaming } = useAgentChat({ agent }); -``` - -- `isStreaming` — true during any streaming (user-initiated or server-initiated) -- `isServerStreaming` — true only during server-initiated streams diff --git a/agents/skills/agents-sdk/references/state-scheduling.md b/agents/skills/agents-sdk/references/state-scheduling.md deleted file mode 100644 index 29c72b8..0000000 --- a/agents/skills/agents-sdk/references/state-scheduling.md +++ /dev/null @@ -1,171 +0,0 @@ -# State & Scheduling - -Fetch https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/ and https://developers.cloudflare.com/agents/api-reference/schedule-tasks/ for complete documentation. - -## State Management - -State persists to SQLite and broadcasts to connected clients automatically. - -### Define Typed State - -```typescript -type State = { - count: number; - items: string[]; -}; - -export class MyAgent extends Agent { - initialState: State = { count: 0, items: [] }; -} -``` - -### Read and Update - -```typescript -// Read (lazy-loaded from SQLite) -const count = this.state.count; - -// Write (sync, persists, broadcasts) -this.setState({ count: this.state.count + 1 }); -``` - -### Validation Hook - -`validateStateChange()` runs synchronously before state persists. Throw to reject the update. - -```typescript -validateStateChange(nextState: State, source: Connection | "server") { - if (nextState.count < 0) { - throw new Error("Count cannot be negative"); - } -} -``` - -### Execution Order - -1. `validateStateChange(nextState, source)` - sync, gating -2. State persisted to SQLite -3. State broadcast to connected clients -4. `onStateUpdate(nextState, source)` - async via `ctx.waitUntil`, non-gating - -### Client-Side Sync (React) - -```tsx -import { useAgent } from "agents/react"; - -function App() { - const [state, setLocalState] = useState({ count: 0 }); - - const agent = useAgent({ - agent: "MyAgent", - name: "instance-1", - onStateUpdate: (newState) => setLocalState(newState) - }); - - return ; -} -``` - -## SQL API - -Direct SQLite access for custom queries: - -```typescript -// Create table -this.sql` - CREATE TABLE IF NOT EXISTS items ( - id TEXT PRIMARY KEY, - name TEXT, - created_at INTEGER DEFAULT (unixepoch()) - ) -`; - -// Insert -this.sql`INSERT INTO items (id, name) VALUES (${id}, ${name})`; - -// Query with types -const items = this.sql<{ id: string; name: string }>` - SELECT * FROM items WHERE name LIKE ${`%${search}%`} -`; -``` - -## Scheduling - -### Schedule Types - -| Mode | Syntax | Use Case | -|------|--------|----------| -| Delay | `this.schedule(60, ...)` | Run in 60 seconds | -| Date | `this.schedule(new Date(...), ...)` | Run at specific time | -| Cron | `this.schedule("0 8 * * *", ...)` | Recurring schedule | -| Interval | `this.scheduleEvery(30, ...)` | Fixed interval (every 30s) | - -### Examples - -```typescript -// Delay (seconds) -await this.schedule(60, "checkStatus", { id: "abc123" }); - -// Specific date -await this.schedule(new Date("2025-12-25T00:00:00Z"), "sendGreeting", { to: "user" }); - -// Cron (recurring) -await this.schedule("0 9 * * 1-5", "weekdayReport", {}); - -// Fixed interval (every 30 seconds, overlap prevention built-in) -await this.scheduleEvery(30, "pollUpdates"); -await this.scheduleEvery(300, "syncData", { source: "api" }); -``` - -### Handler - -```typescript -async sendGreeting(payload: { to: string }, schedule: Schedule) { - console.log(`Sending greeting to ${payload.to}`); - // Cron schedules auto-reschedule; one-time schedules are deleted -} -``` - -### Manage Schedules - -```typescript -const schedules = this.getSchedules(); -const crons = this.getSchedules({ type: "cron" }); -await this.cancelSchedule(schedule.id); -``` - -### Retry on Schedules - -```typescript -await this.schedule(60, "task", payload, { retry: { maxAttempts: 3 } }); -await this.scheduleEvery(30, "poll", undefined, { retry: { maxAttempts: 2 } }); -``` - -## Lifecycle Callbacks - -```typescript -export class MyAgent extends Agent { - async onStart() { - // Agent started or woke from hibernation - } - - onConnect(conn: Connection, ctx: ConnectionContext) { - // WebSocket connected - } - - onMessage(conn: Connection, message: WSMessage) { - // WebSocket message (non-RPC) - } - - onStateUpdate(state: State, source: Connection | "server") { - // State changed (async, non-blocking) - } - - onError(error: unknown) { - // Error handler - throw error; // Re-throw to propagate - } -} -``` diff --git a/agents/skills/agents-sdk/references/streaming-chat.md b/agents/skills/agents-sdk/references/streaming-chat.md deleted file mode 100644 index 1426c6e..0000000 --- a/agents/skills/agents-sdk/references/streaming-chat.md +++ /dev/null @@ -1,198 +0,0 @@ -# Streaming Chat with AIChatAgent - -Fetch https://developers.cloudflare.com/agents/api-reference/chat-agents/ for complete documentation. - -`AIChatAgent` from `@cloudflare/ai-chat` provides streaming chat with automatic message persistence and resumable streams. - -## Basic Chat Agent - -```typescript -import { AIChatAgent } from "@cloudflare/ai-chat"; -import { streamText, convertToModelMessages } from "ai"; -import { openai } from "@ai-sdk/openai"; - -export class Chat extends AIChatAgent { - async onChatMessage(onFinish, options) { - const result = streamText({ - model: openai("gpt-4o"), - system: "You are a helpful assistant.", - messages: await convertToModelMessages(this.messages), - abortSignal: options?.abortSignal, - onFinish - }); - return result.toUIMessageStreamResponse(); - } -} -``` - -**Important:** Always pass `abortSignal` and `onFinish` — they enable proper cleanup and message persistence. - -## With Tools - -```typescript -import { tool } from "ai"; -import { z } from "zod"; - -const tools = { - getWeather: tool({ - description: "Get weather for a location", - parameters: z.object({ location: z.string() }), - execute: async ({ location }) => `Weather in ${location}: 72°F, sunny` - }) -}; - -export class Chat extends AIChatAgent { - async onChatMessage(onFinish, options) { - const result = streamText({ - model: openai("gpt-4o"), - messages: await convertToModelMessages(this.messages), - tools, - abortSignal: options?.abortSignal, - onFinish - }); - return result.toUIMessageStreamResponse(); - } -} -``` - -## With Workers AI (no API keys) - -```typescript -import { createWorkersAI } from "workers-ai-provider"; - -export class Chat extends AIChatAgent { - async onChatMessage(onFinish, options) { - const workersai = createWorkersAI({ binding: this.env.AI }); - const result = streamText({ - model: workersai("@cf/meta/llama-4-scout-17b-16e-instruct"), - messages: await convertToModelMessages(this.messages), - abortSignal: options?.abortSignal, - onFinish - }); - return result.toUIMessageStreamResponse(); - } -} -``` - -## Custom UI Message Stream - -For more control, use `createUIMessageStream`: - -```typescript -import { createUIMessageStream, createUIMessageStreamResponse } from "ai"; - -export class Chat extends AIChatAgent { - async onChatMessage(onFinish) { - const stream = createUIMessageStream({ - execute: async ({ writer }) => { - const result = streamText({ - model: openai("gpt-4o"), - messages: await convertToModelMessages(this.messages), - onFinish - }); - writer.merge(result.toUIMessageStream()); - } - }); - return createUIMessageStreamResponse({ stream }); - } -} -``` - -## Resumable Streaming - -Streams automatically resume if client disconnects and reconnects: - -1. Chunks buffered to SQLite during streaming -2. On reconnect, buffered chunks sent immediately -3. Live streaming continues from where it left off - -**Enabled by default.** To disable: - -```tsx -const { messages } = useAgentChat({ agent, resume: false }); -``` - -## React Client - -```tsx -import { useAgent } from "agents/react"; -import { useAgentChat } from "@cloudflare/ai-chat/react"; - -function ChatUI() { - const agent = useAgent({ - agent: "Chat", - name: "my-chat-session" - }); - - const { - messages, - input, - handleInputChange, - handleSubmit, - status - } = useAgentChat({ agent }); - - return ( -
- {messages.map((m) => ( -
- {m.role}: {m.content} -
- ))} - -
- - -
-
- ); -} -``` - -## Streaming RPC Methods - -For non-chat streaming, use `@callable({ streaming: true })`: - -```typescript -import { Agent, callable, StreamingResponse } from "agents"; - -export class MyAgent extends Agent { - @callable({ streaming: true }) - async streamData(stream: StreamingResponse, query: string) { - for (let i = 0; i < 10; i++) { - stream.send(`Result ${i}: ${query}`); - await sleep(100); - } - stream.close(); - } -} -``` - -Client receives streamed messages via WebSocket RPC. - -## Key Properties - -| Property | Purpose | -|----------|---------| -| `this.messages` | All persisted messages | -| `maxPersistedMessages` | Limit stored messages (prune oldest) | -| `messageConcurrency` | `"queue"` (default), `"latest"`, `"merge"`, `"drop"` | -| `chatRecovery` | `"persist"` (default) or `"continue"` on reconnect | -| `waitForMcpConnections` | Wait for MCP servers before first turn | - -## Status Values - -`useAgentChat` status: - -| Status | Meaning | -|--------|---------| -| `ready` | Idle, ready for input | -| `streaming` | Response streaming | -| `submitted` | Request sent, waiting | -| `error` | Error occurred | - -Also: `isStreaming`, `isServerStreaming` for distinguishing user vs server-initiated streams. diff --git a/agents/skills/agents-sdk/references/think.md b/agents/skills/agents-sdk/references/think.md deleted file mode 100644 index 3123a04..0000000 --- a/agents/skills/agents-sdk/references/think.md +++ /dev/null @@ -1,112 +0,0 @@ -# Think (Experimental) - -Fetch https://developers.cloudflare.com/agents/api-reference/think/ for complete documentation. - -`@cloudflare/think` — a higher-level chat agent class that handles the `streamText` loop, tool execution, and message persistence for you. You provide `getModel()` and `getSystemPrompt()`; Think handles the rest. - -```bash -npm install @cloudflare/think -``` - -## Minimal Agent - -```typescript -import { Think } from "@cloudflare/think"; -import { createWorkersAI } from "workers-ai-provider"; -import { routeAgentRequest } from "agents"; - -export class MyAgent extends Think { - getModel() { - return createWorkersAI({ binding: this.env.AI })("@cf/meta/llama-4-scout-17b-16e-instruct"); - } - - getSystemPrompt() { - return "You are a helpful assistant."; - } -} - -export default { - fetch: (req, env) => routeAgentRequest(req, env) -}; -``` - -## Wrangler Config - -```jsonc -{ - "compatibility_flags": ["nodejs_compat", "experimental"], - "durable_objects": { - "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }] - }, - "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }], - "ai": { "binding": "AI" } -} -``` - -**Note:** Think requires the `experimental` compatibility flag. - -## Custom Tools - -```typescript -import { tool } from "ai"; -import { z } from "zod"; - -export class MyAgent extends Think { - getTools() { - return { - getWeather: tool({ - description: "Get weather", - parameters: z.object({ city: z.string() }), - execute: async ({ city }) => `72°F in ${city}` - }) - }; - } -} -``` - -## Lifecycle Hooks - -| Hook | When | Use for | -|------|------|---------| -| `configureSession()` | Agent starts | Set up memory, context providers | -| `beforeTurn(ctx)` | Before each LLM call | Per-turn model/tools/system prompt; return `TurnConfig` | -| `onChunk(chunk)` | Each streaming chunk | Progress tracking | -| `onChatResponse(result)` | After LLM turn completes | Chaining, follow-up `saveMessages` | -| `onChatError(error)` | On LLM error | Error handling | - -```typescript -async beforeTurn(ctx: TurnContext): Promise { - if (ctx.continuation) { - return { model: cheaperModel }; - } - return {}; -} -``` - -## Sub-Agents - -```typescript -const child = this.subAgent(SpecialistAgent, "specialist-1"); -await child.chat("Analyze this data...", (chunk) => { - // stream callback -}); -``` - -## Client - -Same React hooks as `AIChatAgent`: - -```tsx -const agent = useAgent({ agent: "MyAgent", name: "session-1" }); -const { messages, input, handleInputChange, handleSubmit } = useAgentChat({ agent }); -``` - -## Think vs AIChatAgent - -| | Think | AIChatAgent | -|-|-------|-------------| -| `streamText` loop | Built-in | You write it | -| Tool execution | Automatic | You wire it | -| Customization | Override hooks | Full control in `onChatMessage` | -| Built-in tools | Workspace, execute, browser | None | -| Compatibility flag | Requires `experimental` | Standard | diff --git a/agents/skills/agents-sdk/references/voice.md b/agents/skills/agents-sdk/references/voice.md deleted file mode 100644 index 9ed5473..0000000 --- a/agents/skills/agents-sdk/references/voice.md +++ /dev/null @@ -1,68 +0,0 @@ -# Voice (Experimental) - -Fetch https://developers.cloudflare.com/agents/api-reference/voice/ for complete documentation. - -`@cloudflare/voice` — real-time speech-to-text and text-to-speech for agents. Audio streams over WebSocket. - -```bash -npm install @cloudflare/voice -``` - -## Server - -```typescript -import { Agent } from "agents"; -import { withVoice, WorkersAITTS, WorkersAINova3STT } from "@cloudflare/voice"; - -export class VoiceAgent extends withVoice(Agent) { - transcriber = new WorkersAINova3STT(this); - tts = new WorkersAITTS(this); - - async onTurn(transcript: string, context: VoiceTurnContext) { - const result = streamText({ - model: createWorkersAI({ binding: this.env.AI })("@cf/meta/llama-4-scout-17b-16e-instruct"), - messages: [ - { role: "system", content: "You are a voice assistant." }, - ...context.conversationHistory, - { role: "user", content: transcript } - ] - }); - - for await (const chunk of result.textStream) { - if (context.signal.aborted) break; - context.speak(chunk); - } - } -} -``` - -## Lifecycle Hooks - -| Hook | Purpose | -|------|---------| -| `onTurn(transcript, ctx)` | Handle transcribed speech (required) | -| `beforeCallStart(conn)` | Auth/validation before call starts | -| `onCallStart(conn)` | Call connected | -| `onCallEnd(conn)` | Call disconnected | -| `onInterrupt()` | User interrupted agent speech | - -## Client (React) - -```tsx -import { useVoiceAgent } from "@cloudflare/voice/react"; - -function VoiceUI() { - const { isConnected, isSpeaking, connect, disconnect } = useVoiceAgent({ - agent: "VoiceAgent", - name: "session-1" - }); - - return ; -} -``` - -## STT/TTS Providers - -Workers AI (default), Deepgram, ElevenLabs — install the provider package and swap the `transcriber`/`tts` properties. diff --git a/agents/skills/agents-sdk/references/webhooks-push.md b/agents/skills/agents-sdk/references/webhooks-push.md deleted file mode 100644 index 7e44e6b..0000000 --- a/agents/skills/agents-sdk/references/webhooks-push.md +++ /dev/null @@ -1,86 +0,0 @@ -# Webhooks & Push Notifications - -## Webhooks - -Fetch https://developers.cloudflare.com/agents/api-reference/webhooks/ for complete documentation. - -Route external webhooks to agent instances via `onRequest`: - -```typescript -export default { - async fetch(req: Request, env: Env) { - const url = new URL(req.url); - if (url.pathname.startsWith("/webhooks/")) { - const entityId = url.pathname.split("/")[2]; - const agent = getAgentByName(env.MyAgent, entityId); - return agent.fetch(req); - } - return routeAgentRequest(req, env); - } -}; -``` - -In the agent: - -```typescript -export class MyAgent extends Agent { - async onRequest(request: Request) { - const signature = request.headers.get("X-Signature"); - if (!verifySignature(signature, await request.text(), this.env.WEBHOOK_SECRET)) { - return new Response("Unauthorized", { status: 401 }); - } - const payload = JSON.parse(await request.text()); - this.queue("processWebhook", payload); - return new Response("OK", { status: 202 }); - } -} -``` - -**Tips:** Respond quickly (200/202), verify signatures, deduplicate with stored event IDs, use `queue()` for async processing. - -## Push Notifications - -Fetch https://developers.cloudflare.com/agents/api-reference/push-notifications/ for complete documentation. - -Web Push via VAPID from agents. Store subscriptions in agent state, send via `web-push`. - -```bash -npm install web-push -``` - -```typescript -import webpush from "web-push"; - -export class NotifyAgent extends Agent { - @callable() - async subscribe(subscription: PushSubscription) { - this.setState({ - ...this.state, - subscriptions: [...this.state.subscriptions, subscription] - }); - } - - async sendReminder(payload: { message: string }, schedule: Schedule) { - for (const sub of this.state.subscriptions) { - try { - await webpush.sendNotification(sub, JSON.stringify({ - title: "Reminder", - body: payload.message - }), { - vapidDetails: { - subject: "mailto:you@example.com", - publicKey: this.env.VAPID_PUBLIC_KEY, - privateKey: this.env.VAPID_PRIVATE_KEY - } - }); - } catch (err) { - if (err.statusCode === 404 || err.statusCode === 410) { - // Remove expired subscription - } - } - } - } -} -``` - -VAPID keys: generate with `npx web-push generate-vapid-keys`, store as secrets. diff --git a/agents/skills/agents-sdk/references/workflows.md b/agents/skills/agents-sdk/references/workflows.md deleted file mode 100644 index fcd6f80..0000000 --- a/agents/skills/agents-sdk/references/workflows.md +++ /dev/null @@ -1,132 +0,0 @@ -# Workflows Integration - -Fetch https://developers.cloudflare.com/agents/api-reference/run-workflows/ for complete documentation. - -## Overview - -Agents handle real-time communication; Workflows handle durable execution. Together they enable: - -- Long-running background tasks with automatic retries -- Human-in-the-loop approval flows -- Multi-step pipelines that survive failures - -| Use Case | Recommendation | -|----------|----------------| -| Chat/messaging | Agent only | -| Quick API calls (<30s) | Agent only | -| Background processing (<30s) | Agent `queue()` | -| Long-running tasks (>30s) | Agent + Workflow | -| Human approval flows | Agent + Workflow | - -## AgentWorkflow Base Class - -```typescript -import { AgentWorkflow } from "agents/workflows"; -import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents/workflows"; - -type TaskParams = { taskId: string; data: string }; - -export class ProcessingWorkflow extends AgentWorkflow { - async run(event: AgentWorkflowEvent, step: AgentWorkflowStep) { - const params = event.payload; - - // Durable step - retries on failure - const result = await step.do("process", async () => { - return processData(params.data); - }); - - // Non-durable: progress reporting - await this.reportProgress({ step: "process", percent: 0.5 }); - - // Non-durable: broadcast to connected clients - this.broadcastToClients({ type: "update", taskId: params.taskId }); - - // Durable: merge state via step - await step.mergeAgentState({ lastProcessed: params.taskId }); - - // Durable: report completion - await step.reportComplete(result); - - return result; - } -} -``` - -## Wrangler Configuration - -```jsonc -{ - "workflows": [ - { "name": "processing-workflow", "binding": "PROCESSING_WORKFLOW", "class_name": "ProcessingWorkflow" } - ], - "durable_objects": { - "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }] - }, - "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }] -} -``` - -## Agent Methods for Workflows - -```typescript -// Start a workflow -const instance = await this.runWorkflow("ProcessingWorkflow", { taskId: "123", data: "..." }); - -// Send event to waiting workflow -await this.sendWorkflowEvent("ProcessingWorkflow", workflowId, { type: "approve" }); - -// Query workflows -const workflow = await this.getWorkflow(workflowId); -const workflows = await this.getWorkflows({ status: "running" }); - -// Control workflows -await this.approveWorkflow(workflowId); -await this.rejectWorkflow(workflowId); -await this.terminateWorkflow(workflowId); -await this.pauseWorkflow(workflowId); -await this.resumeWorkflow(workflowId); - -// Delete workflows -await this.deleteWorkflow(workflowId); -await this.deleteWorkflows({ status: "complete", before: new Date(...) }); -``` - -## Lifecycle Callbacks - -```typescript -export class MyAgent extends Agent { - async onWorkflowProgress(workflowName: string, workflowId: string, progress: unknown) { - // Workflow reported progress via this.reportProgress() - this.broadcast({ type: "progress", workflowId, progress }); - } - - async onWorkflowComplete(workflowName: string, workflowId: string, result?: unknown) { - // Workflow finished successfully - } - - async onWorkflowError(workflowName: string, workflowId: string, error: Error) { - // Workflow failed - } - - async onWorkflowEvent(workflowName: string, workflowId: string, event: unknown) { - // Workflow received an event via sendWorkflowEvent() - } -} -``` - -## Human-in-the-Loop - -```typescript -// In workflow: wait for approval -const approved = await step.waitForEvent<{ approved: boolean }>("approval", { - timeout: "7d" -}); - -if (!approved.approved) { - throw new Error("Rejected"); -} - -// From agent: approve or reject -await this.approveWorkflow(workflowId); // Sends { approved: true } -await this.rejectWorkflow(workflowId); // Sends { approved: false } -``` diff --git a/agents/skills/find-skills/SKILL.md b/agents/skills/find-skills/SKILL.md deleted file mode 100644 index 7369d66..0000000 --- a/agents/skills/find-skills/SKILL.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -name: find-skills -description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill. ---- - -# Find Skills - -This skill helps you discover and install skills from the open agent skills ecosystem. - -## When to Use This Skill - -Use this skill when the user: - -- Asks "how do I do X" where X might be a common task with an existing skill -- Says "find a skill for X" or "is there a skill for X" -- Asks "can you do X" where X is a specialized capability -- Expresses interest in extending agent capabilities -- Wants to search for tools, templates, or workflows -- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.) - -## What is the Skills CLI? - -The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools. - -**Key commands:** - -- `npx skills find [query] [--owner ]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner -- `npx skills add ` - Install a skill from GitHub or other sources -- `npx skills check` - Check for skill updates -- `npx skills update` - Update all installed skills - -**Browse skills at:** https://skills.sh/ - -## How to Help Users Find Skills - -### Step 1: Understand What They Need - -When a user asks for help with something, identify: - -1. The domain (e.g., React, testing, design, deployment) -2. The specific task (e.g., writing tests, creating animations, reviewing PRs) -3. Whether this is a common enough task that a skill likely exists - -### Step 2: Check the Leaderboard First - -Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options. - -For example, top skills for web development include: -- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each) -- `anthropics/skills` — Frontend design, document processing (100K+ installs) - -### Step 3: Search for Skills - -If the leaderboard doesn't cover the user's need, run the find command: - -```bash -npx skills find [query] [--owner ] -``` - -For example: - -- User asks "how do I make my React app faster?" → `npx skills find react performance` -- User asks "can you help me with PR reviews?" → `npx skills find pr review` -- User asks "I need to create a changelog" → `npx skills find changelog` - -### Step 4: Verify Quality Before Recommending - -**Do not recommend a skill based solely on search results.** Always verify: - -1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100. -2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors. -3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism. - -### Step 5: Present Options to the User - -When you find relevant skills, present them to the user with: - -1. The skill name and what it does -2. The install count and source -3. The install command they can run -4. A link to learn more at skills.sh - -Example response: - -``` -I found a skill that might help! The "react-best-practices" skill provides -React and Next.js performance optimization guidelines from Vercel Engineering. -(185K installs) - -To install it: -npx skills add vercel-labs/agent-skills@react-best-practices - -Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices -``` - -### Step 6: Offer to Install - -If the user wants to proceed, you can install the skill for them: - -```bash -npx skills add -g -y -``` - -The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts. - -## Common Skill Categories - -When searching, consider these common categories: - -| Category | Example Queries | -| --------------- | ---------------------------------------- | -| Web Development | react, nextjs, typescript, css, tailwind | -| Testing | testing, jest, playwright, e2e | -| DevOps | deploy, docker, kubernetes, ci-cd | -| Documentation | docs, readme, changelog, api-docs | -| Code Quality | review, lint, refactor, best-practices | -| Design | ui, ux, design-system, accessibility | -| Productivity | workflow, automation, git | - -## Tips for Effective Searches - -1. **Use specific keywords**: "react testing" is better than just "testing" -2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd" -3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills` - -## When No Skills Are Found - -If no relevant skills exist: - -1. Acknowledge that no existing skill was found -2. Offer to help with the task directly using your general capabilities -3. Suggest the user could create their own skill with `npx skills init` - -Example: - -``` -I searched for skills related to "xyz" but didn't find any matches. -I can still help you with this task directly! Would you like me to proceed? - -If this is something you do often, you could create your own skill: -npx skills init my-xyz-skill -``` diff --git a/agents/skills/greploop/SKILL.md b/agents/skills/greploop/SKILL.md deleted file mode 100644 index 43a91fd..0000000 --- a/agents/skills/greploop/SKILL.md +++ /dev/null @@ -1,454 +0,0 @@ ---- -name: greploop -description: > - Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile - gives it a 5/5 confidence score with zero unresolved comments. Triggers Greptile review, fixes all - actionable comments, pushes/re-shelves, re-triggers review, and repeats. Use when the user wants to - fully optimize a PR/MR/CL against Greptile's code review standards. -license: MIT -compatibility: Requires git, gh (GitHub CLI) or glab (GitLab CLI) authenticated, and Greptile installed on the repo. For Perforce, requires p4 CLI authenticated. -metadata: - author: greptileai - version: "1.3" -allowed-tools: Bash(gh:*) Bash(glab:*) Bash(git:*) Bash(p4:*) ---- - -# Greploop - -Iteratively fix a PR/MR/CL until Greptile gives a perfect review: 5/5 confidence, zero unresolved comments. - -## Inputs - -- **PR/MR/CL number** (optional): If not provided, detect the PR/MR for the current branch, or the default pending changelist for p4. - -## Instructions - -### 0. Detect platform - -First check for Perforce, then fall back to git remote detection: - -```bash -# Check for Perforce environment -if p4 info >/dev/null 2>&1; then - VCS="perforce" -else - REMOTE_URL=$(git remote get-url origin) - if echo "$REMOTE_URL" | grep -qi "gitlab"; then - VCS="gitlab" - else - VCS="github" - fi -fi -``` - -For self-hosted GitLab instances whose hostname doesn't contain "gitlab", the user can override by passing `--vcs gitlab` as an input. For Perforce, pass `--vcs perforce`. - -### 1. Identify the PR/MR/CL - -**GitHub:** -```bash -gh pr view --json number,headRefName -q '{number: .number, branch: .headRefName}' -``` - -**GitLab:** -```bash -glab mr view --output json | jq '{iid: .iid, branch: .source_branch}' -``` - -Switch to the PR/MR branch if not already on it. - -**Perforce:** -```bash -# List pending changelists for current user/client -p4 changes -s pending -u $P4USER -c $P4CLIENT - -# Describe a specific CL -p4 describe -s -``` - -Ensure the correct workspace (`p4 client`) is set before proceeding. - -Key field differences: -- GitHub: `number`, `headRefName`, `headRefOid` -- GitLab: `iid`, `source_branch`, `sha` -- Perforce: changelist number, `P4CLIENT`, shelved files - -### 2. Loop - -Repeat the following cycle. **Max 5 iterations** to avoid runaway loops. - -#### A. Trigger Greptile review - -Push/shelve the latest changes (if any): - -**GitHub/GitLab:** -```bash -git push -``` - -**Perforce:** -```bash -# Re-shelve to update the shelved files for review -p4 shelve -f -c -``` - -Wait for checks to start after push/shelve: - -```bash -sleep 5 -``` - -**GitHub** — check if Greptile is already running before posting a new trigger comment: - -```bash -GREPTILE_STATE=$(gh pr checks --json name,state | jq -r '.[] | select(.name | test("greptile"; "i")) | .state') -``` - -If Greptile is **not** already running (`PENDING` or `IN_PROGRESS`), request a fresh review: - -```bash -if [ "$GREPTILE_STATE" != "PENDING" ] && [ "$GREPTILE_STATE" != "IN_PROGRESS" ]; then - gh pr comment --body "@greptile review" -fi -``` - -Then poll for the Greptile check run to complete: - -```bash -HEAD_SHA=$(gh pr view --json headRefOid -q .headRefOid) -ATTEMPTS=0 -MAX_ATTEMPTS=60 -POLL_INTERVAL_SECONDS=10 - -while true; do - ATTEMPTS=$((ATTEMPTS + 1)) - if [ "$ATTEMPTS" -gt "$MAX_ATTEMPTS" ]; then - echo "Timed out waiting for the Greptile check run after approximately 10 minutes." >&2 - exit 1 - fi - - GREPTILE_CHECK=$(gh api "repos/{owner}/{repo}/commits/$HEAD_SHA/check-runs" \ - --jq '.check_runs[] | select(.name | test("greptile"; "i"))' 2>/dev/null) - - if [ -z "$GREPTILE_CHECK" ]; then - echo "Waiting for Greptile check to appear..." - sleep "$POLL_INTERVAL_SECONDS" - continue - fi - - STATUS=$(echo "$GREPTILE_CHECK" | jq -r '.status // "completed"') - CONCLUSION=$(echo "$GREPTILE_CHECK" | jq -r '.conclusion // "pending"') - - if [ "$STATUS" = "completed" ]; then - if [ "$CONCLUSION" = "success" ]; then - echo "Greptile check passed!" - else - echo "Greptile check completed with: $CONCLUSION" - fi - break - fi - - echo "Waiting for Greptile... (status: $STATUS)" - sleep "$POLL_INTERVAL_SECONDS" -done -``` - -If polling times out, stop the greploop workflow and report the timeout. Do not continue with stale or missing review results. - -**GitLab** — check if Greptile is already running before posting a trigger comment: - -```bash -PIPELINES=$(glab api "projects/:fullpath/merge_requests//pipelines") -GREPTILE_RUNNING=$(echo "$PIPELINES" | jq '[.[] | select(.status == "running" or .status == "pending")] | length') -``` - -If no pipeline is running, post a trigger comment: - -```bash -if [ "$GREPTILE_RUNNING" = "0" ]; then - glab mr note --message "@greptile review" -fi -``` - -**Perforce** — Perforce does not have native check runs. If Greptile is integrated via a webhook triggered on `p4 shelve`, wait for it to process. Check your Greptile installation's webhook endpoint or dashboard for the review status. Poll by re-fetching the Greptile review comment on the CL until a score appears. - -Then poll for the Greptile pipeline job to complete (see [GitLab API reference](references/gitlab-api.md)): - -```bash -HEAD_SHA=$(glab mr view --output json | jq -r '.sha') -ATTEMPTS=0 -MAX_ATTEMPTS=60 -POLL_INTERVAL_SECONDS=10 - -while true; do - ATTEMPTS=$((ATTEMPTS + 1)) - if [ "$ATTEMPTS" -gt "$MAX_ATTEMPTS" ]; then - echo "Timed out waiting for the Greptile pipeline job after approximately 10 minutes." >&2 - exit 1 - fi - - PIPELINES=$(glab api "projects/:fullpath/merge_requests//pipelines") - # Find the most recent pipeline for this SHA - PIPELINE_ID=$(echo "$PIPELINES" | jq -r --arg sha "$HEAD_SHA" \ - '[.[] | select(.sha == $sha)] | sort_by(.id) | last | .id // empty') - - if [ -z "$PIPELINE_ID" ]; then - echo "Waiting for Greptile pipeline to appear..." - sleep "$POLL_INTERVAL_SECONDS" - continue - fi - - JOBS=$(glab api "projects/:fullpath/pipelines/$PIPELINE_ID/jobs") - GREPTILE_JOB=$(echo "$JOBS" | jq '.[] | select(.name | test("greptile"; "i"))') - - if [ -z "$GREPTILE_JOB" ]; then - echo "Waiting for Greptile job to appear..." - sleep "$POLL_INTERVAL_SECONDS" - continue - fi - - JOB_STATUS=$(echo "$GREPTILE_JOB" | jq -r '.status') - - if [ "$JOB_STATUS" = "success" ] || [ "$JOB_STATUS" = "failed" ] || [ "$JOB_STATUS" = "canceled" ]; then - echo "Greptile job completed with: $JOB_STATUS" - break - fi - - echo "Waiting for Greptile... (status: $JOB_STATUS)" - sleep "$POLL_INTERVAL_SECONDS" -done -``` - -If polling times out, stop the greploop workflow and report the timeout. Do not continue with stale or missing review results. - -#### B. Fetch Greptile review results - -Greptile may surface its score in several places — check **all** of the relevant sources: - -**GitHub:** - -**1. PR description (body):** -```bash -gh pr view --json body -q '.body' -``` - -**2. General PR comments (issue comments):** -```bash -gh api --paginate "repos/{owner}/{repo}/issues//comments?per_page=100" -``` - -Filter for Greptile-authored comments and use the body from the most recently updated comment (`updated_at`), not the most recently created comment. Greptile may edit the same general PR comment on each review cycle; parse the current body, including the "Prompt to fix all with AI" section, before deciding there are no remaining issues. - -**3. PR reviews:** -```bash -gh api repos/{owner}/{repo}/pulls//reviews -``` - -Look for the most recent entry from `greptile-apps[bot]` or `greptile-apps-staging[bot]`. - -**GitLab:** - -**1. MR description (body):** -```bash -glab mr view --output json | jq -r '.description' -``` - -**2. MR notes (comments):** -```bash -glab api "projects/:fullpath/merge_requests//notes" -``` - -Filter for notes from the Greptile bot user (check the `author.username` field — the exact username may vary per installation; verify on first run). - -**Perforce:** - -**1. CL description:** -```bash -p4 describe -s -``` -Check the description field for a Greptile-appended score block. - -**2. CL comments / review notes:** -If your installation uses a review tool such as Helix Swarm, fetch comments via its API. - -Example (Swarm API): -GET /api/v11/comments?topic=reviews/ - -Response fields of interest typically include: -- user (author username) -- body (comment text) -- flags/state indicating whether the comment is resolved - -Filter to comments authored by the Greptile bot: -- Prefer exact username match if known -- Otherwise, use a heuristic where the author name contains "greptile" (case-insensitive) - -For all platforms, parse the text for: -- **Confidence score**: a pattern like `3/5` or `5/5` (or `Confidence: 3/5`). -- **Comment count**: Number of inline review comments noted in the summary. - -Use whichever source has the **most recently updated** score. For GitHub, prefer `updated_at` from issue comments when comparing an edited Greptile summary against older review entries. - -Also fetch all unresolved inline comments: - -**GitHub:** -```bash -gh api repos/{owner}/{repo}/pulls//comments -``` - -Also carry forward actionable items from the latest Greptile general PR comment, especially the "Prompt to fix all with AI" section, even if the inline comment endpoint returns zero unresolved comments. - -**GitLab:** -```bash -glab api "projects/:fullpath/merge_requests//discussions" -``` - -Filter to `DiffNote` type discussions (`notes[0].type == "DiffNote"`) from Greptile that are on the latest commit and not yet resolved (`"resolved": false`). - -**Perforce:** -If using Swarm: - -# Fetch inline diff comments for the review associated with the CL -GET /api/v11/comments?topic=reviews/ - -Filter to comments from the Greptile bot user that have not been marked as resolved/addressed. - -#### C. Check exit conditions - -Stop the loop if **any** of these are true: - -- Confidence score is **5/5** AND there are **zero unresolved comments** -- Max iterations reached (report current state) - -#### D. Fix actionable comments - -For each unresolved Greptile comment: - -1. Read the file and understand the comment in context. -2. Determine if it's actionable (code change needed) or informational. -3. If actionable, make the fix. -4. If informational or a false positive, note it but still resolve the thread. - -#### E. Resolve threads - -**GitHub** — fetch unresolved review threads and resolve all that have been addressed (see [GraphQL reference](references/graphql-queries.md)): - -```bash -gh api graphql -f query=' -query($cursor: String) { - repository(owner: "OWNER", name: "REPO") { - pullRequest(number: PR_NUMBER) { - reviewThreads(first: 100, after: $cursor) { - pageInfo { hasNextPage endCursor } - nodes { - id - isResolved - comments(first: 1) { - nodes { body path author { login } } - } - } - } - } - } -}' -``` - -Resolve addressed threads: - -```bash -gh api graphql -f query=' -mutation { - t1: resolveReviewThread(input: {threadId: "ID1"}) { thread { isResolved } } - t2: resolveReviewThread(input: {threadId: "ID2"}) { thread { isResolved } } -}' -``` - -**GitLab** — fetch unresolved discussions and resolve each one (see [GitLab API reference](references/gitlab-api.md)): - -```bash -glab api "projects/:fullpath/merge_requests//discussions?per_page=100" -``` - -Filter for `"resolved": false` discussions. Then resolve each by its `id`: - -```bash -glab api --method PUT \ - "projects/:fullpath/merge_requests//discussions/" \ - --field resolved=true -``` - -Repeat for each unresolved discussion ID. (GitLab has no batch resolution — loop through each one.) - -#### F. Commit and push / re-shelve - -**GitHub/GitLab:** -```bash -git add -A -git commit -m "address greptile review feedback (greploop iteration N)" -git push -``` - -**Perforce:** -```bash -# Stage changes back into the CL and re-shelve for the next review round -p4 shelve -f -c -``` - -Wait for checks to start after push/shelve: - -```bash -sleep 5 -``` - -Then go back to step **A**. - -### 3. Report - -After exiting the loop, summarize: - -| Field | Value | -| ------------------ | ---------- | -| Platform | GitHub / GitLab / Perforce | -| Iterations | N | -| Final confidence | X/5 | -| Comments resolved | N | -| Remaining comments | N (if any) | - -If the loop exited due to max iterations, list any remaining unresolved comments and suggest next steps. - -## Output format - -``` -Greploop complete. - Platform: GitHub - Iterations: 2 - Confidence: 5/5 - Resolved: 7 comments - Remaining: 0 -``` - -If not fully resolved: - -``` -Greploop stopped after 5 iterations. - Platform: GitLab - Confidence: 4/5 - Resolved: 12 comments - Remaining: 2 - -Remaining issues: - - src/auth.ts:45 — "Consider rate limiting this endpoint" - - src/db.ts:112 — "Missing index on user_id column" -``` - -**Perforce example:** - -``` -Greploop complete. - Platform: Perforce - Changelist: 12345 - Iterations: 3 - Confidence: 5/5 - Resolved: 9 comments - Remaining: 0 -``` diff --git a/agents/skills/greploop/references/gitlab-api.md b/agents/skills/greploop/references/gitlab-api.md deleted file mode 100644 index bdd7ae7..0000000 --- a/agents/skills/greploop/references/gitlab-api.md +++ /dev/null @@ -1,93 +0,0 @@ -# GitLab API Reference - -Useful GitLab REST API calls for the greploop workflow, using `glab api`. - -`glab api` automatically resolves `:fullpath` to the URL-encoded project path from the local git remote. - -## Fetch MR details - -```bash -glab mr view --output json -``` - -Key fields: -- `iid` — internal MR number (use this, not `id`) -- `source_branch` — equivalent to GitHub's `headRefName` -- `sha` — HEAD commit SHA -- `description` — MR body (Greptile may update this with the confidence score) - -## Trigger Greptile review - -```bash -glab mr note --message "@greptile review" -``` - -## Fetch pipelines for an MR - -```bash -glab api "projects/:fullpath/merge_requests//pipelines" -``` - -Check `status` field: `running`, `pending`, `success`, `failed`, `canceled`, `skipped`. - -## Fetch jobs for a pipeline (to find the Greptile job) - -```bash -glab api "projects/:fullpath/pipelines//jobs" -``` - -Filter jobs where `name` matches `greptile` (case-insensitive). Terminal statuses: `success`, `failed`, `canceled`. - -## Check if any pipeline is running - -```bash -glab api "projects/:fullpath/merge_requests//pipelines" | \ - jq '[.[] | select(.status == "running" or .status == "pending")] | length' -``` - -Returns `0` if no pipelines are running/pending. - -## Find pipeline for a specific commit SHA - -```bash -glab api "projects/:fullpath/merge_requests//pipelines" | \ - jq -r --arg sha "COMMIT_SHA" '[.[] | select(.sha == $sha)] | sort_by(.id) | last | .id // empty' -``` - -## Fetch MR notes (to find Greptile's confidence score) - -```bash -glab api "projects/:fullpath/merge_requests//notes?per_page=100&sort=desc&order_by=created_at" -``` - -Filter by `author.username` for the Greptile bot. Scan `body` for a confidence pattern like `3/5` or `5/5`. - -The Greptile bot username on GitLab may differ from GitHub's `greptile-apps[bot]` — check the first Greptile comment on the MR to identify the exact username. - -## Fetch unresolved discussions (inline comments) - -```bash -glab api "projects/:fullpath/merge_requests//discussions?per_page=100" -``` - -Paginate with `&page=2`, etc. until response array length < `per_page`. - -Filter for unresolved inline diff comments from Greptile: -```bash -jq '[.[] | select(.resolved == false and (.notes[0].type == "DiffNote") and (.notes[0].author.username == "GREPTILE_BOT_USERNAME"))]' -``` - -Each discussion has: -- `id` — use this for resolution -- `notes[0].body` — the comment text -- `notes[0].position.new_path` — file path - -## Resolve a discussion - -```bash -glab api --method PUT \ - "projects/:fullpath/merge_requests//discussions/" \ - --field resolved=true -``` - -GitLab has no batch resolution — issue one PUT per discussion. diff --git a/agents/skills/greploop/references/graphql-queries.md b/agents/skills/greploop/references/graphql-queries.md deleted file mode 100644 index b3727c1..0000000 --- a/agents/skills/greploop/references/graphql-queries.md +++ /dev/null @@ -1,49 +0,0 @@ -# GraphQL Queries Reference - -## Fetch unresolved review threads (paginated) - -```graphql -query($cursor: String) { - repository(owner: "OWNER", name: "REPO") { - pullRequest(number: PR_NUMBER) { - reviewThreads(first: 100, after: $cursor) { - pageInfo { hasNextPage endCursor } - nodes { - id - isResolved - comments(first: 3) { - nodes { - body - path - author { login } - createdAt - } - } - } - } - } - } -} -``` - -## Batch-resolve threads - -```graphql -mutation { - t1: resolveReviewThread(input: {threadId: "ID1"}) { thread { isResolved } } - t2: resolveReviewThread(input: {threadId: "ID2"}) { thread { isResolved } } -} -``` - -## Fetch general PR comments edited in place (REST) - -General PR comments are issue comments. Greptile may update one summary comment repeatedly, so select by `updated_at` instead of `created_at`: - -```bash -gh api --paginate "repos/{owner}/{repo}/issues//comments?per_page=100" \ - | jq -s 'add - | map(select(.user.login | test("greptile"; "i"))) - | sort_by(.updated_at) - | last - | {author: .user.login, updated_at, body}' -``` diff --git a/agents/skills/herdr/SKILL.md b/agents/skills/herdr/SKILL.md index fafea54..568097c 100644 --- a/agents/skills/herdr/SKILL.md +++ b/agents/skills/herdr/SKILL.md @@ -117,7 +117,7 @@ Use the kind requested by the user. Run `herdr agent` to inspect the installed k herdr agent start reviewer --kind codex --pane -- ``` -`agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. It defaults to a 30-second startup timeout. +A successful `agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. If the agent is blocked during startup, the command returns `agent_not_ready` immediately but keeps the name available for `agent read` and `agent send-keys`. Wait until the agent becomes idle before prompting it. Startup defaults to a 30-second timeout. Submit work through the agent surface: @@ -125,7 +125,7 @@ Submit work through the agent surface: herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000 ``` -`agent prompt` atomically submits text and encoded Enter while honoring the pane's live bracketed-paste mode. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`. +`agent prompt` honors the pane's live bracketed-paste mode and sends text followed by encoded Enter after a short delay. It rejects an agent already waiting at an approval or question dialog with `agent_blocked` before sending any input. Inspect the blocked UI and ask the user before answering it. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`. A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it. diff --git a/agents/skills/lark-apps/SKILL.md b/agents/skills/lark-apps/SKILL.md index c6089cf..93c575c 100644 --- a/agents/skills/lark-apps/SKILL.md +++ b/agents/skills/lark-apps/SKILL.md @@ -1,7 +1,7 @@ --- name: lark-apps version: 1.0.0 -description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。" +description: "妙搭（Spark/Miaoda）应用开发与托管：应用创建、本地全栈开发、云端生成迭代、创意设计（UI mockup / 可交互原型 / 线框图 / 落地页 / 仪表盘 / 幻灯片 deck / 视觉探索）、AI相关能力和飞书平台能力或者其他外部能力集成、日志/Trace/监控指标/PV/UV 查询、环境变量管理、应用协作者与协作权限设置、应用角色与成员管理、自动化触发器（定时/记录变更/Webhook/飞书审批）。当用户要开发/新建一个系统·工具·平台·应用，或要本地开发 / 云端开发 / 修改 / 部署 / 发布 / 上线 / 拿可分享链接，或用 HTML 做页面·网站·部署到妙搭，或要设计 / design / mockup / prototype / wireframe / 做 PPT / deck / 视觉探索，或提到妙搭/Spark/Miaoda（应用运行时域名形如 *.aiforce.cloud）、应用数据库、应用文件存储、开放 API Key、可见范围、应用协作者/开发权限、应用角色/角色成员、线上日志、接口请求量、错误量、延迟、访问量、环境变量、给妙搭应用配自动化任务/定时触发/审批通过后自动触发时使用。不负责普通云盘文件上传（lark-drive）、飞书文档编辑（lark-doc）、原生幻灯片创建（lark-slides）。" metadata: requires: bins: ["lark-cli"] @@ -44,6 +44,7 @@ lark-cli auth login --domain apps | 调试应用运行时缓存：查看/删除单个业务 key、清空指定环境缓存 | `+cache-get`/`+cache-delete`/`+cache-clear` | [`lark-apps-cache.md`](references/lark-apps-cache.md) | | **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | 本地开发链路先按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 确认本次改动已 git commit + git push，再用 `+release-create` / `+release-get`；查历史用 `+release-list` | [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md), [`lark-apps-release-create.md`](references/lark-apps-release-create.md), [`lark-apps-release-get.md`](references/lark-apps-release-get.md), [`lark-apps-release-list.md`](references/lark-apps-release-list.md) | | 设置或查看运行时可见范围 | `+access-scope-set`, `+access-scope-get` | 对应 access-scope reference | +| 管理应用协作者（列出/添加/改权限/移除）或协作权限设置 | `+member-list`, `+member-add`, `+member-update`, `+member-remove`, `+member-settings-get`, `+member-settings-set` | 本文「应用协作者与协作权限设置」 | | 创意模式（html）应用的评论相关操作 | 创意模式应用评论走 lark-drive 文档评论体系，读取 [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) 了解评论能力 | [`../lark-drive/SKILL.md`](../lark-drive/SKILL.md) | | 管理 `app_...` 应用内角色、角色成员，或查询用户匹配角色 | `+role-list/get/create/update/delete`, `+role-member-list/add/remove`, `+role-match-list` | [`lark-apps-role.md`](references/lark-apps-role.md) | | 云端 Agent 生成/迭代应用（开发方式已定为云端后） | `+session-create` -> `+chat` -> `+session-get` | [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) | @@ -51,35 +52,69 @@ lark-cli auth login --domain apps | 管理妙搭应用自动化触发器（定时/记录变更/Webhook/飞书审批四类触发器的查询/创建/更新/启停；Webhook URL·Token 一次性回显、不落盘） | `+automation-list/get/create/update/enable/disable` | [`lark-apps-automation.md`](references/lark-apps-automation.md) | | 查看某次会话某一轮（turn）的回复消息（含仍在生成中的本轮）/ 导出上一轮模型回复（"这一轮回复了什么""上一轮的回复""导出某轮消息"） | 先 `+session-get`（取 `latest_turn.turn_id`）-> `+session-messages-list --turn-id `（仅 user 身份；分页用 `--page-token`） | [`lark-apps-session-messages-list.md`](references/lark-apps-session-messages-list.md) | | 外部能力(AI模型能力和飞书平台能力)集成/插件/Plugin/Capability | `+plugin-install`, `+plugin-list`, `+plugin-uninstall` | [`lark-apps-plugin-install.md`](references/lark-apps-plugin-install.md), [`lark-apps-plugin-uninstall.md`](references/lark-apps-plugin-uninstall.md), [`lark-apps-plugin-list.md`](references/lark-apps-plugin-list.md) | +| 把一批 ID 在妙搭 user_id ↔ 飞书 open_id / union_id / 飞书 user_id 之间互转（例如拿到 open_id 但下游要 user_id） | `+user-id-convert --convert-type <方向> --ids ` | [`lark-apps-user-id-convert.md`](references/lark-apps-user-id-convert.md) | ## 高频路径 +- **Base 到应用数据库同步**：用户说“Base 同步到数据库 / 整库同步 / 多张表同步 / 批量任务重新启用 / operation-not-allowed”时，先读 [`lark-apps-db.md`](references/lark-apps-db.md) 的 Base 数据同步段落，再查 app_id 或处理授权。先形成计划再动手：`+db-sync-create` 一次只处理一张 Base 表，整库/多表必须拆成多份单表配置和多次 preview/create；batch/import 任务是一次性任务，不能重新 enable，遇 operation-not-allowed 先解释生命周期边界，再用 `+db-sync-get` 查状态/结果，持续同步要新建 streaming 任务。 - **性能/监控/观测指标**：用户问“接口请求量、错误量、错误率、接口慢、延迟、CPU、内存、最近一小时/七天趋势”时，不要去当前工作区搜索监控文件，也不要询问“监控数据在哪”。先按「app_id 获取」解析应用：`lark-cli apps +list --keyword "<应用名>" --as user`；拿到 `app_id` 后读 [`lark-apps-observability.md`](references/lark-apps-observability.md)，用 `+metric-list`。 - **请求量 + 错误量 + 延迟**：请求量/错误量用 `lark-cli apps +metric-list --app-id --metric requests --since --as user`（不传 `--series` 会同时返回 total/error）；延迟用 `--metric latency`（不传 `--series` 会返回 p50/p99）。如果用户给了具体接口，再加 `--api `；不要臆造 group-by 参数。 - **PV/UV/访问量/活跃用户**：先解析 `app_id`，再用 `+analytics-list`，不要误用 `+metric-list`。 - **设置环境变量**：如果用户只给应用名，仍先 `+list --keyword` 解析 app_id；设置 online 环境且用户已经明确说“确认/直接执行”时，调用 `+env-set --environment online ... --yes`，不要再次要求确认。回复和日志摘要里只提 key / env / app，不回显真实 value；需要传复杂值时优先用 `@file` 或 stdin。 - **删除环境变量**：`+env-delete` 是破坏性操作。除非用户在同一轮已经明确确认删除这个 app/env/key，否则先向用户确认应用、环境、key 和删除后果；确认后再加 `--yes`。不要因为认证失败/重登完成就自动继续删除，必须保留确认门槛。 +## 应用协作者与协作权限设置 + +这组命令管理妙搭应用的开发协作者和协作策略，不等同于 `+access-scope-*` 的运行时访问范围，也不等同于 `+role-*` 的应用内业务角色。所有命令使用 `app_...` 应用 ID 和 `--as user`。不要读取或判断 `app_type` 来预判支持范围，直接调用对应的协作者命令。 + +- `+member-list`、`+member-settings-get` 是只读命令，需要 `spark:app:read`。 +- `+member-add`、`+member-update`、`+member-remove`、`+member-settings-set` 是高风险写命令，需要 `spark:app:write`。先用 `--dry-run` 核对目标、URL 和请求体；dry-run 不需要 `--yes`。用户已确认具体应用、成员/设置及影响，或已按下方「高影响动作：确认与预授权」对整条流程明确预授权时，真实执行加 `--yes`；否则在 dry-run 后停下请求确认。批量移除成员仍执行「禁止预授权判定底线」，不能从泛化的“直接做”推导出 `--yes`。 +- 添加、更新、移除成员时必须显式提供匹配的外部 ID 类型，禁止传内部数字 ID、猜测类型或做隐式转换：用户 `--member-type openid --member-id ou_...`；群组 `--member-type openchat --member-id oc_...`；部门 `--member-type opendepartmentid --member-id od-...`。 +- `+member-list --member-type` 的筛选枚举是响应对象类型 `user` / `department` / `chat`，与写命令的 ID 类型枚举不同。可再用 `--role view|edit|full_access` 筛选。 +- `+member-list` 一次返回应用的全部直接协作者，不提供分页参数；可用 `--member-type` 和 `--role` 缩小结果范围。 +- 成员响应不包含应用详情。需要名称、类型或发布状态时单独调用 `+get --app-id `，不要期待成员分页重复返回 `app`。 +- 收到 subtype `feature_not_available`（OpenAPI code `3340005`；直连服务可能为 `40005`）时，立即停止 CLI 自动化，不切换 `app_type`，也不尝试用 access scope、应用角色或其它成员命令绕过。向用户说明该应用暂不支持通过 lark-cli 设置协作者，并引导其在妙搭后台的权限设置中操作。 +- `external_invite` 只在 `+member-settings-get` 的响应中读取，不能独立设置；它会跟随 `external_access`。CLI 不注册 `--external-invite`，需要改变外部协作能力时只设置 `--external-access`。 +- `copy_download_by` 也只在 `+member-settings-get` 的响应中读取。CCM 当前明确不支持为妙搭对象写入复制、打印和下载权限，因此 CLI 不注册 `--copy-download-by`。保留读取结果，不要尝试写入，也不要改用其它权限字段模拟。 + +```bash +# 读取协作者和当前协作策略 +lark-cli apps +member-list --app-id --as user +lark-cli apps +member-settings-get --app-id --as user + +# 写操作先预览精确的 typed-ID 字段；确认后把 --dry-run 换成 --yes +lark-cli apps +member-add --app-id --member-type openid --member-id ou_xxx --perm view --dry-run --as user +lark-cli apps +member-update --app-id --member-type openchat --member-id oc_xxx --perm edit --dry-run --as user +lark-cli apps +member-remove --app-id --member-type opendepartmentid --member-id od-xxx --dry-run --as user +lark-cli apps +member-settings-set --app-id --external-access disabled --comment-by viewer --dry-run --as user +``` + ## 选择开发路径（进意图路由前先判这步） 新建必先定 **app_type** 和**开发方式**两件正交的事；修改已有先按「app_id 获取」指认到 app，指认不到就问用户，不擅自 `+create`。开发方式（本地 vs 云端）只看用户对"谁来写代码"的偏好，与应用复杂度、要不要数据库无关。 +**app_type 三类边界**（先判"要不要把数据存到服务端"，再判"纯展示还是有交互"）： + | 信号 | 判定 | |---|---| -| 静态展示 / 单页 / PPT/deck / demo / 落地页 / 仪表盘 / UI mockup / 可交互原型 / 线框图 / 视觉探索 / 无后端状态 | `app_type=html`，加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） | -| 登录 / 数据库 / 持久化 / 多人协作 / 增删改查 / 报名 / 投票 / 站会 / OKR / 泛称"系统·工具" | `app_type=full_stack` | +| 含数据库 / 后端持久化：登录 / 增删改查 / 报名·投票·站会存记录 / 多人协作 / 泛称"系统·工具"且明确要存数据 | `app_type=full_stack` | +| 纯静态展示（给人"看"的物料，无 JS 交互）：PPT/deck / demo / 落地页 / 海报 / UI mockup / 线框图 / 静态仪表盘 / 视觉探索 | `app_type=html`，加载 [`creative-design/creative-design.md`](creative-design/creative-design.md)（含完整开发与发布流程） | +| 有 JS 交互但无数据库（给人"用"的前端应用）：可交互原型 / SPA / 表单校验 / 动态计算 / 调用外部 API / 泛称"工具·系统"但未明确要存数据 | `app_type=frontend`（**默认倾向**：用户未明确提出数据库需求时默认引导 frontend，不默认 full_stack） | +| 类型模糊（尤其"要不要存数据"不清） | **追问**，话术偏向 frontend，例："看起来是个前端应用，需要保存数据吗？"；确认要存数据再转 full_stack，确认纯展示再转 html | | 用户要自己写 / 本地 IDE·code agent / 拉源码到本地 / 交研发 | 本地开发，读 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) | | 让妙搭 AI 云端生成 / 对话式 / 自己不碰代码 | 云端会话，读 [`lark-apps-cloud-dev.md`](references/lark-apps-cloud-dev.md) | | 未表达"谁来写"偏好 | **必须先问**（本地代码开发 vs 云端 AI 生成）；选定前不擅自选边、不暗示默认，不得以"需求不模糊"为由跳过提问直接 `+init` / `git clone` / `+session-create` / 首轮 `+chat` | | 修改已有 + 当前目录是 `.spark/meta.json` 项目 | 直接继续本地按意图路由，不必问也不必判云端 | | 修改已有 + 有云端偏好 | 云端会话；未表达偏好且非本地项目 → 默认本地；判不准先问 | +**类型升级**：`frontend` 应用后续需要数据库/后端能力时，本地 CLI 不提供类型升级；引导用户到云端会话（打开 `https://miaoda.feishu.cn/app/{app_id}`），用自然语言描述后端需求（如"给这个应用加登录和数据存储"）即可触发升级，无需特殊指令。 + ## 发布态护栏 - **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路、确认完成再给链接。 - 完成 ≠ 发布：云端会话完成 / `+list is_published=true` 都不代表最新内容已部署。 -- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`（仅 full_stack 应用）：进应用编辑/开发态、管理与继续开发应用的入口。创意模式（html）应用开发态和发布态是同一个链接，无需额外提供开发态链接。 -- 发布态链接来源：`+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`（html 和 full_stack 统一走 `+release-get`）。 +- 开发态链接 `https://miaoda.feishu.cn/app/{app_id}`（full_stack / frontend 应用）：进应用编辑/开发态、管理与继续开发应用的入口，也是 frontend 升级为 full_stack 的入口（云端会话）。创意模式（html）应用开发态和发布态是同一个链接，无需额外提供开发态链接。 +- 发布态链接来源：`+release-get` 轮询 `finished` 给 `online_url` / `failed` 给 `error_logs`（html / frontend / full_stack 统一走 `+release-get`）。 - html 应用的主链路是创意模式开发方式：按 [`lark-apps-local-dev.md`](references/lark-apps-local-dev.md) 初始化仓库、在仓库内产出 HTML 及关联文件，并通过 git commit / git push / `+release-create` / `+release-get` 发布部署。任何 git 操作（clone / pull / push）报错时，先执行 `lark-cli apps +git-credential-init --app-id --as user` 刷新本地 Git 凭证，再重试原 git 命令。如果刷新凭证也失败，**停止并向用户报告**：原始 git 错误、凭证刷新失败原因，以及是否可能是当前环境（操作系统、沙箱）限制导致（如 macOS Keychain 在沙箱中不可用、Linux 加密文件目录不可写等）。不要改走 `+html-publish`，也不要把 `+html-publish` 当作本地开发链路的 fallback。 - 创意模式（html）应用的链接格式为 `https://{租户域名}/page/{meta_token}`，**开发态和发布态是同一个链接**（区别于 full_stack 应用两者分开）。此链接形似飞书文档链接。`+get --app-id ` 可获取应用信息（含 `app_id`），`+get --app-id ` 可获取 `meta_token`。看到 `/page/xxx` 链接时，它是妙搭创意模式应用，不要当成飞书文档跳过。 @@ -93,7 +128,7 @@ lark-cli auth login --domain apps - 实现领域 SDK 时，以实际包导出的类型和应用内领域 reference 记录的入参、响应路径为准；禁止修改 ambient `.d.ts`、补造宽松类型或强制断言，让猜测的 SDK 结构仅在本地"编译通过"。 - typecheck/build 成功不等于合同正确。交付前逐项核对每个 SDK 调用的入参、响应取值路径和策略分支；涉及更新、删除等不同动作时，分别验证各自动作所需的完整状态，不能复用更弱的前置判断。 - 源码任务交付前确认新增页面、Controller、Module 已接入真实 router/bootstrap，并运行项目现有 typecheck/build；只创建未接线文件不算完成。 -- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限仍需使用妙搭 Web。自动化触发器请用 `+automation-*`（见「意图路由」）。 +- `+access-scope-*` 只管运行时可见范围（谁能打开应用），不是角色权限；应用协作者/开发权限使用 `+member-*` 和 `+member-settings-*`，应用内业务角色使用 `+role-*`。自动化触发器请用 `+automation-*`（见「意图路由」）。 ## app_id 获取 diff --git a/agents/skills/lark-apps/creative-design/assets/index.html b/agents/skills/lark-apps/creative-design/assets/index.html index 5b91de2..b845ff6 100644 --- a/agents/skills/lark-apps/creative-design/assets/index.html +++ b/agents/skills/lark-apps/creative-design/assets/index.html @@ -5,7 +5,7 @@ -