@vibesdotdev/code-sessions 0.0.0-stage → 1.0.0-rc.0

package/dist/config/preparation.d.ts

@@ -0,0 +1,2 @@
+export * from '../schemas/preparation.ts';
+//# sourceMappingURL=preparation.d.ts.map

package/dist/config/preparation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparation.d.ts","sourceRoot":"","sources":["../../src/config/preparation.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/dist/config/preparation.js

@@ -0,0 +1,2 @@
+export * from "../schemas/preparation.js";
+//# sourceMappingURL=preparation.js.map

package/dist/config/preparation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparation.js","sourceRoot":"","sources":["../../src/config/preparation.ts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC"}

package/dist/docs/code-sessions.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=code-sessions.docs.descriptor.d.ts.map

package/dist/docs/code-sessions.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-sessions.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/code-sessions.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBA+OjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/code-sessions.docs.descriptor.js

@@ -0,0 +1,241 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'code-sessions.overview',
+    parent: 'platform',
+    order: 8,
+    title: 'Code Sessions',
+    summary: 'Manage code sessions — create, list, resume, delete, and run commands in a workspace. Capability model: PTY-capable host → interactive terminal; CF Sandbox → snapshot transcript.',
+    tags: ['code-sessions', 'hq', 'platform', 'build', 'transcript', 'interactive', 'session', 'tui', 'studio'],
+    surfaces: ['web', 'cli', 'in-app'],
+    enabled: true,
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Code Sessions
+summary: Manage code sessions — create, list, resume, delete, and run commands in a workspace.
+tags: [code-sessions, hq, platform, build, transcript, interactive, session, tui, studio]
+parent: platform
+order: 8
+surfaces: [web, cli, in-app]
+hardware: [consumer, cloud]
+---
+
+# Code Sessions
+
+A code session gives you a persistent workspace tied to a repository. You can run commands, browse files,
+and pick up where you left off after a reload. Where the session runs determines what it can do:
+
+| Session type | Runs on | Surface |
+|---|---|---|
+| **Cloud sandbox** | Managed cloud infrastructure | Snapshot execution — independent command runs |
+| **Interactive** | Your local machine or a fleet host | Live terminal — full PTY, persistent shell |
+
+## Creating a session
+
+:::usage{language="ts"}
+import { getVibesClient } from '@vibesdotdev/kernel/client';
+import type { CodeSessionsClient, CodeSessionCreateInput } from '@vibesdotdev/code-sessions';
+
+const client = await getVibesClient<CodeSessionsClient>('code-sessions', runtime);
+
+// Cloud sandbox (ephemeral scratch space)
+const session = await client.create({ ephemeral: true, hostTarget: { kind: 'cloud' } });
+
+// On your local machine with a repository
+const session = await client.create({
+  repositoryId: 'repo-uuid',
+  hostTarget: { kind: 'host', hostId: 'local' }
+});
+
+session.capability; // 'transcript' | 'interactive'
+:::
+
+## Listing sessions
+
+:::usage{language="ts"}
+const sessions = await client.list({ status: 'active' });
+const rows = sessions.map((s) => ({ repository: s.repositoryName, capability: s.capability, status: s.status }));
+:::
+
+## Running commands (cloud sessions)
+
+Cloud sessions use snapshot execution — each command is an independent run. Surfaces can call the
+canonical platform owner route through the package client:
+
+:::usage{language="ts"}
+const result = await client.run({
+  sessionId: session.sessionId,
+  command: ['pwd']
+});
+const cwd = result.stdout.trim();
+:::
+
+App-local SvelteKit transcript bridge routes should still verify auth, ownership, and capability, but
+then call \`client.run(...)\`; platform-web is the owner route that resolves the
+\`agent/code-session\` implementation and calls \`handleTranscriptRun\` from the premium overlay
+\`@vibesdotdev/code-sessions-premium/bridge\`.
+
+Owner-route sketch:
+
+:::usage{language="ts"}
+import { handleTranscriptRun } from '@vibesdotdev/code-sessions-premium/bridge';
+import { resolveCodeSession } from '@vibesdotdev/agent-execution/code-session';
+import { json } from '@sveltejs/kit';
+
+export const POST = async ({ params, request, locals }) => {
+  // ... auth + ownership check ...
+  const { command, cwd, env } = await request.json();
+  const iface = await resolveCodeSession(locals.runtime, { requiredHostTargetKind: 'cloud' });
+  const result = await handleTranscriptRun({ session: iface }, { sessionId: params.id, command, cwd, env });
+  return json(result);
+};
+:::
+
+## Svelte components
+
+\`@vibesdotdev/code-sessions/svelte\` provides ready-to-use components and server-safe
+SvelteKit loader helpers:
+
+- **SessionCard** — status badge, host target, age, preview link, delete action
+- **SessionList** — list of SessionCards with an empty state that teaches creation
+- **CreateSessionDialog** — host-target picker, repository + branch fields
+- **TranscriptView** — command input → output cards, exit codes, re-run, copy
+- **loadCodeSessionsLayoutData** — list route data via the canonical runtime client
+- **loadCodeSessionDetailData** — detail route data via the canonical runtime client
+- **submitCodeSessionCreateAction / submitCodeSessionDeleteAction** — browser-side helpers for
+  SvelteKit route-action FormData and serialized \`ActionResult\` parsing
+
+:::usage{language="ts"}
+import { serviceOrigin } from '@vibesdotdev/infra-core/service';
+import { loadCodeSessionsLayoutData } from '@vibesdotdev/code-sessions/svelte/loaders';
+
+export const load = async (event) =>
+  loadCodeSessionsLayoutData(event, {
+    platformOrigin: await serviceOrigin(event.locals.runtime, 'platform')
+  });
+:::
+
+:::usage{language="svelte"}
+<script>
+  import { deserialize } from '$app/forms';
+  import { goto, invalidateAll } from '$app/navigation';
+  import { SessionList, CreateSessionDialog } from '@vibesdotdev/code-sessions/svelte';
+  import { submitCodeSessionCreateAction } from '@vibesdotdev/code-sessions/svelte/actions';
+
+  let showCreate = $state(false);
+  let createError = $state(null);
+
+  async function handleCreate(input: CodeSessionCreateInput) {
+    const result = await submitCodeSessionCreateAction(fetch, deserialize, input);
+    if (!result.ok) {
+      // Keep app-specific copy/presentation here.
+      createError = result.message;
+      return;
+    }
+    await invalidateAll();
+    if (result.sessionId) goto(\`/sessions/\${result.sessionId}\`);
+  }
+</script>
+
+<SessionList
+  {sessions}
+  oncreate={() => (showCreate = true)}
+  onopen={(s) => goto(\`/sessions/\${s.sessionId}\`)}
+  ondelete={(id) => deleteSession(id)}
+/>
+
+<CreateSessionDialog open={showCreate} oncreate={handleCreate} onclose={() => (showCreate = false)} />
+:::
+
+The Svelte package intentionally does not own auth, billing text, redirects, repository links, or
+server route actions. Those stay in the consuming app; \`./loaders\` owns reads and \`./actions\`
+owns browser submission/result parsing.
+
+## Chat Build projection
+
+chat-web has a projection route because a Build-mode room stores only
+\`metadata.buildSession\` and chat-specific setup fields. Browser code calls the app-local
+\`/api/build/sessions\` route directly for create/unbind. The server route then resolves
+\`getVibesClient<CodeSessionsClient>('code-sessions', runtime)\`, forks it with the caller's verified Bearer token, and talks to
+platform-web. Do not resolve the \`agent/code-session\` execution runtime from browser UI just to call
+the chat projection route; \`agent/code-session\` remains the execution substrate behind
+platform-web and its cloud/host adapters.
+
+## Studio TUI surface
+
+\`@vibesdotdev/code-sessions/tui\` owns the consumer-only Studio route at \`/code-sessions\`.
+The TUI registers:
+
+- \`tui/app\` id \`code-sessions.monitor\`
+- \`tui/command\` id \`code-sessions.open\`
+- \`tui/state\` id \`code-sessions.sessions\`
+
+The state descriptor resolves \`getVibesClient<CodeSessionsClient>('code-sessions')\` through the
+runtime client and calls \`list()\` plus \`getStartOptions()\`. The route shows session identity,
+status, capability, host target, workspace, checkout ref, preview URL, and sign-in or service
+recovery state. It ships runtime-backed create: the form renders the environment/workspace selectors
+returned by \`getStartOptions()\` and dispatches the chosen target/source contract to
+\`CodeSessionsClient.create(...)\`. For selected cloud snapshot sessions, it exposes a transcript
+command runner backed by \`CodeSessionsClient.run(...)\`. For any selected session, it exposes
+confirmed teardown backed by \`CodeSessionsClient.delete(...)\`. Interactive terminal attach stays out
+of the TUI until it has live route-owned lifecycle evidence through the host attach path.
+
+## Catalog and workspace binding
+
+Packaged renderers (Desktop, mobile) never resolve the HTTP client or the local
+execution plane directly. Two consumer-worker kinds project what they may see:
+
+- \`code-sessions/catalog\` (asset \`code-sessions.catalog\`) — renderer-safe
+  session facts via the \`list\`/\`get\` exposure. The projection copies
+  presentation facts only; host paths and setup scripts stay in the worker.
+- \`code-sessions/workspace-binding\` (asset
+  \`code-sessions.local-workspace-binding\`) — binds an opaque workspace
+  identity to a local code session through the \`bind\` exposure.
+
+Both loaders run in \`consumer.worker\` scope behind a \`consumer-renderer\`
+remote exposure. Import the kind contracts from
+\`@vibesdotdev/code-sessions/catalog\` and \`@vibesdotdev/code-sessions/workspace\`.
+
+## Capability flag
+
+Every \`SessionWithCapability\` record has a \`capability\` field:
+
+- \`'transcript'\` — CF Sandbox (snapshot execution, each command independent)
+- \`'interactive'\` — PTY-capable host (live terminal)
+
+Check this before rendering a terminal or transcript surface.
+If you need to branch before a record has been annotated, import
+\`resolveSessionCapability\` from \`@vibesdotdev/code-sessions/config\`.
+
+## Deleting a session
+
+:::usage{language="ts"}
+await client.delete(session.sessionId);
+// Platform record removed and live session torn down.
+:::
+
+## Local lifecycle proof
+
+Direct Vite dev servers cannot prove cloud sandbox lifecycle success because they do not expose the
+workerd \`SANDBOX\` binding. Use the dedicated Wrangler preset when collecting local acceptance
+evidence:
+
+:::usage{language="bash"}
+bun run vibes pm preset start code-session-lifecycle-workerd
+CHAT_E2E_APP_ORIGIN=https://chat.vibes.local \
+CHAT_E2E_AUTH_ORIGIN=https://auth.vibes.local \
+CHAT_E2E_ACCOUNT_ORIGIN=https://account.vibes.local \
+CHAT_E2E_PLATFORM_ORIGIN=https://platform.vibes.local \
+bun run --cwd apps/chat-web probe:code-session:lifecycle --require-workerd-preset --prime-billing
+:::
+
+Use direct Vite probe output only as blocker evidence, not as proof of successful cloud sessions.
+The \`--require-workerd-preset\` flag makes the probe refuse acceptance evidence unless the dedicated
+workerd PM preset is actually running, the \`d1-migrate-dev\` task has passed, app process health is
+green, resources are ready, and conflicting dev stack processes are stopped.
+`
+    }
+};
+export default descriptor;
+//# sourceMappingURL=code-sessions.docs.descriptor.js.map

