@tangle-network/agent-interface 5.4.0 → 5.5.0

package/dist/environment-runtime.d.ts

@@ -1816,6 +1816,10 @@ export declare function createAgentEnvironmentWithIdempotency<T extends object>(
 /** Reconstruct an existing environment; never allocates a replacement. */
 export interface AgentEnvironmentGetOptions {
     signal?: AbortSignal;
+    /** Side-effect-free custody discovery on a qualified provider. Never resumes, installs or
+     * rebinds; the returned snapshot cannot execute. Unsupported providers must reject this mode.
+     * Expired installed custody may be returned as metadata, never as dispatch authority. */
+    readOnly?: true;
     /** Explicit custody attachment through the existing egress lifecycle. Omission reads current
      * custody; [] revokes custom bindings. A get never allocates a replacement environment. */
     proxySecrets?: readonly ProxySecretBinding[];
@@ -1827,7 +1831,7 @@ export interface AgentEnvironmentGetOptions {
      * Authorize the first turn of an accepted portable transfer. The provider looks up the exact
      * durable operation and returns its dispatch-capable environment with contextTransferReceipt.
      * A missing, uncertain, conflicting or unsupported receipt refuses attachment. The request's
-     * exact profile, workspace and resources remain authoritative; ordinary get remains read-only.
+     * exact profile, workspace and resources remain authoritative; use readOnly for discovery without reconnect side effects.
      */
     contextTransfer?: ContextTransferRequest;
 }
@@ -2323,6 +2327,11 @@ export declare const AgentEnvironmentGetOptionsSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/** Explicit opt-in for providers implementing side-effect-free, non-executable discovery. */
+export declare const AgentEnvironmentReadOnlyGetOptionsSchema: z.ZodObject<{
+    signal: z.ZodOptional<z.ZodCustom<AbortSignal, AbortSignal>>;
+    readOnly: z.ZodLiteral<true>;
+}, z.core.$strict>;
 export interface AgentEnvironmentProvider {
     readonly name: string;
     readonly exactProcess?: AgentExactProcessProvider;

package/dist/environment-runtime.js

@@ -526,8 +526,11 @@ export async function createAgentEnvironmentWithIdempotency(records, input, crea
         throw error;
     }
 }
+// Keep the existing parser strict: published providers that import it must not silently
+// accept readOnly and then perform their ordinary reconnect side effects.
+const environmentGetSignalSchema = z.custom().optional();
 export const AgentEnvironmentGetOptionsSchema = z.strictObject({
-    signal: z.custom().optional(),
+    signal: environmentGetSignalSchema,
     proxySecrets: ProxySecretsSchema.optional(),
     proxySecretParents: ProxySecretParentsSchema.optional(),
     ...ProxySecretUpdateControlsSchema.shape,
@@ -545,3 +548,8 @@ export const AgentEnvironmentGetOptionsSchema = z.strictObject({
         ctx.addIssue({ code: "custom", path: ["proxySecrets"], message: "proxy update controls require an explicit proxySecrets selection" });
     }
 });
+/** Explicit opt-in for providers implementing side-effect-free, non-executable discovery. */
+export const AgentEnvironmentReadOnlyGetOptionsSchema = z.strictObject({
+    signal: environmentGetSignalSchema,
+    readOnly: z.literal(true),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",