@dharma-ai-labs/agent-fabric-relay-client 0.2.30 → 0.2.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,7 +1,9 @@
1
1
  import { createHash, createPublicKey, generateKeyPairSync, randomBytes, randomUUID, sign } from 'node:crypto';
2
2
  import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
3
- import { dirname } from 'node:path';
4
- import { canonicalize, refreshActionDecisionAcknowledgement, validateActionDecisionAcknowledgementContract, verifyInitialServerSigningKeyset, verifyServerSigningKeysetUpdate, } from '@dharma-ai-labs/agent-fabric-contracts';
3
+ import { dirname, resolve } from 'node:path';
4
+ import { userInfo } from 'node:os';
5
+ import { acquireEnrollmentAnchorLock } from './enrollmentAnchorLock.js';
6
+ import { canonicalize, refreshActionDecisionAcknowledgement, validateActionDecisionAcknowledgementContract, verifyInitialServerSigningKeyset, verifyServerSigningKeysetUpdate, validateDeviceConfigContract, validateDeviceConnectionPreferenceContract, } from '@dharma-ai-labs/agent-fabric-contracts';
5
7
  import { createSystemSecureStore } from '@dharma-ai-labs/agent-fabric-secure-store';
6
8
  import { HostOperationFence } from './hostOperationScope.js';
7
9
  export { claimSetupReference, setupClaimSourceRegistration } from './setupClaim.js';
@@ -170,26 +172,120 @@ function enrollmentAnchorHasBaseIdentity(anchor, config) {
170
172
  && anchor.enrolledAt === config.enrolledAt
171
173
  && Number.isFinite(Date.parse(anchor.enrolledAt));
172
174
  }
175
+ // The namespace follows the OS user and protected legacy account, rather than
176
+ // DHARMA_HOME/configPath. Different configured homes share the same anchor lock.
177
+ async function withEnrollmentAnchorLock(config, fence, operation) {
178
+ const identity = userInfo();
179
+ const user = createHash('sha256').update(identity.homedir + ':' + identity.username).digest('hex').slice(0, 32);
180
+ const account = legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId);
181
+ // Use a stable OS-user path even when callers override HOME, TMPDIR or DHARMA_HOME.
182
+ const temporaryRoot = process.platform === 'win32' ? resolve(identity.homedir, 'AppData', 'Local', 'Temp') : '/tmp';
183
+ const path = resolve(temporaryRoot, `dharma-enrollment-locks-${user}`, `${account}.lock`);
184
+ let release;
185
+ try {
186
+ release = await acquireEnrollmentAnchorLock(path, fence);
187
+ return fence ? await fence.step(operation) : await operation();
188
+ }
189
+ finally {
190
+ await release?.();
191
+ }
192
+ }
193
+ async function freshAnchorValue(store, account) {
194
+ return (store.getFresh ?? store.get).call(store, account);
195
+ }
196
+ async function writeEnrollmentAnchor(store, config, secret, expectedCurrent, expectedLegacy) {
197
+ const account = enrollmentAnchorAccountFor(config.hqUrl, config.organizationId, config.deviceId);
198
+ if (store.backend === 'windows-credential-manager') {
199
+ if (!store.compareAndPutEnrollmentAnchor)
200
+ throw Error('connection_anchor_store_unavailable');
201
+ const written = await store.compareAndPutEnrollmentAnchor({ account, secret, expectedCurrent, expectedLegacy,
202
+ legacyAccount: legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId) });
203
+ if (!written)
204
+ throw Error('connection_existing_anchor_requires_recovery');
205
+ }
206
+ else {
207
+ await store.put(account, secret);
208
+ }
209
+ }
210
+ /** Missing-anchor recovery must prove both current and historical slots absent. */
211
+ export async function assertDeviceEnrollmentAnchorAbsent(input) {
212
+ const config = input.config;
213
+ let values;
214
+ try {
215
+ const store = await protectedStore(input.store, input.hostScope);
216
+ const get = (account) => store.getFresh ? store.getFresh(account) : store.get(account);
217
+ values = await Promise.all([
218
+ get(enrollmentAnchorAccountFor(config.hqUrl, config.organizationId, config.deviceId)),
219
+ get(legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId)),
220
+ ]);
221
+ }
222
+ catch {
223
+ throw new Error('connection_anchor_store_unavailable');
224
+ }
225
+ if (values.some(value => value !== null))
226
+ throw new Error('connection_existing_anchor_requires_recovery');
227
+ }
173
228
  export async function saveDeviceEnrollmentAnchor(input) {
174
- const anchor = enrollmentAnchorFromConfig(input.hostScope ? structuredClone(input.config) : input.config);
229
+ const config = structuredClone(input.config);
230
+ const fence = input.hostScope ? new HostOperationFence(input.hostScope) : undefined;
231
+ return withEnrollmentAnchorLock(config, fence, () => saveEnrollmentAnchorLocked({ ...input, config }));
232
+ }
233
+ async function saveEnrollmentAnchorLocked(input) {
234
+ const anchor = enrollmentAnchorFromConfig(input.config);
175
235
  const serialized = JSON.stringify(anchor);
176
236
  const account = enrollmentAnchorAccountFor(anchor.hqUrl, anchor.organizationId, anchor.deviceId);
177
237
  const store = await protectedStore(input.store, input.hostScope);
178
- await store.put(account, serialized);
179
- if (await store.get(account) !== serialized)
238
+ let previous, legacy;
239
+ try {
240
+ previous = await freshAnchorValue(store, account);
241
+ legacy = input.requireAbsent || store.backend === 'windows-credential-manager'
242
+ ? await freshAnchorValue(store, legacyEnrollmentAnchorAccountFor(anchor.hqUrl, anchor.organizationId)) : null;
243
+ }
244
+ catch (error) {
245
+ if (input.requireAbsent)
246
+ throw Error('connection_anchor_store_unavailable');
247
+ throw error;
248
+ }
249
+ if (input.requireAbsent) {
250
+ if (previous !== null || legacy !== null)
251
+ throw Error('connection_existing_anchor_requires_recovery');
252
+ }
253
+ else {
254
+ if (previous !== null) {
255
+ const existing = parseProtectedAnchor(previous, input.hostScope, 'Protected enrollment anchor is corrupt.');
256
+ if (!enrollmentAnchorHasBaseIdentity(existing, input.config)) {
257
+ throw new Error('connection_existing_anchor_requires_recovery');
258
+ }
259
+ if (canonicalize(existing.serverSigningKeyset ?? null) !== canonicalize(anchor.serverSigningKeyset ?? null)) {
260
+ if (!anchor.serverSigningKeyset
261
+ || !verifyKeysetTransition(input.config, existing.serverSigningKeyset, anchor.serverSigningKeyset, input.now ?? new Date()).ok) {
262
+ throw new Error('connection_existing_anchor_requires_recovery');
263
+ }
264
+ }
265
+ }
266
+ }
267
+ await writeEnrollmentAnchor(store, input.config, serialized, previous, legacy);
268
+ if (await freshAnchorValue(store, account) !== serialized)
180
269
  throw new Error('Secure store did not confirm the enrollment anchor write.');
181
270
  return anchor;
182
271
  }