package/dist/docs/code-sessions.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-sessions.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/code-sessions.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,wBAAwB;IAC5B,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,eAAe;IACtB,OAAO,EACN,oLAAoL;IACrL,IAAI,EAAE,CAAC,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC;IAC3G,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,OAAO,EAAE,IAAI;IACb,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+NT;KACC;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @vibesdotdev/code-sessions — runtime-aligned code session feature package.
+ *
+ * Owns the canonical `runtime/client` surface for code-session management.
+ * Sessions are read/written through `getVibesClient<CodeSessionsClient>('code-sessions', runtime)`.
+ * Session data is owned by platform-web (`apps/platform-web/src/routes/api/code-sessions/*`).
+ *
+ * NOTE: the consumer impl is NOT exported from this barrel — it is lazily loaded
+ * by the plugin. `CodeSessionsApiClientConsumer` and `createSsrCodeSessionsClient`
+ * live on `./api` only, so root importers (including browser runtimes that take
+ * just the plugin or the types) never load the HTTP implementation module. Import
+ * the impl or the SSR factory from `@vibesdotdev/code-sessions/api`, the capability
+ * resolver from `./config`. The hosted transcript bridge is the premium overlay
+ * `@vibesdotdev/code-sessions-premium/bridge`.
+ *
+ * @see https://docs.vibes.dev/code-sessions
+ */
+export { codeSessionsPlugin, default } from './code-sessions.plugin.ts';
+export { codeSessionsApiClientDescriptor, default as codeSessionsApiClientDescriptorDefault } from './api/code-sessions.api-client.descriptor.ts';
+export { CodeSessionsApiError, CodeSessionsNotSignedInError, type CodeSessionsClient, type CodeSessionsClientOptions, type CodeSessionServiceAssertion, type SessionCapability, type SessionWithCapability, type CodeSessionListOptions, type CodeSessionCreateInput, type LocalCodeSessionCreateInput, type PlatformCodeSessionCreateInput, type CodeSessionStartTargetOption, type CodeSessionStartSourceOption, type CodeSessionStartOptions, type RunCommandRequest, type RunCommandResponse, type PushBranchRequest, type PushBranchResponse, type CreatePullRequestRequest, type CreatePullRequestResponse } from './api/code-sessions.api-client.types.ts';
+export type { CodeSessionSeed } from '@vibesdotdev/platform/api';
+export { resolveSessionCapability } from './capability.ts';
+export * from './catalog/index.ts';
+export * from './workspace/index.ts';
+export { pullRequestPlanForSession, pullRequestPlanAfterPublish, type PullRequestPlan, type PullRequestPlanSession } from './pull-request-plan.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIxE,OAAO,EACN,+BAA+B,EAC/B,OAAO,IAAI,sCAAsC,EACjD,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACN,oBAAoB,EACpB,4BAA4B,EAC5B,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,EACjC,KAAK,uBAAuB,EAC5B,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,MAAM,yCAAyC,CAAC;AAKjD,YAAY,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACN,yBAAyB,EACzB,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+/**
+ * @vibesdotdev/code-sessions — runtime-aligned code session feature package.
+ *
+ * Owns the canonical `runtime/client` surface for code-session management.
+ * Sessions are read/written through `getVibesClient<CodeSessionsClient>('code-sessions', runtime)`.
+ * Session data is owned by platform-web (`apps/platform-web/src/routes/api/code-sessions/*`).
+ *
+ * NOTE: the consumer impl is NOT exported from this barrel — it is lazily loaded
+ * by the plugin. `CodeSessionsApiClientConsumer` and `createSsrCodeSessionsClient`
+ * live on `./api` only, so root importers (including browser runtimes that take
+ * just the plugin or the types) never load the HTTP implementation module. Import
+ * the impl or the SSR factory from `@vibesdotdev/code-sessions/api`, the capability
+ * resolver from `./config`. The hosted transcript bridge is the premium overlay
+ * `@vibesdotdev/code-sessions-premium/bridge`.
+ *
+ * @see https://docs.vibes.dev/code-sessions
+ */
+export { codeSessionsPlugin, default } from "./code-sessions.plugin.js";
+// Explicit re-exports from the leaf modules — never `export *` from `./api`,
+// which would re-expose the consumer impl above and defeat the plugin's lazy
+// loader for every root importer.
+export { codeSessionsApiClientDescriptor, default as codeSessionsApiClientDescriptorDefault } from "./api/code-sessions.api-client.descriptor.js";
+export { CodeSessionsApiError, CodeSessionsNotSignedInError } from "./api/code-sessions.api-client.types.js";
+export { resolveSessionCapability } from "./capability.js";
+export * from "./catalog/index.js";
+export * from "./workspace/index.js";
+export { pullRequestPlanForSession, pullRequestPlanAfterPublish } from "./pull-request-plan.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACxE,6EAA6E;AAC7E,6EAA6E;AAC7E,kCAAkC;AAClC,OAAO,EACN,+BAA+B,EAC/B,OAAO,IAAI,sCAAsC,EACjD,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACN,oBAAoB,EACpB,4BAA4B,EAmB5B,MAAM,yCAAyC,CAAC;AAMjD,OAAO,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAC3D,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EACN,yBAAyB,EACzB,2BAA2B,EAG3B,MAAM,wBAAwB,CAAC"}

