Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 91 additions & 1 deletion apps/server/src/mcp/McpHttpServer.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Logger from "effect/Logger";
import * as Schema from "effect/Schema";
import * as SqlClient from "effect/sql/SqlClient";
import * as Stream from "effect/Stream";
import * as Tracer from "effect/Tracer";
import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
Expand All @@ -43,6 +44,7 @@ import * as McpOAuth from "../auth/McpOAuth.ts";
import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
import * as Sqlite from "../persistence/Sqlite.ts";
import * as WorkLedger from "../persistence/WorkLedger.ts";
import * as ManagedPolicy from "../policy/ManagedPolicy.ts";

import * as DeviceService from "../device/DeviceService.ts";
Expand Down Expand Up @@ -75,7 +77,7 @@ const invocation = {
providerInstanceId: ProviderInstanceId.make("codex"),
},
client: undefined,
capabilities: new Set(["preview"] as const),
capabilities: new Set(["preview", "orchestration"] as const),
issuedAt: 1,
};
const client = McpSchema.McpServerClient.of({
Expand Down Expand Up @@ -643,6 +645,94 @@ it.effect("decodes null optional arguments the way it decodes omitted ones", ()
}).pipe(Effect.provide(layerRecordingTools(calls)));
});

it.effect(
"classifies ledger parameter refusals as invalid_request and accepts explicit null clears",
() =>
Effect.gen(function* () {
const server = yield* McpServer.McpServer;
const upsertTool = server.tools.find(({ tool }) => tool.name === "ledger_upsert")!;
const nullable = { anyOf: expect.arrayContaining([{ type: "null" }]) };
expect(upsertTool.tool.inputSchema).toMatchObject({
properties: {
ownerThreadId: nullable,
blocker: nullable,
waitReason: nullable,
nextCheckAt: nullable,
},
});
for (const [name, args] of [
["ledger_query", { status: "BLOCKED_TECH" }],
["ledger_query", { cursor: "x".repeat(257) }],
["ledger_upsert", { key: "bad", nextAction: "x".repeat(8001) }],
] as const) {
const result = yield* callTool(name, args).pipe(Effect.flip);
expect(result).toMatchObject({ _tag: "InvalidParams" });
}
const args = { key: "valid", title: "Task", ownerKind: "jarvis", ownerName: "chief" };
expect(
yield* callTool("ledger_upsert", {
...args,
ownerThreadId: threadId,
blocker: "Waiting for event",
waitReason: "natural",
nextCheckAt: "2026-11-13T12:00:00.000Z",
}),
).not.toMatchObject({ isError: true });
const cleared = yield* callTool("ledger_upsert", {
key: "valid",
ownerThreadId: null,
blocker: null,
waitReason: null,
nextCheckAt: null,
});
expect(cleared.structuredContent).toMatchObject({
ownerKind: "jarvis",
ownerThreadId: null,
blocker: null,
waitReason: null,
nextCheckAt: null,
warnings: [],
});
for (const fields of [
{ ownerThreadId: "null" },
{ ownerThreadId: "NuLl" },
{ ownerThreadId: " null " },
{ approval: { source: { threadId: " null ", itemId: "dialog" } } },
{ approval: { source: { threadId, itemId: "NULL" } } },
{ approval: { source: { threadId, itemId: "dialog", questionId: "NuLl" } } },
]) {
const rejected = yield* callTool("ledger_upsert", { key: "valid", ...fields }).pipe(
Effect.flip,
);
expect(rejected).toMatchObject({ _tag: "InvalidParams" });
expect(rejected.message).toContain("JSON null");
}
expect((yield* (yield* WorkLedger.WorkLedger).query({})).items).toMatchObject([
{ key: "valid", ownerThreadId: null, blocker: null, waitReason: null, nextCheckAt: null },
]);
expect(
yield* callTool("ledger_query", { cursor: null, ownerName: null, waitReason: null }),
).not.toMatchObject({ isError: true });
const sql = yield* SqlClient.SqlClient;
yield* sql`UPDATE work_ledger SET owner_thread_id = 'null' WHERE work_key = 'valid'`;
expect(
(yield* callTool("ledger_upsert", { key: "valid", ownerThreadId: null })).structuredContent,
).toMatchObject({ ownerThreadId: null, warnings: [] });
const errors =
yield* sql`SELECT error_class FROM mcp_request_log WHERE error_class IS NOT NULL`;
expect(errors).toEqual(Array.from({ length: 9 }, () => ({ error_class: "invalid_request" })));
}).pipe(
Effect.provide(
McpHttpServer.layerLedgerToolkit.pipe(
Layer.provideMerge(McpHttpServer.layerInProcessMcpServer),
Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
Layer.provideMerge(WorkLedger.layer.pipe(Layer.provideMerge(Sqlite.layerMemory))),
Layer.provideMerge(RequestLog.layer.pipe(Layer.provideMerge(Sqlite.layerMemory))),
),
),
),
);

