@cursor/july 0.1.1

package/docs/reference/schedules.md

@@ -0,0 +1,220 @@
+---
+title: "Schedules & reminders"
+description: "Cron-driven runs defined at deploy time, and per-session durable wakes created at runtime."
+---
+
+# Schedules and reminders
+
+Two ways an agent acts without an inbound message. A schedule is
+deploy-time cron: "every weekday at 09:00, summarize open incidents." A
+reminder is a runtime wake bound to one conversation: "re-check this
+PR's CI in two hours." Schedules live in the filesystem; reminders are
+created by running code.
+
+## Schedules
+
+Cron expressions are standard 5-field, evaluated in UTC with minute
+granularity.
+
+### Schedules in Markdown
+
+A plain markdown file with `cron:` frontmatter is a fire-and-forget
+task:
+
+```md
+---
+cron: "0 9 * * 1-5"
+---
+
+Pull open incidents and post a summary to the metrics endpoint.
+```
+
+Each firing starts a task-mode session: the body is the prompt, the
+session runs to `session.completed` or `session.failed`, and it isn't
+followable.
+
+### Schedules as handlers
+
+`defineSchedule` with a `run` handler gives you full control, most
+usefully to hand the work into a channel so its delivery events fire:
+
+```ts
+import { defineSchedule } from "@cursor/july/schedules";
+import webhook from "../channels/webhook.js";
+
+export default defineSchedule({
+  cron: "*/30 * * * *",
+  async run({ receive, waitUntil, appAuth, host }) {
+    // optional: await host.mcp.callTool("units", "celsius_to_fahrenheit", { value: 0 });
+    waitUntil(
+      receive(webhook, {
+        message:
+          "Check for new critical alerts. Report only when there are any.",
+        auth: appAuth,
+      })
+    );
+  },
+});
+```
+
+`defineSchedule` requires exactly one of `markdown` or `run`. The `run`
+handler receives `receive` (hand off into a channel), `callTool`
+(deterministic server-tool calls), `waitUntil`, `appAuth` (a
+schedule-scoped principal for work the agent does on its own behalf),
+and `host` (shared services: `host.mcp`, `host.github`, `host.slack`,
+`host.reminders`).
+
+### Dispatch and dev mode
+
+In production (`agentkit serve`), schedules fire on their cron
+cadence. Disable them with `--no-schedules`. There's no cross-host
+coordination, so run them in exactly one process per project.
+
+In dev (`serve --dev`), schedules never fire automatically. Dispatch one
+by hand, exactly once, through the same path production uses:
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/schedules/heartbeat
+# {"scheduleId":"heartbeat","sessionIds":["ses_…"]}
+```
+
+The playground can dispatch schedules in dev mode too, and
+`handle.dispatchSchedule("heartbeat")` does it programmatically.
+
+## Reminders
+
+A reminder is created at runtime and bound to a channel continuation.
+When it fires, it wakes that conversation. Recurring reminders behave
+like `setInterval`, one-shots like `setTimeout`, and both are durable on
+disk.
+
+```ts
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:owner/repo#1",
+  delay: "2h", // or a cron / explicit schedule
+  prompt: "Re-check CI. Only act if still failing.",
+  until: "Cancel once CI is green or the PR is merged.",
+});
+```
+
+Use `run` when host code should decide what happens on each tick:
+
+```ts
+await handle.createReminder({
+  purpose: "ci_recheck",
+  channelId: "drive",
+  continuationToken: "pr:owner/repo#1",
+  every: "30m",
+  async run({ fireCount, followup }) {
+    if (fireCount >= 3) {
+      return { action: "stop" };
+    }
+
+    await followup({
+      message: "Re-check CI and report only if the status changed.",
+    });
+    return { action: "delivered" };
+  },
+});
+```
+
+This reminder wakes the conversation three times, then stops itself.
+
+The same API is `host.reminders` on channel handlers, tools, and
+schedule runs. An agent can even be given a tool that creates its own
+reminders.
+
+For example, create `agent/tools/remind_me.ts`:
+
+```ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Schedule a one-time reminder in this conversation.",
+  inputSchema: z.object({
+    delay: z
+      .string()
+      .describe("When to wake the conversation, such as 20m or 2h"),
+    prompt: z
+      .string()
+      .min(1)
+      .describe("What the agent should do when it wakes"),
+  }),
+  async execute({ delay, prompt }, ctx) {
+    const reminders = ctx.host.reminders;
+    if (reminders === undefined) {
+      throw new Error("Reminders are disabled on this host.");
+    }
+
+    const continuationToken = ctx.session.continuationKey;
+    if (continuationToken == null) {
+      throw new Error("This session cannot receive reminder follow-ups.");
+    }
+
+    const reminder = await reminders.create({
+      purpose: "user_follow_up",
+      channelId: ctx.session.channelId,
+      continuationToken,
+      delay,
+      prompt,
+    });
+
+    return {
+      reminderId: reminder.id,
+      nextFireAt: reminder.nextFireAt,
+    };
+  },
+});
+```
+
+The tool binds the reminder to the current channel conversation. When
+the delay expires, the prompt returns to the same session as a follow-up.
+
+Reminders fire in one of two styles. The **prompt form** (above) sends
+`prompt` into the session, with `until` stating the standing
+cancellation condition for the model to honor. The **run form** passes a
+`run` handler instead: it returns `stop`, `skip`, or `delivered` per
+tick. That's silent host-side policy with no model turn. Run handlers are
+in-memory, so after a restart those reminders are disarmed
+(`handler_lost_on_restart`); re-arm them from the code path that created
+them, or prefer the prompt form.
+
+Dev mode matches schedules. Auto-timers follow `ServeOptions.reminders`
+(default `!dev`), so in `--dev` fire by hand:
+
+```bash
+curl http://127.0.0.1:3000/<slug>/v1/dev/reminders             # list
+curl -X POST http://127.0.0.1:3000/<slug>/v1/dev/reminders/<id>  # fire one
+```
+
+`handle.dispatchReminder(id)` is the programmatic equivalent.
+
+Two habits worth copying: cancel reminders when their subject
+dies (say, cancel PR-scoped reminders on `pull_request.closed`), and keep
+wake prompts generic. A plain "re-check the PR" works better than
+replaying stale payload details, because the agent re-reads the live
+state when it wakes.
+
+## Schedule or reminder?
+
+The split comes down to scope and timing.
+
+|          | Schedule                                                   | Reminder                                        |
+| -------- | ---------------------------------------------------------- | ----------------------------------------------- |
+| Defined  | at deploy time, `agent/schedules/*`                        | at runtime, `createReminder` / `host.reminders` |
+| Scope    | global to the agent                                        | one channel continuation (one conversation)     |
+| Session  | starts a new task session (or hands off through `receive`) | wakes an existing conversation                  |
+| Cadence  | cron (UTC)                                                 | delay, cron, or explicit schedule               |
+| Dev mode | manual dispatch only                                       | manual dispatch only (timers off)               |
+
+## What's next
+
+Continue with these pages:
+
+- [Channels](./channels.md): `receive` and the delivery events
+- [GitHub guide](../guides/github.md): reminders in a real webhook loop
+- [HTTP API](./http-api.md#dev-mode-routes): the dev
+  dispatch routes

package/docs/reference/sessions.md

@@ -0,0 +1,165 @@
+---
+title: "Sessions, events, and streaming"
+description: "Understand how conversations continue, how events stream, and where session data lives."
+---
+
+# Sessions, events, and streaming
+
+A session keeps one conversation, its workspace, and an append-only
+record of every message and tool call.
+
+## What does a session contain?
+
+Each session combines:
+
+- A channel and authenticated caller
+- A conversation the caller can continue
+- A workspace for local turns
+- An NDJSON event stream
+- Runtime state needed to resume after a server restart
+
+Sessions belong to the principal that created them. Follow-up, stream,
+and list routes return `403` when another caller tries to access one.
+
+## Which session identifier should I use?
+
+Sessions have two identifiers because conversation routing and
+inspection are different jobs.
+
+| Identifier | Use it for |
+| --- | --- |
+| `continuationToken` | Continue a conversation through its channel |
+| `sessionId` | Stream events, inspect state, resolve approvals, or run a session-bound tool call |
+
+Channels decide what a continuation token looks like. Slack uses its
+thread identity. A PR channel can use a key such as `pr:owner/repo#1`.
+The built-in HTTP API returns an opaque token and rotates it after each
+accepted follow-up. Reusing a stale HTTP token returns `409`.
+
+Use the continuation token to keep talking. Use the session ID to
+observe or manage the stored session.
+
+## Which session modes are available?
+
+| Mode | Created by | What happens after a turn |
+| --- | --- | --- |
+| `chat` | HTTP sessions, channel `send`, Slack, or MCP `ask` | Waits in `session.waiting` and accepts follow-ups |
+| `task` | Markdown schedules and fire-and-forget dispatch | Ends in `session.completed` or `session.failed` |
+
+Task sessions don't accept follow-ups. Trying one returns `409`.
+
+## What happens when I send a follow-up?
+
+A follow-up to an idle chat session starts another turn. A follow-up to
+a busy session interrupts the current turn, waits for it to settle, and
+then sends the new message.
+
+`POST /v1/session/:id/stop` interrupts a turn without sending a new
+message. Interrupted turns record `turn.failed` with
+`"turn interrupted"`. This means the turn was preempted.
+
+Session-bound deterministic tool calls share the same execution lock.
+They return `409 session_busy` while a model turn is running.
+
+## Which events can I stream?
+
+Each NDJSON line uses this envelope:
+`{ type, index, sessionId, turnId?, at, data }`. The `index` increases
+within one session. The `at` field is an ISO-8601 timestamp.
+
+| Phase | Events | What they tell you |
+| --- | --- | --- |
+| Session | `session.started`, [`ab.assigned`](../ab.md#assign-sticky-variants), `session.waiting`, `session.completed`, `session.failed` | Session creation, A/B enrollment, readiness, and task completion |
+| Agent | `agent.bound` | Cursor SDK agent ID and cloud conversation URL |
+| Input | `message.received` | A user message was accepted |
+| Turn | `turn.started`, `turn.completed`, `turn.failed` | Turn status, final result, and token usage |
+| Steps | `step.started`, `step.completed` | Model step boundaries and duration |
+| Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
+| Reply | `message.appended`, `message.completed` | Text deltas and finalized assistant messages |
+| Tools | `actions.requested`, `action.result` | Tool names, validated arguments, outputs, and errors |
+| Approvals | `action.approval_requested`, `action.approval_resolved` | A parked tool call and the human decision |
+| Subagents | `subagent.called`, `subagent.completed` | Delegated work |
+
+Pair `actions.requested` with `action.result` to reconstruct the tool
+trajectory. Read `turn.completed.data.usage` for input, output, and
+cache token counts.
+
+## How do I stream or replay session events?
+
+One endpoint handles both live streaming and replay:
+
+```bash
+curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
+```
+
+Pass `startIndex` to continue after the last event you received. Omit it
+or pass `0` to replay the full session before following new events.
+`GET /v1/session/:id/events` returns a one-time dump without staying
+connected.
+
+Event streams replay from disk after a server restart. Conversation
+state resumes from the Cursor SDK store.
+
+## What goes into a local session workspace?
+
+agentkit creates a workspace before the first local turn:
+
+| Source path                        | Lands as                                                                |
+| ---------------------------------- | ----------------------------------------------------------------------- |
+| `instructions.*`                   | `AGENTS.md`                                                             |
+| `skills/*`                         | `.cursor/skills/<name>/SKILL.md`                                        |
+| agent tools (`execution: "agent"`) | scripts under `.agentkit/tools/`, with a catalog in `AGENTS.md` |
+| `sandbox/workspace/**`             | copied in as seed files                                                 |
+| per-send `workspaceFiles`          | written before the turn                                                 |
+
+The local harness uses this workspace as its working directory. Parent
+directories can contribute `AGENTS.md` and `.cursor` settings. Set
+`local.cwd` when you need a clean parent directory. A channel can also
+provide a different working directory for one session, such as a PR
+worktree.
+
+See [Agent config: local cwd](./agent-config.md#local-cwd) for the
+inheritance rules.
+
+## Where does agentkit store session data?
+
+Local state uses one directory tree:
+
+```text
+<project>/.agentkit/            # or <stateRoot>/<slug>/ under serve
+  sessions/<id>/session.json       # metadata: channel, mode, principal, tokens
+  sessions/<id>/events.ndjson      # the durable stream
+  sessions/<id>/workspace/         # the harness cwd
+  traces/<sessionId>.ndjson        # written by `run`
+  runner/                          # Cursor SDK conversation store
+  tool-calls/<callId>/             # ephemeral deterministic-call workspaces
+```
+
+Deleting a session directory removes the session from the server: it
+disappears from listings and can no longer be streamed or continued.
+The `runner/` store keeps its own conversation copy until you remove it.
+Cloud conversations remain on the Cursor backend.
+
+Change the root with `--state-root` or `stateRoot`. Keep it outside
+repositories whose parent rules shouldn't reach the agent. See
+[local session workspaces](../concepts.md#what-files-can-a-local-session-access).
+
+## How do I inspect a saved event stream?
+
+Use `trajectory` with a trace or session event file:
+
+```bash
+agentkit trajectory --events .agentkit/traces/<sessionId>.ndjson
+agentkit trajectory --events <stateRoot>/<slug>/sessions/<id>/events.ndjson
+```
+
+The command prints tool calls, the reply, and token usage in the same
+JSON shape as `run`. Use **Open trace** in the playground for a visual
+view.
+
+## Related
+
+- [HTTP API](./http-api.md)
+- [Hooks](./hooks.md)
+- [Live A/B metrics](../ab.md)
+- [How agentkit works](../concepts.md)

package/docs/reference/skills.md

@@ -0,0 +1,79 @@
+---
+title: "Skills"
+description: "On-demand procedures the model loads only when relevant, in three authoring forms."
+---
+
+# Skills
+
+A skill is an on-demand procedure following the `SKILL.md` convention:
+the harness advertises each skill by its description, and the model
+loads the full content only when the task calls for it. Skills are how
+you give an agent a multi-step workflow without carrying it in the
+always-on [instructions](./instructions.md).
+
+## Authoring forms
+
+Three forms cover every case.
+
+| Form | Reach for it when |
+| --- | --- |
+| `agent/skills/<name>.md` | Flat markdown. Optional `description` frontmatter; the first body line is the fallback. |
+| `agent/skills/<name>/SKILL.md` plus siblings | A packaged directory with reference files (`references/…`). Requires `description` frontmatter. |
+| `agent/skills/<name>.ts` | Generated content, with `defineSkill` from `@cursor/july/skills`. |
+
+Flat markdown:
+
+```md
+---
+description: Use when a pull request needs a structured approval checklist.
+---
+
+# PR review checklist
+
+1. Call `inspect_pr` and confirm required checks passed.
+2. Summarize the PR title, author, and remaining risks.
+3. Call `approve_pr` only after an explicit request; it requires approval.
+```
+
+TypeScript, when the content must be generated or carry inline sibling
+files:
+
+```ts
+import { defineSkill } from "@cursor/july/skills";
+
+export default defineSkill({
+  description: "Research unfamiliar topics before answering.",
+  markdown: "Gather evidence first, then answer with the key facts.",
+  files: { "references/checklist.md": "# Checklist\n\n- Find sources.\n" },
+});
+```
+
+## How skills reach the model
+
+On the local runtime, skills land in the session workspace at
+`.cursor/skills/<name>/SKILL.md`, and the harness advertises and loads
+them natively. On the cloud runtime, skills aren't materialized. The VM
+only sees skills that exist in the cloud repo itself, and `validate`
+warns about the combination.
+
+## Instructions, skills, or tools?
+
+Instructions are always in context: identity, tool-choice rules, the
+output contract. Keep them short. Skills load when relevant: procedures,
+checklists, house style. Reach for a skill when the model needs to
+*follow* something but only sometimes needs it loaded. Tools are typed,
+executable behavior: anything that must be correct every time belongs in
+tool code, not in prose the model might paraphrase.
+
+A good skill description is a routing rule, not a title. Say *when* to
+use it, like "Use when a pull request needs a structured approval
+checklist," because the description is all the model sees before
+deciding to load it.
+
+## What's next
+
+Continue with these pages:
+
+- [Instructions](./instructions.md): what stays always-on
+- [Tools](./tools.md): when prose needs to become code
+- [Project layout](./project-layout.md): where skills sit in the tree

package/docs/reference/subagents.md

@@ -0,0 +1,74 @@
+---
+title: "Subagents"
+description: "Specialist child agents the model delegates to mid-turn, each its own directory under agent/subagents/."
+---
+
+# Subagents
+
+A subagent is a specialist child agent the model can delegate to
+mid-turn. Each one is its own directory under `agent/subagents/<id>/`,
+with the same `agent.ts` + `instructions.md` shape as the root. On the
+Cursor harness, subagents run as SDK custom subagents: the parent model
+delegates through the harness `task` tool, and the stream records
+`subagent.called` and `subagent.completed`.
+
+```text
+agent/subagents/researcher/
+├── agent.ts            # description (required), model (optional)
+└── instructions.md     # the subagent's own system prompt
+```
+
+```ts
+// agent/subagents/researcher/agent.ts
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  description:
+    "Background research: climate history, records, comparisons across many cities.",
+  // model: omit to inherit the parent's model
+});
+```
+
+## Subagent rules
+
+`description` is required. It's the only thing the parent model reads
+when deciding whether to delegate, so write it as a routing rule
+("Background research: …"), the same discipline as a
+[skill](./skills.md) description. `model` is optional; omit it to
+inherit the parent's model, or set it to run the specialist on a
+different one.
+
+Subagents inherit the parent's execution surface. Per-subagent `tools/`,
+`skills/`, and `mcp-connections/` directories are reported as warnings and
+ignored. Nested subagents aren't supported.
+
+Delegation needs both halves: the description makes it possible, and the
+parent's [instructions](./instructions.md) make it happen. "When a
+request needs background research, delegate to the `researcher`
+subagent."
+
+## Subagent or peer?
+
+Subagents split one job into roles inside a single agent. When the
+specialist is independently useful, with its own tools, sessions, and
+playground, make it a full agent and wire a peer MCP connection instead. The
+comparison table is in the
+[Agent-to-agent guide](../guides/agent-to-agent.md#peer-or-subagent).
+
+## Patterns
+
+Fan-out reviews: a PR-approval agent can delegate to two review
+subagents that read a host-prepared `pr/` evidence tree and report
+prioritized findings, which the parent embeds in its approval comment.
+
+Keep the parent lean: a subagent with focused instructions usually
+works better than a longer parent prompt with conditional sections. The
+parent routes; the specialist executes.
+
+## What's next
+
+Continue with these pages:
+
+- [Agent-to-agent](../guides/agent-to-agent.md): the peer alternative
+- [Skills](./skills.md): when a procedure is enough and a child agent
+  is overkill