package/dist/pull-request-plan.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Can this session become a pull request, and with what?
+ *
+ * Drew's fifth predicate is "the code session results in a PR with a live
+ * preview URL if applicable". The dangerous half is `if applicable`: an
+ * ephemeral scratch session has no repository and no branch, so there is
+ * nothing to open a PR from, and a surface that offers the button anyway — or
+ * worse, invents a branch — would be claiming work exists where it does not.
+ *
+ * This module answers the question ONCE, as data, so the web action, the CLI,
+ * and any future automation agree on when a PR is possible and what it should
+ * say. It deliberately does NOT open the PR: `forge-tools`'
+ * `executePrCreateFromBranch` already owns that, and a second creation path
+ * would drift from it.
+ */
+/** The subset of a session record this decision needs. */
+export interface PullRequestPlanSession {
+    sessionId: string;
+    repositoryName?: string | null;
+    repositoryId?: string | null;
+    checkoutRef?: string | null;
+    ephemeral?: boolean;
+    seed?: {
+        source?: string;
+        title?: string;
+        ref?: string;
+        body?: string;
+    } | null;
+}
+export type PullRequestPlan = {
+    ready: true;
+    /** Repo ref for `forge-pr-create-from-branch` (`repo`). */
+    repo: string;
+    /** Branch the session's work is on (`sourceRef`). */
+    sourceRef: string;
+    title: string;
+    description: string;
+} | {
+    ready: false;
+    /** Shown to the user verbatim — say why, never imply the PR is coming. */
+    reason: string;
+};
+/**
+ * Build the PR plan for a session, or explain precisely why there isn't one.
+ *
+ * Ordering matters: the ephemeral check comes FIRST because an ephemeral
+ * session is a deliberate product state ("scratch space, no repository"), not
+ * a misconfiguration, and telling the user their session "has no branch" would
+ * describe it as broken when it is working as designed.
+ */
+export declare function pullRequestPlanForSession(session: PullRequestPlanSession): PullRequestPlan;
+/**
+ * Plan a PR immediately after a successful publish.
+ *
+ * The push response carries the repository and branch the platform *proved*
+ * (`owner/name` + the branch git actually pushed). Those take precedence over
+ * the session's create-time fields: a session may have drifted off its original
+ * checkout ref, and the push binding is the only `owner/name` Forge URLs and
+ * `forge-pr-create-from-branch` both accept without ambiguity.
+ *
+ * Surfaces must not invent a second plan — call this (or
+ * {@link pullRequestPlanForSession}) and render/act on the result.
+ */
+export declare function pullRequestPlanAfterPublish(session: PullRequestPlanSession, published: {
+    repository?: string | null;
+    branch?: string | null;
+}): PullRequestPlan;
+//# sourceMappingURL=pull-request-plan.d.ts.map

