Commit 0eba548282b96ee420ad0b1a3f5d9d4487376b90 | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-06-20 17:35:07-07:00
committer	GitHub <noreply@github.com> 2026-06-20 17:35:07-07:00
log	0eba548282b96ee420ad0b1a3f5d9d4487376b90
tree	d831a177719d88b2ce1fd2c161b870ad90f7199c
parent	68c0dd3b7095cae054a9db5e48157e89f65c0664
signature	Signed by PGP key B5690EEEBB952194

[codex] Model asset access failures with distinct errors (#3448)

Co-authored-by: codex <codex@users.noreply.github.com>

4 files changed, 200 insertions(+), 79 deletions(-)

apps
- server
  - src
    assets
    AssetAccess.test.ts
    AssetAccess.ts
    ws.ts
packages
- contracts
  - src
    assets.ts

apps/server/src/assets/AssetAccess.test.ts+3-2

...	@@ -88,7 +88,7 @@ describe("AssetAccess", () => {	...	@@ -88,7 +88,7 @@ describe("AssetAccess", () => {
88	}).pipe(Effect.flip);	88	}).pipe(Effect.flip);
89	expect(error.message).toBe("Workspace file path must be relative to the project root.");	89	expect(error.message).toBe("Workspace file path must be relative to the project root.");
90	expect(error).toMatchObject({	90	expect(error).toMatchObject({
91	operation: "validate-workspace-path",	91	_tag: "AssetWorkspacePathValidationError",
92	resource: {	92	resource: {
93	_tag: "workspace-file",	93	_tag: "workspace-file",
94	threadId: "thread-1",	94	threadId: "thread-1",
...	@@ -130,7 +130,7 @@ describe("AssetAccess", () => {	...	@@ -130,7 +130,7 @@ describe("AssetAccess", () => {
130		130
131	expect(error.message).toBe("Failed to inspect the workspace asset.");	131	expect(error.message).toBe("Failed to inspect the workspace asset.");
132	expect(error).toMatchObject({	132	expect(error).toMatchObject({
133	operation: "inspect-workspace-asset",	133	_tag: "AssetWorkspaceAssetInspectionError",
134	resource: {	134	resource: {
135	_tag: "workspace-file",	135	_tag: "workspace-file",
136	threadId: "thread-1",	136	threadId: "thread-1",
...	@@ -268,6 +268,7 @@ describe("AssetAccess", () => {	...	@@ -268,6 +268,7 @@ describe("AssetAccess", () => {
268	);	268	);
269		269
270	expect(error.message).toBe("Failed to resolve project favicon.");	270	expect(error.message).toBe("Failed to resolve project favicon.");
		271	expect(error._tag).toBe("AssetProjectFaviconResolutionError");
271	expect(error.cause).toBe(resolutionCause);	272	expect(error.cause).toBe(resolutionCause);
272	}).pipe(Effect.provide(testLayer)),	273	}).pipe(Effect.provide(testLayer)),
273	);	274	);

apps/server/src/assets/AssetAccess.ts+28-43

 @@ -1,5 +1,18 @@
 import type { AssetResource } from "@t3tools/contracts";
-import { AssetAccessError } from "@t3tools/contracts";
+import {
+  AssetAttachmentNotFoundError,
+  AssetPreviewTypeValidationError,
+  AssetProjectFaviconInspectionError,
+  AssetProjectFaviconNotFoundError,
+  AssetProjectFaviconResolutionError,
+  AssetSigningKeyLoadError,
+  AssetWorkspaceAssetInspectionError,
+  AssetWorkspaceAssetNotFoundError,
+  AssetWorkspaceContextNotFoundError,
+  AssetWorkspacePathValidationError,
+  AssetWorkspaceResolutionError,
+  AssetWorkspaceRootNormalizationError,
+} from "@t3tools/contracts";
 import {
   isWorkspaceImagePreviewPath,
   isWorkspacePreviewEntryPath,
 @@ -165,19 +178,15 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
   switch (input.resource._tag) {
     case "workspace-file": {
       if (!input.workspaceRoot) {
-        return yield* new AssetAccessError({
+        return yield* new AssetWorkspaceContextNotFoundError({
-          operation: "resolve-workspace-context",
           resource: input.resource,
-          message: "Workspace context was not found.",
         });
       }
       const workspaceRoot = yield* workspacePaths.normalizeWorkspaceRoot(input.workspaceRoot).pipe(
         Effect.mapError(
           (cause) =>
-            new AssetAccessError({
+            new AssetWorkspaceRootNormalizationError({
-              operation: "normalize-workspace-root",
               resource: input.resource,
-              message: "Failed to normalize the workspace root.",
               cause,
             }),
         ),
 @@ -190,19 +199,15 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         .pipe(
           Effect.mapError(
             (cause) =>
-              new AssetAccessError({
+              new AssetWorkspacePathValidationError({
-                operation: "validate-workspace-path",
                 resource: input.resource,
-                message: "Workspace file path must be relative to the project root.",
                 cause,
               }),
           ),
         );
       if (!isWorkspacePreviewEntryPath(resolved.relativePath)) {
-        return yield* new AssetAccessError({
+        return yield* new AssetPreviewTypeValidationError({
-          operation: "validate-preview-type",
           resource: input.resource,
-          message: "Only browser documents and images can be previewed.",
         });
       }
       const canonicalFile = yield* resolveCanonicalWorkspaceFile({
 @@ -211,28 +216,22 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
       }).pipe(
         Effect.mapError(
           (cause) =>
-            new AssetAccessError({
+            new AssetWorkspaceAssetInspectionError({
-              operation: "inspect-workspace-asset",
               resource: input.resource,
-              message: "Failed to inspect the workspace asset.",
               cause,
             }),
         ),
       );
       if (!canonicalFile) {
-        return yield* new AssetAccessError({
+        return yield* new AssetWorkspaceAssetNotFoundError({
-          operation: "locate-workspace-asset",
           resource: input.resource,
-          message: "Workspace asset was not found.",
         });
       }
       const canonicalWorkspaceRoot = yield* fileSystem.realPath(workspaceRoot).pipe(
         Effect.mapError(
           (cause) =>
-            new AssetAccessError({
+            new AssetWorkspaceResolutionError({
-              operation: "resolve-workspace",
               resource: input.resource,
-              message: "Failed to resolve workspace.",
               cause,
             }),
         ),
 @@ -262,10 +261,8 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         attachmentId: input.resource.attachmentId,
       });
       if (!attachmentPath) {
-        return yield* new AssetAccessError({
+        return yield* new AssetAttachmentNotFoundError({
-          operation: "locate-attachment",
           resource: input.resource,
-          message: "Attachment was not found.",
         });
       }
       claims = {
 @@ -281,10 +278,8 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
       const workspaceRoot = yield* workspacePaths.normalizeWorkspaceRoot(input.resource.cwd).pipe(
         Effect.mapError(
           (cause) =>
-            new AssetAccessError({
+            new AssetWorkspaceRootNormalizationError({
-              operation: "normalize-workspace-root",
               resource: input.resource,
-              message: "Failed to normalize the workspace root.",
               cause,
             }),
         ),
 @@ -293,10 +288,8 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
       const faviconPath = yield* faviconResolver.resolvePath(workspaceRoot).pipe(
         Effect.mapError(
           (cause) =>
-            new AssetAccessError({
+            new AssetProjectFaviconResolutionError({
-              operation: "resolve-project-favicon",
               resource: input.resource,
-              message: "Failed to resolve project favicon.",
               cause,
             }),
         ),
 @@ -307,19 +300,15 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         !(yield* resolveCanonicalWorkspaceFile({ workspaceRoot, relativePath }).pipe(
           Effect.mapError(
             (cause) =>
-              new AssetAccessError({
+              new AssetProjectFaviconInspectionError({
-                operation: "inspect-project-favicon",
                 resource: input.resource,
-                message: "Failed to inspect the project favicon.",
                 cause,
               }),
           ),
         ))
       ) {
-        return yield* new AssetAccessError({
+        return yield* new AssetProjectFaviconNotFoundError({
-          operation: "locate-project-favicon",
           resource: input.resource,
-          message: "Project favicon was not found.",
         });
       }
       claims = {
 @@ -328,10 +317,8 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         workspaceRoot: yield* fileSystem.realPath(workspaceRoot).pipe(
           Effect.mapError(
             (cause) =>
-              new AssetAccessError({
+              new AssetWorkspaceResolutionError({
-                operation: "resolve-workspace",
                 resource: input.resource,
-                message: "Failed to resolve workspace.",
                 cause,
               }),
           ),
 @@ -348,10 +335,8 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
   const signingSecret = yield* secretStore.getOrCreateRandom(SIGNING_SECRET_NAME, 32).pipe(
     Effect.mapError(
       (cause) =>
-        new AssetAccessError({
+        new AssetSigningKeyLoadError({
-          operation: "load-signing-key",
           resource: input.resource,
-          message: "Failed to load the asset signing key.",
           cause,
         }),
     ),

apps/server/src/ws.ts+6-13

 @@ -46,7 +46,8 @@ import {
   OrchestrationReplayEventsError,
   type FilesystemBrowseFailure,
   FilesystemBrowseError,
-  AssetAccessError,
+  AssetWorkspaceContextNotFoundError,
+  AssetWorkspaceContextResolutionError,
   EnvironmentAuthorizationError,
   ThreadId,
   type TerminalAttachStreamEvent,
 @@ -1413,19 +1414,15 @@ const makeWsRpcLayer = (currentSession: EnvironmentAuth.AuthenticatedSession) =>
                 .pipe(
                   Effect.mapError(
                     (cause) =>
-                      new AssetAccessError({
+                      new AssetWorkspaceContextResolutionError({
-                        operation: "resolve-workspace-context",
                         resource: input.resource,
-                        message: "Failed to resolve workspace context.",
                         cause,
                       }),
                   ),
                 );
               if (Option.isNone(thread)) {
-                return yield* new AssetAccessError({
+                return yield* new AssetWorkspaceContextNotFoundError({
-                  operation: "resolve-workspace-context",
                   resource: input.resource,
-                  message: "Workspace context was not found.",
                 });
               }
               const project = yield* projectionSnapshotQuery
 @@ -1433,19 +1430,15 @@ const makeWsRpcLayer = (currentSession: EnvironmentAuth.AuthenticatedSession) =>
                 .pipe(
                   Effect.mapError(
                     (cause) =>
-                      new AssetAccessError({
+                      new AssetWorkspaceContextResolutionError({
-                        operation: "resolve-workspace-context",
                         resource: input.resource,
-                        message: "Failed to resolve workspace context.",
                         cause,
                       }),
                   ),
                 );
               if (Option.isNone(project)) {
-                return yield* new AssetAccessError({
+                return yield* new AssetWorkspaceContextNotFoundError({
-                  operation: "resolve-workspace-context",
                   resource: input.resource,
-                  message: "Workspace context was not found.",
                 });
               }
               return yield* issueAssetUrl({

packages/contracts/src/assets.ts+163-21

...	@@ -29,28 +29,170 @@ export const AssetCreateUrlResult = Schema.Struct({	...	@@ -29,28 +29,170 @@ export const AssetCreateUrlResult = Schema.Struct({
29	});	29	});
30	export type AssetCreateUrlResult = typeof AssetCreateUrlResult.Type;	30	export type AssetCreateUrlResult = typeof AssetCreateUrlResult.Type;
31		31
32	export const AssetAccessOperation = Schema.Literals([	32	export class AssetWorkspaceContextNotFoundError extends Schema.TaggedErrorClass<AssetWorkspaceContextNotFoundError>()(
33	"resolve-workspace-context",	33	"AssetWorkspaceContextNotFoundError",
34	"normalize-workspace-root",	34	{
35	"validate-workspace-path",	35	resource: AssetResource,
36	"validate-preview-type",	36	},
37	"inspect-workspace-asset",	37	) {
38	"locate-workspace-asset",	38	override get message(): string {
39	"resolve-workspace",	39	return "Workspace context was not found.";
40	"locate-attachment",	40	}
41	"resolve-project-favicon",	41	}
42	"inspect-project-favicon",	42
43	"locate-project-favicon",	43	export class AssetWorkspaceContextResolutionError extends Schema.TaggedErrorClass<AssetWorkspaceContextResolutionError>()(
44	"load-signing-key",	44	"AssetWorkspaceContextResolutionError",
45	]);	45	{
46	export type AssetAccessOperation = typeof AssetAccessOperation.Type;	46	resource: AssetResource,
		47	cause: Schema.Defect(),
		48	},
		49	) {
		50	override get message(): string {
		51	return "Failed to resolve workspace context.";
		52	}
		53	}
		54
		55	export class AssetWorkspaceRootNormalizationError extends Schema.TaggedErrorClass<AssetWorkspaceRootNormalizationError>()(
		56	"AssetWorkspaceRootNormalizationError",
		57	{
		58	resource: AssetResource,
		59	cause: Schema.Defect(),
		60	},
		61	) {
		62	override get message(): string {
		63	return "Failed to normalize the workspace root.";
		64	}
		65	}
		66
		67	export class AssetWorkspacePathValidationError extends Schema.TaggedErrorClass<AssetWorkspacePathValidationError>()(
		68	"AssetWorkspacePathValidationError",
		69	{
		70	resource: AssetResource,
		71	cause: Schema.Defect(),
		72	},
		73	) {
		74	override get message(): string {
		75	return "Workspace file path must be relative to the project root.";
		76	}
		77	}
		78
		79	export class AssetPreviewTypeValidationError extends Schema.TaggedErrorClass<AssetPreviewTypeValidationError>()(
		80	"AssetPreviewTypeValidationError",
		81	{
		82	resource: AssetResource,
		83	},
		84	) {
		85	override get message(): string {
		86	return "Only browser documents and images can be previewed.";
		87	}
		88	}
		89
		90	export class AssetWorkspaceAssetInspectionError extends Schema.TaggedErrorClass<AssetWorkspaceAssetInspectionError>()(
		91	"AssetWorkspaceAssetInspectionError",
		92	{
		93	resource: AssetResource,
		94	cause: Schema.Defect(),
		95	},
		96	) {
		97	override get message(): string {
		98	return "Failed to inspect the workspace asset.";
		99	}
		100	}
		101
		102	export class AssetWorkspaceAssetNotFoundError extends Schema.TaggedErrorClass<AssetWorkspaceAssetNotFoundError>()(
		103	"AssetWorkspaceAssetNotFoundError",
		104	{
		105	resource: AssetResource,
		106	},
		107	) {
		108	override get message(): string {
		109	return "Workspace asset was not found.";
		110	}
		111	}
		112
		113	export class AssetWorkspaceResolutionError extends Schema.TaggedErrorClass<AssetWorkspaceResolutionError>()(
		114	"AssetWorkspaceResolutionError",
		115	{
		116	resource: AssetResource,
		117	cause: Schema.Defect(),
		118	},
		119	) {
		120	override get message(): string {
		121	return "Failed to resolve workspace.";
		122	}
		123	}
47		124
48	export class AssetAccessError extends Schema.TaggedErrorClass<AssetAccessError>()(	125	export class AssetAttachmentNotFoundError extends Schema.TaggedErrorClass<AssetAttachmentNotFoundError>()(
49	"AssetAccessError",	126	"AssetAttachmentNotFoundError",
50	{	127	{
51	operation: AssetAccessOperation,
52	resource: AssetResource,	128	resource: AssetResource,
53	message: TrimmedNonEmptyString,
54	cause: Schema.optional(Schema.Defect()),
55	},	129	},
56	) {}	130	) {
		131	override get message(): string {
		132	return "Attachment was not found.";
		133	}
		134	}
		135
		136	export class AssetProjectFaviconResolutionError extends Schema.TaggedErrorClass<AssetProjectFaviconResolutionError>()(
		137	"AssetProjectFaviconResolutionError",
		138	{
		139	resource: AssetResource,
		140	cause: Schema.Defect(),
		141	},
		142	) {
		143	override get message(): string {
		144	return "Failed to resolve project favicon.";
		145	}
		146	}
		147
		148	export class AssetProjectFaviconInspectionError extends Schema.TaggedErrorClass<AssetProjectFaviconInspectionError>()(
		149	"AssetProjectFaviconInspectionError",
		150	{
		151	resource: AssetResource,
		152	cause: Schema.Defect(),
		153	},
		154	) {
		155	override get message(): string {
		156	return "Failed to inspect the project favicon.";
		157	}
		158	}
		159
		160	export class AssetProjectFaviconNotFoundError extends Schema.TaggedErrorClass<AssetProjectFaviconNotFoundError>()(
		161	"AssetProjectFaviconNotFoundError",
		162	{
		163	resource: AssetResource,
		164	},
		165	) {
		166	override get message(): string {
		167	return "Project favicon was not found.";
		168	}
		169	}
		170
		171	export class AssetSigningKeyLoadError extends Schema.TaggedErrorClass<AssetSigningKeyLoadError>()(
		172	"AssetSigningKeyLoadError",
		173	{
		174	resource: AssetResource,
		175	cause: Schema.Defect(),
		176	},
		177	) {
		178	override get message(): string {
		179	return "Failed to load the asset signing key.";
		180	}
		181	}
		182
		183	export const AssetAccessError = Schema.Union([
		184	AssetWorkspaceContextNotFoundError,
		185	AssetWorkspaceContextResolutionError,
		186	AssetWorkspaceRootNormalizationError,
		187	AssetWorkspacePathValidationError,
		188	AssetPreviewTypeValidationError,
		189	AssetWorkspaceAssetInspectionError,
		190	AssetWorkspaceAssetNotFoundError,
		191	AssetWorkspaceResolutionError,
		192	AssetAttachmentNotFoundError,
		193	AssetProjectFaviconResolutionError,
		194	AssetProjectFaviconInspectionError,
		195	AssetProjectFaviconNotFoundError,
		196	AssetSigningKeyLoadError,
		197	]);
		198	export type AssetAccessError = typeof AssetAccessError.Type;