@tangle-network/agent-interface 1.9.0 → 2.1.0

package/README.md

@@ -27,6 +27,17 @@ The portable contract owns only inline profile and harness selection, shared or
 
 `shared` means ordinary same-computer file visibility. It is not automatic merge behavior or tenant isolation. `isolated` asks the provider for a private writable view and explicit inspect or commit behavior. Providers must reject unsatisfied machine requirements rather than silently replacing or migrating a live environment.
 
+`WorkspaceRequest.cwd` is an explicitly based path reference.
+Use `base: "repository"` for a portable repository-relative POSIX path.
+Use `base: "host"` for a provider-owned native host path.
+The shared schema rejects unsafe repository paths and control characters in both path forms.
+It canonicalizes redundant `.` segments and separators for repository paths.
+Use `.` for the repository root.
+Providers advertise accepted path bases under `AgentEnvironmentCapabilities.workspace.cwdBases`.
+To migrate a string cwd, wrap it in the base that owns its path.
+Use the repository base for Tangle and other portable workspace providers.
+Use the host base for CLI Bridge native process paths.
+
 The public `AgentInstanceRecord` contains a credential-free profile identity, not the full profile or provider request. Existing session APIs can implement this contract without a new service: one instance maps to one managed session, compatible sessions may reuse a backend process, and stop maps to idempotent session deletion or process release.
 
 ## Durable runs, interactions, and context

package/dist/agent-candidate-execution-plan-schema.d.ts