183
272
  export async function loadDeviceEnrollmentAnchor(input) {
273
+ if (input.readOnly)
274
+ return loadEnrollmentAnchorLocked(input);
275
+ const config = structuredClone(input.config);
276
+ const fence = input.hostScope ? new HostOperationFence(input.hostScope) : undefined;
277
+ return withEnrollmentAnchorLock(config, fence, () => loadEnrollmentAnchorLocked({ ...input, config }));
278
+ }
279
+ async function loadEnrollmentAnchorLocked(input) {
184
280
  const { hostScope, store: suppliedStore } = input;
185
281
  const config = hostScope ? structuredClone(input.config) : input.config;
186
282
  const account = enrollmentAnchorAccountFor(config.hqUrl, config.organizationId, config.deviceId);
187
283
  const store = await protectedStore(suppliedStore, hostScope);
188
- let serialized = await store.get(account);
284
+ let serialized = await freshAnchorValue(store, account);
189
285
  let migratedLegacy = false;
190
- if (!serialized) {
191
- serialized = await store.get(legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId));
192
- migratedLegacy = Boolean(serialized);
286
+ if (serialized === null) {
287
+ serialized = await freshAnchorValue(store, legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId));
288
+ migratedLegacy = serialized !== null;
193
289
  }
194
290
  if (!serialized)
195
291
  throw new Error('Device enrollment is not anchored in secure storage. Run dharma login again.');
@@ -198,9 +294,9 @@ export async function loadDeviceEnrollmentAnchor(input) {
198
294
  || JSON.stringify(anchor.serverSigningKeyset ?? null) !== JSON.stringify(config.serverSigningKeyset ?? null)) {
199
295
  throw new Error('Device configuration does not match the secure enrollment anchor. Run dharma login again.');
200
296
  }