package/dist/pull-request-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-request-plan.d.ts","sourceRoot":"","sources":["../src/pull-request-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,sBAAsB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/E;AAED,MAAM,MAAM,eAAe,GACxB;IACA,KAAK,EAAE,IAAI,CAAC;IACZ,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACnB,GACD;IACA,KAAK,EAAE,KAAK,CAAC;IACb,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CACd,CAAC;AAEL;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CA8C1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,sBAAsB,EAC/B,SAAS,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAC/D,eAAe,CAYjB"}

package/dist/pull-request-plan.js

@@ -0,0 +1,94 @@
+/**
+ * Can this session become a pull request, and with what?
+ *
+ * Drew's fifth predicate is "the code session results in a PR with a live
+ * preview URL if applicable". The dangerous half is `if applicable`: an
+ * ephemeral scratch session has no repository and no branch, so there is
+ * nothing to open a PR from, and a surface that offers the button anyway — or
+ * worse, invents a branch — would be claiming work exists where it does not.
+ *
+ * This module answers the question ONCE, as data, so the web action, the CLI,
+ * and any future automation agree on when a PR is possible and what it should
+ * say. It deliberately does NOT open the PR: `forge-tools`'
+ * `executePrCreateFromBranch` already owns that, and a second creation path
+ * would drift from it.
+ */
+/**
+ * Build the PR plan for a session, or explain precisely why there isn't one.
+ *
+ * Ordering matters: the ephemeral check comes FIRST because an ephemeral
+ * session is a deliberate product state ("scratch space, no repository"), not
+ * a misconfiguration, and telling the user their session "has no branch" would
+ * describe it as broken when it is working as designed.
+ */
+export function pullRequestPlanForSession(session) {
+    if (session.ephemeral === true) {
+        return {
+            ready: false,
+            reason: 'This is an ephemeral workspace — scratch space with no repository, so there is nothing to open a pull request from. Start a session against a repository to produce one.'
+        };
+    }
+    const repo = session.repositoryName?.trim();
+    if (!repo) {
+        return {
+            ready: false,
+            reason: 'This session is not linked to a repository, so there is no repository to open a pull request against.'
+        };
+    }
+    const sourceRef = session.checkoutRef?.trim();
+    if (!sourceRef) {
+        return {
+            ready: false,
+            reason: 'This session has no branch recorded, so there is no branch to open a pull request from.'
+        };
+    }
+    // The seed is what makes the PR traceable to the work item it came from —
+    // the whole point of carrying `{source:'work-item', ref}` through the
+    // spawn flow. Without a seed the session is still PR-able; it just cannot
+    // claim a work item it does not have.
+    const seedTitle = session.seed?.title?.trim();
+    const workItemRef = session.seed?.source === 'work-item' ? session.seed.ref?.trim() : undefined;
+    const title = seedTitle ? seedTitle : `Work from code session ${session.sessionId}`;
+    const lines = [
+        seedTitle
+            ? `Opened from a code session started for: ${seedTitle}`
+            : 'Opened from a code session.',
+        '',
+        `Session: ${session.sessionId}`,
+        `Branch: ${sourceRef}`
+    ];
+    if (workItemRef)
+        lines.push(`Work item: ${workItemRef}`);
+    // NOTE (ruling, SESSIONS.md 2026-07-25): a preview URL is NEVER derived
+    // from `session.previewUrl`. That is the sandbox's dev-server port and dies
+    // with the session; a PR's preview must be a deployed branch preview. If
+    // one does not exist, the PR says nothing about previews rather than
+    // pointing at a URL that will be dead when a reviewer opens it.
+    return { ready: true, repo, sourceRef, title, description: lines.join('\n') };
+}
+/**
+ * Plan a PR immediately after a successful publish.
+ *
+ * The push response carries the repository and branch the platform *proved*
+ * (`owner/name` + the branch git actually pushed). Those take precedence over
+ * the session's create-time fields: a session may have drifted off its original
+ * checkout ref, and the push binding is the only `owner/name` Forge URLs and
+ * `forge-pr-create-from-branch` both accept without ambiguity.
+ *
+ * Surfaces must not invent a second plan — call this (or
+ * {@link pullRequestPlanForSession}) and render/act on the result.
+ */
+export function pullRequestPlanAfterPublish(session, published) {
+    const repository = Object.prototype.hasOwnProperty.call(published, 'repository')
+        ? published.repository?.trim()
+        : session.repositoryName;
+    const branch = Object.prototype.hasOwnProperty.call(published, 'branch')
+        ? published.branch?.trim()
+        : session.checkoutRef;
+    return pullRequestPlanForSession({
+        ...session,
+        repositoryName: repository,
+        checkoutRef: branch
+    });
+}
+//# sourceMappingURL=pull-request-plan.js.map

