@cursor/july 0.1.1

package/dist/internal/host-platforms.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Host-side GitHub + Slack clients shared across tools, channel routes,
+ * schedules, and channel packs — same injection pattern as MCP.
+ */
+import type { HostGitHubClient, HostSlackClient } from "../types.js";
+export interface HostPlatforms {
+    github: HostGitHubClient;
+    slack: HostSlackClient;
+}
+/**
+ * How ambient host GitHub auth was resolved.
+ * `app` = GitHub App installation token (preferred in production).
+ * `env` / `gh` = local PAT / CLI fallbacks when App creds are unset.
+ */
+export type HostGitHubAuthSource = "app" | "env" | "gh" | "unavailable";
+/**
+ * Build host platforms from ambient credentials. Prefer App installation
+ * auth when configured; otherwise fall back to PAT / `gh auth` for local
+ * testing. Webhook-scoped calls should still prefer `ctx.github`.
+ */
+export declare function createHostPlatforms(): HostPlatforms;
+/**
+ * Detect ambient host GitHub auth without throwing.
+ * Order matches {@link createGitHubOctokit}: App installation, then
+ * `GITHUB_TOKEN` / `GH_TOKEN`, then `gh auth token`.
+ */
+export declare function resolveHostGitHubAuthSource(): Promise<HostGitHubAuthSource>;
+/**
+ * Soft boot-time GitHub auth check: log the resolved source and optionally
+ * prime `github.getOctokit()` so the first request does not pay CLI latency.
+ * When auth is App-backed, also export an installation token as `GH_TOKEN`
+ * so tools that shell out to `gh` (a host-side `prepare_pr` tool, say)
+ * authenticate on corp hosts that have no PAT / `gh
+ * auth login`. Never fails serve — missing auth is logged as a warning.
+ */
+export declare function warmupHostGitHubAuth(options: {
+    logger: (line: string) => void;
+    github?: HostGitHubClient;
+}): Promise<HostGitHubAuthSource>;
+//# sourceMappingURL=host-platforms.d.ts.map

package/dist/internal/host-platforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-platforms.d.ts","sourceRoot":"","sources":["../../src/internal/host-platforms.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,aAAa,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CA4BnD;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAejF;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8ChC"}

package/dist/internal/host-platforms.js