it.effect("rejects arguments a tool does not declare instead of dropping them", () => {
const calls: Array<unknown> = [];
return Effect.gen(function* () {
Expand Down
17 changes: 14 additions & 3 deletions apps/server/src/mcp/McpHttpServer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1029,11 +1029,19 @@ const isRequestErrorCode = Schema.is(OrchestratorMcpFailure.fields.code);
const decodeDeclaredFailure = Schema.decodeUnknownOption(
Schema.fromJsonString(OrchestratorMcpFailure),
);
const requestErrorClass = (result: McpSchema.CallToolResult | undefined) => {
const requestErrorClass = (
result: McpSchema.CallToolResult | undefined,
cause?: Cause.Cause<unknown>,
) => {
const outcome = toolOutcome(result);
if (outcome.outcome === "ok") return null;
if (isRequestErrorCode(outcome.errorCode)) return outcome.errorCode;
if (result === undefined) return "execution_failure";
if (result === undefined)
return cause?.reasons.some(
(reason) => Cause.isFailReason(reason) && Predicate.isTagged(reason.error, "InvalidParams"),
)
? "invalid_request"
: "execution_failure";
for (const content of result.content) {
if (content.type !== "text") continue;
const failure = decodeDeclaredFailure(content.text);
Expand Down Expand Up @@ -1207,7 +1215,10 @@ const withToolAnalytics =
),
),
responseBytes,
errorClass: requestErrorClass(result),
errorClass: requestErrorClass(
result,
exit._tag === "Failure" ? exit.cause : undefined,
),
})
.pipe(Effect.ignoreCause);
}
Expand Down
21 changes: 13 additions & 8 deletions apps/server/src/mcp/advertisedJsonSchema.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,23 @@ it("drops JSON noise, merges tagged unions, and keeps null where it is required"
expect(advertisedJsonSchema(tool)).toEqual({
type: "object",
properties: {
threadId: { type: "string" },
threadId: { anyOf: [{ type: "string" }, { type: "null" }] },
beforeRunId: { anyOf: [{ type: "string" }, { type: "null" }] },
limit: { type: "integer" },
every: { type: "object", properties: { ms: { type: "integer" } }, required: ["ms"] },
target: {
type: "object",
properties: {
kind: { type: "string", enum: ["url", "number"] },
url: { type: "string" },
number: { type: "integer" },
},
required: ["kind"],
anyOf: [
{
type: "object",
properties: {
kind: { type: "string", enum: ["url", "number"] },
url: { type: "string" },
number: { type: "integer" },
},
required: ["kind"],
},
{ type: "null" },
],
},
},
required: ["beforeRunId", "every"],
Expand Down
46 changes: 36 additions & 10 deletions apps/server/src/mcp/advertisedJsonSchema.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import * as Predicate from "effect/Predicate";
import type * as SchemaAST from "effect/SchemaAST";
import { Tool } from "effect/ai";

type Json = unknown;
Expand Down Expand Up @@ -67,7 +68,22 @@ const mergeTaggedObjects = (branches: ReadonlyArray<Json>): JsonObject | undefin
return { type: "object", properties, required: [tag, ...requiredByAll] };
};

const compact = (schema: Json, optional: boolean): Json => {
const sourceProperty = (
source: SchemaAST.AST | undefined,
name: string,
): SchemaAST.AST | undefined => {
if (source?._tag === "Objects")
return source.propertySignatures.find((property) => property.name === name)?.type;
if (source?._tag === "Union")
return source.types
.map((type) => sourceProperty(type, name))
.find((type) => type !== undefined);
return undefined;
};
const explicitlyNullable = (source: SchemaAST.AST | undefined): boolean =>
source?._tag === "Null" || (source?._tag === "Union" && source.types.some(explicitlyNullable));

const compact = (schema: Json, optional: boolean, source?: SchemaAST.AST): Json => {
if (Array.isArray(schema)) return schema.map((item) => compact(item, false));
if (!Predicate.isObject(schema)) return schema;
const required = new Set(Array.isArray(schema.required) ? schema.required : []);
Expand All @@ -80,27 +96,37 @@ const compact = (schema: Json, optional: boolean): Json => {
? Object.fromEntries(
Object.entries(value).map(([name, property]) => [
name,
compact(property, !required.has(name)),
compact(property, !required.has(name), sourceProperty(source, name)),
]),
)
: compact(value, false);
}
if (Array.isArray(result.anyOf)) {
const branches = result.anyOf
.flatMap((branch) => (isBareAnyOf(branch) ? branch.anyOf : [branch]))
.filter((branch) => !(optional && isNullSchema(branch)) && !isJsonStringSchema(branch));
.filter(
(branch) =>
!(optional && isNullSchema(branch) && !explicitlyNullable(source)) &&
!isJsonStringSchema(branch),
);
const nonNull = branches.filter((branch) => !isNullSchema(branch));
const merged = mergeTaggedObjects(nonNull);
const distinct = [
...(merged === undefined ? nonNull : [merged]),
...(branches.some(isNullSchema) ? [{ type: "null" }] : []),
];
const { anyOf: _anyOf, ...rest } = result;
const only = branches.length === 1 ? branches[0] : mergeTaggedObjects(branches);
result = Predicate.isObject(only) ? { ...only, ...rest } : { ...rest, anyOf: branches };
const only = distinct.length === 1 ? distinct[0] : undefined;
result = Predicate.isObject(only) ? { ...only, ...rest } : { ...rest, anyOf: distinct };
}
return result;
};

/**
* The input schema T3 advertises for a tool. Drops JSON noise that every thread pays for:
* `additionalProperties: true`, safe-integer bounds, nested `anyOf`, JSON-string fallbacks, and
* the `null` branch of optional properties. A tagged union of objects becomes one object.
* Decoding still uses the full schema, so each tag's own required fields still apply.
* Compact advertised schemas keep explicit null clears, but omit synthesized optional nulls.
* Tagged object unions merge for display; decoding still enforces each tag's required fields.
*/
export const advertisedJsonSchema = (tool: Tool.Any) =>
compact(Tool.getJsonSchema(tool), false) as ReturnType<typeof Tool.getJsonSchema>;
compact(Tool.getJsonSchema(tool), false, tool.parametersSchema.ast) as ReturnType<
typeof Tool.getJsonSchema
>;
7 changes: 6 additions & 1 deletion apps/server/src/mcp/toolkits/ledger/handlers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import * as Ledger from "../../../persistence/WorkLedger.ts";
import * as Access from "../../McpToolAccess.ts";
import { readCaller } from "../../threadAccess.ts";
import { LedgerToolkit } from "./tools.ts";
import { messageSenderFor } from "../../McpInvocationContext.ts";
export const layer = Access.toLayer(LedgerToolkit, {
ledger_upsert: Access.writes((input) =>
Effect.gen(function* () {
Expand All @@ -14,7 +15,11 @@ export const layer = Access.toLayer(LedgerToolkit, {
code: "capability_denied",
message: "A caller identity is required.",
});
return yield* (yield* Ledger.WorkLedger).upsert(input, updatedBy);
return yield* (yield* Ledger.WorkLedger).upsert(
input,
updatedBy,
messageSenderFor(scope).senderClient,
);
}),
),
ledger_history: Access.reads((input) =>
Expand Down
6 changes: 3 additions & 3 deletions apps/server/src/mcp/toolkits/ledger/tools.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ export const LedgerToolkit = Toolkit.make(
Tool.make("ledger_history", {
...common,
description:
"Read who changed a ledger key, when, and the before/after values. Ordered oldest first; continue with nextCursor. Default 25 rows.",
"Read ledger changes with handoffArgs and server-recorded changedByClient labels. Oldest first; nextCursor paginates. Default 25 rows.",
parameters: WorkLedgerHistoryInput,
success: WorkLedgerHistoryResult,
})
Expand All @@ -35,7 +35,7 @@ export const LedgerToolkit = Toolkit.make(
Tool.make("portfolio_status", {
...common,
description:
"Open ledger rows with owner thread latest run, pending request count, result excerpt and staleWorker (no run for over 24 hours). Default 10 rows; continue with nextCursor.",
"Open ledger rows with owner thread run, pending requests, result excerpt, staleWorker (no run for 24h), and flapping (>3 open/blocked flips in 24h). Flags grant no restart permission. Default 10 rows; nextCursor paginates.",
parameters: PortfolioStatusInput,
success: PortfolioStatusResult,
})
Expand All @@ -44,7 +44,7 @@ export const LedgerToolkit = Toolkit.make(
Tool.make("ledger_upsert", {
...common,
description:
"Create or partially update work by a stable `key`. New items need title, ownerKind and ownerName. Omitted fields stay; null clears a nullable field. Requires operate access. approvalNote grants no approval. For Chris's approval, ask him in a dialog whose question has `Ledger key: <key>` on its own line, then pass `approval.source` (itemId, sourceThreadId from t3_thread_read); the server verifies and quotes it, or refuses. `approval: null` revokes.",
"Update work by stable key; new rows need title, ownerKind, ownerName. Omitted fields stay; JSON null clears nullable fields (not the string \"null\"). links replaces all; addLinks/removeLinks deduplicate; removals win. handoffArgs stores exact JSON tool arguments, at most 4096 UTF-8 bytes; never put secrets here. Requires operate access. approvalNote/handoffArgs grant no approval. For Chris's approval, ask a dialog with `Ledger key: <key>` on its own question line; pass approval.source (threadId = item's sourceThreadId, itemId from t3_thread_read). Server verifies and quotes, or refuses. approval:null revokes.",
parameters: WorkLedgerUpsertInput,
success: WorkLedgerUpsertResult,
}).annotate(Tool.Destructive, true),
Expand Down
2 changes: 2 additions & 0 deletions apps/server/src/persistence/ForkMigrations.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import ForkMigration0009 from "./ForkMigrations/009_McpInboxRelay.ts";
import ForkMigration0010 from "./ForkMigrations/010_WorkLedgerPortfolio.ts";
import ForkMigration0011 from "./ForkMigrations/011_ForkRunExclusions.ts";
import ForkMigration0012 from "./ForkMigrations/012_WorkLedgerApproval.ts";
import ForkMigration0013 from "./ForkMigrations/013_WorkLedgerHygiene.ts";
// Fork-only migrations, recorded in their own table so upstream keeps every id in
// effect_sql_migrations. They run after all upstream migrations. Add new ones here, never in
// Migrations.ts, and never rename one: the repair below finds old rows by name. See FORK.md.
Expand All @@ -30,6 +31,7 @@ const forkMigrationEntries = [
[10, "WorkLedgerPortfolio", ForkMigration0010],
[11, "ForkRunExclusions", ForkMigration0011],
[12, "WorkLedgerApproval", ForkMigration0012],
[13, "WorkLedgerHygiene", ForkMigration0013],
] as const;

export const FORK_MIGRATIONS_TABLE = "t3_fork_migrations";
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import * as Effect from "effect/Effect";
import * as SqlClient from "effect/sql/SqlClient";

export default Effect.gen(function* () {
const sql = yield* SqlClient.SqlClient;
yield* sql`ALTER TABLE work_ledger ADD COLUMN handoff_args_json TEXT
CHECK (handoff_args_json IS NULL OR (json_valid(handoff_args_json) AND length(CAST(handoff_args_json AS BLOB)) <= 4096))`;
yield* sql`ALTER TABLE work_ledger_history ADD COLUMN changed_by_client_json TEXT`;
});
Loading
Loading