package/dist/pull-request-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-request-plan.js","sourceRoot":"","sources":["../src/pull-request-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4BH;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAA+B;IACxE,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAChC,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,0KAA0K;SAClL,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACX,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,uGAAuG;SAC/G,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO;YACN,KAAK,EAAE,KAAK;YACZ,MAAM,EAAE,yFAAyF;SACjG,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,sEAAsE;IACtE,0EAA0E;IAC1E,sCAAsC;IACtC,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9C,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhG,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,OAAO,CAAC,SAAS,EAAE,CAAC;IACpF,MAAM,KAAK,GAAG;QACb,SAAS;YACR,CAAC,CAAC,2CAA2C,SAAS,EAAE;YACxD,CAAC,CAAC,6BAA6B;QAChC,EAAE;QACF,YAAY,OAAO,CAAC,SAAS,EAAE;QAC/B,WAAW,SAAS,EAAE;KACtB,CAAC;IACF,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,WAAW,EAAE,CAAC,CAAC;IACzD,wEAAwE;IACxE,4EAA4E;IAC5E,yEAAyE;IACzE,qEAAqE;IACrE,gEAAgE;IAEhE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CAC1C,OAA+B,EAC/B,SAAiE;IAEjE,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC;QAC/E,CAAC,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE;QAC9B,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC;IAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC;QACvE,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE;QAC1B,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACvB,OAAO,yBAAyB,CAAC;QAChC,GAAG,OAAO;QACV,cAAc,EAAE,UAAU;QAC1B,WAAW,EAAE,MAAM;KACnB,CAAC,CAAC;AACJ,CAAC"}