@@ -0,0 +1,113 @@
+/**
+ * Host-side GitHub + Slack clients shared across tools, channel routes,
+ * schedules, and channel packs — same injection pattern as MCP.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { WebClient } from "@slack/web-api";
+import { createGitHubOctokit } from "../channels/github/api.js";
+import { ensureGhCliTokenEnv, hasGitHubAppCredentials, resolveCredentialValue, resolveGitHubInstallationId, tryResolveGhAuthToken, } from "../channels/github/auth.js";
+import { tryResolveBotToken } from "../channels/slack/credentials.js";
+/**
+ * Build host platforms from ambient credentials. Prefer App installation
+ * auth when configured; otherwise fall back to PAT / `gh auth` for local
+ * testing. Webhook-scoped calls should still prefer `ctx.github`.
+ */
+export function createHostPlatforms() {
+    let octokitPromise;
+    let slackPromise;
+    return {
+        github: {
+            getOctokit: () => {
+                octokitPromise !== null && octokitPromise !== void 0 ? octokitPromise : (octokitPromise = createGitHubOctokit({}));
+                return octokitPromise;
+            },
+        },
+        slack: {
+            getClient: () => __awaiter(this, void 0, void 0, function* () {
+                if (slackPromise === undefined) {
+                    slackPromise = (() => __awaiter(this, void 0, void 0, function* () {
+                        const token = yield tryResolveBotToken(undefined);
+                        if (token === undefined) {
+                            throw new Error("No Slack bot token available (set SLACK_BOT_TOKEN or a channel envPrefix).");
+                        }
+                        return new WebClient(token);
+                    }))();
+                }
+                return slackPromise;
+            }),
+        },
+    };
+}
+/**
+ * Detect ambient host GitHub auth without throwing.
+ * Order matches {@link createGitHubOctokit}: App installation, then
+ * `GITHUB_TOKEN` / `GH_TOKEN`, then `gh auth token`.
+ */
+export function resolveHostGitHubAuthSource() {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        if ((yield hasGitHubAppCredentials()) &&
+            (yield resolveGitHubInstallationId()) !== undefined) {
+            return "app";
+        }
+        const fromEnv = (_a = (yield resolveCredentialValue(process.env.GITHUB_TOKEN))) !== null && _a !== void 0 ? _a : (yield resolveCredentialValue(process.env.GH_TOKEN));
+        if (fromEnv !== undefined) {
+            return "env";
+        }
+        const fromGh = yield tryResolveGhAuthToken();
+        return fromGh === undefined ? "unavailable" : "gh";
+    });
+}
+/**
+ * Soft boot-time GitHub auth check: log the resolved source and optionally
+ * prime `github.getOctokit()` so the first request does not pay CLI latency.
+ * When auth is App-backed, also export an installation token as `GH_TOKEN`
+ * so tools that shell out to `gh` (a host-side `prepare_pr` tool, say)
+ * authenticate on corp hosts that have no PAT / `gh
+ * auth login`. Never fails serve — missing auth is logged as a warning.
+ */
+export function warmupHostGitHubAuth(options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const source = yield resolveHostGitHubAuthSource();
+        if (source === "unavailable") {
+            options.logger("[agent-serve] GitHub auth: unavailable (set GITHUB_APP_ID + GITHUB_APP_PRIVATE_KEY + GITHUB_APP_INSTALLATION_ID, or GITHUB_TOKEN / GH_TOKEN, or run `gh auth login`)");
+            return source;
+        }
+        let exportedGhToken = false;
+        if (source === "app") {
+            try {
+                exportedGhToken = yield ensureGhCliTokenEnv();
+            }
+            catch (error) {
+                options.logger(`[agent-serve] GitHub auth: failed to export GH_TOKEN for gh CLI: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const label = source === "app"
+            ? exportedGhToken
+                ? "GitHub App installation token (also exported as GH_TOKEN for gh CLI)"
+                : "GitHub App installation token"
+            : source === "env"
+                ? "GITHUB_TOKEN/GH_TOKEN"
+                : "gh auth token";
+        if (options.github === undefined) {
+            options.logger(`[agent-serve] GitHub auth: ${label}`);
+            return source;
+        }
+        try {
+            yield options.github.getOctokit();
+            options.logger(`[agent-serve] GitHub auth: ${label}`);
+        }
+        catch (error) {
+            options.logger(`[agent-serve] GitHub auth: ${label} resolved but Octokit warmup failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return source;
+    });
+}

package/dist/internal/http-channel.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The built-in HTTP session channel: the default API that `curl`, SDK
+ * clients, and frontends talk to. Mounted at `/v1/session*` and enabled even
+ * when `agent/channels/http.ts` does not exist; author that file with
+ * `httpChannel({ ... })` to override auth or observe events.
+ *
+ * Continuation semantics: `POST /v1/session` returns a `continuationToken`;
+ * each accepted follow-up rotates it and returns the replacement, and a
+ * stale token is rejected with 409. Follow-ups address any chat session by
+ * id (including custom channels such as `drive`) when the token matches
+ * that session's channel + key; task sessions stay fire-and-forget.
+ */
+import type { AuthContext, AuthPolicy, HttpChannelDefinition, SessionRecord } from "../types.js";
+import type { ServerRoute } from "./router.js";
+import { type SessionEngine } from "./session-engine.js";
+export declare function buildHttpChannelRoutes(args: {
+    engine: SessionEngine;
+    config: HttpChannelDefinition;
+    auth: AuthPolicy[];
+    /** Path prefix ("" single-agent, "/<slug>" multi-agent). */
+    basePath?: string;
+    /**
+     * When true (server `--dev` without bearer/custom auth), session
+     * stream/events/follow-up are readable without matching the creating
+     * principal — matching `GET /v1/sessions` includeAll so the playground
+     * can open every listed session. Still requires a loopback caller unless
+     * {@link relaxSessionReadAuthBeyondLoopback} is also set.
+     */
+    relaxSessionReadAuth?: boolean;
+    /**
+     * With {@link relaxSessionReadAuth}, skip the loopback IP check so remote
+     * callers (e.g. Tailscale + `--allow-anonymous`) can open listed sessions.
+     */
+    relaxSessionReadAuthBeyondLoopback?: boolean;
+    /**
+     * `--dev` bridge: allow playground / HTTP callers to Approve/Deny parked
+     * tools on Slack-owned sessions (Slack principals never match local /
+     * anonymous auth). Does not open approval writes on HTTP-owned sessions.
+     * Respects the same loopback / beyondLoopback gate as session reads.
+     */
+    relaxSessionApprovalAuth?: boolean;
+}): ServerRoute[];
+export declare function requireSessionOwner(record: SessionRecord, caller: AuthContext | null, options?: {
+    relax?: boolean;
+    beyondLoopback?: boolean;
+    requestIp?: string | null;
+}): Response | undefined;
+export declare function jsonResponse(data: unknown, init?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;
+export declare function errorResponse(status: number, code: string, message: string): Response;
+export declare function readJsonObject(request: Request): Promise<Record<string, unknown> | undefined>;
+//# sourceMappingURL=http-channel.d.ts.map

package/dist/internal/http-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-channel.d.ts","sourceRoot":"","sources":["../../src/internal/http-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,qBAAqB,EAErB,aAAa,EACd,MAAM,aAAa,CAAC;AAQrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAQ7B,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,kCAAkC,CAAC,EAAE,OAAO,CAAC;IAC7C;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,GAAG,WAAW,EAAE,CAkYhB;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,WAAW,GAAG,IAAI,EAC1B,OAAO,CAAC,EAAE;IACR,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,GACA,QAAQ,GAAG,SAAS,CAiBtB;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,OAAO,EACb,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAO,GAC/D,QAAQ,CAQV;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,QAAQ,CAEV;AA0BD,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAc9C"}

package/dist/internal/http-channel.js

@@ -0,0 +1,382 @@
+/**
+ * The built-in HTTP session channel: the default API that `curl`, SDK
+ * clients, and frontends talk to. Mounted at `/v1/session*` and enabled even
+ * when `agent/channels/http.ts` does not exist; author that file with
+ * `httpChannel({ ... })` to override auth or observe events.
+ *
+ * Continuation semantics: `POST /v1/session` returns a `continuationToken`;
+ * each accepted follow-up rotates it and returns the replacement, and a
+ * stale token is rejected with 409. Follow-ups address any chat session by
+ * id (including custom channels such as `drive`) when the token matches
+ * that session's channel + key; task sessions stay fire-and-forget.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { samePrincipal } from "./auth.js";
+import { formatContinuationToken, newContinuationKey, parseContinuationToken, } from "./ids.js";
+import { isLoopbackAddress } from "./net.js";
+import { ApprovalInterruptedError, ApprovalNotFoundError, HTTP_CHANNEL_ID, SessionAuthError, SessionBusyError, } from "./session-engine.js";
+import { eventsUrlForSession, playgroundUrlForSession, } from "./session-urls.js";
+const SESSION_ID_HEADER = "x-agent-serve-session-id";
+export function buildHttpChannelRoutes(args) {
+    var _a, _b, _c, _d;
+    const { engine, config, auth } = args;
+    const base = (_a = args.basePath) !== null && _a !== void 0 ? _a : "";
+    const relaxSessionReadAuth = (_b = args.relaxSessionReadAuth) !== null && _b !== void 0 ? _b : false;
+    const relaxSessionReadAuthBeyondLoopback = (_c = args.relaxSessionReadAuthBeyondLoopback) !== null && _c !== void 0 ? _c : false;
+    const relaxSessionApprovalAuth = (_d = args.relaxSessionApprovalAuth) !== null && _d !== void 0 ? _d : false;
+    const transformMessage = (message, authContext) => __awaiter(this, void 0, void 0, function* () {
+        if (config.onMessage === undefined) {
+            return message;
+        }
+        return config.onMessage(message, { auth: authContext });
+    });
+    const createSession = {
+        method: "POST",
+        pattern: `${base}/v1/session`,
+        auth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const body = yield readJsonObject(request);
+            if (body === undefined || typeof body.message !== "string") {
+                return errorResponse(400, "invalid_request", "Expected a JSON body with a string `message`.");
+            }
+            const message = yield transformMessage(body.message, ctx.auth);
+            const workspaceFiles = readWorkspaceFiles(body.workspaceFiles);
+            const session = yield engine.send(HTTP_CHANNEL_ID, message, Object.assign(Object.assign(Object.assign(Object.assign({ auth: ctx.auth }, (body.state === undefined ? {} : { state: body.state })), (typeof body.title === "string" ? { title: body.title } : {})), (body.purpose === "eval" ? { purpose: "eval" } : {})), (workspaceFiles === undefined ? {} : { workspaceFiles })));
+            return jsonResponse({
+                ok: true,
+                sessionId: session.id,
+                continuationToken: formatContinuationToken(HTTP_CHANNEL_ID, (_a = session.continuationToken) !== null && _a !== void 0 ? _a : ""),
+                playgroundUrl: playgroundUrlForSession(request, base, session.id),
+                traceUrl: eventsUrlForSession(request.url, base, session.id),
+            }, { headers: { [SESSION_ID_HEADER]: session.id } });
+        }),
+    };
+    const followUp = {
+        method: "POST",
+        pattern: `${base}/v1/session/:sessionId`,
+        auth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const sessionId = (_a = ctx.params.sessionId) !== null && _a !== void 0 ? _a : "";
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+            }
+            // Playground (and other HTTP clients) may follow up on any chat
+            // session — including custom channels like `drive` — using that
+            // session's own continuation token. Task/schedule sessions stay
+            // fire-and-forget.
+            if (record.mode === "task") {
+                return errorResponse(409, "session_not_followable", "Task sessions are fire-and-forget; they do not accept follow-ups.");
+            }
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                relax: relaxSessionReadAuth,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return ownership;
+            }
+            const body = yield readJsonObject(request);
+            if (body === undefined || typeof body.message !== "string") {
+                return errorResponse(400, "invalid_request", "Expected a JSON body with a string `message`.");
+            }
+            if (typeof body.continuationToken !== "string") {
+                return errorResponse(400, "invalid_request", "Expected a `continuationToken` from the previous response.");
+            }
+            const presented = parseContinuationToken(body.continuationToken);
+            if (presented === null ||
+                presented.channelId !== record.channelId ||
+                record.continuationKey === null ||
+                presented.key !== record.continuationKey) {
+                return errorResponse(409, "stale_continuation_token", "The continuation token does not address this session's active continuation.");
+            }
+            const message = yield transformMessage(body.message, ctx.auth);
+            try {
+                // Continue as the session owner after the HTTP ownership gate so
+                // `--dev` relaxed reads can follow up on channel-owned sessions
+                // (drive/slack/…) without failing SessionAuthError.
+                yield engine.send(record.channelId, message, {
+                    auth: record.auth,
+                    continuationToken: record.continuationKey,
+                });
+            }
+            catch (error) {
+                if (error instanceof SessionBusyError) {
+                    return errorResponse(409, "session_busy", "A turn is already running; wait for session.waiting before sending a follow-up.");
+                }
+                throw error;
+            }
+            // Rotate only after the message is accepted so a rejected send leaves
+            // the caller's token valid for retry.
+            const rotated = newContinuationKey();
+            yield engine.setContinuationToken(sessionId, rotated);
+            return jsonResponse({
+                ok: true,
+                sessionId,
+                continuationToken: formatContinuationToken(record.channelId, rotated),
+            }, { headers: { [SESSION_ID_HEADER]: sessionId } });
+        }),
+    };
+    const stream = {
+        method: "GET",
+        pattern: `${base}/v1/session/:sessionId/stream`,
+        auth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const sessionId = (_a = ctx.params.sessionId) !== null && _a !== void 0 ? _a : "";
+            // The stream-and-inspect handle is runtime-owned: sessions started by
+            // custom channels or schedules are observable here too when the caller
+            // matches the session's stored principal (or `--dev` relax). Follow-ups
+            // use the same ownership gate plus the session's continuation token.
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+            }
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                relax: relaxSessionReadAuth,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return ownership;
+            }
+            const url = new URL(request.url);
+            const rawStartIndex = url.searchParams.get("startIndex");
+            const startIndex = rawStartIndex === null ? 0 : Number.parseInt(rawStartIndex, 10);
+            if (Number.isNaN(startIndex) || startIndex < 0) {
+                return errorResponse(400, "invalid_request", "startIndex must be a non-negative integer.");
+            }
+            const body = yield engine.eventStream(sessionId, startIndex);
+            return new Response(body, {
+                status: 200,
+                headers: {
+                    "content-type": "application/x-ndjson; charset=utf-8",
+                    "cache-control": "no-store",
+                    [SESSION_ID_HEADER]: sessionId,
+                },
+            });
+        }),
+    };
+    /** One-shot NDJSON (or JSON) dump of the session trace. */
+    const events = {
+        method: "GET",
+        pattern: `${base}/v1/session/:sessionId/events`,
+        auth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const sessionId = (_a = ctx.params.sessionId) !== null && _a !== void 0 ? _a : "";
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+            }
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                relax: relaxSessionReadAuth,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return ownership;
+            }
+            const url = new URL(request.url);
+            const asJson = url.searchParams.get("format") === "json";
+            const snapshot = yield engine.listEvents(sessionId, 0);
+            if (asJson) {
+                return jsonResponse({
+                    sessionId,
+                    events: snapshot,
+                    playgroundUrl: playgroundUrlForSession(request, base, sessionId),
+                });
+            }
+            const ndjson = `${snapshot.map((e) => JSON.stringify(e)).join("\n")}${snapshot.length > 0 ? "\n" : ""}`;
+            return new Response(ndjson, {
+                status: 200,
+                headers: {
+                    "content-type": "application/x-ndjson; charset=utf-8",
+                    "cache-control": "no-store",
+                    "content-disposition": `attachment; filename="${sessionId}.ndjson"`,
+                    [SESSION_ID_HEADER]: sessionId,
+                },
+            });
+        }),
+    };
+    const listApprovals = {
+        method: "GET",
+        pattern: `${base}/v1/session/:sessionId/approvals`,
+        auth,
+        handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const sessionId = (_a = ctx.params.sessionId) !== null && _a !== void 0 ? _a : "";
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+            }
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                relax: relaxSessionReadAuth,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return ownership;
+            }
+            const pending = yield engine.listPendingApprovals(sessionId);
+            return jsonResponse({ ok: true, sessionId, pending });
+        }),
+    };
+    const resolveApproval = {
+        method: "POST",
+        pattern: `${base}/v1/session/:sessionId/approvals/:callId`,
+        auth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b, _c;
+            const sessionId = (_b = ctx.params.sessionId) !== null && _b !== void 0 ? _b : "";
+            const callId = (_c = ctx.params.callId) !== null && _c !== void 0 ? _c : "";
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+            }
+            const bridgeSlackApproval = relaxSessionApprovalAuth === true &&
+                ((_a = record.auth) === null || _a === void 0 ? void 0 : _a.authenticator) === "slack" &&
+                (relaxSessionReadAuthBeyondLoopback === true ||
+                    (typeof ctx.requestIp === "string" &&
+                        isLoopbackAddress(ctx.requestIp)));
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                // HTTP sessions stay strict. Slack sessions may use the --dev
+                // playground bridge (see relaxSessionApprovalAuth).
+                relax: bridgeSlackApproval,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return ownership;
+            }
+            const body = yield readJsonObject(request);
+            const decision = body === null || body === void 0 ? void 0 : body.decision;
+            if (decision !== "approve" && decision !== "deny") {
+                return errorResponse(400, "invalid_request", 'Expected a JSON body with `decision`: "approve" | "deny".');
+            }
+            try {
+                const pending = yield engine.resolveApproval(sessionId, callId, decision, ctx.auth, bridgeSlackApproval ? { asSessionOwner: true } : undefined);
+                return jsonResponse({
+                    ok: true,
+                    sessionId,
+                    callId,
+                    decision,
+                    toolName: pending.toolName,
+                });
+            }
+            catch (error) {
+                if (error instanceof ApprovalNotFoundError) {
+                    return errorResponse(404, "approval_not_found", error.message);
+                }
+                if (error instanceof ApprovalInterruptedError) {
+                    return errorResponse(409, "approval_interrupted", error.message);
+                }
+                if (error instanceof SessionAuthError) {
+                    return errorResponse(403, "forbidden", error.message);
+                }
+                throw error;
+            }
+        }),
+    };
+    const stop = {
+        method: "POST",
+        pattern: `${base}/v1/session/:sessionId/stop`,
+        auth,
+        handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const sessionId = (_a = ctx.params.sessionId) !== null && _a !== void 0 ? _a : "";
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+            }
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                relax: relaxSessionReadAuth,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return ownership;
+            }
+            const interrupted = yield engine.interrupt(sessionId);
+            return jsonResponse({ ok: true, interrupted }, { headers: { [SESSION_ID_HEADER]: sessionId } });
+        }),
+    };
+    return [
+        createSession,
+        followUp,
+        stop,
+        stream,
+        events,
+        listApprovals,
+        resolveApproval,
+    ];
+}
+export function requireSessionOwner(record, caller, options) {
+    // Dev playground lists every session (`includeAll`); match that by
+    // allowing cross-principal read/follow-up. Loopback-only unless
+    // `--allow-anonymous` also opted into beyondLoopback.
+    const relaxOwnership = (options === null || options === void 0 ? void 0 : options.relax) === true &&
+        (options.beyondLoopback === true ||
+            (typeof options.requestIp === "string" &&
+                isLoopbackAddress(options.requestIp)));
+    if (relaxOwnership || samePrincipal(record.auth, caller)) {
+        return undefined;
+    }
+    return errorResponse(403, "forbidden", "This session belongs to a different principal.");
+}
+export function jsonResponse(data, init = {}) {
+    var _a;
+    return new Response(JSON.stringify(data), {
+        status: (_a = init.status) !== null && _a !== void 0 ? _a : 200,
+        headers: Object.assign({ "content-type": "application/json; charset=utf-8" }, init.headers),
+    });
+}
+export function errorResponse(status, code, message) {
+    return jsonResponse({ ok: false, error: code, message }, { status });
+}
+function readWorkspaceFiles(value) {
+    if (value === undefined || value === null || typeof value !== "object") {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return undefined;
+    }
+    const files = {};
+    for (const [path, contents] of Object.entries(value)) {
+        if (typeof path !== "string" || path.trim() === "") {
+            continue;
+        }
+        if (typeof contents !== "string") {
+            continue;
+        }
+        files[path] = contents;
+    }
+    return Object.keys(files).length === 0 ? undefined : files;
+}
+export function readJsonObject(request) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            const parsed = yield request.json();
+            if (typeof parsed === "object" &&
+                parsed !== null &&
+                !Array.isArray(parsed)) {
+                return parsed;
+            }
+            return undefined;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    });
+}

