@cursor/july 0.1.92 → 0.1.94

package/docs/example-agents/weather-agent.md

@@ -1,301 +0,0 @@
----
-title: "Explore the full Agent SDK surface with a weather agent"
-description: "Trace cloud tools, MCP, channels, skills, subagents, schedules, hooks, A/B metrics, and evals through one agent."
----
-
-# Explore the full Agent SDK surface with a weather agent
-
-The weather agent is the broadest small example in the repository. It fetches
-live conditions and forecasts, converts units through MCP, writes notes in a
-session workspace, and runs from HTTP, Slack, a schedule, and the MCP endpoint.
-
-Use this project when you want to see how the Agent SDK's filesystem pieces fit
-together before you design a larger agent.
-
-[Browse the weather agent source.](../../examples/weather-agent/)
-
-## See the runtime features together
-
-Most examples focus on one feature. Weather agent puts the major runtime
-features side by side:
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Root config and instructions | [`agent/agent.ts`](../../examples/weather-agent/agent/agent.ts), [`agent/instructions.md`](../../examples/weather-agent/agent/instructions.md) | Select the cloud runtime and route each request. |
-| Server tools | [`agent/tools/`](../../examples/weather-agent/agent/tools/) | Fetch Open-Meteo data and call MCP from the serve host. |
-| Agent tool | [`save_weather_note.ts`](../../examples/weather-agent/agent/tools/save_weather_note.ts) | Run a Python script inside the session workspace. |
-| Stdio MCP | [`units.ts`](../../examples/weather-agent/agent/mcp-connections/units.ts), [`probe.ts`](../../examples/weather-agent/agent/mcp-connections/probe.ts) | Expose conversion tools to the model, host tools, and channel handlers. Author VM-side probe tools as TypeScript `execute` functions. |
-| Custom HTTP | [`webhook.ts`](../../examples/weather-agent/agent/channels/webhook.ts) | Start a turn or call MCP without a model turn. |
-| Slack | [`slack.ts`](../../examples/weather-agent/agent/channels/slack.ts), [`slack-app.ts`](../../examples/weather-agent/agent/channels/slack-app.ts) | Compare account-linked chat with a dedicated app. |
-| Skill and subagent | [`forecast.md`](../../examples/weather-agent/agent/skills/forecast.md), [`researcher/`](../../examples/weather-agent/agent/subagents/researcher/) | Load a procedure on demand or delegate broad research. |
-| Schedule and hooks | [`heartbeat.md`](../../examples/weather-agent/agent/schedules/heartbeat.md), [`audit.ts`](../../examples/weather-agent/agent/hooks/audit.ts), [`journal.ts`](../../examples/weather-agent/agent/hooks/journal.ts) | Start recurring tasks, log usage, and save turn summaries. |
-| A/B and evals | [`agent/ab.ts`](../../examples/weather-agent/agent/ab.ts), [`evals/`](../../examples/weather-agent/evals/) | Compare a sticky variant and protect tool routing with regression cases. |
-
-## Follow one request
-
-A current-weather question takes this path:
-
-1. The built-in HTTP channel, Slack, or the custom `/report` route creates a
-   durable session.
-2. `instructions.md` tells the model to call `get_weather` instead of
-   guessing.
-3. The server tool geocodes the city, fetches Open-Meteo, validates the
-   response, and returns normalized fields.
-4. The agent writes a short answer. The Agent SDK records every event in the
-   session stream.
-5. The audit hook observes `turn.completed`. If the session joined the A/B
-   experiment, the collector updates its metrics too.
-
-Forecasts route to `get_forecast`. Unit conversions route to
-`convert_temperature`, which calls the `units` MCP server through
-`ctx.host.mcp`. Climate history and broad comparisons route to the
-`researcher` subagent.
-
-## Prepare the example
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential.
-- Network access to Open-Meteo.
-- Python 3 for `save_weather_note`.
-
-The project mounts an account-linked Slack channel. The Agent SDK checks the
-connection at startup, so sign in even when you plan to call a deterministic
-tool.
-
-The optional dedicated Slack app also needs a token pair.
-`agent-sdk slack create --dir examples/weather-agent` provisions the
-app and writes the tokens for you (see the
-[Slack guide](../guides/slack.md#set-it-up)); with hand-minted tokens,
-export them instead:
-
-```bash
-export WEATHER_AGENT_SLACK_BOT_TOKEN=xoxb-...
-export WEATHER_AGENT_SLACK_APP_TOKEN=xapp-...
-agent-sdk slack doctor --prefix WEATHER_AGENT
-```
-
-Without those two tokens, the dedicated channel stays idle. The
-account-linked channel still works.
-
-## Inspect before running
-
-```bash
-agent-sdk validate --dir examples/weather-agent
-agent-sdk info --dir examples/weather-agent --json
-agent-sdk eval --dir examples/weather-agent --list
-```
-
-`validate` should pass. `info` and `eval --list` should match the capabilities
-described above.
-
-## Call the typed tools
-
-Start with the current-weather server tool:
-
-```bash
-agent-sdk call get_weather \
-  --dir examples/weather-agent \
-  --input '{"city":"New York City"}'
-```
-
-`defineTool` gives the input a Zod schema. The Agent SDK validates the JSON before
-`execute` runs. The result includes the matched place, condition,
-temperature, humidity, wind, gusts, and precipitation.
-
-Try the forecast:
-
-```bash
-agent-sdk call get_forecast \
-  --dir examples/weather-agent \
-  --input '{"city":"Lisbon","days":5}'
-```
-
-The tool accepts one to seven days. Shared Open-Meteo code lives under
-`agent/lib/`, so the Agent SDK imports it without discovering another tool.
-
-## Compare server and agent execution
-
-Most weather tools use the default `execution: "server"`. Their TypeScript
-runs inside the serve host and can reach `ctx.host` services.
-
-`save_weather_note` uses `execution: "agent"` instead. The Agent SDK materializes
-its script into the agent environment. The script reads JSON from stdin and
-appends to `weather-notes.md` in that session's workspace:
-
-```bash
-agent-sdk run --dir examples/weather-agent \
-  --message "Save a note that Boston is cold and windy."
-```
-
-Each session gets its own workspace. Saving a note doesn't edit the authored
-example.
-
-This split matters on cloud. Server tools stay on the Agent SDK host.
-Agent tools run inside the cloud workspace.
-
-## Verify tool execution on the agent VM
-
-Ask the agent to call `probe_cloud_tool` on the `probe` MCP server.
-`agent/mcp-connections/probe.ts` authors that tool as TypeScript. The Agent
-SDK packages it as stdio MCP so a cloud VM with no checkout of this example
-can still run it. The model lists the server and calls the tool; it does
-not write a `.sh`.
-
-A real call writes `vm-tool-observations/<id>.json` in the agent cwd and
-returns hostname, cwd, and pid. Stream events show `probe:probe_cloud_tool`,
-not `shell`.
-
-A local `.agent-serve/tools/probe_cloud_tool.sh` or a marker under `probes/`
-means the model invented a substitute.
-
-```bash
-agent-sdk run --dir examples/weather-agent \
-  --message "Test custom tool execution from this cloud agent. Call probe_cloud_tool."
-```
-
-## Use MCP connections in three places
-
-`agent/mcp-connections/units.ts` starts a local stdio server. The filename
-makes its server name `units`. The Agent SDK exposes it to:
-
-- the model as MCP tools,
-- server tools through `ctx.host.mcp`, and
-- channel handlers through `host.mcp`.
-
-`probe` is a second stdio connection. Its tools are TypeScript `execute`
-functions; the Agent SDK packages them so a cloud VM can spawn the server
-without this checkout. The model calls `probe_cloud_tool` directly; no host
-tool wraps it.
-
-`convert_temperature` demonstrates the server-tool path:
-
-```bash
-agent-sdk call convert_temperature \
-  --dir examples/weather-agent \
-  --input '{"value":72,"from":"F"}'
-```
-
-The custom channel demonstrates the handler path. Start the dev server:
-
-```bash
-agent-sdk dev examples/weather-agent
-```
-
-Then call MCP deterministically through `/convert`:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/convert \
-  -H 'content-type: application/json' \
-  -d '{"value":20,"from":"C"}'
-```
-
-No model chooses a tool in this route. The handler calls the MCP server and
-returns its result.
-
-## Keep conversation state in a custom channel
-
-`POST /report` starts a model turn and waits for it:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report \
-  -H 'content-type: application/json' \
-  -d '{"message":"What is the weather in Paris?"}'
-```
-
-The response includes a `key`. Send it back on the next request to continue
-the same session:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report \
-  -H 'content-type: application/json' \
-  -d '{"message":"How about tomorrow?","key":"<key>"}'
-```
-
-This is the custom-channel version of a continuation token. See
-[webhooks and custom channels](../guides/webhooks.md) for route schemas,
-authentication, and asynchronous handlers.
-
-## Load procedures and delegate research
-
-The forecast skill gives the root agent an on-demand procedure. The Agent SDK
-advertises the skill's description, then the harness loads its content when
-the request matches.
-
-The `researcher` directory is an SDK subagent. Its description tells the
-parent when to delegate. It inherits the parent's execution surface, but
-gets its own instructions:
-
-```bash
-agent-sdk run --dir examples/weather-agent \
-  --message "Compare record summer temperatures across Paris, London, and Rome."
-```
-
-Use a skill when the same agent needs a procedure. Use a subagent when the
-parent should hand a bounded task to a specialist. The
-[subagents reference](../reference/subagents.md) explains the current
-inheritance limits.
-
-## Trigger the schedule and inspect the hook
-
-The heartbeat schedule runs at 09:00 UTC on weekdays. Automatic schedule
-timers stay off under `--dev`, so dispatch it manually:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/dev/schedules/heartbeat
-```
-
-It creates a task session to check San Francisco, New York, and London.
-The audit hook logs usage after each completed turn. Hooks observe recorded
-events; their failures don't fail the turn.
-
-## Measure variants and regressions
-
-The `weather-tool-efficiency` A/B experiment assigns sessions by a sticky
-hash:
-
-- `control` returns current conditions in Fahrenheit.
-- `treatment` adds a brief Celsius instruction and changes `get_weather` to
-  return Celsius fields.
-
-Samples and aggregate snapshots persist under `.agent-serve/`. The treatment
-only changes current conditions; `get_forecast` still returns Fahrenheit.
-Treat the branch as an example of `ctx.session.abs`, not a complete unit
-policy.
-
-List and run the evals:
-
-```bash
-agent-sdk eval --dir examples/weather-agent --list
-agent-sdk eval --dir examples/weather-agent --json
-```
-
-The suite covers weather and forecast routing, the local converter, workspace
-notes, and the VM-side probe.
-
-## Turn the weather tour into your own agent
-
-Keep the shape and replace the domain:
-
-- Swap Open-Meteo tools for your typed service clients.
-- Keep deterministic transforms behind direct server tools or MCP.
-- Use an agent tool only when code must run in the agent workspace.
-- Put reusable procedures in skills and narrow specialist work into
-  subagents.
-- Add a channel only when the external surface needs its own identity,
-  continuation key, or delivery behavior.
-
-## Where to go next
-
-- [Tools](../reference/tools.md)
-- [MCP connections](../reference/connections.md)
-- [Human-in-the-loop approvals](../guides/human-in-the-loop.md)
-- [Slack](../guides/slack.md)
-- [Schedules and reminders](../reference/schedules.md)
-- [Evals](../evals.md)
-- [Live A/B metrics](../ab.md)

package/src/channels/slack/cursor-account.ts

@@ -1,202 +0,0 @@
-/**
- * Cursor-account mode for the Slack channel pack: instead of a dedicated
- * Slack app (Socket Mode + `xoxb`/`xapp` tokens), the channel rides the
- * signed-in Cursor account's Slack connection. Inbound events are relayed
- * by the serve host from `/v0/slack-events` (see
- * `internal/cursor-slack-relay.ts`); outbound Web API calls run through a
- * {@link SlackApiTransport} bound to the backend proxy.
- *
- * This file is the seam between the channel definition (authored at
- * `defineChannel` time) and the serve-time relay: `slackChannel()` registers
- * a runtime ref here, and the server discovers it, binds the transport, and
- * dispatches relayed envelopes through the pack's normal inbound path.
- */
-
-import type { ArtifactsApi, HostContext, SendMessageFn } from "../../types.js";
-import { dispatchInboundMessage } from "./dispatch.js";
-import type { EventIdDedupe } from "./event-id-dedupe.js";
-import { slackTextToMarkdown } from "./inbound.js";
-import type { SlackLog } from "./log.js";
-import type {
-  SlackApiTransport,
-  SlackChannelOptions,
-  SlackCredentials,
-  SlackMessage,
-  SlackMessageFile,
-  SlackMessageHandler,
-} from "./types.js";
-
-/**
- * Transport placeholder created at `slackChannel()` definition time and
- * bound to the real backend proxy caller when the serve host starts its
- * relay. Calls before binding soft-fail Slack-style.
- */
-export interface PendingSlackApiTransport extends SlackApiTransport {
-  bind(impl: SlackApiTransport["call"]): void;
-}
-
-export function createPendingSlackApiTransport(): PendingSlackApiTransport {
-  let bound: SlackApiTransport["call"] | undefined;
-  return {
-    kind: "api-transport",
-    label: "cursor-account",
-    bind(impl) {
-      bound = impl;
-    },
-    async call(method, args) {
-      if (bound === undefined) {
-        return { ok: false, error: "cursor_slack_relay_not_started" };
-      }
-      return bound(method, args);
-    },
-  };
-}
-
-/**
- * One routed Slack event from `/v0/slack-events` (mirror of the backend's
- * SlackAgentEventEnvelope, minus server-only fields).
- */
-export interface CursorSlackEnvelope {
-  eventName: string;
-  slackTeamId: string;
-  channelId: string;
-  channelType?: string;
-  threadTs: string;
-  messageTs: string;
-  slackUserId?: string;
-  text: string;
-  agentName: string;
-  consumerId: string;
-  /**
-   * How the backend routed the event: leading agent name or owned thread.
-   */
-  matchedBy: "name" | "thread";
-  eventId?: string;
-  receivedAtMs: number;
-  /**
-   * Slack file uploads on the triggering message. When `dataBase64` is set
-   * the Cursor backend already downloaded bytes (cursorAccount has no bot
-   * token for files.slack.com).
-   */
-  files?: SlackMessageFile[];
-}
-
-/** Serve-time runtime handle for one cursor-account Slack channel. */
-export interface SlackCursorAccountRuntime {
-  options: SlackChannelOptions;
-  /** The channel's live credentials (botToken slot holds the transport). */
-  credentials: SlackCredentials;
-  transport: PendingSlackApiTransport;
-  eventIds: EventIdDedupe;
-  onAppMention: SlackMessageHandler;
-  onDirectMessage: SlackMessageHandler;
-  getLog: () => SlackLog;
-}
-
-const runtimeByDefinition = new WeakMap<object, SlackCursorAccountRuntime>();
-
-export function registerSlackCursorAccountRuntime(
-  definition: object,
-  runtime: SlackCursorAccountRuntime
-): void {
-  runtimeByDefinition.set(definition, runtime);
-}
-
-/**
- * Recover the cursor-account runtime for a channel definition, if it was
- * created via `slackChannel({ cursorAccount: true })`.
- */
-export function getSlackCursorAccountRuntime(
-  definition: object
-): SlackCursorAccountRuntime | undefined {
-  return runtimeByDefinition.get(definition);
-}
-
-/**
- * Dispatch one relayed envelope through the pack's normal inbound path
- * (same handlers, session continuation, and reply delivery as Socket Mode).
- */
-export async function dispatchCursorSlackEnvelope(args: {
-  runtime: SlackCursorAccountRuntime;
-  envelope: CursorSlackEnvelope;
-  send: SendMessageFn;
-  host: HostContext;
-  artifacts: ArtifactsApi;
-  hasContinuationSession?: (continuationToken: string) => Promise<boolean>;
-  isContinuationBusy?: (continuationToken: string) => Promise<boolean>;
-  getContinuationLastBotMessageTs?: (
-    continuationToken: string
-  ) => Promise<string | undefined>;
-  interruptContinuation?: (continuationToken: string) => Promise<boolean>;
-}): Promise<void> {
-  const { runtime, envelope } = args;
-  const log = runtime.getLog();
-
-  if (
-    envelope.eventId !== undefined &&
-    envelope.eventId.length > 0 &&
-    !runtime.eventIds.tryHandle(envelope.eventId)
-  ) {
-    log.debug("cursor-account inbound dedupe drop", {
-      event_id: envelope.eventId,
-    });
-    return;
-  }
-
-  const message: SlackMessage = {
-    text: envelope.text,
-    body: envelope.text,
-    markdown: slackTextToMarkdown(envelope.text),
-    ts: envelope.messageTs,
-    threadTs: envelope.threadTs,
-    channelId: envelope.channelId,
-    teamId: envelope.slackTeamId,
-    ...(envelope.slackUserId === undefined
-      ? {}
-      : {
-          author: { userId: envelope.slackUserId, isBot: false },
-        }),
-    files: envelope.files,
-  };
-
-  // DMs to @Cursor route as direct messages; everything else (explicit
-  // `@Cursor <agent> …` mentions and claimed-thread replies) dispatches on
-  // the mention handler — a claimed-thread reply is addressed to the agent
-  // by construction. Mentions/DM disable toggles are rejected at
-  // `slackChannel({ cursorAccount: true })` construction so the backend
-  // never consumes events the host would drop.
-  const isDm =
-    envelope.channelType === "im" || envelope.channelId.startsWith("D");
-  const kind = isDm ? "direct_message" : "app_mention";
-  const handler = isDm ? runtime.onDirectMessage : runtime.onAppMention;
-  await dispatchInboundMessage({
-    kind,
-    message,
-    handler,
-    send: args.send,
-    credentials: runtime.credentials,
-    host: args.host,
-    artifacts: args.artifacts,
-    log,
-    evalCommandsEnabled: runtime.options.evalCommands !== false,
-    cursorAgentName: envelope.agentName,
-    // Backend router already refused externals for this envelope.
-    blockExternals: false,
-    ...(args.hasContinuationSession === undefined
-      ? {}
-      : { hasContinuationSession: args.hasContinuationSession }),
-    ...(args.isContinuationBusy === undefined
-      ? {}
-      : { isContinuationBusy: args.isContinuationBusy }),
-    ...(args.getContinuationLastBotMessageTs === undefined
-      ? {}
-      : {
-          getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
-        }),
-    ...(args.interruptContinuation === undefined
-      ? {}
-      : { interruptContinuation: args.interruptContinuation }),
-    continuation: runtime.options.continuation,
-    ...(envelope.eventId === undefined ? {} : { eventId: envelope.eventId }),
-  });
-}