@@ -84,6 +84,7 @@ export declare const agentCandidateProfilePlanMaterialSchema: z.ZodObject<{
         relPath: z.ZodString;
         mode: z.ZodNumber;
         contentSha256: z.ZodType<`sha256:${string}`, unknown, z.core.$ZodTypeInternals<`sha256:${string}`, unknown>>;
+        root: z.ZodOptional<z.ZodLiteral<"agent">>;
     }, z.core.$strict>>;
     env: z.ZodRecord<z.ZodString, z.ZodObject<{
         kind: z.ZodLiteral<"public">;
@@ -536,6 +537,7 @@ export declare const agentCandidateProfilePlanEvidenceSchema: z.ZodObject<{
             relPath: string;
             mode: number;
             contentSha256: `sha256:${string}`;
+            root?: "agent" | undefined;
         }[];
         env: Record<string, {
             kind: "public";
@@ -564,6 +566,7 @@ export declare const agentCandidateProfilePlanEvidenceSchema: z.ZodObject<{
             relPath: string;
             mode: number;
             contentSha256: `sha256:${string}`;
+            root?: "agent" | undefined;
         }[];
         env: Record<string, {
             kind: "public";
@@ -617,6 +620,7 @@ export declare const agentCandidateProfileActivationSchema: z.ZodObject<{
                 relPath: string;
                 mode: number;
                 contentSha256: `sha256:${string}`;
+                root?: "agent" | undefined;
             }[];
             env: Record<string, {
                 kind: "public";
@@ -668,6 +672,7 @@ export declare const agentCandidateProfileActivationSchema: z.ZodObject<{
                 relPath: string;
                 mode: number;
                 contentSha256: `sha256:${string}`;
+                root?: "agent" | undefined;
             }[];
             env: Record<string, {
                 kind: "public";

package/dist/agent-candidate-execution-plan-schema.js

@@ -15,6 +15,9 @@ function isCanonicalAbsolutePath(value) {
 function pathsOverlap(left, right) {
     return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
 }
+function profilePlanFileIdentity(file) {
+    return `${file.root ?? "workspace"}\u0000${file.relPath}`;
+}
 function isExactPublicGatewayDomain(value) {
     if (value.length > 253 ||
         value !== value.toLowerCase() ||
@@ -113,6 +116,7 @@ export const agentCandidateProfilePlanMaterialSchema = z
             .refine((value) => isSafeRelativePath(value, false), "profile-plan file must use a canonical relative path"),
         mode: z.number().int().min(0).max(0o777),
         contentSha256: sha256DigestSchema,
+        root: z.literal("agent").optional(),
     })
         .strict()),
     env: environmentConfigSchema,
@@ -130,14 +134,14 @@ export const agentCandidateProfilePlanMaterialSchema = z
 })
     .strict()
     .superRefine((material, ctx) => {
-    addDuplicateIssues(material.files.map((file) => file.relPath), ["files"], ctx);
+    const fileIdentities = material.files.map(profilePlanFileIdentity);
+    addDuplicateIssues(fileIdentities, ["files"], ctx);
     for (let index = 1; index < material.files.length; index++) {
-        if ((material.files[index - 1]?.relPath ?? "") >=
-            (material.files[index]?.relPath ?? "")) {
+        if ((fileIdentities[index - 1] ?? "") >= (fileIdentities[index] ?? "")) {
             ctx.addIssue({
                 code: "custom",
                 path: ["files", index, "relPath"],
-                message: "profile-plan files must be lexicographically sorted",
+                message: "profile-plan files must be lexicographically sorted by root and path",
             });
         }
     }

package/dist/agent-candidate-promotion-schema.d.ts

@@ -2076,6 +2076,7 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
                         relPath: string;
                         mode: number;
                         contentSha256: `sha256:${string}`;
+                        root?: "agent" | undefined;
                     }[];
                     env: Record<string, {
                         kind: "public";
@@ -2127,6 +2128,7 @@ export declare const candidateExecutionEvidenceSchema: z.ZodObject<{
                         relPath: string;
                         mode: number;
                         contentSha256: `sha256:${string}`;
+                        root?: "agent" | undefined;
                     }[];
                     env: Record<string, {
                         kind: "public";
@@ -5664,6 +5666,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 relPath: string;
                                 mode: number;
                                 contentSha256: `sha256:${string}`;
+                                root?: "agent" | undefined;
                             }[];
                             env: Record<string, {
                                 kind: "public";
@@ -5715,6 +5718,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 relPath: string;
                                 mode: number;
                                 contentSha256: `sha256:${string}`;
+                                root?: "agent" | undefined;
                             }[];
                             env: Record<string, {
                                 kind: "public";
@@ -7059,6 +7063,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 relPath: string;
                                 mode: number;
                                 contentSha256: `sha256:${string}`;
+                                root?: "agent" | undefined;
                             }[];
                             env: Record<string, {
                                 kind: "public";
@@ -7110,6 +7115,7 @@ export declare const agentImprovementMeasuredComparisonSchema: z.ZodObject<{
                                 relPath: string;
                                 mode: number;
                                 contentSha256: `sha256:${string}`;
+                                root?: "agent" | undefined;
                             }[];
                             env: Record<string, {
                                 kind: "public";
@@ -10679,6 +10685,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     relPath: string;
                                     mode: number;
                                     contentSha256: `sha256:${string}`;
+                                    root?: "agent" | undefined;
                                 }[];
                                 env: Record<string, {
                                     kind: "public";
@@ -10730,6 +10737,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     relPath: string;
                                     mode: number;
                                     contentSha256: `sha256:${string}`;
+                                    root?: "agent" | undefined;
                                 }[];
                                 env: Record<string, {
                                     kind: "public";
@@ -12074,6 +12082,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     relPath: string;
                                     mode: number;
                                     contentSha256: `sha256:${string}`;
+                                    root?: "agent" | undefined;
                                 }[];
                                 env: Record<string, {
                                     kind: "public";
@@ -12125,6 +12134,7 @@ export declare const agentImprovementProposalSchema: z.ZodObject<{
                                     relPath: string;
                                     mode: number;
                                     contentSha256: `sha256:${string}`;
+                                    root?: "agent" | undefined;
                                 }[];
                                 env: Record<string, {
                                     kind: "public";

package/dist/agent-candidate-receipt-schema.d.ts

@@ -201,6 +201,7 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
                     relPath: string;
                     mode: number;
                     contentSha256: `sha256:${string}`;
+                    root?: "agent" | undefined;
                 }[];
                 env: Record<string, {
                     kind: "public";
@@ -252,6 +253,7 @@ export declare const agentCandidateMaterializationReceiptSchema: z.ZodObject<{
                     relPath: string;
                     mode: number;
                     contentSha256: `sha256:${string}`;
+                    root?: "agent" | undefined;
                 }[];
                 env: Record<string, {
                     kind: "public";

package/dist/agent-candidate-schema-common.d.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import type { Sha256Digest } from "./agent-candidate.js";
+export type RelativePathSafetyIssue = "empty" | "control-character" | "malformed-unicode" | "absolute" | "backslash" | "parent-traversal";
+export type PathSafetyIssue = "control-character" | "malformed-unicode";
 export declare const sha256DigestSchema: z.ZodType<Sha256Digest>;
 export declare const gitObjectSchema: z.ZodString;
 export declare const environmentNameSchema: z.ZodString;
@@ -15,6 +17,10 @@ export declare function omitTopLevelDigest<T extends {
     digest: Sha256Digest;
 }>(value: T): Omit<T, "digest">;
 export declare function isWellFormedUnicode(value: string): boolean;
+/** Return shared boundary violations for path strings. */
+export declare function pathSafetyIssues(value: string): PathSafetyIssue[];
+/** Return shared boundary violations for paths that must stay inside a workspace. */
+export declare function relativePathSafetyIssues(value: string): RelativePathSafetyIssue[];
 export declare function isSafeRelativePath(value: string, allowDot: boolean): boolean;
 export declare function isSafeExecutable(value: string): boolean;
 export declare function isObviouslyPrivateHostname(rawHostname: string): boolean;

package/dist/agent-candidate-schema-common.js

@@ -1,4 +1,4 @@
-import { sha256 } from "@noble/hashes/sha256";
+import { sha256 } from "@noble/hashes/sha2.js";
 import { z } from "zod";
 const sha256Pattern = /^sha256:[a-f0-9]{64}$/;
 const gitObjectPattern = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
@@ -86,20 +86,35 @@ export function isWellFormedUnicode(value) {
     }
     return true;
 }
+/** Return shared boundary violations for path strings. */
+export function pathSafetyIssues(value) {
+    const issues = [];
+    if (controlCharacterPattern.test(value))
+        issues.push("control-character");
+    if (!isWellFormedUnicode(value))
+        issues.push("malformed-unicode");
+    return issues;
+}
+/** Return shared boundary violations for paths that must stay inside a workspace. */
+export function relativePathSafetyIssues(value) {
+    const issues = [...pathSafetyIssues(value)];
+    if (value.length === 0)
+        issues.push("empty");
+    if (value.startsWith("/") || /^[A-Za-z]:/.test(value))
+        issues.push("absolute");
+    if (value.includes("\\"))
+        issues.push("backslash");
+    if (value.split("/").includes(".."))
+        issues.push("parent-traversal");
+    return issues;
+}
 export function isSafeRelativePath(value, allowDot) {
-    if (value.length === 0 ||
-        controlCharacterPattern.test(value) ||
-        !isWellFormedUnicode(value) ||
-        value.startsWith("/") ||
-        value.startsWith("\\") ||
-        value.includes("\\") ||
-        /^[A-Za-z]:/.test(value)) {
+    if (relativePathSafetyIssues(value).length > 0)
         return false;
-    }
     if (value === ".")
         return allowDot;
     const parts = value.split("/");
-    return (parts.every((part) => part.length > 0 && part !== "." && part !== "..") &&
+    return (parts.every((part) => part.length > 0 && part !== ".") &&
         !parts.some((part) => reservedWorkspaceRoots.has(part)));
 }
 export function isSafeExecutable(value) {

package/dist/agent-candidate.d.ts

@@ -341,6 +341,8 @@ export interface AgentCandidateProfilePlanMaterial {
         relPath: string;
         mode: number;
         contentSha256: Sha256Digest;
+        /** Omit for a workspace-root file; agent-root files must name this root. */
+        root?: "agent";
     }>;
     env: Record<string, AgentCandidateConfigValue>;
     flags: AgentCandidateConfigValue[];

package/dist/environment-command-turn.js

@@ -119,7 +119,10 @@ export function execOnlyEnvironmentCapabilities(workspace) {
             turnIdempotency: false,
         },
         sessions: { continue: false, list: false, messages: false },
-        workspace: { ...workspace },
+        workspace: {
+            cwdBases: { repository: false, host: false },
+            ...workspace,
+        },
         branching: { checkpoint: false, fork: false },
         placement: true,
         usage: false,

package/dist/environment-provider.d.ts

@@ -5,3 +5,4 @@ export * from "./environment-observation.js";
 export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";
 export * from "./environment-command-turn.js";
+export * from "./workspace-cwd.js";

package/dist/environment-provider.js

@@ -5,3 +5,4 @@ export * from "./environment-observation.js";
 export * from "./environment-terminal.js";
 export * from "./environment-runtime.js";
 export * from "./environment-command-turn.js";
+export * from "./workspace-cwd.js";

package/dist/environment-requests.d.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+import type { WorkspaceCwd } from "./workspace-cwd.js";
 import type { AgentProfile } from "./agent-profile.js";
 /** Portable profile reference: inline profile or provider catalog id. */
 export type AgentProfileRef = AgentProfile | string;
@@ -12,11 +14,29 @@ export interface WorkspaceRequest {
     repoUrl?: string;
     /** Git ref for {@link repoUrl}. */
     gitRef?: string;
-    /** Initial working directory inside the environment. */
-    cwd?: string;
+    /**
+     * Explicitly based working directory inside the environment or on the host.
+     * Repository paths use `base: "repository"`; host paths use `base: "host"`.
+     */
+    cwd?: WorkspaceCwd;
     /** Opaque provider-native workspace fields. */
     providerOptions?: Record<string, unknown>;
 }
+/** Runtime contract for the portable workspace request carried by providers. */
+export declare const WorkspaceRequestSchema: z.ZodObject<{
+    environment: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    repoUrl: z.ZodOptional<z.ZodString>;
+    gitRef: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        base: z.ZodLiteral<"repository">;
+        path: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    }, z.core.$strict>, z.ZodObject<{
+        base: z.ZodLiteral<"host">;
+        path: z.ZodString;
+    }, z.core.$strict>], "base">>;
+    providerOptions: z.ZodOptional<z.ZodCustom<Record<string, unknown>, Record<string, unknown>>>;
+}, z.core.$strict>;
 export interface ResourceRequest {
     cpu?: number;
     memoryMb?: number;

package/dist/environment-requests.js

@@ -1 +1,29 @@
-export {};
+import { z } from "zod";
+import { boundedIdentifierSchema, boundedJsonRecordSchema, boundedStringSchema, } from "./contract-limits.js";
+import { workspaceCwdSchema } from "./workspace-cwd.js";
+/** Runtime contract for the portable workspace request carried by providers. */
+export const WorkspaceRequestSchema = z
+    .strictObject({
+    environment: boundedIdentifierSchema.optional(),
+    image: boundedStringSchema.min(1).optional(),
+    repoUrl: boundedStringSchema.min(1).optional(),
+    gitRef: boundedIdentifierSchema.optional(),
+    cwd: workspaceCwdSchema.optional(),
+    providerOptions: boundedJsonRecordSchema.optional(),
+})
+    .superRefine((workspace, refinement) => {
+    if (workspace.environment !== undefined && workspace.image !== undefined) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["image"],
+            message: "workspace cannot specify both environment and image",
+        });
+    }
+    if (workspace.gitRef !== undefined && workspace.repoUrl === undefined) {
+        refinement.addIssue({
+            code: "custom",
+            path: ["gitRef"],
+            message: "workspace gitRef requires repoUrl",
+        });
+    }
+});

package/dist/environment-runtime.d.ts

@@ -818,6 +818,11 @@ export interface AgentEnvironmentCapabilities {
         git: boolean;
         upload: boolean;
         download: boolean;
+        /** Path bases accepted by the provider's workspace create contract. */
+        cwdBases?: {
+            repository: boolean;
+            host: boolean;
+        };
     };
     branching: {
         checkpoint: boolean;
@@ -949,6 +954,10 @@ export declare const AgentEnvironmentCapabilitiesSchema: z.ZodObject<{
         git: z.ZodBoolean;
         upload: z.ZodBoolean;
         download: z.ZodBoolean;
+        cwdBases: z.ZodOptional<z.ZodObject<{
+            repository: z.ZodBoolean;
+            host: z.ZodBoolean;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     branching: z.ZodObject<{
         checkpoint: z.ZodBoolean;

package/dist/environment-runtime.js

@@ -205,6 +205,12 @@ export const AgentEnvironmentCapabilitiesSchema = z
         git: z.boolean(),
         upload: z.boolean(),
         download: z.boolean(),
+        cwdBases: z
+            .strictObject({
+            repository: z.boolean(),
+            host: z.boolean(),
+        })
+            .optional(),
     }),
     branching: z.strictObject({
         checkpoint: z.boolean(),

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
 export type * from "./environment-provider.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, canonicalWorkspaceCwd, MAX_WORKSPACE_CWD_LENGTH, workspaceCwdSchema, workspaceCwdPathForBase, WorkspaceRequestSchema, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export * from "./provider-config.js";
 export * from "./host-services.js";
 export * from "./mcp.js";
 export * from "./provider-adapter.js";
-export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
+export { AgentEnvironmentCapabilitiesSchema, AgentNativeContextContinuationAdmissionSchema, AgentNativeContextContinuationResultSchema, AgentTurnInputSchema, AgentTurnResultSchema, agentEnvironmentCreateInputDigest, agentNativeContextContinuationAdmissionMatchesRequest, agentNativeContextContinuationResultMatchesRequest, AccountUsageSchema, AgentEnvironmentObservationSchema, AgentEnvironmentStatusSchema, ComputeBillingSchema, EnvironmentLifecycleSchema, ModelUsageSchema, ObservationProvenanceSchema, ObservationStateSchema, PlacementDescriptorSchema, ProviderIdentitySchema, ResourceProfileSchema, ResourceUseSampleSchema, SafeEndpointSchema, agentEnvironmentObservationIdentityMatches, assertObservationCredentialFree, observationContainsCredential, observationOf, AgentInteractiveSessionAttachSchema, AgentInteractiveSessionControlClaimAcknowledgementSchema, AgentInteractiveSessionControlClaimRequestSchema, AgentInteractiveSessionControlClaimSchema, AgentInteractiveSessionPromptAcknowledgementSchema, AgentInteractiveSessionPromptCommandSchema, AgentInteractiveSessionRefSchema, AgentInteractiveSessionStartSchema, AgentInteractiveSessionStopAcknowledgementSchema, AgentInteractiveSessionStopCommandSchema, AgentInteractiveSessionStatusSchema, agentInteractiveSessionControlClaimAcknowledgementMatchesRequest, agentInteractiveSessionControlClaimRequestDigest, agentInteractiveSessionControlClaimMatchesRef, agentInteractiveSessionControlClaimIsNewer, agentInteractiveSessionPromptAcknowledgementMatchesCommand, agentInteractiveSessionPromptRequestDigest, agentInteractiveSessionStopAcknowledgementMatchesCommand, agentInteractiveSessionStopRequestDigest, agentInteractiveSessionRequestDigest, agentInteractiveSessionRefMatchesStart, agentInteractiveSessionRunRef, agentInteractiveSessionStatusMatchesRef, exactAgentInteractiveSessionStart, AgentEnvironmentCreationSchema, createAgentEnvironmentWithIdempotency, replayedAgentEnvironmentView, canonicalWorkspaceCwd, MAX_WORKSPACE_CWD_LENGTH, workspaceCwdSchema, workspaceCwdPathForBase, WorkspaceRequestSchema, TerminalAttachRequestSchema, TerminalAttachResultSchema, TerminalDetachAckSchema, TerminalInputSchema, TerminalOutputEventSchema, TerminalReplayWindowSchema, TerminalResizeSchema, TerminalSessionRefSchema, terminalAttachResultMatchesRequest, terminalSessionUsable, } from "./environment-provider.js";
 export * from "./plan.js";
 export * from "./runtime-control.js";
 export * from "./portable-context.js";

package/dist/workspace-cwd.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/** Maximum number of UTF-16 code units accepted in a workspace cwd path. */
+export declare const MAX_WORKSPACE_CWD_LENGTH = 4096;
+export type WorkspaceCwdBase = "repository" | "host";
+export type WorkspaceCwd = {
+    base: "repository";
+    path: string;
+} | {
+    base: "host";
+    path: string;
+};
+/**
+ * Validate and canonicalize an explicitly based workspace path.
+ *
+ * Repository paths never start with `./`, contain duplicate separators, or
+ * leave the workspace root. Host paths preserve native separators and values.
+ */
+export declare const workspaceCwdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    base: z.ZodLiteral<"repository">;
+    path: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+}, z.core.$strict>, z.ZodObject<{
+    base: z.ZodLiteral<"host">;
+    path: z.ZodString;
+}, z.core.$strict>], "base">;
+/** Validate and return the canonical form of a workspace cwd. */
+export declare function canonicalWorkspaceCwd(value: WorkspaceCwd): WorkspaceCwd;
+/** Return a provider path only when its explicit base is supported. */
+export declare function workspaceCwdPathForBase(value: WorkspaceCwd | undefined, base: WorkspaceCwdBase, providerLabel: string): string | undefined;

package/dist/workspace-cwd.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { pathSafetyIssues, relativePathSafetyIssues, } from "./agent-candidate-schema-common.js";
+/** Maximum number of UTF-16 code units accepted in a workspace cwd path. */
+export const MAX_WORKSPACE_CWD_LENGTH = 4_096;
+const workspaceCwdIssueMessages = {
+    absolute: "Workspace cwd must be relative",
+    backslash: "Workspace cwd must use POSIX separators",
+    "control-character": "Workspace cwd cannot contain control characters",
+    "parent-traversal": "Workspace cwd cannot leave the workspace root",
+    "malformed-unicode": "Workspace cwd must contain well-formed Unicode",
+};
+function normalizeWorkspaceCwd(value) {
+    const segments = value
+        .split("/")
+        .filter((segment) => segment.length > 0 && segment !== ".");
+    return segments.join("/") || ".";
+}
+const pathIssueMessages = {
+    "control-character": "Workspace cwd cannot contain control characters",
+    "malformed-unicode": "Workspace cwd must contain well-formed Unicode",
+};
+const repositoryWorkspaceCwdPathSchema = z
+    .string()
+    .min(1)
+    .max(MAX_WORKSPACE_CWD_LENGTH)
+    .superRefine((value, refinement) => {
+    for (const issue of relativePathSafetyIssues(value)) {
+        const message = workspaceCwdIssueMessages[issue];
+        if (message === undefined)
+            continue;
+        refinement.addIssue({
+            code: "custom",
+            message,
+        });
+    }
+})
+    .transform(normalizeWorkspaceCwd);
+const hostWorkspaceCwdPathSchema = z
+    .string()
+    .max(MAX_WORKSPACE_CWD_LENGTH)
+    .superRefine((value, refinement) => {
+    for (const issue of pathSafetyIssues(value)) {
+        refinement.addIssue({
+            code: "custom",
+            message: pathIssueMessages[issue],
+        });
+    }
+});
+/**
+ * Validate and canonicalize an explicitly based workspace path.
+ *
+ * Repository paths never start with `./`, contain duplicate separators, or
+ * leave the workspace root. Host paths preserve native separators and values.
+ */
+export const workspaceCwdSchema = z.discriminatedUnion("base", [
+    z.strictObject({
+        base: z.literal("repository"),
+        path: repositoryWorkspaceCwdPathSchema,
+    }),
+    z.strictObject({
+        base: z.literal("host"),
+        path: hostWorkspaceCwdPathSchema,
+    }),
+]);
+/** Validate and return the canonical form of a workspace cwd. */
+export function canonicalWorkspaceCwd(value) {
+    return workspaceCwdSchema.parse(value);
+}
+/** Return a provider path only when its explicit base is supported. */
+export function workspaceCwdPathForBase(value, base, providerLabel) {
+    if (value === undefined)
+        return undefined;
+    if (value.base !== base) {
+        throw new Error(`${providerLabel} supports workspace cwd base "${base}", not "${value.base}"`);
+    }
+    return value.path;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-interface",
-  "version": "1.9.0",
+  "version": "2.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -83,9 +83,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@noble/hashes": "1.8.0",
+    "@noble/hashes": "2.4.0",
     "spdx-expression-parse": "5.0.0",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   },
   "devDependencies": {
     "@types/node": "26.4.0",