package/dist/internal/ids.d.ts

@@ -0,0 +1,19 @@
+/** Fresh session id (`ses_<24 hex>` — a single safe path segment). */
+export declare function newSessionId(): string;
+export declare function newContinuationKey(): string;
+/**
+ * Unique server-tool call id (a single safe path segment). Used when the
+ * SDK omits `context.toolCallId` and for direct (deterministic) tool calls.
+ */
+export declare function newToolCallId(toolName: string): string;
+/**
+ * Wire form of a continuation token: the owning channel id, a colon, then
+ * the channel-local key (mirrors how platform channels key sessions by
+ * thread identity).
+ */
+export declare function formatContinuationToken(channelId: string, key: string): string;
+export declare function parseContinuationToken(token: string): {
+    channelId: string;
+    key: string;
+} | null;
+//# sourceMappingURL=ids.d.ts.map

package/dist/internal/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/internal/ids.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GACV,MAAM,CAER;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GACZ;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS3C"}

package/dist/internal/ids.js

@@ -0,0 +1,34 @@
+import { randomBytes } from "node:crypto";
+/** Fresh session id (`ses_<24 hex>` — a single safe path segment). */
+export function newSessionId() {
+    return `ses_${randomBytes(12).toString("hex")}`;
+}
+export function newContinuationKey() {
+    return randomBytes(16).toString("hex");
+}
+/**
+ * Unique server-tool call id (a single safe path segment). Used when the
+ * SDK omits `context.toolCallId` and for direct (deterministic) tool calls.
+ */
+export function newToolCallId(toolName) {
+    const safe = toolName.replace(/[^A-Za-z0-9_]/g, "_").slice(0, 32);
+    return `tool_${safe}_${randomBytes(8).toString("hex")}`;
+}
+/**
+ * Wire form of a continuation token: the owning channel id, a colon, then
+ * the channel-local key (mirrors how platform channels key sessions by
+ * thread identity).
+ */
+export function formatContinuationToken(channelId, key) {
+    return `${channelId}:${key}`;
+}
+export function parseContinuationToken(token) {
+    const separator = token.indexOf(":");
+    if (separator <= 0 || separator === token.length - 1) {
+        return null;
+    }
+    return {
+        channelId: token.slice(0, separator),
+        key: token.slice(separator + 1),
+    };
+}