@kortix/sdk 0.12.4 → 0.12.5

package/README.md

@@ -33,6 +33,31 @@ const kortix = createKortix({
 await kortix.projects.list();
 ```
 
+### Call external systems through Connectors
+
+Use one six-method data plane for every Connector provider. A user token binds
+the project explicitly. An agent-minted session token already carries its
+project scope, so it can use the top-level fallback.
+
+```ts
+const connectors = projectId
+  ? kortix.project(projectId).connectors
+  : kortix.connectors;
+
+await connectors.catalog();
+await connectors.tools();
+await connectors.search('send email');
+await connectors.describe('gmail.send_email');
+await connectors.call('gmail.send_email', { to, subject, body });
+await connectors.uploadAttachment(bytes, {
+  filename: 'invoice.pdf',
+  contentType: 'application/pdf',
+});
+```
+
+A Connector defines callable tools. A Connection stores one authorization for
+that Connector. Credentials remain server-side and never enter the sandbox.
+
 ## No bundler, no framework
 
 The published package ships a browser IIFE bundle alongside its ESM `dist/` —
@@ -86,7 +111,19 @@ const kortix = createKortix({
 // Projects
 const projects = await kortix.projects.list();
 const detail = await kortix.project(pid).detail();
-await kortix.project(pid).secrets.upsert({ name: "STRIPE_API_KEY", value });
+await kortix.project(pid).secrets.upsert({
+  name: "LOCAL_TOOL_TOKEN",
+  value,
+  strategy: "runtime",
+  consumer: "sandbox",
+});
+await kortix.project(pid).secrets.upsert({
+  identifier: "anthropic-primary",
+  name: "ANTHROPIC_API_KEY",
+  value: providerKey,
+  strategy: "broker",
+  consumer: "llm_gateway",
+});
 const visibleSessions = await kortix.project(pid).sessions.list();
 const projectInventory = await kortix
   .project(pid)
@@ -150,7 +187,8 @@ exhaustive — see `API-MAP.md` for the full per-domain surface:
 | `kortix.billing` | entitlement/usage reads: `accountState` · `accountStateMinimal` · `transactions` · `transactionsSummary` · `creditBreakdown` · `usageHistory` · `usageRollup` · `sessionCosts.{list,get}` · `tierConfigurations` — plus a curated mutation surface: `checkout.{createSession,confirmSession}` · `subscription.{createPortalSession,cancel,reactivate,scheduleDowngrade,cancelScheduledChange,prorationPreview}` · `credits.{purchase,autoTopupSettings,configureAutoTopup}` |
 | `kortix.marketplace` | public marketplace catalog browse + sources (not project-scoped): `items` · `item` · `itemFile` · `marketplaces` · `featured` · `sources.{list,add,remove}` — distinct from the install-scoped `project(id).marketplace` |
 | `kortix.validateToken()` | pasted-API-key validation helper — `GET /accounts/me`, never throws, resolves `{valid, identity?, error?}` |
-| `kortix.project(id)` | id-bound handle: `.secrets` · `.access` · `.connectors` · `.policies` · `.triggers` · `.files` · `.git` · `.changeRequests` (incl. `requestChanges`) · `.sessions` · `.tokens` (project-scoped CLI PATs — the `KORTIX_TOKEN` shape) · `.marketplace` / `.registry` (install/update/remove catalog items) · `.setupLinks.{requestSecret,requestConnector}` (agent-minted secret-entry / connector links) · `.validateManifest` · `.gitToken` · `.setDefaultAgent(name)` · `.session(sid)` (+ more namespaces: `.review`, `.approvals`, `.gateway` (incl. `.routing` and `.playground`), `.channels`, `.modelDefaults`, `.sandbox`) |
+| `kortix.connectors` | Connector data plane for an agent-minted session token: `catalog` · `tools` · `search` · `describe` · `call` · `uploadAttachment` |
+| `kortix.project(id)` | id-bound handle: `.secrets` · `.access` · `.connectors` (data plane + configuration + Connections) · `.policies` · `.triggers` · `.files` · `.git` · `.changeRequests` (incl. `requestChanges`) · `.sessions` · `.tokens` (project-scoped CLI PATs — the `KORTIX_TOKEN` shape) · `.marketplace` / `.registry` (install/update/remove catalog items) · `.setupLinks.{requestSecret,requestConnector}` (agent-minted secret-entry / connector links) · `.validateManifest` · `.gitToken` · `.setDefaultAgent(name)` · `.session(sid)` (+ more namespaces: `.review`, `.approvals`, `.gateway` (incl. `.routing` and `.playground`), `.channels`, `.modelDefaults`, `.sandbox`) |
 | `kortix.session(pid, sid)` | id-bound handle: lifecycle (`get`/`update`/`delete`/`start`/`restart`/`stop`/`setSharing`/`previews`/`commit`/`publicShares`/`ensureReady`) · finalized `cost()` · `send`/`abort`/`rewind`/`restoreRewind`/`setModel`/`setAgent` · `transcript()` · `.files` · runtime URL helpers (`health`/`previewUrl`/`proxyUrl`) · OpenCode REST compatibility escape hatches: `stream()` and `.runtime` |
 | `kortix.runtime()` | the OpenCode v2 compatibility client for the active sandbox; use a session-scoped handle in multi-tenant code |
 
@@ -172,12 +210,12 @@ await kortix.project(projectId).sessions.create({
 ```
 
 Do not put credentials in this map. For a white-label/backend wrapper, create an
-operator-managed connection profile, store its credential through the dedicated
-credential endpoint, and pass only the non-secret profile id at session create:
+operator-managed connection, store its credential through the dedicated
+credential endpoint, and pass only the non-secret connection id at session create:
 
 ```ts
 const project = kortix.project(projectId);
-const profile = await project.connectors.profiles.reconcile({
+const connection = await project.connectors.connections.reconcile({
   connector_alias: "customer-data",
   owner_type: "external",
   owner_id: wrapperUserId,
@@ -191,39 +229,39 @@ const auth = await project.connectors.auth.discover({
   provider: "postman",
   spec: "https://github.com/HubSpot/HubSpot-public-api-spec-collection",
 });
-await project.connectors.profiles.updateCredential(profile.profile_id, {
+await project.connectors.connections.updateCredential(connection.connection_id, {
   value: shortLivedCapability,
   kind: "secret",
 });
 await project.sessions.create({
   runtime_context: { locale: "de" },
   connector_bindings: {
-    "customer-data": { profile_id: profile.profile_id },
+    "customer-data": { connection_id: connection.connection_id },
   },
 });
 ```
 
 For bring-your-own authorization, each logged-in member creates their own
-profile without supplying an owner id; Kortix derives ownership from the bearer
+connection without supplying an owner id; Kortix derives ownership from the bearer
 token:
 
 ```ts
-const profile = await project.connectors.profiles.reconcileMember({
+const connection = await project.connectors.connections.reconcileMember({
   connector_alias: "gmail",
   label: "My Gmail",
 });
-await project.connectors.profiles.pipedreamConnect(profile.profile_id);
+await project.connectors.connections.pipedreamConnect(connection.connection_id);
 // Complete OAuth, then:
-await project.connectors.profiles.pipedreamFinalize(profile.profile_id);
+await project.connectors.connections.pipedreamFinalize(connection.connection_id);
 await project.sessions.create({
-  connector_bindings: { gmail: { profile_id: profile.profile_id } },
+  connector_bindings: { gmail: { connection_id: connection.connection_id } },
 });
 ```
 
-Member profiles are owner-only even for project managers, and sessions using
+Member connections are owner-only even for project managers, and sessions using
 one must remain private. Project defaults remain shared; external/agent/subject
-profiles remain operator-managed. Every profile is project/connector scoped
-and resolved on every Executor request, so revocation takes effect without a
+connections remain operator-managed. Every connection is project/connector scoped
+and resolved on every Connector request, so revocation takes effect without a
 restart. Credentials are encrypted server-side and are never returned, placed
 in `KORTIX_SESSION_CONTEXT`, or injected into the sandbox environment. Raw env
 and MCP configuration are not session-create inputs.
@@ -438,6 +476,7 @@ Stable, tree-shakeable surfaces (also reachable via the facade). Not exhaustive
 interface KortixPlatformConfig {
   backendUrl: string;
   getToken: () => Promise<string | null>;
+  clientSource?: 'api' | 'cli' | 'mobile' | 'web';
   getUserId?: () => Promise<string | null>;
   billingEnabled?: boolean;
   sandboxId?: string | null;
@@ -448,6 +487,10 @@ interface KortixPlatformConfig {
 }
 ```
 
+Set `clientSource` when a non-web host needs its requests separated in the
+centralized audit log. The SDK sends the validated value as request metadata.
+Actor identity and permissions still come from the bearer token.
+
 The SDK is host-agnostic: no Next.js / web coupling in the core. The host injects
 its token getter and toast/notify sinks; the SDK does the rest. Today that's proven
 in React DOM (`apps/web` and the `apps/whitelabel-demo` reference app are the

package/dist/browser/session-sync/session-transcript-cache.d.ts

@@ -38,10 +38,27 @@ export declare function toHydrateEntries(transcript: CachedTranscript): Array<{
  * store holds anything for this session — from SSE, an optimistic send, or a
  * completed reconcile — it outranks whatever is on disk, so hydrating again
  * could only ever move the transcript backwards.
+ *
+ * With exactly one exception, and it is not hypothetical: a session whose agent
+ * is still running when the store evicts it. Eviction deletes the key; the
+ * agent's next SSE frame puts it straight back, holding only what streamed
+ * after the eviction. The store "has" the session, but what it has is strictly
+ * less than the disk copy, so standing down leaves the user with a fragment and
+ * a `loadOlder` for their own history. `hydrate` merges rather than replaces —
+ * it never drops a message the store has that the incoming set lacks, and for
+ * text parts it keeps whichever side has more — so painting the disk copy under
+ * a live fragment restores the history without touching the live tail.
  */
 export declare function shouldHydrateFromCache(input: {
     storeHasSession: boolean;
     cachedMessageCount: number;
+    /**
+     * The store's entry for this session is a post-eviction fragment. From
+     * `useSyncStore.wasTranscriptEvicted`, which also reports false the moment a
+     * send goes in flight — repainting under one would retire the message the
+     * user just typed.
+     */
+    storeSessionWasEvicted?: boolean;
 }): boolean;
 /**
  * Read this session's cached transcript. Resolves to null when there is no

package/dist/browser/session-sync/session-transcript-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-transcript-cache.d.ts","sourceRoot":"","sources":["../../../src/browser/session-sync/session-transcript-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AAIhE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;CAC/B;AAED,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,oBAAoB,EAC3B,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,IAAI,CASzB;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,gBAAgB,GAC3B,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC,CAIzC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAGV;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAIlC;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,EAC3B,SAAS,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,IAAI,CAAC,CAIf"}
+{"version":3,"file":"session-transcript-cache.d.ts","sourceRoot":"","sources":["../../../src/browser/session-sync/session-transcript-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,4BAA4B,CAAC;AAIhE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;CAC/B;AAED,UAAU,oBAAoB;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,oBAAoB,EAC3B,SAAS,EAAE,MAAM,GAChB,gBAAgB,GAAG,IAAI,CASzB;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,gBAAgB,GAC3B,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC,CAIzC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GAAG,OAAO,CAIV;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAIlC;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,EAC3B,SAAS,EAAE,MAAM,EACjB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/browser/session-sync/session-transcript-cache.js

@@ -42,11 +42,23 @@ export function toHydrateEntries(transcript) {
  * store holds anything for this session — from SSE, an optimistic send, or a
  * completed reconcile — it outranks whatever is on disk, so hydrating again
  * could only ever move the transcript backwards.
+ *
+ * With exactly one exception, and it is not hypothetical: a session whose agent
+ * is still running when the store evicts it. Eviction deletes the key; the
+ * agent's next SSE frame puts it straight back, holding only what streamed
+ * after the eviction. The store "has" the session, but what it has is strictly
+ * less than the disk copy, so standing down leaves the user with a fragment and
+ * a `loadOlder` for their own history. `hydrate` merges rather than replaces —
+ * it never drops a message the store has that the incoming set lacks, and for
+ * text parts it keeps whichever side has more — so painting the disk copy under
+ * a live fragment restores the history without touching the live tail.
  */
 export function shouldHydrateFromCache(input) {
-    if (input.storeHasSession)
+    if (input.cachedMessageCount <= 0)
         return false;
-    return input.cachedMessageCount > 0;
+    if (!input.storeHasSession)
+        return true;
+    return input.storeSessionWasEvicted === true;
 }
 /**
  * Read this session's cached transcript. Resolves to null when there is no

package/dist/browser/session-sync/session-transcript-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-transcript-cache.js","sourceRoot":"","sources":["../../../src/browser/session-sync/session-transcript-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAY/E;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA2B,EAC3B,SAAiB;IAEjB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,EAAE,EAAE;YAAE,SAAS;QAC3B,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAC9B,UAA4B;IAE5B,OAAO,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC;SAC/B,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;SAClC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;AACxF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAGtC;IACC,IAAI,KAAK,CAAC,eAAe;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,KAAK,CAAC,kBAAkB,GAAG,CAAC,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB,EACjB,kBAA2B;IAE3B,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;AAClE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,KAA2B,EAC3B,SAAiB,EACjB,kBAA2B;IAE3B,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1C,OAAO,gBAAgB,CAAC,SAAS,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;AAChG,CAAC"}
+{"version":3,"file":"session-transcript-cache.js","sourceRoot":"","sources":["../../../src/browser/session-sync/session-transcript-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAY/E;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAA2B,EAC3B,SAAiB;IAEjB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,OAAO,EAAE,EAAE;YAAE,SAAS;QAC3B,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAC9B,UAA4B;IAE5B,OAAO,CAAC,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAC;SAC/B,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;SAClC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;AACxF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAUtC;IACC,IAAI,KAAK,CAAC,kBAAkB,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,KAAK,CAAC,eAAe;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,KAAK,CAAC,sBAAsB,KAAK,IAAI,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB,EACjB,kBAA2B;IAE3B,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IACvE,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;AAClE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,KAA2B,EAC3B,SAAiB,EACjB,kBAA2B;IAE3B,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU;QAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1C,OAAO,gBAAgB,CAAC,SAAS,EAAE,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC;AAChG,CAAC"}

package/dist/browser/stores/sync-store.d.ts

@@ -13,9 +13,40 @@ interface SyncState {
     applyEvent: (event: OpenCodeEvent) => void;
     upsertMessage: (sessionID: string, message: Message) => void;
     removeMessage: (sessionID: string, messageID: string) => void;
-    upsertPart: (messageID: string, part: Part) => void;
+    /**
+     * `sessionID` is optional. Omitted, the deltaActiveParts guard below reads
+     * `part.sessionID` directly. Pass it explicitly whenever the caller already
+     * resolved a more trustworthy session id than the wire part carries — see
+     * the `message.part.updated` handler in `applyEvent`, which falls back to
+     * scanning every session's message list specifically because
+     * `part.sessionID` can be absent on the wire. Without this parameter that
+     * resolved id has nowhere to go, and the guard silently no-ops for exactly
+     * the malformed events it exists to protect against.
+     *
+     * Kept optional (not merged into `part`, not required) because `upsertPart`
+     * has real callers outside this file (`apps/web` via `useSessionStateStore`)
+     * that only ever pass `(messageID, part)` — this stays source-compatible
+     * with them.
+     */
+    upsertPart: (messageID: string, part: Part, sessionID?: string) => void;
     removePart: (messageID: string, partID: string) => void;
-    applyPartDelta: (messageID: string, partID: string, field: string, delta: string) => void;
+    /**
+     * `sessionID` is a new REQUIRED leading parameter (was `(messageID, partID,
+     * field, delta)`) — a breaking arity change for anyone calling this action
+     * directly. Deliberate, not silent: the only caller of `applyPartDelta` in
+     * this repo is this file's own `applyEvent` (`message.part.delta` case),
+     * which already has a reliable `sessionID` on the event itself — no
+     * "resolve it from an unreliable field" case like `upsertPart` above.
+     * Kept required, not optional-with-fallback, because there is no
+     * `part.sessionID`-equivalent to fall back to here that wouldn't be a
+     * guess. Verified no other in-repo caller exists (`apps/web`, `apps/mobile`
+     * both use their own stores/methods, not this one). This action is exported
+     * on `useSyncStore` (`./sync-store`, `./internal/sync-store`), which makes
+     * it technically part of the published surface, so an out-of-repo consumer
+     * calling it directly would fail to compile — that needs a semver-relevant
+     * callout in the next release notes.
+     */
+    applyPartDelta: (sessionID: string, messageID: string, partID: string, field: string, delta: string) => void;
     setStatus: (sessionID: string, status: SessionStatus) => void;
     setDiff: (sessionID: string, diffs: FileDiff[]) => void;
     setTodo: (sessionID: string, todos: Todo[]) => void;
@@ -39,6 +70,59 @@ interface SyncState {
      *  whose first prompt the server hasn't registered yet. */
     hasOptimisticMessages: (sessionID: string) => boolean;
     clearSession: (sessionID: string) => void;
+    /**
+     * Take a hold on `sessionID`'s transcript for one mounted consumer, and get
+     * back the release for it. The session's data stays resident until every
+     * hold is released; see {@link DETACHED_SESSION_LIMIT} for what happens
+     * after that.
+     *
+     * Returning the release rather than exposing a separate `releaseSession`
+     * makes the pairing structural — a caller cannot take a hold without
+     * receiving the matching release, and a React effect returns it directly:
+     *
+     * ```ts
+     * useEffect(() => useSyncStore.getState().retainSession(id), [id]);
+     * ```
+     *
+     * Same shape as `retainSessionSyncController` in session-sync-registry.ts.
+     * The release is idempotent: calling it twice drops one hold, not two.
+     */
+    retainSession: (sessionID: string) => () => void;
+    /**
+     * True when this session's `messages` entry — if it has one at all — is a
+     * post-eviction fragment rather than the transcript.
+     *
+     * Eviction deletes the key, and `use-session-sync.ts` reads its absence as
+     * "the disk copy may repaint". A session whose agent is still running defeats
+     * that on its own: its SSE frames put the key back within a second or two,
+     * holding only what streamed after the eviction, so the user came back to the
+     * fragment and had to `loadOlder` for everything before it.
+     *
+     * Answering this at the store is what makes the repaint decision correct
+     * without dropping any event — dropping events for a session nobody has
+     * mounted would blind the spawn-tool preview of a child session, which has no
+     * reconcile of its own and is fed by SSE alone.
+     *
+     * Goes false again the moment anything re-establishes the session:
+     * `hydrate` (the repaint, or a reconcile), `clearSession`, `optimisticAdd`.
+     */
+    wasTranscriptEvicted: (sessionID: string) => boolean;
+    /**
+     * Join this session's messages with their parts, memoized on the identity of
+     * the arrays it read.
+     *
+     * Every consumer selects through here — `useSessionSync` and
+     * `useOpenCodeMessages` alike. It has to be one shared memo rather than one
+     * per hook: `getMessages` rebuilds via `.map()` on every call, so a raw
+     * selector returns a new array each time, fails `useSyncExternalStore`'s
+     * `Object.is` check and re-renders forever. The memo previously existed
+     * TWICE, once in each hook file, and neither copy was dropped when a
+     * session's data was — so an evicted transcript stayed reachable through
+     * whichever memo still held its rows. Keeping it in the store, next to the
+     * eviction that invalidates it, is what makes that impossible rather than
+     * merely fixed.
+     */
+    buildSessionMessages: (sessionID: string, msgs: Message[] | undefined, parts: Record<string, Part[]>) => MessageWithParts[];
     hydrate: (sessionID: string, msgs: Array<{
         info: Message;
         parts: Part[];

package/dist/browser/stores/sync-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync-store.d.ts","sourceRoot":"","sources":["../../../src/browser/stores/sync-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync-store.d.ts","sourceRoot":"","sources":["../../../src/browser/stores/sync-store.ts"],"names":[],"mappings":"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"}