package/dist/schemas/preparation.d.ts

@@ -0,0 +1,51 @@
+import * as z from 'zod/v4';
+/** A replayable request for repository-backed execution, before its first turn. */
+export declare const codeSessionPreparationSchema: z.ZodObject<{
+    operationId: z.ZodUUID;
+    repositoryId: z.ZodOptional<z.ZodUUID>;
+    createRepositoryIfMissing: z.ZodDefault<z.ZodBoolean>;
+    hostTarget: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"cloud">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"host">;
+        hostId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"provisioned">;
+        adapter: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        ttlHours: z.ZodOptional<z.ZodNumber>;
+        providerConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>], "kind">>;
+    goal: z.ZodString;
+    chatRoomId: z.ZodUUID;
+}, z.core.$strip>;
+export type CodeSessionPreparationInput = z.input<typeof codeSessionPreparationSchema>;
+/** Only a ready filesystem is an execution binding; allocation alone is not. */
+export declare const preparedCodeSessionSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    repositoryId: z.ZodUUID;
+    hostTarget: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"cloud">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"host">;
+        hostId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"provisioned">;
+        adapter: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        ttlHours: z.ZodOptional<z.ZodNumber>;
+        providerConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>], "kind">;
+    workspacePath: z.ZodString;
+    status: z.ZodLiteral<"active">;
+}, z.core.$strip>;
+export type PreparedCodeSession = z.infer<typeof preparedCodeSessionSchema>;
+//# sourceMappingURL=preparation.d.ts.map