201
- if (migratedLegacy) {
202
- await store.put(account, serialized);
203
- if (await store.get(account) !== serialized)
297
+ if (migratedLegacy && !input.readOnly) {
298
+ await writeEnrollmentAnchor(store, config, serialized, null, serialized);
299
+ if (await freshAnchorValue(store, account) !== serialized)
204
300
  throw new Error('Secure store did not confirm the enrollment anchor migration.');
205
301
  }
206
302
  return anchor;
@@ -614,15 +710,23 @@ export async function recoverDeviceEnrollmentConsistency(input) {
614
710
  async function recoverEnrollmentWithFence(input) {
615
711
  const config = input.hostFence ? await input.hostFence.step(() => loadDeviceConfig(input.configPath))
616
712
  : await loadDeviceConfig(input.configPath);
713
+ return withEnrollmentAnchorLock(config, input.hostFence, () => recoverEnrollmentLocked({ ...input, lockedConfig: config }));
714
+ }
715
+ async function recoverEnrollmentLocked(input) {
716
+ const config = input.hostFence ? await input.hostFence.step(() => loadDeviceConfig(input.configPath))
717
+ : await loadDeviceConfig(input.configPath);
718
+ if (!enrollmentAnchorHasBaseIdentity(enrollmentAnchorFromConfig(input.lockedConfig), config)) {
719
+ throw new Error('connection_enrollment_changed');
720
+ }
617
721
  const rawStore = input.hostFence ? await input.hostFence.step(async () => input.store ?? await createSystemSecureStore())
618
722
  : input.store ?? await createSystemSecureStore();
619
723
  const store = input.hostFence ? input.hostFence.store(rawStore) : rawStore;
620
724
  const account = enrollmentAnchorAccountFor(config.hqUrl, config.organizationId, config.deviceId);
621
- let serialized = await store.get(account);
725
+ let serialized = await freshAnchorValue(store, account);
622
726
  let migratedLegacy = false;
623
- if (!serialized) {
624
- serialized = await store.get(legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId));
625
- migratedLegacy = Boolean(serialized);
727
+ if (serialized === null) {
728
+ serialized = await freshAnchorValue(store, legacyEnrollmentAnchorAccountFor(config.hqUrl, config.organizationId));
729
+ migratedLegacy = serialized !== null;
626
730
  }
627
731
  if (!serialized)
628
732
  return config;
@@ -631,8 +735,8 @@ async function recoverEnrollmentWithFence(input) {
631
735
  throw new Error('Device configuration does not match the secure enrollment anchor. Run dharma login again.');
632
736
  }
633
737
  if (migratedLegacy) {
634
- await store.put(account, serialized);
635
- if (await store.get(account) !== serialized)
738
+ await writeEnrollmentAnchor(store, config, serialized, null, serialized);
739
+ if (await freshAnchorValue(store, account) !== serialized)
636
740
  throw new Error('Secure store did not confirm the enrollment anchor migration.');
637
741
  }
638
742
  if (canonicalize(anchor.serverSigningKeyset ?? null) === canonicalize(config.serverSigningKeyset ?? null)) {
@@ -650,7 +754,7 @@ async function recoverEnrollmentWithFence(input) {
650
754
  if (config.serverSigningKeyset) {
651
755
  const verification = verifyKeysetTransition(config, anchor.serverSigningKeyset, config.serverSigningKeyset, now);
652
756
  if (verification.ok) {
653
- await saveDeviceEnrollmentAnchor({ config, store });
757
+ await saveEnrollmentAnchorLocked({ config, store, now });
654
758
  return config;
655
759
  }
656
760
  }
@@ -661,10 +765,16 @@ export async function installTrustedServerSigningKeyset(input) {
661
765
  hostFence: input.hostScope === undefined ? undefined : new HostOperationFence(input.hostScope) });
662
766
  }
663
767
  async function installKeysetWithFence(input) {
768
+ const config = input.hostFence ? await input.hostFence.step(() => loadDeviceConfig(input.configPath))
769
+ : await loadDeviceConfig(input.configPath);
770
+ return withEnrollmentAnchorLock(config, input.hostFence, () => installKeysetLocked({ ...input, lockedConfig: config }));
771
+ }
772
+ async function installKeysetLocked(input) {
664
773
  const rawStore = input.hostFence ? await input.hostFence.step(async () => input.store ?? await createSystemSecureStore())
665
774
  : input.store ?? await createSystemSecureStore();
666
775
  const store = input.hostFence ? input.hostFence.store(rawStore) : rawStore;
667
- const config = await recoverEnrollmentWithFence({ configPath: input.configPath, store, now: input.now, hostFence: input.hostFence });
776
+ const config = await recoverEnrollmentLocked({ configPath: input.configPath, store, now: input.now,
777
+ hostFence: input.hostFence, lockedConfig: input.lockedConfig });
668
778
  const now = input.now ?? new Date();
669
779
  if (canonicalize(config.serverSigningKeyset ?? null) === canonicalize(input.candidate))
670
780
  return config;
@@ -674,17 +784,83 @@ async function installKeysetWithFence(input) {
674
784
  const next = { ...config, serverSigningKeyset: input.candidate };
675
785
  // The protected anchor is the write-ahead record. If the process stops before
676
786
  // the disk configuration is replaced, startup verifies and completes it.
677
- await saveDeviceEnrollmentAnchor({ config: next, store });
787
+ await saveEnrollmentAnchorLocked({ config: next, store, now });
678
788
  await atomicJson(input.configPath, next, input.hostFence);
679
789
  return next;
680
790
  }
791
+ export function parseDeviceConfig(bytes) {
792
+ let value;
793
+ try {
794
+ value = JSON.parse(bytes);
795
+ }
796
+ catch {
797
+ throw new Error('connection_config_corrupt');
798
+ }
799
+ if (!validateDeviceConfigContract(value))
800
+ throw new Error('connection_config_invalid');
801
+ const config = value;
802
+ try {
803
+ assertInstallationId(config.installationId);
804
+ return { ...config, hqUrl: normalizeHqUrl(config.hqUrl), relayUrl: normalizeRelayUrl(config.relayUrl) };
805
+ }
806
+ catch {
807
+ throw new Error('connection_config_invalid');
808
+ }
809
+ }
681
810
  export async function loadDeviceConfig(path) {
682
- const config = JSON.parse(await readFile(path, 'utf8'));
683
- if (config.schema !== 'dharma.device-config/v1' || !config.deviceId || !config.organizationId || !config.hqUrl) {
684
- throw new Error('Device is not enrolled. Run dharma login.');
811
+ let bytes;
812
+ try {
813
+ bytes = await readFile(path, 'utf8');
814
+ }
815
+ catch (error) {
816
+ if (error.code === 'ENOENT')
817
+ throw error;
818
+ throw new Error('connection_config_unreadable');
819
+ }
820
+ return readDeviceConnectionPreference(path, parseDeviceConfig(bytes));
821
+ }
822
+ function connectionPreferenceBinding(config) {
823
+ const { schema, hqUrl, organizationId, installationId, deviceId, publicKeyEd25519, serverPublicKeyEd25519, relayUrl, enrolledAt } = config;
824
+ return sha256(canonicalize({ schema, hqUrl, organizationId, installationId: installationId ?? null,
825
+ deviceId, publicKeyEd25519, serverPublicKeyEd25519, relayUrl, enrolledAt }));
826
+ }
827
+ /** Separate local preference from trust snapshots so a delayed keyset write cannot overwrite opt-out. */
828
+ export async function readDeviceConnectionPreference(path, config) {
829
+ const binding = connectionPreferenceBinding(config);
830
+ let bytes;
831
+ try {
832
+ bytes = await readFile(`${path}.connection.json`, 'utf8');
833
+ }
834
+ catch (error) {
835
+ if (error.code === 'ENOENT')
836
+ return config;
837
+ throw new Error('connection_preference_unreadable');
685
838
  }
686
- assertInstallationId(config.installationId);
687
- return { ...config, hqUrl: normalizeHqUrl(config.hqUrl), relayUrl: normalizeRelayUrl(config.relayUrl) };
839
+ let value;
840
+ try {
841
+ value = JSON.parse(bytes);
842
+ }
843
+ catch {
844
+ throw new Error('connection_preference_corrupt');
845
+ }
846
+ if (!validateDeviceConnectionPreferenceContract(value))
847
+ throw new Error('connection_preference_invalid');
848
+ // A changed scope cannot inherit consent or resurrect an older inline opt-in.
849
+ if (value.binding !== binding)
850
+ return { ...config, connectionMode: 'manual' };
851
+ return { ...config, connectionMode: value.connectionMode };
852
+ }
853
+ export async function saveDeviceConnectionPreference(input) {
854
+ if (input.connectionMode !== 'manual' && input.connectionMode !== 'resume')
855
+ throw new Error('connection_preference_invalid');
856
+ const fence = input.hostScope === undefined ? undefined : new HostOperationFence(input.hostScope);
857
+ const binding = connectionPreferenceBinding(input.config);
858
+ const current = fence ? await fence.step(() => loadDeviceConfig(input.configPath)) : await loadDeviceConfig(input.configPath);
859
+ if (connectionPreferenceBinding(current) !== binding)
860
+ throw new Error('connection_state_changed');
861
+ const preference = { schema: 'dharma.device-connection-preference/v1',
862
+ binding, connectionMode: input.connectionMode };
863
+ await atomicJson(`${input.configPath}.connection.json`, preference, fence);
688
864
  }
689
865
  export class AgentFabricClient {
690
866
  config;
@@ -696,6 +872,9 @@ export class AgentFabricClient {
696
872
  #directTransport;
697
873
  #hostFence;
698
874
  #hostBinding;
875
+ #readOnly;
876
+ #isolatedSession;
877
+ #readSessionAdmissionUsed = false;
699
878
  #state;
700
879
  #serial = Promise.resolve();
701
880
  constructor(input) {
@@ -709,6 +888,8 @@ export class AgentFabricClient {
709
888
  this.#directTransport = Boolean(input.fetcher);
710
889
  this.#hostFence = input.hostFence;
711
890
  this.#hostBinding = this.#binding();
891
+ this.#readOnly = input.readOnly === true;
892
+ this.#isolatedSession = input.isolatedSession === true;
712
893
  }
713
894
  #binding() {
714
895
  const { schema, organizationId, deviceId, installationId, hqUrl, relayUrl, publicKeyEd25519, serverPublicKeyEd25519, enrolledAt, platform, setupClaimReference, setupClaimRepositoryFingerprint } = this.config;
@@ -729,22 +910,26 @@ export class AgentFabricClient {
729
910
  await this.#hostFence.assert();
730
911
  }
731
912
  static async open(input) {
732
- const { configPath, statePath, store: suppliedStore, fetcher, hostScope } = input;
913
+ const { configPath, statePath, store: suppliedStore, fetcher, hostScope, readOnly, isolatedSession } = input;
914
+ if (readOnly !== undefined && typeof readOnly !== 'boolean')
915
+ throw new Error('relay_read_only_option_invalid');
916
+ if (isolatedSession !== undefined && typeof isolatedSession !== 'boolean')
917
+ throw new Error('relay_isolated_session_option_invalid');
733
918
  const fence = hostScope === undefined ? undefined : new HostOperationFence(hostScope);
734
919
  const rawStore = fence ? await fence.step(async () => suppliedStore ?? await createSystemSecureStore())
735
920
  : suppliedStore ?? await createSystemSecureStore();
736
- const store = fence ? fence.store(rawStore) : rawStore;
737
- const config = await recoverEnrollmentWithFence({ configPath, store, hostFence: fence });
738
- const identity = fence ? await existingHostDeviceIdentity(config, store) : await loadOrCreateDeviceIdentity({
739
- hqUrl: config.hqUrl,
740
- organizationId: config.organizationId,
741
- installationId: config.installationId,
742
- store,
743
- });
921
+ const safeStore = readOnly ? { backend: rawStore.backend,
922
+ get: account => rawStore.get(account),
923
+ put: async () => { throw new Error('relay_read_only_secure_store_write_denied'); },
924
+ delete: async () => { throw new Error('relay_read_only_secure_store_write_denied'); } } : rawStore;
925
+ const store = fence ? fence.store(safeStore) : safeStore;
926
+ const config = readOnly || isolatedSession ? (fence ? await fence.step(() => loadDeviceConfig(configPath)) : await loadDeviceConfig(configPath))
927
+ : await recoverEnrollmentWithFence({ configPath, store, hostFence: fence });
928
+ const identity = await existingHostDeviceIdentity(config, store);
744
929
  if (identity.publicKeyEd25519 !== config.publicKeyEd25519)
745
930
  throw new Error('Enrolled device identity does not match the secure store.');
746
931
  try {
747
- await loadDeviceEnrollmentAnchor({ config, store });
932
+ await loadDeviceEnrollmentAnchor({ config, store, readOnly: readOnly || isolatedSession });
748
933
  }
749
934
  catch (error) {
750
935
  if (!(error instanceof Error) || !error.message.includes('not anchored in secure storage'))
@@ -755,28 +940,32 @@ export class AgentFabricClient {
755
940
  schema: 'dharma.protocol-state/v1', sessionId: null, nextSequence: 1, pending: null,
756
941
  recoveredTaskCompletions: [],
757
942
  };
758
- try {
759
- const bytes = fence ? await fence.step(() => readFile(statePath, 'utf8')) : await readFile(statePath, 'utf8');
760
- const parsed = JSON.parse(bytes);
761
- assertProtocolState(parsed);
762
- state = parsed;
763
- }
764
- catch (error) {
765
- if (error.code !== 'ENOENT') {
766
- if (fence)
767
- await fence.assert();
768
- throw new Error('Relay protocol state is invalid; preserve the file for recovery and re-enroll if necessary.', { cause: error });
943
+ if (!readOnly && !isolatedSession)
944
+ try {
945
+ const bytes = fence ? await fence.step(() => readFile(statePath, 'utf8')) : await readFile(statePath, 'utf8');
946
+ const parsed = JSON.parse(bytes);
947
+ assertProtocolState(parsed);
948
+ state = parsed;
949
+ }
950
+ catch (error) {
951
+ if (error.code !== 'ENOENT') {
952
+ if (fence)
953
+ await fence.assert();
954
+ throw new Error('Relay protocol state is invalid; preserve the file for recovery and re-enroll if necessary.', { cause: error });
955
+ }
769
956
  }
770
- }
771
957
  state.recoveredTaskCompletions ??= [];
772
958
  await fence?.assert();
773
959
  return new AgentFabricClient({
774
960
  config, privateJwk: identity.privateJwk, configPath,
775
- statePath, state, store, fetcher, hostFence: fence,
961
+ statePath, state, store, fetcher, hostFence: fence, readOnly, isolatedSession,
776
962
  });
777
963
  }
778
964
  async openSession(relayVersion = '0.1.0') {
779
965
  await this.#assertHostScope();
966
+ if (this.#readOnly && (this.#state.sessionId || this.#readSessionAdmissionUsed)) {
967
+ throw new Error('relay_read_only_session_already_started');
968
+ }
780
969
  if (this.#state.pending && isExplicitlyRebuiltPath(this.#state.pending.pathname)) {
781
970
  // Content-bearing requests require refreshed consent. Repository connect
782
971
  // requests depend on current workspace registration. Both are rebuilt by
@@ -838,6 +1027,8 @@ export class AgentFabricClient {
838
1027
  acknowledgeRecoveredTaskCompletion(taskId, receiptHash) {
839
1028
  const operation = this.#serial.then(async () => {
840
1029
  await this.#assertHostScope();
1030
+ if (this.#readOnly)
1031
+ throw new Error('relay_read_only_mutation_denied');
841
1032
  const current = this.#state.recoveredTaskCompletions || [];
842
1033
  const matching = current.find((item) => item.taskId === taskId);
843
1034
  if (!matching)
@@ -883,6 +1074,16 @@ export class AgentFabricClient {
883
1074
  await this.#assertHostScope();
884
1075
  if (!this.#state.sessionId)
885
1076
  throw new Error('Relay session is not open.');
1077
+ if (this.#readOnly) {
1078
+ if (this.#state.pending)
1079
+ throw new Error('relay_read_only_pending_request');
1080
+ if (method !== 'GET') {
1081
+ if (route !== '/agent-fabric/sessions' || this.#readSessionAdmissionUsed || this.#state.nextSequence !== 1) {
1082
+ throw new Error('relay_read_only_mutation_denied');
1083
+ }
1084
+ this.#readSessionAdmissionUsed = true;
1085
+ }
1086
+ }
886
1087
  const pathname = `/api/v1/orgs/${encodeURIComponent(this.config.organizationId)}${route}`;
887
1088
  const serialized = method === 'GET' ? '' : canonicalize(body);
888
1089
  if (this.#state.pending && isContentBearingPath(this.#state.pending.pathname)) {
@@ -1190,6 +1391,10 @@ export class AgentFabricClient {
1190
1391
  });
1191
1392
  }
1192
1393
  async #persist() {
1394
+ if (this.#readOnly || this.#isolatedSession) {
1395
+ await this.#assertHostScope();
1396
+ return;
1397
+ }
1193
1398
  await this.#assertHostScope();
1194
1399
  // Authorized content and state-dependent repository connects are rebuilt
1195
1400
  // from their governed source. Do not retain them as an automatic replay