@miaws/miaw 1.18.4 → 1.18.5

package/test/fixture/flock-worker.ts

@@ -0,0 +1,72 @@
+import fs from "fs/promises"
+import { Flock } from "@miaw/core/util/flock"
+
+type Msg = {
+  key: string
+  dir: string
+  staleMs?: number
+  timeoutMs?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  holdMs?: number
+  ready?: string
+  active?: string
+  done?: string
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+function input() {
+  const raw = process.argv[2]
+  if (!raw) {
+    throw new Error("Missing flock worker input")
+  }
+
+  return JSON.parse(raw) as Msg
+}
+
+async function job(input: Msg) {
+  if (input.ready) {
+    await fs.writeFile(input.ready, String(process.pid))
+  }
+
+  if (input.active) {
+    await fs.writeFile(input.active, String(process.pid), { flag: "wx" })
+  }
+
+  try {
+    if (input.holdMs && input.holdMs > 0) {
+      await sleep(input.holdMs)
+    }
+
+    if (input.done) {
+      await fs.appendFile(input.done, "1\n")
+    }
+  } finally {
+    if (input.active) {
+      await fs.rm(input.active, { force: true })
+    }
+  }
+}
+
+async function main() {
+  const msg = input()
+
+  await Flock.withLock(msg.key, () => job(msg), {
+    dir: msg.dir,
+    staleMs: msg.staleMs,
+    timeoutMs: msg.timeoutMs,
+    baseDelayMs: msg.baseDelayMs,
+    maxDelayMs: msg.maxDelayMs,
+  })
+}
+
+await main().catch((err) => {
+  const text = err instanceof Error ? (err.stack ?? err.message) : String(err)
+  process.stderr.write(text)
+  process.exit(1)
+})

package/test/fixture/lsp/fake-lsp-server.js

@@ -0,0 +1,249 @@
+// Simple JSON-RPC 2.0 LSP-like fake server over stdio
+
+let nextId = 1
+let readBuffer = Buffer.alloc(0)
+let lastChange = null
+let initializeParams = null
+let diagnosticRequestCount = 0
+let registeredCapability = false
+const pendingClientRequests = new Map()
+let pullConfig = {
+  delayMs: 0,
+  registerOn: undefined,
+  registrations: [],
+  documentDiagnostics: [],
+  documentDiagnosticsByIdentifier: {},
+  documentDelayMsByIdentifier: {},
+  workspaceDiagnostics: [],
+  workspaceDiagnosticsByIdentifier: {},
+  workspaceDelayMsByIdentifier: {},
+}
+
+function encode(message) {
+  const json = JSON.stringify(message)
+  const header = `Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n`
+  return Buffer.concat([Buffer.from(header, "utf8"), Buffer.from(json, "utf8")])
+}
+
+function decodeFrames(buffer) {
+  const results = []
+  let idx
+  while ((idx = buffer.indexOf("\r\n\r\n")) !== -1) {
+    const header = buffer.slice(0, idx).toString("utf8")
+    const match = /Content-Length:\s*(\d+)/i.exec(header)
+    const length = match ? parseInt(match[1], 10) : 0
+    const bodyStart = idx + 4
+    const bodyEnd = bodyStart + length
+    if (buffer.length < bodyEnd) break
+    results.push(buffer.slice(bodyStart, bodyEnd).toString("utf8"))
+    buffer = buffer.slice(bodyEnd)
+  }
+  return { messages: results, rest: buffer }
+}
+
+function send(message) {
+  process.stdout.write(encode(message))
+}
+
+function sendRequest(method, params) {
+  const id = nextId++
+  send({ jsonrpc: "2.0", id, method, params })
+  return id
+}
+
+function sendResponse(id, result) {
+  send({ jsonrpc: "2.0", id, result })
+}
+
+function sendNotification(method, params) {
+  send({ jsonrpc: "2.0", method, params })
+}
+
+function maybeRegister(method) {
+  if (pullConfig.registerOn !== method || registeredCapability) return
+  registeredCapability = true
+  sendRequest("client/registerCapability", {
+    registrations: pullConfig.registrations.map((registration, index) => ({
+      id: registration.id ?? `pull-${index}`,
+      method: registration.method ?? "textDocument/diagnostic",
+      registerOptions: registration.registerOptions ?? registration,
+    })),
+  })
+}
+
+function delayed(id, result, delayMs = pullConfig.delayMs) {
+  if (!delayMs) {
+    sendResponse(id, result)
+    return
+  }
+  setTimeout(() => sendResponse(id, result), delayMs)
+}
+
+function diagnosticsForIdentifier(identifier) {
+  return pullConfig.documentDiagnosticsByIdentifier[identifier] ?? pullConfig.documentDiagnostics
+}
+
+function workspaceDiagnosticsForIdentifier(identifier) {
+  return pullConfig.workspaceDiagnosticsByIdentifier[identifier] ?? pullConfig.workspaceDiagnostics
+}
+
+function documentDelayForIdentifier(identifier) {
+  return pullConfig.documentDelayMsByIdentifier[identifier] ?? pullConfig.delayMs
+}
+
+function workspaceDelayForIdentifier(identifier) {
+  return pullConfig.workspaceDelayMsByIdentifier[identifier] ?? pullConfig.delayMs
+}
+
+function handle(raw) {
+  let data
+  try {
+    data = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  if (typeof data.method === "undefined" && typeof data.id !== "undefined") {
+    const pending = pendingClientRequests.get(data.id)
+    if (!pending) return
+    pendingClientRequests.delete(data.id)
+    sendResponse(pending, data.result ?? null)
+    return
+  }
+
+  if (data.method === "initialize") {
+    initializeParams = data.params
+    sendResponse(data.id, {
+      capabilities: {
+        textDocumentSync: {
+          change: 2,
+        },
+      },
+    })
+    return
+  }
+
+  if (data.method === "test/get-initialize-params") {
+    sendResponse(data.id, initializeParams)
+    return
+  }
+
+  if (data.method === "test/request-configuration") {
+    const id = sendRequest("workspace/configuration", data.params)
+    pendingClientRequests.set(id, data.id)
+    return
+  }
+
+  if (data.method === "initialized" || data.method === "workspace/didChangeConfiguration") {
+    return
+  }
+
+  if (data.method === "textDocument/didOpen") {
+    maybeRegister("didOpen")
+    return
+  }
+
+  if (data.method === "textDocument/didChange") {
+    lastChange = data.params
+    maybeRegister("didChange")
+    return
+  }
+
+  if (data.method === "test/trigger") {
+    const method = data.params && data.params.method
+    if (method === "client/registerCapability") {
+      sendRequest(method, {
+        registrations: [
+          {
+            id: "test-diagnostic-registration",
+            method: "textDocument/diagnostic",
+            registerOptions: { identifier: "syntax" },
+          },
+        ],
+      })
+      return
+    }
+    if (method === "client/unregisterCapability") {
+      sendRequest(method, {
+        unregisterations: [{ id: "test-diagnostic-registration", method: "textDocument/diagnostic" }],
+      })
+      return
+    }
+    if (method) sendRequest(method, {})
+    return
+  }
+
+  if (data.method === "test/configure-pull-diagnostics") {
+    pullConfig = {
+      delayMs: data.params?.delayMs ?? 0,
+      registerOn: data.params?.registerOn,
+      registrations: data.params?.registrations ?? [],
+      documentDiagnostics: data.params?.documentDiagnostics ?? [],
+      documentDiagnosticsByIdentifier: data.params?.documentDiagnosticsByIdentifier ?? {},
+      documentDelayMsByIdentifier: data.params?.documentDelayMsByIdentifier ?? {},
+      workspaceDiagnostics: data.params?.workspaceDiagnostics ?? [],
+      workspaceDiagnosticsByIdentifier: data.params?.workspaceDiagnosticsByIdentifier ?? {},
+      workspaceDelayMsByIdentifier: data.params?.workspaceDelayMsByIdentifier ?? {},
+    }
+    registeredCapability = false
+    sendResponse(data.id, null)
+    return
+  }
+
+  if (data.method === "test/register-configured-pull-diagnostics") {
+    maybeRegister(undefined)
+    sendResponse(data.id, null)
+    return
+  }
+
+  if (data.method === "test/publish-diagnostics") {
+    sendNotification("textDocument/publishDiagnostics", data.params)
+    return
+  }
+
+  if (data.method === "test/get-last-change") {
+    sendResponse(data.id, lastChange)
+    return
+  }
+
+  if (data.method === "test/get-diagnostic-request-count") {
+    sendResponse(data.id, diagnosticRequestCount)
+    return
+  }
+
+  if (data.method === "textDocument/diagnostic") {
+    diagnosticRequestCount += 1
+    delayed(
+      data.id,
+      {
+        kind: "full",
+        items: diagnosticsForIdentifier(data.params?.identifier ?? ""),
+      },
+      documentDelayForIdentifier(data.params?.identifier ?? ""),
+    )
+    return
+  }
+
+  if (data.method === "workspace/diagnostic") {
+    diagnosticRequestCount += 1
+    delayed(
+      data.id,
+      {
+        items: workspaceDiagnosticsForIdentifier(data.params?.identifier ?? ""),
+      },
+      workspaceDelayForIdentifier(data.params?.identifier ?? ""),
+    )
+    return
+  }
+
+  if (typeof data.id !== "undefined") {
+    sendResponse(data.id, null)
+  }
+}
+
+process.stdin.on("data", (chunk) => {
+  readBuffer = Buffer.concat([readBuffer, chunk])
+  const { messages, rest } = decodeFrames(readBuffer)
+  readBuffer = rest
+  for (const message of messages) handle(message)
+})

package/test/fixture/mcp-session-recovery.ts

@@ -0,0 +1,50 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js"
+
+const posts: Array<{ method: string; session: string | null }> = []
+let initializeCount = 0
+let pingCount = 0
+const server = Bun.serve({
+  port: 0,
+  async fetch(request) {
+    if (request.method === "GET") return new Response(null, { status: 405 })
+    if (request.method === "DELETE") return new Response(null, { status: 200 })
+
+    const message = (await request.json()) as { id?: number; method: string }
+    const session = request.headers.get("mcp-session-id")
+    posts.push({ method: message.method, session })
+
+    if (message.method === "initialize") {
+      initializeCount++
+      return Response.json(
+        {
+          jsonrpc: "2.0",
+          id: message.id,
+          result: {
+            protocolVersion: LATEST_PROTOCOL_VERSION,
+            capabilities: {},
+            serverInfo: { name: "test", version: "1" },
+          },
+        },
+        { headers: { "mcp-session-id": initializeCount === 1 ? "expired" : "replacement" } },
+      )
+    }
+
+    if (message.method === "notifications/initialized") return new Response(null, { status: 202 })
+
+    pingCount++
+    if (pingCount === 1) return new Response("Session not found", { status: 404 })
+    return Response.json({ jsonrpc: "2.0", id: message.id, result: {} })
+  },
+})
+const client = new Client({ name: "test", version: "1" })
+
+try {
+  await client.connect(new StreamableHTTPClientTransport(server.url))
+  await client.ping()
+  process.stdout.write(JSON.stringify(posts))
+} finally {
+  await client.close()
+  server.stop(true)
+}

package/test/fixture/plug-worker.ts

@@ -0,0 +1,93 @@
+import path from "path"
+
+import { createPlugTask, type PlugCtx, type PlugDeps } from "../../src/cli/cmd/plug"
+import { Filesystem } from "@/util/filesystem"
+
+type Msg = {
+  dir: string
+  target: string
+  mod: string
+  global?: boolean
+  force?: boolean
+  globalDir?: string
+  vcs?: string
+  worktree?: string
+  directory?: string
+  holdMs?: number
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+function input() {
+  const raw = process.argv[2]
+  if (!raw) {
+    throw new Error("Missing plug worker input")
+  }
+
+  const msg = JSON.parse(raw) as Partial<Msg>
+  if (!msg.dir || !msg.target || !msg.mod) {
+    throw new Error("Invalid plug worker input")
+  }
+
+  return msg as Msg
+}
+
+function deps(msg: Msg): PlugDeps {
+  return {
+    spinner: () => ({
+      start() {},
+      stop() {},
+    }),
+    log: {
+      error() {},
+      info() {},
+      success() {},
+    },
+    resolve: async () => msg.target,
+    readText: (file) => Filesystem.readText(file),
+    write: async (file, text) => {
+      if (msg.holdMs && msg.holdMs > 0) {
+        await sleep(msg.holdMs)
+      }
+      await Filesystem.write(file, text)
+    },
+    exists: (file) => Filesystem.exists(file),
+    files: (dir, name) => [path.join(dir, `${name}.jsonc`), path.join(dir, `${name}.json`)],
+    global: msg.globalDir ?? path.join(msg.dir, ".global"),
+  }
+}
+
+function ctx(msg: Msg): PlugCtx {
+  return {
+    vcs: msg.vcs ?? "git",
+    worktree: msg.worktree ?? msg.dir,
+    directory: msg.directory ?? msg.dir,
+  }
+}
+
+async function main() {
+  const msg = input()
+  const run = createPlugTask(
+    {
+      mod: msg.mod,
+      global: msg.global,
+      force: msg.force,
+    },
+    deps(msg),
+  )
+
+  const ok = await run(ctx(msg))
+  if (!ok) {
+    throw new Error("Plug task failed")
+  }
+}
+
+await main().catch((err) => {
+  const text = err instanceof Error ? (err.stack ?? err.message) : String(err)
+  process.stderr.write(text)
+  process.exit(1)
+})

package/test/fixture/plugin-meta-worker.ts

@@ -0,0 +1,19 @@
+const raw = process.argv[2]
+if (!raw) throw new Error("Missing worker payload")
+
+const value = JSON.parse(raw)
+if (!value || typeof value !== "object") {
+  throw new Error("Invalid worker payload")
+}
+
+const msg = Object.fromEntries(Object.entries(value))
+if (typeof msg.file !== "string" || typeof msg.spec !== "string" || typeof msg.target !== "string") {
+  throw new Error("Invalid worker payload")
+}
+if (typeof msg.id !== "string") throw new Error("Invalid worker payload")
+
+process.env.MIAW_PLUGIN_META_FILE = msg.file
+
+const { PluginMeta } = await import("../../src/plugin/meta")
+
+await PluginMeta.touch(msg.spec, msg.target, msg.id)

package/test/fixture/plugin.ts

@@ -0,0 +1,10 @@
+import { mkdir } from "fs/promises"
+import path from "path"
+
+export async function markPluginDependenciesReady(dir: string) {
+  await mkdir(path.join(dir, "node_modules"), { recursive: true })
+  await Bun.write(
+    path.join(dir, "package-lock.json"),
+    JSON.stringify({ packages: { "": { dependencies: { "@miaw/plugin": "0.0.0" } } } }),
+  )
+}

package/test/fixture/skills/agents-sdk/SKILL.md

@@ -0,0 +1,152 @@
+---
+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, or chat applications. Covers Agent class, state management, callable RPC, Workflows integration, and React hooks.
+---
+
+# Cloudflare Agents SDK
+
+**STOP.** Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.
+
+## Documentation
+
+Fetch current docs from `https://github.com/cloudflare/agents/tree/main/docs` before implementing.
+
+| Topic               | Doc                           | Use for                                        |
+| ------------------- | ----------------------------- | ---------------------------------------------- |
+| Getting started     | `docs/getting-started.md`     | First agent, project setup                     |
+| State               | `docs/state.md`               | `setState`, `validateStateChange`, persistence |
+| Routing             | `docs/routing.md`             | URL patterns, `routeAgentRequest`, `basePath`  |
+| Callable methods    | `docs/callable-methods.md`    | `@callable`, RPC, streaming, timeouts          |
+| Scheduling          | `docs/scheduling.md`          | `schedule()`, `scheduleEvery()`, cron          |
+| Workflows           | `docs/workflows.md`           | `AgentWorkflow`, durable multi-step tasks      |
+| HTTP/WebSockets     | `docs/http-websockets.md`     | Lifecycle hooks, hibernation                   |
+| Email               | `docs/email.md`               | Email routing, secure reply resolver           |
+| MCP client          | `docs/mcp-client.md`          | Connecting to MCP servers                      |
+| MCP server          | `docs/mcp-servers.md`         | Building MCP servers with `McpAgent`           |
+| Client SDK          | `docs/client-sdk.md`          | `useAgent`, `useAgentChat`, React hooks        |
+| Human-in-the-loop   | `docs/human-in-the-loop.md`   | Approval flows, pausing workflows              |
+| Resumable streaming | `docs/resumable-streaming.md` | Stream recovery on disconnect                  |
+
+Cloudflare docs: https://developers.cloudflare.com/agents/
+
+## Capabilities
+
+The Agents SDK provides:
+
+- **Persistent state** - SQLite-backed, auto-synced to clients
+- **Callable RPC** - `@callable()` methods invoked over WebSocket
+- **Scheduling** - One-time, recurring (`scheduleEvery`), and cron tasks
+- **Workflows** - Durable multi-step background processing via `AgentWorkflow`
+- **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
+- **React hooks** - `useAgent`, `useAgentChat` for client apps
+
+## FIRST: Verify Installation
+
+```bash
+npm ls agents  # Should show agents package
+```
+
+If not installed:
+
+```bash
+npm install agents
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
+}
+```
+
+## Agent Class
+
+```typescript
+import { Agent, routeAgentRequest, callable } from "agents"
+
+type State = { count: number }
+
+export class Counter extends Agent<Env, State> {
+  initialState = { count: 0 }
+
+  // Validation hook - runs before state persists (sync, throwing rejects the update)
+  validateStateChange(nextState: State, source: Connection | "server") {
+    if (nextState.count < 0) throw new Error("Count cannot be negative")
+  }
+
+  // Notification hook - runs after state persists (async, non-blocking)
+  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" })`
+
+## 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)` |
+
+## 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 <button onClick={() => agent.setState({ count: state.count + 1 })}>Count: {state.count}</button>
+}
+```
+
+## References
+
+- **[references/workflows.md](references/workflows.md)** - Durable Workflows integration
+- **[references/callable.md](references/callable.md)** - RPC methods, streaming, timeouts
+- **[references/state-scheduling.md](references/state-scheduling.md)** - State persistence, scheduling
+- **[references/streaming-chat.md](references/streaming-chat.md)** - AIChatAgent, resumable streams
+- **[references/mcp.md](references/mcp.md)** - MCP server integration
+- **[references/email.md](references/email.md)** - Email routing and handling
+- **[references/codemode.md](references/codemode.md)** - Code Mode (experimental)