package/dist/schemas/preparation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparation.d.ts","sourceRoot":"","sources":["../../src/schemas/preparation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAG5B,mFAAmF;AACnF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;iBAOvC,CAAC;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAEvF,gFAAgF;AAChF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;iBAMpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/schemas/preparation.js

@@ -0,0 +1,20 @@
+import * as z from 'zod/v4';
+import { SessionHostTargetSchema } from '@vibesdotdev/agent-execution/code-session';
+/** A replayable request for repository-backed execution, before its first turn. */
+export const codeSessionPreparationSchema = z.object({
+    operationId: z.uuid(),
+    repositoryId: z.uuid().optional(),
+    createRepositoryIfMissing: z.boolean().default(false),
+    hostTarget: SessionHostTargetSchema.optional(),
+    goal: z.string().min(1),
+    chatRoomId: z.uuid()
+});
+/** Only a ready filesystem is an execution binding; allocation alone is not. */
+export const preparedCodeSessionSchema = z.object({
+    sessionId: z.string().min(1),
+    repositoryId: z.uuid(),
+    hostTarget: SessionHostTargetSchema,
+    workspacePath: z.string().min(1),
+    status: z.literal('active')
+});
+//# sourceMappingURL=preparation.js.map

package/dist/schemas/preparation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preparation.js","sourceRoot":"","sources":["../../src/schemas/preparation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,uBAAuB,EAAE,MAAM,2CAA2C,CAAC;AAEpF,mFAAmF;AACnF,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE;IACrB,YAAY,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;IACjC,yBAAyB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACrD,UAAU,EAAE,uBAAuB,CAAC,QAAQ,EAAE;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE;CACpB,CAAC,CAAC;AAGH,gFAAgF;AAChF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,YAAY,EAAE,CAAC,CAAC,IAAI,EAAE;IACtB,UAAU,EAAE,uBAAuB;IACnC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;CAC3B,CAAC,CAAC"}