@cursor/july 0.1.113 → 0.2.0

package/dist/docs/assets/reference_channels.md.DZr14vm7.js

@@ -0,0 +1,23 @@
+import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Channels","description":"Define custom channel routes, schemas, state, events, and authentication.","frontmatter":{"title":"Channels","description":"Define custom channel routes, schemas, state, events, and authentication."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),i={name:"reference/channels.md"};function o(d,e,r,h,l,c){return a(),s("div",null,[...e[0]||(e[0]=[n(`<h1 id="channels" tabindex="-1">Channels <a class="header-anchor" href="#channels" aria-label="Permalink to &quot;Channels&quot;">​</a></h1><p>A channel connects an external surface to agent sessions. A file at <code>agent/channels/&lt;id&gt;.ts</code> defines channel <code>&lt;id&gt;</code> and mounts its routes under <code>/v1/channels/&lt;id&gt;</code>. The built-in HTTP session channel is always available alongside any custom or prebuilt channels.</p><h2 id="built-in-http-channel" tabindex="-1">Built-in HTTP channel <a class="header-anchor" href="#built-in-http-channel" aria-label="Permalink to &quot;Built-in HTTP channel&quot;">​</a></h2><p>The built-in channel serves the session, approval, tool, discovery, and health routes. In a multi-agent host, each agent&#39;s routes sit under its slug. See the <a href="./http-api.html">HTTP API</a> for request and response contracts.</p><h2 id="define-a-custom-channel" tabindex="-1">Define a custom channel <a class="header-anchor" href="#define-a-custom-channel" aria-label="Permalink to &quot;Define a custom channel&quot;">​</a></h2><p>Use <code>defineChannel</code> with one or more typed routes:</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/july/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
+<span class="line"></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">export</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> default</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> defineChannel</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  routes: [</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">    POST</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;/review&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      description: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Review a pull request on this channel&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      bodySchema: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">object</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        message: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        prUrl: z.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">string</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">().</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">url</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      }),</span></span>
+<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">      handler</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">async</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">_request</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#E36209;--shiki-dark:#FFAB70;">body</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }) </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=&gt;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> session</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
+<span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">          \`\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">message</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\n\\n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Pull request: \${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          {</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">            continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\`pr:\${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">prUrl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}\`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">          }</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">        );</span></span>
+<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">        return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ sessionId: session.id });</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">      },</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    }),</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  ],</span></span>
+<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>The route above is <code>POST /v1/channels/&lt;id&gt;/review</code>. Calls for the same pull request reuse one conversation because they pass the same continuation token.</p><h2 id="route-verbs-and-schemas" tabindex="-1">Route verbs and schemas <a class="header-anchor" href="#route-verbs-and-schemas" aria-label="Permalink to &quot;Route verbs and schemas&quot;">​</a></h2><p>Route paths must begin with <code>/</code>. The method helper determines which Zod schemas the route accepts:</p><table tabindex="0"><thead><tr><th>Helper</th><th>Schema contract</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>querySchema</code> is required</td></tr><tr><td><code>POST</code>, <code>PUT</code>, <code>PATCH</code></td><td><code>bodySchema</code> is required; <code>querySchema</code> is optional</td></tr><tr><td><code>DELETE</code></td><td>Both schemas are optional</td></tr></tbody></table><p>Plain JSON Schema objects don&#39;t type-check. Use <code>z.object({})</code> or <code>z.unknown()</code> for an open surface. The host validates the body and query before calling the handler, returning <code>400</code> on failure; an empty body is read as <code>{}</code>. Declared schemas also appear in <code>GET /v1/info</code> for playground requests and slash commands.</p><h2 id="handler-arguments" tabindex="-1">Handler arguments <a class="header-anchor" href="#handler-arguments" aria-label="Permalink to &quot;Handler arguments&quot;">​</a></h2><p>Each handler receives the Fetch <code>Request</code> and a typed arguments object.</p><table tabindex="0"><thead><tr><th>Member</th><th>Contract</th></tr></thead><tbody><tr><td><code>send(message, options?)</code></td><td>Start or resume a session on this channel</td></tr><tr><td><code>getSession(sessionId)</code></td><td>Return this channel&#39;s session, or <code>null</code></td></tr><tr><td><code>receive(channel, input)</code></td><td>Hand work to another channel</td></tr><tr><td><code>callTool(name, input, options?)</code></td><td><a href="./tools.html#call-a-tool-without-a-model-turn">Call a server tool</a> without a model turn</td></tr><tr><td><code>body</code>, <code>query</code>, <code>params</code></td><td>Validated inputs and <code>:param</code> path segments</td></tr><tr><td><code>auth</code></td><td>The <code>AuthContext</code> returned by the route&#39;s auth chain</td></tr><tr><td><code>requestIp</code></td><td>The TCP peer address, or <code>null</code></td></tr><tr><td><code>host</code></td><td>Shared MCP, provider, storage, telemetry, and reminder services</td></tr><tr><td><code>waitUntil(promise)</code></td><td>Track work after the response returns</td></tr><tr><td><code>sessionUrls(request, sessionId)</code></td><td>Build absolute playground and trace URLs for this mount</td></tr><tr><td><code>artifacts</code></td><td>List or tag <a href="./artifacts.html">artifacts</a>; pass <code>sessionId</code> when attributing one</td></tr></tbody></table><h3 id="send-options" tabindex="-1"><code>send</code> options <a class="header-anchor" href="#send-options" aria-label="Permalink to &quot;\`send\` options&quot;">​</a></h3><table tabindex="0"><thead><tr><th>Option</th><th>Contract</th></tr></thead><tbody><tr><td><code>continuationToken</code></td><td>Resume the session with this channel-local key, or create one when the key is new</td></tr><tr><td><code>admission</code></td><td><code>&quot;preempt&quot;</code> interrupts a busy turn; <code>&quot;coalesce&quot;</code> queues behind it. The default is <code>&quot;preempt&quot;</code></td></tr><tr><td><code>workspaceFiles</code></td><td>Add relative files for the next turn</td></tr><tr><td><code>workspaceDir</code></td><td>Use an absolute local working directory</td></tr><tr><td><code>cloud</code></td><td>Override cloud session options when creating a session</td></tr><tr><td><code>auth</code></td><td>Set the session principal; defaults to the request principal</td></tr><tr><td><code>state</code></td><td>Set starting channel state for a new session</td></tr><tr><td><code>title</code></td><td>Set the display title for a new session</td></tr><tr><td><code>purpose</code></td><td>Use <code>&quot;eval&quot;</code> to mark a new session as regression traffic</td></tr><tr><td><code>dryRun</code></td><td>Run read tools and stub write tools for a new session</td></tr><tr><td><code>asOf</code></td><td>Freeze a new session at an ISO-8601 instant with a timezone</td></tr></tbody></table><p><code>send</code> returns a <code>ChannelSession</code>. Its <code>id</code> identifies the session, <code>continuationToken</code> contains its current channel key, and <code>isNew</code> says whether this call created it. A coalesced call also returns <code>coalesced: true</code>.</p><h2 id="events" tabindex="-1">Events <a class="header-anchor" href="#events" aria-label="Permalink to &quot;Events&quot;">​</a></h2><p>The <code>events</code> map subscribes the channel to stream events for the sessions it owns. Keys are event types from the <a href="./sessions.html#stream-events">event vocabulary</a>, or <code>&quot;*&quot;</code>. Each handler receives <code>(event, channel, ctx)</code>, including the session&#39;s <code>channel.state</code>, session info, and shared host services. Use these handlers to deliver progress and replies to the surface that owns the channel.</p><h2 id="session-state" tabindex="-1">Session state <a class="header-anchor" href="#session-state" aria-label="Permalink to &quot;Session state&quot;">​</a></h2><p><code>state</code> on the channel definition supplies starting JSON for each new session. A route can instead pass <code>state</code> to <code>send</code>; event handlers read and update the active value through <code>channel.state</code>.</p><h2 id="start-and-stop-a-channel" tabindex="-1">Start and stop a channel <a class="header-anchor" href="#start-and-stop-a-channel" aria-label="Permalink to &quot;Start and stop a channel&quot;">​</a></h2><p><code>onStart(args)</code> runs when the channel mounts, and <code>onStop()</code> runs when the host stops. <code>onStart</code> receives the route helpers plus these transport controls:</p><table tabindex="0"><thead><tr><th>Helper</th><th>Contract</th></tr></thead><tbody><tr><td><code>emitAssistantMessage(sessionId, text)</code></td><td>Append final assistant text without starting a model turn</td></tr><tr><td><code>hasContinuationSession(token)</code></td><td>Check whether a token maps to a session</td></tr><tr><td><code>isContinuationBusy(token)</code></td><td>Check whether a turn is active for a token</td></tr><tr><td><code>interruptContinuation(token)</code></td><td>Stop the active turn and clear queued coalesced follow-ups</td></tr><tr><td><code>resolveApproval(...)</code></td><td>Approve or deny a parked tool call</td></tr></tbody></table><h2 id="auth-policies" tabindex="-1">Auth policies <a class="header-anchor" href="#auth-policies" aria-label="Permalink to &quot;Auth policies&quot;">​</a></h2><p>Every route runs the channel&#39;s <code>auth</code> array. The default is <code>[localDevStrict()]</code>. Policies may be asynchronous; the first one to return an <code>AuthContext</code> admits the request, and an all-null result returns <code>401</code>.</p><table tabindex="0"><thead><tr><th>Policy</th><th>Admits</th></tr></thead><tbody><tr><td><code>localDevStrict()</code></td><td>Direct loopback requests with a loopback hostname and no proxy-forwarding headers</td></tr><tr><td><code>localDev()</code></td><td>Direct loopback requests with no proxy-forwarding headers, without checking the hostname</td></tr><tr><td><code>loopbackOnly()</code></td><td>Any loopback TCP peer, including local relays that carry forwarding headers</td></tr><tr><td><code>bearerAuth(tokenOrVerify)</code></td><td>A matching bearer token, or a token accepted by the verifier</td></tr><tr><td><code>sharedSecretAuth({ header, secret })</code></td><td>A header matching the named environment or deployment secret</td></tr><tr><td><code>hmacSignatureAuth({ header, secret, prefix? })</code></td><td>A hex HMAC-SHA256 signature over the raw body using the named secret</td></tr><tr><td><code>allowAll()</code></td><td>Every caller as an anonymous principal</td></tr><tr><td><code>publicEndpoint()</code></td><td>Every caller on this custom channel; managed hosting also exposes the route without an alias token</td></tr></tbody></table><p>Use <code>allowAll()</code> only for an intentionally public surface or one protected upstream. With <code>publicEndpoint()</code>, the handler must verify the provider&#39;s signature. The policy applies only to custom channel routes; it doesn&#39;t open the built-in session or tool API.</p><p>The resolved <code>AuthContext</code> (<code>{ authenticator, principalId, principalType, attributes? }</code>) becomes the request principal. Sessions belong to the principal that created them, and other principals receive <code>403</code> on owned routes.</p><p>Server flags interact with authored auth: <code>--bearer-token</code> swaps the default <code>localDevStrict()</code> for <code>bearerAuth(...)</code> on channels that don&#39;t author their own chain, and <code>--allow-anonymous</code> swaps it for <code>allowAll()</code>. An authored <code>auth</code> array always takes precedence.</p><h2 id="prebuilt-channels" tabindex="-1">Prebuilt channels <a class="header-anchor" href="#prebuilt-channels" aria-label="Permalink to &quot;Prebuilt channels&quot;">​</a></h2><table tabindex="0"><thead><tr><th>Import</th><th>Factory</th><th>Surface</th></tr></thead><tbody><tr><td><code>@cursor/july/channels/slack</code></td><td><code>slackChannel()</code></td><td>Slack messages, threads, streaming replies, and approvals. See <a href="./../guides/slack.html">Slack</a></td></tr><tr><td><code>@cursor/july/channels/github</code></td><td><code>githubChannel()</code></td><td>GitHub and GitHub Enterprise webhooks. See <a href="./../guides/github.html">GitHub</a></td></tr><tr><td><code>@cursor/july/channels/gitlab</code></td><td><code>gitlabChannel()</code></td><td>GitLab.com and self-managed GitLab hooks. See <a href="./../guides/gitlab.html">GitLab</a></td></tr><tr><td><code>@cursor/july/channels/bitbucket</code></td><td><code>bitbucketChannel()</code></td><td>Bitbucket Cloud and Data Center hooks. See <a href="./../guides/bitbucket.html">Bitbucket</a></td></tr><tr><td><code>@cursor/july/channels/deployments</code></td><td><code>deploymentsChannel()</code></td><td>Deployment events filtered by source, environment, or event name</td></tr><tr><td><code>@cursor/july/channels/change-monitors</code></td><td><code>changeMonitorsChannel()</code></td><td>Change Monitor <code>checkpoint.created</code> events</td></tr><tr><td><code>@cursor/july/channels/issues</code></td><td><code>issuesChannel()</code></td><td>Factory <code>issue.created</code> events</td></tr></tbody></table><p>For other platforms like Discord or Teams, use the authored <code>defineChannel</code> route form.</p><h2 id="continuation-tokens" tabindex="-1">Continuation tokens <a class="header-anchor" href="#continuation-tokens" aria-label="Permalink to &quot;Continuation tokens&quot;">​</a></h2><p>Each channel defines its continuation-token format. The same token resumes the same conversation; the built-in HTTP channel rotates its opaque token after every accepted follow-up and returns <code>409</code> for a stale token. See <a href="./sessions.html#session-identifiers">Session identifiers</a> for the full contract.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../guides/webhooks.html">Webhooks</a></li><li><a href="./http-api.html">HTTP API</a></li><li><a href="./sessions.html">Sessions</a></li><li><a href="./hooks.html">Hooks</a></li></ul>`,38)])])}const u=t(i,[["render",o]]);export{k as __pageData,u as default};

package/dist/docs/assets/reference_channels.md.DZr14vm7.lean.js

@@ -0,0 +1 @@
+import{_ as t,c as s,o as a,a3 as n}from"./chunks/framework.BNw1pucY.js";const k=JSON.parse('{"title":"Channels","description":"Define custom channel routes, schemas, state, events, and authentication.","frontmatter":{"title":"Channels","description":"Define custom channel routes, schemas, state, events, and authentication."},"headers":[],"relativePath":"reference/channels.md","filePath":"reference/channels.md"}'),i={name:"reference/channels.md"};function o(d,e,r,h,l,c){return a(),s("div",null,[...e[0]||(e[0]=[n("",38)])])}const u=t(i,[["render",o]]);export{k as __pageData,u as default};