diff --git a/apps/server/src/mcp/McpHttpServer.test.ts b/apps/server/src/mcp/McpHttpServer.test.ts index f66db9bd6b317..c52fbde1a8a65 100644 --- a/apps/server/src/mcp/McpHttpServer.test.ts +++ b/apps/server/src/mcp/McpHttpServer.test.ts @@ -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"; @@ -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"; @@ -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({ @@ -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 = []; return Effect.gen(function* () { diff --git a/apps/server/src/mcp/McpHttpServer.ts b/apps/server/src/mcp/McpHttpServer.ts index d47860c6da012..71366fab53a93 100644 --- a/apps/server/src/mcp/McpHttpServer.ts +++ b/apps/server/src/mcp/McpHttpServer.ts @@ -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, +) => { 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); @@ -1207,7 +1215,10 @@ const withToolAnalytics = ), ), responseBytes, - errorClass: requestErrorClass(result), + errorClass: requestErrorClass( + result, + exit._tag === "Failure" ? exit.cause : undefined, + ), }) .pipe(Effect.ignoreCause); } diff --git a/apps/server/src/mcp/advertisedJsonSchema.test.ts b/apps/server/src/mcp/advertisedJsonSchema.test.ts index 09a90556a9dd0..4b84e18e11437 100644 --- a/apps/server/src/mcp/advertisedJsonSchema.test.ts +++ b/apps/server/src/mcp/advertisedJsonSchema.test.ts @@ -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"], diff --git a/apps/server/src/mcp/advertisedJsonSchema.ts b/apps/server/src/mcp/advertisedJsonSchema.ts index 10001307f2d6c..2691cfef9c1a6 100644 --- a/apps/server/src/mcp/advertisedJsonSchema.ts +++ b/apps/server/src/mcp/advertisedJsonSchema.ts @@ -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; @@ -67,7 +68,22 @@ const mergeTaggedObjects = (branches: ReadonlyArray): 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 : []); @@ -80,7 +96,7 @@ 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); @@ -88,19 +104,29 @@ const compact = (schema: Json, optional: boolean): Json => { 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; + compact(Tool.getJsonSchema(tool), false, tool.parametersSchema.ast) as ReturnType< + typeof Tool.getJsonSchema + >; diff --git a/apps/server/src/mcp/toolkits/ledger/handlers.ts b/apps/server/src/mcp/toolkits/ledger/handlers.ts index effd615be4256..8c073945a7465 100644 --- a/apps/server/src/mcp/toolkits/ledger/handlers.ts +++ b/apps/server/src/mcp/toolkits/ledger/handlers.ts @@ -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* () { @@ -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) => diff --git a/apps/server/src/mcp/toolkits/ledger/tools.ts b/apps/server/src/mcp/toolkits/ledger/tools.ts index 49b80c8dc4866..87130d71ec59d 100644 --- a/apps/server/src/mcp/toolkits/ledger/tools.ts +++ b/apps/server/src/mcp/toolkits/ledger/tools.ts @@ -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, }) @@ -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, }) @@ -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: ` 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: ` 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), diff --git a/apps/server/src/persistence/ForkMigrations.ts b/apps/server/src/persistence/ForkMigrations.ts index 786ecf72c9ed1..271f0fb4b53b8 100644 --- a/apps/server/src/persistence/ForkMigrations.ts +++ b/apps/server/src/persistence/ForkMigrations.ts @@ -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. @@ -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"; diff --git a/apps/server/src/persistence/ForkMigrations/013_WorkLedgerHygiene.ts b/apps/server/src/persistence/ForkMigrations/013_WorkLedgerHygiene.ts new file mode 100644 index 0000000000000..b5ea51a08db8e --- /dev/null +++ b/apps/server/src/persistence/ForkMigrations/013_WorkLedgerHygiene.ts @@ -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`; +}); diff --git a/apps/server/src/persistence/WorkLedger.test.ts b/apps/server/src/persistence/WorkLedger.test.ts index f4ad60a937c11..9e797d389e67b 100644 --- a/apps/server/src/persistence/WorkLedger.test.ts +++ b/apps/server/src/persistence/WorkLedger.test.ts @@ -8,6 +8,7 @@ import * as SqlClient from "effect/sql/SqlClient"; import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient"; import LedgerMigration from "./ForkMigrations/010_WorkLedgerPortfolio.ts"; import BaseLedgerMigration from "./ForkMigrations/002_WorkLedger.ts"; +import HygieneMigration from "./ForkMigrations/013_WorkLedgerHygiene.ts"; import * as TestClock from "effect/testing/TestClock"; import * as Sqlite from "./Sqlite.ts"; import * as WorkLedger from "./WorkLedger.ts"; @@ -88,7 +89,22 @@ it.effect( ).toContain("a"); // Thread ids from create_threads can be longer than a display name. const longCaller = `thread:${"x".repeat(300)}`; - expect((yield* ledger.upsert({ key: "a" }, longCaller)).updatedBy).toBe(longCaller); + expect((yield* ledger.upsert({ key: "a", nextAction: "Review" }, longCaller)).updatedBy).toBe( + longCaller, + ); + const fullLinks = Array.from({ length: 100 }, (_, index) => `https://example.com/${index}`); + yield* ledger.upsert({ key: "a", links: fullLinks }, "caller"); + const beforeOverflow = yield* ledger.history({ key: "a" }); + expect( + yield* ledger + .upsert({ key: "a", addLinks: ["https://example.com/overflow"] }, "caller") + .pipe(Effect.flip), + ).toMatchObject({ + code: "invalid_request", + message: "A ledger item can have at most 100 links.", + }); + expect((yield* ledger.query({})).items[0]!.links).toEqual(fullLinks); + expect(yield* ledger.history({ key: "a" })).toEqual(beforeOverflow); }).pipe(Effect.provide(WorkLedger.layer.pipe(Layer.provideMerge(Sqlite.layerMemory)))), ); @@ -109,6 +125,7 @@ it.effect( "https://app.t3.codes/threads/env-1/also-missing", "[remote]()", "[local]()", + "[review](https://example.com/pr/old)", ], waitReason: "external", nextCheckAt: "1970-01-01T01:00:00+01:00", @@ -120,6 +137,7 @@ it.effect( "t3-thread://v2/env-1/also-missing", "t3-thread://v2/remote/thread", "t3-thread://v1/angle-missing", + "[review](https://example.com/pr/old)", ]); expect(first.warnings).toHaveLength(4); expect( @@ -128,7 +146,12 @@ it.effect( expect((yield* ledger.query({ due: false })).items).toEqual([]); const change = { key: "wait", waitReason: null, nextCheckAt: null } as const; yield* ledger.upsert(change, "caller-b"); - yield* ledger.upsert({ key: "wait" }, "caller-b"); + const unchanged = (yield* ledger.query({})).items[0]!; + yield* TestClock.setTime(2000); + expect(yield* ledger.upsert({ key: "wait" }, "caller-c")).toEqual({ + ...unchanged, + warnings: expect.any(Array), + }); const page = yield* ledger.history({ key: "wait", limit: 1 }); expect(page.items[0]).toMatchObject({ changedBy: "caller-a", @@ -144,7 +167,7 @@ it.effect( nextCheckAt: { before: "1970-01-01T00:00:00.000Z", after: null }, }, }); - expect(rest.items[1]!.changes).toEqual({}); + expect(rest.items).toHaveLength(1); expect((yield* ledger.query({ waitReason: null })).items).toHaveLength(1); expect((yield* ledger.query({ due: true })).items).toEqual([]); const before = yield* ledger.history({ key: "wait" }); @@ -161,6 +184,75 @@ it.effect( ).toBe("invalid_request"); yield* ledger.upsert({ key: "wait", nextCheckAt: "invalid" }, "caller-c").pipe(Effect.flip); expect(yield* ledger.history({ key: "wait" })).toEqual(before); + const sender = { + sessionId: "12345678", + clientLabel: "Coordinator", + kind: "outside-client", + access: "full-access", + } as const; + const args = { + tool: "t3_thread_send", + arguments: { threadId: "worker", message: "Exact payload", mode: "queue" }, + }; + const links = yield* ledger.upsert( + { + key: "wait", + addLinks: ["https://example.com/pr/1", "t3-thread://v1/angle-missing"], + removeLinks: ["[remote]()", "https://example.com/pr/old"], + handoffArgs: args, + }, + "12345678-full-session", + sender, + ); + expect(links.links).toEqual([ + "t3-thread://v2/env-1/also-missing", + "t3-thread://v1/angle-missing", + "https://example.com/pr/1", + ]); + expect((yield* ledger.query({})).items[0]!.handoffArgs).toEqual(args); + const history = yield* ledger.history({ key: "wait" }); + expect(history.items.at(-1)).toMatchObject({ + changedBy: "12345678-full-session", + changedByClient: sender, + changes: { handoffArgs: { before: null, after: args } }, + }); + const cleared = yield* ledger.upsert( + decodeUpsert({ key: "wait", handoffArgs: null }), + "caller-c", + ); + expect(cleared.handoffArgs).toBeNull(); + expect((yield* ledger.history({ key: "wait" })).items.at(-1)!.changes.handoffArgs).toEqual({ + before: args, + after: null, + }); + expect( + decodeUpsert({ key: "wait", handoffArgs: { payload: "x".repeat(4082) } }).handoffArgs, + ).toEqual({ payload: "x".repeat(4082) }); + for (const handoffArgs of [ + { payload: "x".repeat(4083) }, + { payload: "🎉".repeat(1021) }, + { bad: undefined }, + { bad: NaN }, + ]) { + expect(() => decodeUpsert({ key: "wait", handoffArgs })).toThrow(); + } + expect(yield* ledger.upsert({ key: "wait", status: "blocked" }, "caller-c")).toMatchObject({ + waitReason: "decision", + warnings: expect.arrayContaining([expect.stringContaining("defaulted")]), + }); + for (const blocker of ["BLOCKED_TECH: tool offline", "WAIT_DECISION: choose route"]) { + for (const waitReason of ["external", "natural"] as const) { + expect( + (yield* ledger.upsert({ key: "wait", blocker, waitReason }, "caller-c")).warnings, + ).toContainEqual(expect.stringContaining("contradicts")); + expect( + (yield* ledger.upsert({ key: "wait", nextAction: "Review" }, "caller-c")).warnings, + ).not.toContainEqual(expect.stringContaining("contradicts")); + expect( + (yield* ledger.upsert({ key: "wait", status: "blocked" }, "caller-c")).warnings, + ).toContainEqual(expect.stringContaining("contradicts")); + } + } }).pipe(Effect.provide(WorkLedger.layer.pipe(Layer.provideMerge(Sqlite.layerMemory)))), ); @@ -229,7 +321,7 @@ it.effect( yield* sql`UPDATE orchestration_v2_projection_runs SET completed_at = '1970-01-01T00:00:02.000Z' WHERE run_id = 'run-1'`; expect( (yield* ledger.query({})).items.find((item) => item.key === "run-key")!.updatedAt, - ).toBe("1970-01-02T01:00:00.000Z"); + ).toBe("1970-01-01T00:00:02.000Z"); expect(page.nextCursor).toBe("run-key"); expect((yield* ledger.portfolio({ cursor: page.nextCursor! })).items[0]).toMatchObject({ item: { key: "z" }, @@ -239,6 +331,24 @@ it.effect( expect( (yield* ledger.query({})).items.find((item) => item.key === "run-key")!.lastRunStatus, ).toBe("completed"); + for (const status of ["blocked", "open", "blocked"] as const) { + yield* ledger.upsert({ key: "z", status }, "caller"); + } + expect((yield* ledger.portfolio({ cursor: "run-key" })).items[0]).toMatchObject({ + openBlockedFlips24h: 3, + flapping: false, + }); + yield* ledger.upsert({ key: "z", status: "open" }, "caller"); + yield* ledger.upsert({ key: "z", nextAction: "No status change" }, "caller"); + expect((yield* ledger.portfolio({ cursor: "run-key" })).items[0]).toMatchObject({ + openBlockedFlips24h: 4, + flapping: true, + }); + yield* TestClock.adjust(24 * 60 * 60 * 1000 + 1); + expect((yield* ledger.portfolio({ cursor: "run-key" })).items[0]).toMatchObject({ + openBlockedFlips24h: 0, + flapping: false, + }); }).pipe(Effect.provide(WorkLedger.layer.pipe(Layer.provideMerge(Sqlite.layerMemory)))), ); @@ -616,6 +726,13 @@ it.effect("records Chris's dialog answer only for the row it names, and withdraw expect((yield* approve("typed-row", {}, "r3/typed")).approval?.quotedAnswer).toBe( "Yes, for R&D, if a < b.", ); + expect( + (yield* ledger.upsert({ key: "r3/typed", handoffArgs: { target: "changed" } }, "agent")) + .approval, + ).toBeNull(); + expect(yield* approve("typed-row", {}, "r3/typed").pipe(Effect.flip)).toMatchObject({ + message: expect.stringContaining("already used or withdrawn"), + }); // An answer older than a day no longer approves anything. yield* TestClock.setTime(25 * 60 * 60 * 1000); @@ -665,5 +782,25 @@ it.effect("backfills recognized blockers and preserves legacy thread link destin { wait_reason: null }, ]); expect(yield* sql`SELECT * FROM work_ledger_history`).toEqual([]); + yield* sql`INSERT INTO work_ledger_history (work_key, changed_at, changed_by, changes_json) + VALUES ('a', '1970-01-01', 'legacy-editor', '{"status":{"before":"open","after":"blocked"}}')`; + const ledgerBefore = yield* sql`SELECT * FROM work_ledger ORDER BY work_key`; + const historyBefore = yield* sql`SELECT * FROM work_ledger_history`; + yield* HygieneMigration; + expect(yield* sql`SELECT * FROM work_ledger ORDER BY work_key`).toEqual( + ledgerBefore.map((row) => ({ ...row, handoff_args_json: null })), + ); + expect(yield* sql`SELECT * FROM work_ledger_history`).toEqual( + historyBefore.map((row) => ({ ...row, changed_by_client_json: null })), + ); + const boundary = `"${"x".repeat(4094)}"`; + yield* sql`UPDATE work_ledger SET handoff_args_json = ${boundary} WHERE work_key = 'a'`; + for (const invalid of ['{"broken":', `"${"x".repeat(4095)}"`, `"${"🎉".repeat(1024)}"`]) { + expect( + yield* sql`UPDATE work_ledger SET handoff_args_json = ${invalid} WHERE work_key = 'a'`.pipe( + Effect.isFailure, + ), + ).toBe(true); + } }).pipe(Effect.provide(NodeSqliteClient.layer({ filename: ":memory:" }))), ); diff --git a/apps/server/src/persistence/WorkLedger.ts b/apps/server/src/persistence/WorkLedger.ts index 79d5352393309..8da108a22b318 100644 --- a/apps/server/src/persistence/WorkLedger.ts +++ b/apps/server/src/persistence/WorkLedger.ts @@ -14,6 +14,7 @@ import { type WorkLedgerQueryInput, type WorkLedgerQueryResult, OrchestratorMcpFailure, + OrchestrationV2SenderClient, } from "@t3tools/contracts"; import { parseThreadLinkHref, formatThreadLink } from "@t3tools/shared/threadLinks"; import * as Context from "effect/Context"; @@ -36,6 +37,7 @@ export class WorkLedger extends Context.Service< readonly upsert: ( input: WorkLedgerUpsertInput, updatedBy: string, + updatedByClient?: OrchestrationV2SenderClient, ) => Effect.Effect; readonly history: ( input: WorkLedgerHistoryInput, @@ -56,11 +58,14 @@ const decode = Schema.decodeUnknownEffect( Struct.assign({ links: Schema.fromJsonString(WorkLedgerItem.fields.links), approval: Schema.NullOr(approvalJson), + handoffArgs: Schema.NullOr(Schema.fromJsonString(Schema.Json)), }), ), ), ); const encodeApproval = Schema.encodeEffect(approvalJson); +const encodeEditor = Schema.encodeEffect(Schema.fromJsonString(OrchestrationV2SenderClient)); +const encodeHandoffArgs = Schema.encodeEffect(Schema.fromJsonString(Schema.Json)); const decodeTurnItem = Schema.decodeUnknownEffect( Schema.fromJsonString(OrchestrationV2TurnItemJson), ); @@ -131,6 +136,7 @@ const ledgerRowHash = (row: WorkLedgerItem) => row.blocker, row.approvalNote, row.links, + ...(row.handoffArgs == null ? [] : [row.handoffArgs]), ]), ) .digest("hex"); @@ -139,6 +145,7 @@ const decodeHistory = Schema.decodeUnknownEffect( WorkLedgerHistoryEntry.mapFields( Struct.assign({ changes: Schema.fromJsonString(WorkLedgerHistoryEntry.fields.changes), + changedByClient: Schema.NullOr(Schema.fromJsonString(OrchestrationV2SenderClient)), }), ), ), @@ -156,7 +163,7 @@ const storage = () => }); const make = Effect.gen(function* () { const sql = yield* SqlClient.SqlClient; - const select = sql`SELECT work_key AS key, title, owner_kind AS "ownerKind", owner_name AS "ownerName", owner_thread_id AS "ownerThreadId", status, wait_reason AS "waitReason", next_check_at AS "nextCheckAt", last_run_id AS "lastRunId", last_run_status AS "lastRunStatus", last_run_at AS "lastRunAt", blocker, next_action AS "nextAction", approval_note AS "approvalNote", approval_json AS approval, links_json AS links, created_at AS "createdAt", updated_at AS "updatedAt", updated_by AS "updatedBy" FROM work_ledger`; + const select = sql`SELECT work_key AS key, title, owner_kind AS "ownerKind", owner_name AS "ownerName", owner_thread_id AS "ownerThreadId", status, wait_reason AS "waitReason", next_check_at AS "nextCheckAt", last_run_id AS "lastRunId", last_run_status AS "lastRunStatus", last_run_at AS "lastRunAt", blocker, next_action AS "nextAction", approval_note AS "approvalNote", approval_json AS approval, handoff_args_json AS "handoffArgs", links_json AS links, created_at AS "createdAt", updated_at AS "updatedAt", updated_by AS "updatedBy" FROM work_ledger`; const read = (key: string) => sql`${select} WHERE work_key = ${key}`.pipe( Effect.flatMap(decode), @@ -321,13 +328,13 @@ const make = Effect.gen(function* () { Effect.mapError(storage), ), ), - upsert: Effect.fn("WorkLedger.upsert")((input, updatedBy) => + upsert: Effect.fn("WorkLedger.upsert")((input, updatedBy, updatedByClient) => sql .withTransaction( Effect.gen(function* () { const current = yield* read(input.key); const now = DateTime.formatIso(yield* DateTime.now); - const { approval: approvalInput, ...fieldsInput } = input; + const { approval: approvalInput, addLinks, removeLinks, ...fieldsInput } = input; const patch = Object.fromEntries( Object.entries(fieldsInput).filter(([, value]) => value !== undefined), ); @@ -343,6 +350,7 @@ const make = Effect.gen(function* () { nextAction: null, approvalNote: null, links: [], + handoffArgs: null, ...current, ...patch, approval: null, @@ -360,6 +368,21 @@ const make = Effect.gen(function* () { candidate.nextCheckAt = DateTime.formatIso(parsed.value); } const warnings: string[] = []; + if (candidate.status === "blocked" && candidate.waitReason === null) { + candidate.waitReason = "decision"; + warnings.push("Blocked work has no waitReason; defaulted to decision."); + } + if ( + (input.status !== undefined || + input.waitReason !== undefined || + input.blocker !== undefined) && + /^(BLOCKED_TECH|WAIT_DECISION)\b/i.test(candidate.blocker ?? "") && + (candidate.waitReason === "external" || candidate.waitReason === "natural") + ) { + warnings.push( + `Blocker contradicts waitReason ${candidate.waitReason}; review the waiting reason.`, + ); + } const threadIds = new Set(); if (candidate.ownerThreadId !== null) { const ref = parseThreadLinkHref(candidate.ownerThreadId); @@ -372,14 +395,30 @@ const make = Effect.gen(function* () { if (ref !== null) candidate.ownerThreadId = ref.threadId; threadIds.add(candidate.ownerThreadId); } - candidate.links = candidate.links.map((link) => { - const href = (link.match(/^\[[^\]]*\]\((.*)\)$/)?.[1] ?? link).replace(/^<|>$/g, ""); + const linkHref = (link: string) => + (link.match(/^\[[^\]]*\]\((.*)\)$/)?.[1] ?? link).replace(/^<|>$/g, ""); + const normalizeLink = (link: string) => { + const href = linkHref(link); const ref = parseThreadLinkHref(href); if (ref === null) return link; + return formatThreadLink(ref).slice(1, -1); + }; + const linkTarget = (link: string) => normalizeLink(linkHref(link)); + const removedLinks = new Set((removeLinks ?? []).map(linkTarget)); + candidate.links = [ + ...new Set([...candidate.links, ...(addLinks ?? [])].map(normalizeLink)), + ].filter((link) => !removedLinks.has(linkTarget(link))); + if (candidate.links.length > 100) + return yield* new OrchestratorMcpFailure({ + code: "invalid_request", + message: "A ledger item can have at most 100 links.", + }); + for (const link of candidate.links) { + const ref = parseThreadLinkHref(link); + if (ref === null) continue; if (ref.environmentId === null) threadIds.add(ref.threadId); else warnings.push(`Scoped thread ${ref.threadId} was not checked locally.`); - return formatThreadLink(ref).slice(1, -1); - }); + } for (const threadId of threadIds) { const exists = yield* sql`SELECT 1 FROM orchestration_v2_projection_threads WHERE thread_id = ${threadId} AND deleted_at IS NULL`; @@ -420,7 +459,7 @@ const make = Effect.gen(function* () { else if (approval !== null && approval.rowHash !== ledgerRowHash(item)) yield* retire( approval, - "the row's title, next action, owner, blocker, links or approval note changed. Ask Chris again.", + "the row's title, next action, owner, blocker, links, handoff arguments or approval note changed. Ask Chris again.", ); if (approvalInput !== undefined && approvalInput !== null) { if (finished) @@ -443,6 +482,21 @@ const make = Effect.gen(function* () { approval === null ? null : yield* encodeApproval(approval).pipe(Effect.mapError(storage)); + const changes = Object.fromEntries( + Object.entries({ ...item, approval }) + .filter( + ([field, value]) => + !["createdAt", "updatedAt", "updatedBy"].includes(field) && + JSON.stringify(current?.[field as keyof WorkLedgerItem] ?? null) !== + JSON.stringify(value), + ) + .map(([field, value]) => [ + field, + { before: current?.[field as keyof WorkLedgerItem] ?? null, after: value }, + ]), + ); + if (current !== undefined && Object.keys(changes).length === 0) + return { ...current, warnings }; const row = { work_key: item.key, title: item.title, @@ -457,6 +511,8 @@ const make = Effect.gen(function* () { approval_note: item.approvalNote, approval_json: approvalJsonText, links_json: linksJson, + handoff_args_json: + item.handoffArgs == null ? null : yield* encodeHandoffArgs(item.handoffArgs), created_at: item.createdAt, updated_at: item.updatedAt, updated_by: item.updatedBy, @@ -467,23 +523,13 @@ const make = Effect.gen(function* () { wait_reason=excluded.wait_reason, next_check_at=excluded.next_check_at, next_action=excluded.next_action, approval_note=excluded.approval_note, approval_json=excluded.approval_json, links_json=excluded.links_json, + handoff_args_json=excluded.handoff_args_json, updated_at=excluded.updated_at, updated_by=excluded.updated_by`; - const changes = Object.fromEntries( - Object.entries({ ...item, approval }) - .filter( - ([field, value]) => - !["createdAt", "updatedAt", "updatedBy"].includes(field) && - JSON.stringify(current?.[field as keyof WorkLedgerItem] ?? null) !== - JSON.stringify(value), - ) - .map(([field, value]) => [ - field, - { before: current?.[field as keyof WorkLedgerItem] ?? null, after: value }, - ]), - ); const changesJson = yield* encodeChanges(changes); - yield* sql`INSERT INTO work_ledger_history (work_key, changed_at, changed_by, changes_json) - VALUES (${item.key}, ${now}, ${updatedBy}, ${changesJson})`; + const changedByClientJson = + updatedByClient === undefined ? null : yield* encodeEditor(updatedByClient); + yield* sql`INSERT INTO work_ledger_history (work_key, changed_at, changed_by, changes_json, changed_by_client_json) + VALUES (${item.key}, ${now}, ${updatedBy}, ${changesJson}, ${changedByClientJson})`; return { ...item, approval, warnings }; }), ) @@ -493,7 +539,7 @@ const make = Effect.gen(function* () { history: Effect.fn("WorkLedger.history")(function* (input) { const limit = input.limit ?? 25; const rows = - yield* sql`SELECT id, work_key AS key, changed_at AS "changedAt", changed_by AS "changedBy", changes_json AS changes + yield* sql`SELECT id, work_key AS key, changed_at AS "changedAt", changed_by AS "changedBy", changes_json AS changes, changed_by_client_json AS "changedByClient" FROM work_ledger_history WHERE work_key = ${input.key} AND id > ${input.cursor ?? 0} ORDER BY id LIMIT ${limit + 1}`; const decoded = yield* decodeHistory(rows); @@ -508,12 +554,28 @@ const make = Effect.gen(function* () { Effect.flatMap(decode), Effect.mapError(storage), ); - const now = DateTime.toEpochMillis(yield* DateTime.now); + const nowDate = yield* DateTime.now; + const now = DateTime.toEpochMillis(nowDate); + const cutoff = DateTime.formatIso(DateTime.subtract(nowDate, { hours: 24 })); + const upperBound = DateTime.formatIso(nowDate); const items = yield* Effect.forEach(ledgerRows.slice(0, limit), (item) => Effect.gen(function* () { + const [flips] = yield* sql<{ + count: number; + }>`SELECT COUNT(*) AS count FROM work_ledger_history + WHERE work_key = ${item.key} AND changed_at >= ${cutoff} + AND changed_at <= ${upperBound} + AND json_extract(changes_json, '$.status.before') IN ('open', 'blocked') + AND json_extract(changes_json, '$.status.after') IN ('open', 'blocked') + AND json_extract(changes_json, '$.status.before') != json_extract(changes_json, '$.status.after')`; + const flap = { + openBlockedFlips24h: flips?.count ?? 0, + flapping: (flips?.count ?? 0) > 3, + }; if (item.ownerThreadId === null) return { item, + ...flap, latestRunId: null, latestRunStatus: null, pendingRequestCount: 0, @@ -538,6 +600,7 @@ const make = Effect.gen(function* () { ORDER BY created_at DESC, message_id DESC LIMIT 1`; return { item, + ...flap, latestRunId: run === undefined ? null : RunId.make(run.run_id), latestRunStatus: run?.status ?? null, pendingRequestCount: pending?.count ?? 0, diff --git a/apps/server/src/provider/agentContextBudget.json b/apps/server/src/provider/agentContextBudget.json index defd10125f7b9..ce6d27233f0ef 100644 --- a/apps/server/src/provider/agentContextBudget.json +++ b/apps/server/src/provider/agentContextBudget.json @@ -1,5 +1,5 @@ { "claudeSystemAppendBytes": 5597, "codexAdditionalContextBytes": 7327, - "mcpToolListJsonBytes": 56426 + "mcpToolListJsonBytes": 57258 } diff --git a/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md b/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md index b9cf1722e8d4c..a5ebf8a97ad26 100644 --- a/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md +++ b/docs/jarvis/decisions/0012-ledger-fields-history-and-portfolio.md @@ -6,11 +6,13 @@ Accepted 2026-11-12. The ledger separates a work item's status from its reason for waiting. External waits depend on a vendor or another party. Natural waits depend on a real event. Decision waits need Chris's answer. Existing blocker prefixes become wait reasons during migration. A due check means the recorded next check time has arrived. It does not start work. -Every upsert retains its caller, time, and changed values. A run started with a client request id equal to a work item's key records its terminal outcome on that item without changing the item's status. Finishing a run does not prove that the work is done. +Every material upsert retains its caller, time, and changed values. An unchanged upsert writes neither a row nor history and preserves its last editor and timestamp. History retains the server-recorded sender record from [0013](0013-server-recorded-message-senders.md) for new MCP edits; old entries remain unattributed. A run started with a client request id equal to a work item's key records its terminal outcome on that item without changing the item's status. Finishing a run does not prove that the work is done. -An owner thread belongs to the ledger's environment. References to other environments retain their scope as links. +Omitted fields stay unchanged; explicit null clears nullable fields. `links` still replaces the list, while `addLinks` and `removeLinks` apply normalized set changes; removals win. Removing a URL also matches its Markdown link form. The resulting list cannot exceed 100 links. `handoffArgs` retains exact tool-call arguments as JSON bounded to 4096 UTF-8 bytes, not instructions or approval; never store secrets there. Changing it withdraws an existing approval. A blocked row without a wait reason defaults to decision and warns. When an upsert touches status, wait reason or blocker, contradictory `BLOCKED_TECH` or `WAIT_DECISION` prefixes with external/natural reasons warn without refusing the update. -The portfolio joins open work with each owner thread's latest run, pending requests, and a short result excerpt. A worker with no run for over 24 hours is flagged for attention. That flag does not establish failure or authorize a restart. The web panel reads the same ledger and provides no editing controls. +An owner thread belongs to the ledger's environment. JSON null clears it; ID inputs refuse the literal string "null", ignoring surrounding whitespace and case. Older rows with that string remain readable so an explicit null can repair them. Jarvis-owned work need not have an owner thread; the Jarvis inbox is not its worker. References to other environments retain their scope as links. + +The portfolio joins open work with each owner thread's latest run, pending requests, and a short result excerpt. A worker with no run for over 24 hours is flagged for attention. It also counts open-to-blocked and blocked-to-open transitions in the last 24 hours, flagging more than three as flapping, including work without an owner thread. Neither flag establishes failure or authorizes a restart. The web panel reads the same ledger and provides no editing controls. ## Alternatives diff --git a/packages/contracts/src/workLedger.ts b/packages/contracts/src/workLedger.ts index 85f2ebd828b4a..5095cd0d15623 100644 --- a/packages/contracts/src/workLedger.ts +++ b/packages/contracts/src/workLedger.ts @@ -9,6 +9,7 @@ import { TurnItemId, } from "./baseSchemas.ts"; import { UserInputAnsweringClient } from "./providerPolicy.ts"; +import { OrchestrationV2SenderClient } from "./orchestrationV2.ts"; const text = Schema.String.check(Schema.isMaxLength(8000)); const name = TrimmedNonEmptyString.check(Schema.isMaxLength(256)); @@ -26,6 +27,21 @@ const pageLimit = Schema.optional( NonNegativeInt.check(Schema.isBetween({ minimum: 1, maximum: 100 })), ); const ownerKind = Schema.Literals(["jarvis", "vision", "t3", "human"]); +const links = Schema.Array(Schema.String.check(Schema.isMaxLength(4096))).check( + Schema.isMaxLength(100), +); +const handoffArgs = Schema.Json.check( + Schema.makeFilter( + (value) => + new TextEncoder().encode(JSON.stringify(value)).byteLength <= 4096 || + "handoffArgs must be at most 4096 UTF-8 bytes of JSON.", + ), +); +const notStringNull = Schema.makeFilter( + (value: string) => + value.trim().toLowerCase() !== "null" || + 'The string "null" is not an ID. Send JSON null to clear a nullable field.', +); const fields = { title: TrimmedNonEmptyString.check(Schema.isMaxLength(512)), ownerKind, @@ -37,14 +53,15 @@ const fields = { nextCheckAt: Schema.NullOr(IsoDateTime), nextAction: Schema.NullOr(text), approvalNote: Schema.NullOr(text), - links: Schema.Array(Schema.String.check(Schema.isMaxLength(4096))).check(Schema.isMaxLength(100)), + links, + handoffArgs, }; /** Chris's answer to a question dialog whose question names the row as `Ledger key: `. */ export const WorkLedgerApprovalSource = Schema.Struct({ - threadId: ThreadId, - itemId: TurnItemId, + threadId: ThreadId.check(notStringNull), + itemId: TurnItemId.check(notStringNull), /** Which question of the dialog; needed when the dialog asked more than one. */ - questionId: Schema.optional(TrimmedNonEmptyString), + questionId: Schema.optional(TrimmedNonEmptyString.check(notStringNull)), }); export type WorkLedgerApprovalSource = typeof WorkLedgerApprovalSource.Type; /** Written only by the server after it verifies the source; the quotes come from the dialog. */ @@ -66,6 +83,7 @@ export type WorkLedgerApproval = typeof WorkLedgerApproval.Type; export const WorkLedgerItem = Schema.Struct({ key: name, ...fields, + handoffArgs: Schema.optional(handoffArgs), // Optional: an environment on an older build omits it. approval: Schema.optional(Schema.NullOr(WorkLedgerApproval)), lastRunId: Schema.NullOr(RunId), @@ -80,6 +98,9 @@ export type WorkLedgerItem = typeof WorkLedgerItem.Type; export const WorkLedgerUpsertInput = Schema.Struct({ key: name, ...Schema.Struct(fields).mapFields(Struct.map(Schema.optional)).fields, + ownerThreadId: Schema.optional(Schema.NullOr(ThreadId.check(notStringNull))), + addLinks: Schema.optional(links), + removeLinks: Schema.optional(links), /** A source to verify as Chris's approval, or null to revoke the recorded one. */ approval: Schema.optional(Schema.NullOr(Schema.Struct({ source: WorkLedgerApprovalSource }))), }); @@ -117,6 +138,7 @@ export const WorkLedgerHistoryEntry = Schema.Struct({ key: name, changedAt: IsoDateTime, changedBy: TrimmedNonEmptyString, + changedByClient: Schema.optional(Schema.NullOr(OrchestrationV2SenderClient)), changes: Schema.Record( Schema.String, Schema.Struct({ before: Schema.Unknown, after: Schema.Unknown }), @@ -141,6 +163,8 @@ export const PortfolioStatusResult = Schema.Struct({ pendingRequestCount: NonNegativeInt, resultExcerpt: Schema.NullOr(Schema.String), staleWorker: Schema.Boolean, + openBlockedFlips24h: Schema.optional(NonNegativeInt), + flapping: Schema.optional(Schema.Boolean), }), ), nextCursor: Schema.NullOr(name),