statewire 0.19.4 → 0.20.0

package/README.md

@@ -35,7 +35,7 @@ export const App = () => {
 
 Connections negotiate date ranges through `Statewire-Version` and `Statewire-Protocol`. Protocols are additive and required by default. The server selects versions in `syn`; WebSockets use `statewire.v1`.
 
-Each protocol owns its commands, context documents, and state documents. The main document is independent of its optional read key. Command sequences and replay remain shared across protocols. Python hosts support lazy, chained compatibility adapters.
+Each protocol owns its commands, lease context, and state documents. The main document is independent of its optional read key. Command sequences and replay remain shared across protocols. Python hosts support lazy, chained compatibility adapters.
 
 See the [protocol registration and migration guide](https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/spec/statewire-protocol/protocols/page.mdx).
 
@@ -45,3 +45,17 @@ See the [protocol registration and migration guide](https://github.com/assistant
 - Guide: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/guides/statewire/consume/page.mdx
 - Reference: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/reference/statewire/page.mdx
 - Spec: https://github.com/assistant-ui/harness-sdk/blob/main/apps/docs/app/statewire/docs/spec/statewire-protocol/page.mdx
+
+## Lease context
+
+Native context belongs to a protocol and a connection lease, independently of command history:
+
+```ts
+const client = new StatewireClient({
+  transport,
+  context: { "acme-chat": { locale: "en" } },
+});
+client.setContext("acme-chat", { locale: "de" });
+```
+
+The client restores its latest object on every attachment, including a fresh hello on a preserved socket. Hosts validate through `validateContext` and react through `contextChanged`. Command handlers read `this.context`, captured when the command was admitted; later replacements cannot change queued commands. Context uses document encoding (including dates), full replacements, and a 64 KiB limit per entry. Updates consume no command sequence numbers.

package/dist/client/session.d.ts

@@ -5,6 +5,7 @@ import { RemoteLink, StatewireRemoteProps } from "../transports/sse.js";
 import { StatewireClient } from "../statewire.js";
 import { Statewire } from "../types.js";
 import { StatewirePath } from "../wire/ops.js";
+import { encodeContext } from "../wire/context.js";
 //#region src/client/session.d.ts
 type WireCommand = {
   protocol: string;
@@ -28,6 +29,7 @@ type Pending = {
 };
 type AttachState = "detached" | "attached" | "finished";
 type StatewireSessionOptions = StatewireProtocol.Options & {
+  context?: Readonly<Record<string, Statewire.Context>>;
   sessionStore?: StatewireClient.SessionStorage | undefined;
   onSessionLost?: StatewireClient.OnSessionLost | undefined;
   onDone?: (() => void) | undefined;
@@ -42,6 +44,10 @@ type Shared = {
 };
 type Session = {
   options: StatewireSessionOptions;
+  configuredContext: StatewireSessionOptions["context"];
+  contexts: Map<string, ReturnType<typeof encodeContext>>;
+  dirtyContexts: Set<string>;
+  attachContexts: Map<string, ReturnType<typeof encodeContext>>;
   selection: StatewireProtocol.Selection | undefined;
   record: StatewireClient.SessionRecord;
   ctx: StatewireRemoteProps;
@@ -93,7 +99,8 @@ declare const discardFailed: (s: Session, entry: StatewireClient.FailedCommand)
 declare const retryFailed: (s: Session, entry: StatewireClient.FailedCommand) => Promise<unknown>;
 declare const documentSource: (s: Session) => StatewireDocuments.Source;
 declare const invokeProtocol: (s: Session, protocol: string, method: string, params: readonly unknown[]) => Promise<unknown>;
+declare const setContext: (s: Session, protocol: string, value: Statewire.Context) => void;
 declare const useStatewireSession: (options: StatewireSessionOptions) => Session;
 //#endregion
-export { StatewireSessionOptions, discardFailed, documentSource, failedCommands, invokeProtocol, retryFailed, setTransport, useStatewireSession };
+export { StatewireSessionOptions, discardFailed, documentSource, failedCommands, invokeProtocol, retryFailed, setContext, setTransport, useStatewireSession };
 //# sourceMappingURL=session.d.ts.map

package/dist/client/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","names":[],"sources":["../../src/client/session.ts"],"mappings":";;;;;;;;KAyCK;EACH;EACA,WAAW,YAAY,gBAAgB;EACvC;EACA;EACA;;KAGG;WACM;WACA,SAAS;WACT,KAAK;;EAEd;;EAEA;;EAEA;EACA,UAAU;EACV,SAAS;;KAeN;KAEO,0BAA0B,kBAAkB;EACtD,eAAe,gBAAgB;EAC/B,gBAAgB,gBAAgB;EAChC;;KAGG;EACH,KAAK;EACL;IAAU;IAAkB,SAAS,gBAAgB;;EACrD;;KAGG;EACH,SAAS;EACT,WAAW,kBAAkB;EAC7B,QAAQ,gBAAgB;EACxB,KAAK;EACL;EACA;EACA,OAAO;EACP;EACA,iBAAiB,gBAAgB;EACjC,OAAO,gBAAgB;EACvB,eAAe,mBAAmB;EAClC,QAAQ;;EAER;;EAEA;EACA;EACA,YAAY;;EAEZ,eAAe;EACf;EACA;EACA,eAAe,gBAAgB;EAC/B;EACA;EACA,eAAe,YAAY;EAC3B;EACA,SAAS;EACT,qBAAqB,gBAAgB;EACrC,gCAAgC,gBAAgB;EAChD;EACA,mBAAmB;EACnB,WAAW,mBAAmB;EAC9B;EACA,SAAS;EACT,QAAQ,UAAU;EAClB,QAAQ;EACR;EACA;EACA;EACA,WAAW;EACX;EACA,WAAW;EACX;EACA,UAAU,mBAAmB,sBAAsB;;cA2MxC,iBACX,GAAG,qBACO,gBAAgB;cA+uBtB,eAAgB,GAAG,SAAS,WAAW;cAiNhC,gBACX,GAAG,SACH,OAAO,gBAAgB;cAYZ,cACX,GAAG,SACH,OAAO,gBAAgB,kBACtB;cA4DU,iBAAkB,GAAG,YAAU,mBAAmB;cA+BlD,iBACX,GAAG,SACH,kBACA,gBACA,+BAA0B;cAoEf,sBACX,SAAS,4BACR"}
+{"version":3,"file":"session.d.ts","names":[],"sources":["../../src/client/session.ts"],"mappings":";;;;;;;;;KA0CK;EACH;EACA,WAAW,YAAY,gBAAgB;EACvC;EACA;EACA;;KAGG;WACM;WACA,SAAS;WACT,KAAK;;EAEd;;EAEA;;EAEA;EACA,UAAU;EACV,SAAS;;KAeN;KAEO,0BAA0B,kBAAkB;EACtD,UAAU,SAAS,eAAe,UAAU;EAC5C,eAAe,gBAAgB;EAC/B,gBAAgB,gBAAgB;EAChC;;KAGG;EACH,KAAK;EACL;IAAU;IAAkB,SAAS,gBAAgB;;EACrD;;KAGG;EACH,SAAS;EACT,mBAAmB;EACnB,UAAU,YAAY,kBAAkB;EACxC,eAAe;EACf,gBAAgB,YAAY,kBAAkB;EAC9C,WAAW,kBAAkB;EAC7B,QAAQ,gBAAgB;EACxB,KAAK;EACL;EACA;EACA,OAAO;EACP;EACA,iBAAiB,gBAAgB;EACjC,OAAO,gBAAgB;EACvB,eAAe,mBAAmB;EAClC,QAAQ;;EAER;;EAEA;EACA;EACA,YAAY;;EAEZ,eAAe;EACf;EACA;EACA,eAAe,gBAAgB;EAC/B;EACA;EACA,eAAe,YAAY;EAC3B;EACA,SAAS;EACT,qBAAqB,gBAAgB;EACrC,gCAAgC,gBAAgB;EAChD;EACA,mBAAmB;EACnB,WAAW,mBAAmB;EAC9B;EACA,SAAS;EACT,QAAQ,UAAU;EAClB,QAAQ;EACR;EACA;EACA;EACA,WAAW;EACX;EACA,WAAW;EACX;EACA,UAAU,mBAAmB,sBAAsB;;cA2MxC,iBACX,GAAG,qBACO,gBAAgB;cA+wBtB,eAAgB,GAAG,SAAS,WAAW;cAiNhC,gBACX,GAAG,SACH,OAAO,gBAAgB;cAYZ,cACX,GAAG,SACH,OAAO,gBAAgB,kBACtB;cA4DU,iBAAkB,GAAG,YAAU,mBAAmB;cA+BlD,iBACX,GAAG,SACH,kBACA,gBACA,+BAA0B;cAoEf,aACX,GAAG,SACH,kBACA,OAAO,UAAU;cAcN,sBACX,SAAS,4BACR"}

package/dist/client/session.js

@@ -1,10 +1,11 @@
 import { reviveDocumentValue } from "../document.js";
+import "../wire/limits.js";
 import { inRange, protocolOffers } from "../wire/protocol.js";
+import { encodeContext } from "../wire/context.js";
 import { createMethodProxy } from "../util/methodProxy.js";
 import { StatewireSendError } from "../types.js";
 import { bindCommandsHost } from "../host/host.js";
 import { encodeParams, reviveResponse } from "../wire/meta.js";
-import "../wire/limits.js";
 import { applyDocumentOps, findDocument, mainDocument, resolveDocumentKey } from "../wire/documents.js";
 import { DocumentStorageContext, SessionStorageContext, createMemorySessionStore } from "./sessionStore.js";
 import { backoff, retryHint } from "./timing.js";
@@ -475,6 +476,13 @@ const selectionOf = (syn) => {
 	};
 };
 const handleHello = (s, { ops, syn }) => {
+	if (s.attach === "attached") {
+		s.ephemeralSeqs = {};
+		detachEphemeralLanes(s);
+	}
+	for (const [protocol, value] of s.contexts) if (s.attachContexts.get(protocol) === value) s.dirtyContexts.delete(protocol);
+	else s.dirtyContexts.add(protocol);
+	s.attachContexts.clear();
 	s.selection = selectionOf(syn);
 	s.documents = {
 		mode: null,
@@ -574,15 +582,19 @@ const buildLanes = (s, cmdGate = "all") => {
 		last[protocol] = entry.seq;
 		entries.push(entry);
 	}
-	if (entries.length === 0) return null;
+	const ctx = [...s.dirtyContexts].map((protocol) => s.contexts.get(protocol));
+	if (entries.length === 0 && ctx.length === 0) return null;
 	return {
-		frame: { cmd: entries.map((p) => {
-			const { produced: _produced, ...command } = p.command;
-			return {
-				...command,
-				seq: p.seq
-			};
-		}) },
+		frame: {
+			...ctx.length > 0 && { ctx },
+			...entries.length > 0 && { cmd: entries.map((p) => {
+				const { produced: _produced, ...command } = p.command;
+				return {
+					...command,
+					seq: p.seq
+				};
+			}) }
+		},
 		entries
 	};
 };
@@ -590,6 +602,8 @@ const takeAttachLanes = (s) => {
 	s.attachEntries = /* @__PURE__ */ new Set();
 	const wanted = s.lanesOnAttach;
 	s.lanesOnAttach = false;
+	for (const protocol of s.contexts.keys()) s.dirtyContexts.add(protocol);
+	s.attachContexts = new Map(s.contexts);
 	const lanes = buildLanes(s, wanted && s.sessionKnown ? "persisted" : "none");
 	if (!lanes) return null;
 	s.attachEntries = new Set(lanes.entries);
@@ -620,6 +634,7 @@ const pump = async (s) => {
 			if (!s.hydrated) await s.ready;
 			const transport = s.transport;
 			if (buildLanes(s) === null) return;
+			if (transport?.parked && s.pending.length === 0) return;
 			if (s.attach !== "attached" || !transport) {
 				if (transport?.connection.status === "standby" && transport.connection.reason === "idle" || transport?.parked && s.pending.length > 0) transport.connection.reconnect();
 				await waitForWake(s);
@@ -644,12 +659,21 @@ const pump = async (s) => {
 				result = await (s.shared && !s.deactivated ? s.store.lock(send) : send());
 			} catch {
 				if (!s.running || isFinished(s)) return;
+				if (lanes.frame.ctx?.length) {
+					s.lanesOnAttach = true;
+					transport.connection.reconnect();
+					await waitForWake(s);
+					continue;
+				}
 				s.frameFailures += 1;
 				await sleepUntilWake(s, backoff(s.frameFailures));
 				continue;
 			}
 			if (!s.running) return;
 			s.frameFailures = 0;
+			if (epoch === s.attachEpoch && (result.type === "ok" || result.type === "refusal")) {
+				for (const entry of lanes.frame.ctx ?? []) if (s.contexts.get(entry.protocol) === entry) s.dirtyContexts.delete(entry.protocol);
+			}
 			if (result.type === "ok") {
 				if (epoch === s.attachEpoch) {
 					for (const entry of lanes.entries) if (s.pending.includes(entry)) {
@@ -836,7 +860,7 @@ const sendCommand = (s, method, params, protocol = s.options.protocol ?? "defaul
 		enqueue(s, {
 			protocol,
 			produced: {
-				wire: s.options.wireVersion ?? { version: "2026-09-13" },
+				wire: s.options.wireVersion ?? { version: "2026-09-30" },
 				protocols: protocolOffers(s.options) === "*" && s.selection ? s.selection.protocols : protocolOffers(s.options)
 			},
 			method,
@@ -968,7 +992,7 @@ const loadSessionRecord = (store, options) => {
 	let stored = store.load();
 	if (stored !== null) validateLanes(stored);
 	const current = {
-		wire: options.wireVersion ?? { version: "2026-09-13" },
+		wire: options.wireVersion ?? { version: "2026-09-30" },
 		protocols: protocolOffers(options)
 	};
 	const compatible = (record) => Object.entries(record.lanes).every(([protocol, lane]) => lane.commands.every((command) => storedCommandCompatible(protocol, command, current)));
@@ -988,6 +1012,13 @@ const loadSessionRecord = (store, options) => {
 	if (stored === null) store.save(record);
 	return record;
 };
+const setContext = (s, protocol, value) => {
+	if (s.selection ? !s.selection.protocols.some((p) => p.name === protocol) : !offered(s, protocol)) throw new Error(`statewire: protocol "${protocol}" is not negotiated`);
+	s.contexts.set(protocol, encodeContext(protocol, value));
+	s.dirtyContexts.add(protocol);
+	wake(s);
+	pump(s);
+};
 const useStatewireSession = (options) => {
 	const [defaultStore] = useState(createMemorySessionStore);
 	const mounted = useContext(SessionStorageContext);
@@ -1002,6 +1033,10 @@ const useStatewireSession = (options) => {
 		};
 		const session = {
 			options,
+			configuredContext: options.context,
+			contexts: new Map(Object.entries(options.context ?? {}).map(([protocol, value]) => [protocol, encodeContext(protocol, value)])),
+			dirtyContexts: new Set(Object.keys(options.context ?? {})),
+			attachContexts: /* @__PURE__ */ new Map(),
 			selection: void 0,
 			record,
 			ctx: {
@@ -1095,6 +1130,11 @@ const useStatewireSession = (options) => {
 		return session;
 	});
 	if (store.lock !== void 0 !== (s.shared !== false)) throw new Error("statewire: session storage changed sharedness across renders — lock/subscribe must be present from the first render or never");
+	useEffect(() => {
+		if (s.configuredContext === options.context) return;
+		s.configuredContext = options.context;
+		for (const [protocol_0, value_0] of Object.entries(options.context ?? {})) setContext(s, protocol_0, value_0);
+	}, [s, options.context]);
 	s.options = options;
 	s.store = store;
 	s.documentStore = documentStore;
@@ -1118,6 +1158,6 @@ const useStatewireSession = (options) => {
 	return s;
 };
 //#endregion
-export { discardFailed, documentSource, failedCommands, invokeProtocol, retryFailed, setTransport, useStatewireSession };
+export { discardFailed, documentSource, failedCommands, invokeProtocol, retryFailed, setContext, setTransport, useStatewireSession };
 
 //# sourceMappingURL=session.js.map