Skip to content
TypeScript

fix(server): agents see why a project update was refused instead of a generic failure (#30564)

MarcoDotIO7057a74d03d9
diff --git a/apps/server/src/mcp/toolkits/project/handlers.test.ts b/apps/server/src/mcp/toolkits/project/handlers.test.ts
index 6721e894785..2ecbde990d8 100644
--- a/apps/server/src/mcp/toolkits/project/handlers.test.ts
+++ b/apps/server/src/mcp/toolkits/project/handlers.test.ts
@@ -664,3 +664,31 @@ it.effect("deleting a project through MCP also discards its clone record", () =>
expect(discarded).toEqual([harness.projectId]);
}),
);
+
+it.effect("an update the project refuses tells the agent why", () =>
+ Effect.gen(function* () {
+ const harness = clientLaunchHarness({ runtimeModeCeiling: "full-access", launched: [] });
+ const detail = "Project monograms must contain at most two characters.";
+ const dependencies = Layer.merge(
+ harness.dependencies,
+ Layer.mock(Project.ProjectService)({
+ update: (input) =>
+ Effect.fail(new Project.ProjectInvalidError({ projectId: input.projectId, detail })),
+ }),
+ );
+ const toolkit = yield* ProjectToolkit.pipe(
+ Effect.provide(
+ McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(Layer.provide(dependencies)),
+ ),
+ );
+
+ const refused = yield* toolkit
+ .handle("t3_project_update", {
+ projectId: harness.projectId,
+ projectIcon: { kind: "monogram", text: "ABC", color: "blue" },
+ })
+ .pipe(Stream.unwrap, Stream.runCollect, Effect.provide(dependencies));
+
+ expect(refused.at(-1)?.result).toMatchObject({ code: "invalid_request", message: detail });
+ }),
+);
diff --git a/apps/server/src/mcp/toolkits/project/handlers.ts b/apps/server/src/mcp/toolkits/project/handlers.ts
index a14ee03daa4..667b878e68d 100644
--- a/apps/server/src/mcp/toolkits/project/handlers.ts
+++ b/apps/server/src/mcp/toolkits/project/handlers.ts
@@ -37,11 +37,13 @@ const isAboveCeilingError = Schema.is(OrchestratorRuntimeModeAboveCeilingError);
function projectFailure(error: Project.ProjectServiceError) {
if (error._tag === "ProjectOperationError") return unavailable();
const message =
- error._tag === "ProjectNotFoundError"
- ? "The project was not found."
- : error._tag === "ProjectConflictError"
- ? "The workspace is already registered to a project."
- : "The project is not empty; force=true is required to delete it.";
+ error._tag === "ProjectInvalidError"
+ ? error.detail
+ : error._tag === "ProjectNotFoundError"
+ ? "The project was not found."
+ : error._tag === "ProjectConflictError"
+ ? "The workspace is already registered to a project."
+ : "The project is not empty; force=true is required to delete it.";
return new OrchestratorMcpFailure({ code: "invalid_request", message });
}
diff --git a/apps/server/src/project/ProjectService.test.ts b/apps/server/src/project/ProjectService.test.ts
index 11d3fea8f06..988578f49d1 100644
--- a/apps/server/src/project/ProjectService.test.ts
+++ b/apps/server/src/project/ProjectService.test.ts
@@ -452,15 +452,12 @@ it.layer(layerTest)("ProjectService", (it) => {
],
};
const first = yield* service.update(invalid).pipe(Effect.flip);
- assert.equal(first._tag, "ProjectOperationError");
+ assert.equal(first._tag, "ProjectInvalidError");
+ assert.include(first.message, "Script IDs must be 1-24 lowercase letters");
const replayed = yield* service
.update({ ...invalid, scripts: [{ ...invalid.scripts[0]!, id: "valid" }] })
.pipe(Effect.flip);
- assert.equal(replayed._tag, "ProjectOperationError");
- assert.include(
- String(replayed._tag === "ProjectOperationError" && replayed.cause),
- "Script ID",
- );
+ assert.deepEqual(replayed, first);
const receipts = yield* sql<{ readonly status: string; readonly aggregate_id: string }>`
SELECT status, aggregate_id FROM orchestration_command_receipts
WHERE command_id = ${invalid.commandId}
diff --git a/apps/server/src/project/ProjectService.ts b/apps/server/src/project/ProjectService.ts
index 914456a500c..9afaf22087a 100644
--- a/apps/server/src/project/ProjectService.ts
+++ b/apps/server/src/project/ProjectService.ts
@@ -84,6 +84,16 @@ export class ProjectNotEmptyError extends Schema.TaggedError<ProjectNotEmptyErro
}
}
+/** A change the project's rules refuse, such as an invalid script ID: the caller's input is wrong, nothing failed. */
+export class ProjectInvalidError extends Schema.TaggedError<ProjectInvalidError>()(
+ "ProjectInvalidError",
+ { projectId: ProjectId, detail: Schema.String },
+) {
+ override get message(): string {
+ return this.detail;
+ }
+}
+
export class ProjectOperationError extends Schema.TaggedError<ProjectOperationError>()(
"ProjectOperationError",
{
@@ -109,6 +119,7 @@ export type ProjectServiceError =
| ProjectNotFoundError
| ProjectConflictError
| ProjectNotEmptyError
+ | ProjectInvalidError
| ProjectOperationError;
export class ProjectService extends Context.Service<
@@ -292,6 +303,8 @@ export const make = Effect.gen(function* () {
});
case "ProjectCommandMissingProjectError":
return yield* new ProjectNotFoundError({ projectId });
+ case "ProjectCommandInvariantError":
+ return yield* new ProjectInvalidError({ projectId, detail: rejection.detail });
default:
return yield* dispatchError(
rejection ?? receipt.error ?? "The command was previously rejected.",
diff --git a/apps/server/src/project/http.ts b/apps/server/src/project/http.ts
index 0c4c7a44a5f..b6dfc5ae75e 100644
--- a/apps/server/src/project/http.ts
+++ b/apps/server/src/project/http.ts
@@ -24,7 +24,8 @@ const failProjectMutation = Effect.fn("environment.projects.failMutation")(funct
if (
cause._tag === "ProjectNotFoundError" ||
cause._tag === "ProjectConflictError" ||
- cause._tag === "ProjectNotEmptyError"
+ cause._tag === "ProjectNotEmptyError" ||
+ cause._tag === "ProjectInvalidError"
) {
return yield* failEnvironmentInvalidRequest("invalid_command");
}