From 39fe8a531e425e856646481c00aac5d3395ed2b3 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:01:55 +0530 Subject: [PATCH 1/4] feat(kin): LEAD-14 end-to-end shadow week dry run Replays a recorded day through the full Kin path at L0 (queue, wake-up runner, lead tools, level gate, shadow entries, memory writer, routine content, summary and review cards) with a scripted provider, prints the owner's view and the memory remote's ref changes, and exits non-zero unless only kin/shadow/ moved, nothing left the owner's direct chat and nothing executed. Refuses a state directory in or at ~/.t3. Co-Authored-By: Claude Opus 5.5 --- .../scripts/kin-shadow-dry-run.day.json | 213 +++++ .../server/scripts/kin-shadow-dry-run.test.ts | 67 ++ apps/server/scripts/kin-shadow-dry-run.ts | 820 ++++++++++++++++++ .../src/kin/lead/WakeupRunner.testkit.ts | 33 +- docs/operations/kin-shadow-dry-run.md | 108 +++ 5 files changed, 1236 insertions(+), 5 deletions(-) create mode 100644 apps/server/scripts/kin-shadow-dry-run.day.json create mode 100644 apps/server/scripts/kin-shadow-dry-run.test.ts create mode 100644 apps/server/scripts/kin-shadow-dry-run.ts create mode 100644 docs/operations/kin-shadow-dry-run.md diff --git a/apps/server/scripts/kin-shadow-dry-run.day.json b/apps/server/scripts/kin-shadow-dry-run.day.json new file mode 100644 index 000000000000..fb8e59379731 --- /dev/null +++ b/apps/server/scripts/kin-shadow-dry-run.day.json @@ -0,0 +1,213 @@ +{ + "day": "2026-11-09", + "lead": { + "name": "Fixture Lead" + }, + "people": [ + { + "personId": "sam", + "handle": "sam", + "displayName": "Sam" + } + ], + "groups": [ + { + "chatId": "team", + "members": ["sam"] + } + ], + "workerProjects": ["fixture-project"], + "github": { + "reviews": [ + { + "repo": "example-org/app", + "number": 7, + "title": "Add request rate limits", + "url": "https://github.com/example-org/app/pull/7" + } + ], + "ciRed": [] + }, + "memory": { + "rules.md": "Invented standing rules for the dry run.\n", + "INDEX.md": "As of 2026-11-08T00:00:00.000Z\n", + "deferrals/def-rate-limits.md": "---\nid: \"def-rate-limits\"\nkind: \"deferral\"\ntitle: \"Start the rate-limit work\"\nstatus: \"open\"\ndue: \"2026-11-09T10:00Z\"\non_due: \"remind\"\nowner: \"fixture-lead\"\nrecorded_at: \"2026-11-02T09:00:00.000Z\"\nvalid_from: \"2026-11-02T09:00:00.000Z\"\ninvalid_at: null\nsuperseded_by: null\nreview_by: \"2026-12-01\"\nsource: \"https://example.invalid/messages/seed\"\nsaid_by: \"owner\"\ntrust: \"owner\"\nlinks: []\n---\nInvented deferral: start the rate-limit work on Monday.\n", + "commitments/com-docs.md": "---\nid: \"com-docs\"\nkind: \"commitment\"\ntitle: \"Docs for the public API\"\nstatus: \"open\"\ndue: \"2026-11-12T17:00Z\"\nowner: \"fixture-lead\"\nrecorded_at: \"2026-11-02T09:00:00.000Z\"\nvalid_from: \"2026-11-02T09:00:00.000Z\"\ninvalid_at: null\nsuperseded_by: null\nreview_by: \"2026-12-01\"\nsource: \"https://example.invalid/messages/seed\"\nsaid_by: \"sam\"\ntrust: \"member\"\nlinks: []\n---\nInvented commitment: Sam writes the API docs.\n" + }, + "events": [ + { + "_tag": "routine", + "id": "brief", + "at": "2026-11-09T08:30:00.000Z", + "routine": "morning_brief" + }, + { + "_tag": "message", + "id": "owner-morning", + "at": "2026-11-09T09:05:00.000Z", + "chat": "owner", + "from": "owner", + "body": "Morning. What needs me today?", + "lead": [ + { + "tool": "memory_search", + "arguments": { + "kind": "deferral" + } + }, + { + "tool": "kin_chat_post", + "arguments": { + "chatId": "$ownerChat", + "clientMessageId": "reply-owner-morning", + "intent": "answer", + "body": "Rate limits start today at 10:00, and Sam's PR example-org/app#7 is waiting for your review." + } + }, + { + "tool": "kin_journal", + "arguments": { + "saw": ["Owner asked what needs them today"], + "did": ["Listed today's deferral and the open review"], + "skipped": [] + } + }, + { + "tool": "kin_end", + "arguments": { + "summary": "Answered the owner's morning question" + } + } + ] + }, + { + "_tag": "message", + "id": "sam-review", + "at": "2026-11-09T10:15:00.000Z", + "chat": "team", + "from": "sam", + "body": "Can someone review example-org/app#7? I'd like it merged before lunch.", + "lead": [ + { + "tool": "kin_chat_post", + "arguments": { + "chatId": "$chat", + "clientMessageId": "reply-sam-review", + "intent": "answer", + "body": "I've asked the owner to review #7 before lunch." + } + }, + { + "tool": "request_action", + "arguments": { + "kind": "merge_pull_request", + "reason": "Sam asked for #7 to be merged before lunch.", + "sourceEventId": "$event", + "target": { + "_tag": "pull_request", + "host": "github.com", + "repo": "example-org/app", + "number": 7, + "mergeMethod": "squash", + "deleteBranchAfter": true + } + } + }, + { + "tool": "memory_write", + "arguments": { + "op": "create", + "sourceEventId": "$event", + "item": { + "id": "com-review-7", + "kind": "commitment", + "title": "Review example-org/app#7 before lunch", + "body": "Sam asked for a review of #7 before lunch.", + "status": "open", + "due": "2026-11-09T12:00Z", + "recorded_at": "2026-11-09T10:15:00.000Z", + "valid_from": "2026-11-09T10:15:00.000Z", + "invalid_at": null, + "superseded_by": null, + "source": "chat", + "said_by": "sam", + "trust": "member", + "links": ["example-org/app#7"] + } + } + }, + { + "tool": "kin_journal", + "arguments": { + "saw": ["Sam asked for a review of #7"], + "did": ["Drafted a reply", "Drafted a merge request for the owner"], + "skipped": [] + } + }, + { + "tool": "kin_end", + "arguments": { + "summary": "Handled Sam's review request" + } + } + ] + }, + { + "_tag": "github", + "id": "ci-failed-7", + "at": "2026-11-09T13:40:00.000Z", + "eventName": "check_suite", + "repo": "example-org/app", + "summary": "CI failed on example-org/app#7", + "lead": [ + { + "tool": "kin_delegate", + "arguments": { + "kind": "build", + "title": "Fix CI on #7", + "goal": "Make the failing check on example-org/app#7 pass.", + "brief": "The check_suite on #7 failed after the last push.", + "projectId": "fixture-project", + "sourceEventId": "$event" + } + }, + { + "tool": "kin_end", + "arguments": { + "summary": "Would start a worker for the CI failure" + } + } + ] + }, + { + "_tag": "watchdog", + "id": "docs-check", + "at": "2026-11-09T15:00:00.000Z", + "finding": "The API docs commitment is due Thursday with no update.", + "lead": [ + { + "tool": "kin_defer", + "arguments": { + "what": "Ask Sam how the API docs are going", + "due": "2026-11-11T09:00:00Z", + "onDue": "remind", + "chatId": "$ownerChat", + "sourceEventId": "$event" + } + }, + { + "tool": "kin_end", + "arguments": { + "summary": "Deferred a check on the docs" + } + } + ] + }, + { + "_tag": "routine", + "id": "summary", + "at": "2026-11-09T18:30:00.000Z", + "routine": "evening_summary" + } + ] +} diff --git a/apps/server/scripts/kin-shadow-dry-run.test.ts b/apps/server/scripts/kin-shadow-dry-run.test.ts new file mode 100644 index 000000000000..d179699cbaf0 --- /dev/null +++ b/apps/server/scripts/kin-shadow-dry-run.test.ts @@ -0,0 +1,67 @@ +import * as NodeServices from "@effect/platform-node/NodeServices"; +import { assert, it } from "@effect/vitest"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; + +import * as Vcs from "../src/vcs/VcsProcess.ts"; +import { runDryRun } from "./kin-shadow-dry-run.ts"; + +const day = new URL("./kin-shadow-dry-run.day.json", import.meta.url).pathname; +const services = Vcs.layer.pipe(Layer.provideMerge(NodeServices.layer)); + +it.live( + "replays the recorded day at L0: only the shadow branch moves, nothing leaves the owner's chat, nothing runs", + () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped()); + const report = yield* runDryRun({ + dayFile: day, + stateDir: `${root}/state`, + agentId: "fixture-lead", + home: `${root}/home`, + }); + assert.deepStrictEqual(report.violations, []); + assert.deepStrictEqual( + report.refChanges.map(({ ref, before }) => ({ ref, before })), + [{ ref: "refs/heads/kin/shadow/fixture-lead", before: null }], + ); + // The group reply, the merge request and the worker were drafted and held back. + assert.deepStrictEqual( + report.toolCalls.filter((call) => call.outcome !== "ok"), + [ + { tool: "kin_chat_post", outcome: "shadowed" }, + { tool: "request_action", outcome: "shadowed" }, + { tool: "kin_delegate", outcome: "shadowed" }, + ], + ); + const text = report.lines.join("\n"); + assert.include(text, "[shadow_summary card] What Fixture Lead would have done today"); + assert.include(text, "[shadow_review card] Review what Fixture Lead would have done today"); + assert.include(text, "[evening_summary card, 2026-11-09]"); + }).pipe(Effect.provide(services), Effect.scoped), +); + +it.live("refuses a state directory that is the live ~/.t3 or inside it, before creating it", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped()); + yield* fs.makeDirectory(`${root}/home/.t3`, { recursive: true }); + yield* fs.symlink(`${root}/home/.t3`, `${root}/alias`); + for (const stateDir of [ + `${root}/home/.t3`, + `${root}/home/.t3/dry-run`, + `${root}/alias/dry-run`, + ]) { + const error = yield* runDryRun({ + dayFile: day, + stateDir, + agentId: "fixture-lead", + home: `${root}/home`, + }).pipe(Effect.flip); + assert.strictEqual(error._tag, "KinDryRunError"); + } + assert.deepStrictEqual(yield* fs.readDirectory(`${root}/home/.t3`), []); + }).pipe(Effect.provide(services), Effect.scoped), +); diff --git a/apps/server/scripts/kin-shadow-dry-run.ts b/apps/server/scripts/kin-shadow-dry-run.ts new file mode 100644 index 000000000000..990bef2c98f8 --- /dev/null +++ b/apps/server/scripts/kin-shadow-dry-run.ts @@ -0,0 +1,820 @@ +#!/usr/bin/env node +// Ops only: replays a recorded Kin day through the full lead path at L0, with a scripted +// provider instead of a model, and checks that memory reached only kin/shadow/. +// Runbook: docs/operations/kin-shadow-dry-run.md. +import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; +import * as NodeRuntime from "@effect/platform-node/NodeRuntime"; +import * as NodeServices from "@effect/platform-node/NodeServices"; +import * as NodeOS from "node:os"; +import { + AuthSessionId, + AuthStandardClientScopes, + EnvironmentId, + KinAgentId, + KinChatId, + KinEvent, + KinOrgId, + KinPersonId, + KinRoutineCard, + KinShadowReviewCard, + KinShadowSummaryCard, + ProviderDriverKind, + ProviderInstanceId, + type ThreadId, +} from "@t3tools/contracts"; +import * as Cause from "effect/Cause"; +import * as Clock from "effect/Clock"; +import * as Console from "effect/Console"; +import * as ConfigProvider from "effect/ConfigProvider"; +import * as Context from "effect/Context"; +import * as DateTime from "effect/DateTime"; +import * as Effect from "effect/Effect"; +import * as FileSystem from "effect/FileSystem"; +import * as Layer from "effect/Layer"; +import * as Option from "effect/Option"; +import * as Path from "effect/Path"; +import * as References from "effect/References"; +import * as Schema from "effect/Schema"; +import * as SqlClient from "effect/sql/SqlClient"; +import * as TestClock from "effect/testing/TestClock"; +import { McpSchema } from "effect/ai"; +// oxlint-disable-next-line t3code/no-raw-mcp-registration -- calls the Kin tools toolkitRegistration registered and registers none. +import { McpServer } from "effect/ai"; +import { Command, Flag } from "effect/cli"; + +import { McpInvocationContext, type McpInvocationScope } from "../src/mcp/McpInvocationContext.ts"; +import * as McpHttpServer from "../src/mcp/McpHttpServer.ts"; +import { provideDeterministicTestRuntime } from "../src/orchestration-v2/testkit/DeterministicRuntime.ts"; +import * as Sqlite from "../src/persistence/Sqlite.ts"; +import type { ProviderInstance } from "@t3tools/provider-core/server/driver"; +import { ProviderInstanceRegistry } from "../src/provider/ProviderInstanceRegistry.ts"; +import * as Vcs from "../src/vcs/VcsProcess.ts"; +import * as KinApprovalsMcp from "../src/kin/approvals/mcp.ts"; +import * as RequestAction from "../src/kin/approvals/RequestAction.ts"; +import { KinChatService } from "../src/kin/chat/KinChatService.ts"; +import * as KinChatRepository from "../src/kin/chat/KinChatRepository.ts"; +import { KinIdentity } from "../src/kin/chat/KinIdentity.ts"; +import { environment } from "../src/kin/chat/TaskCard.testkit.ts"; +import * as Kin from "../src/kin/layer.ts"; +import { KinShadowSummary } from "../src/kin/lead/KinLevels.ts"; +import * as KinEventQueue from "../src/kin/lead/KinEventQueue.ts"; +import * as KinLeadRegistry from "../src/kin/lead/KinLeadRegistry.ts"; +import * as LeadMemory from "../src/kin/lead/LeadMemory.ts"; +import { KinLeadPrompt } from "../src/kin/lead/LeadPrompt.ts"; +import * as RoutineContent from "../src/kin/lead/RoutineContent.ts"; +import * as WakeupRunner from "../src/kin/lead/WakeupRunner.ts"; +import { orchestrationStack } from "../src/kin/lead/WakeupRunner.testkit.ts"; +import * as Workers from "../src/kin/lead/Workers.ts"; +import { KinLeadToolkit } from "../src/kin/lead/mcp/tools.ts"; +import { handlers as leadHandlers } from "../src/kin/lead/mcp/handlers.ts"; +import { KinChatToolkit, handlers as chatHandlers } from "../src/kin/mcp/KinChatToolkit.ts"; +import { memoryGit } from "../src/kin/memory/git.ts"; +import * as Memory from "../src/kin/memory/Memory.ts"; +import * as Cache from "../src/kin/memory/MemoryCache.ts"; +import { MemoryConfig } from "../src/kin/memory/MemoryConfig.ts"; +import * as Writer from "../src/kin/memory/MemoryWriter.ts"; +import * as Scan from "../src/kin/memory/secretScan.ts"; +import * as KinPersistence from "../src/kin/persistence/KinPersistence.ts"; + +const ToolCall = Schema.Struct({ + tool: Schema.String, + arguments: Schema.Record(Schema.String, Schema.Unknown), +}); +const step = { + id: Schema.String, + at: Schema.String, + /** What the lead does in the wake-up that handles this event, as recorded tool calls. */ + lead: Schema.optional(Schema.Array(ToolCall)), +}; +const DayEvent = Schema.Union([ + Schema.TaggedStruct("message", { + ...step, + chat: Schema.String, + from: Schema.String, + body: Schema.String, + }), + Schema.TaggedStruct("routine", { + ...step, + routine: Schema.Literals(["morning_brief", "evening_summary"]), + }), + Schema.TaggedStruct("github", { + ...step, + eventName: Schema.String, + repo: Schema.String, + summary: Schema.String, + }), + Schema.TaggedStruct("watchdog", { ...step, finding: Schema.String }), +]); +type DayEvent = typeof DayEvent.Type; + +/** A recorded day. Every value is synthetic; real organization data never goes in the repo. */ +const RecordedDay = Schema.Struct({ + day: Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/)), + lead: Schema.Struct({ name: Schema.String }), + people: Schema.Array( + Schema.Struct({ personId: Schema.String, handle: Schema.String, displayName: Schema.String }), + ), + groups: Schema.Array( + Schema.Struct({ chatId: Schema.String, members: Schema.Array(Schema.String) }), + ), + workerProjects: Schema.Array(Schema.String), + github: Schema.Struct({ + reviews: Schema.Array( + Schema.Struct({ + repo: Schema.String, + number: Schema.Number, + title: Schema.String, + url: Schema.String, + }), + ), + ciRed: Schema.Array(Schema.Struct({ repo: Schema.String, branch: Schema.String })), + }), + /** Seeds the local fixture remote; unused when --memory-url names a real repository. */ + memory: Schema.Record(Schema.String, Schema.String), + events: Schema.Array(DayEvent), +}); +type RecordedDay = typeof RecordedDay.Type; +const decodeDay = Schema.decodeUnknownEffect(Schema.fromJsonString(RecordedDay)); +const decodeEvent = Schema.decodeUnknownEffect(KinEvent); +const decodeEventIds = Schema.decodeUnknownEffect( + Schema.fromJsonString(Schema.Array(Schema.String)), +); + +class KinDryRunError extends Schema.TaggedError()("KinDryRunError", { + message: Schema.String, +}) {} + +interface DryRunOptions { + readonly dayFile: string; + readonly stateDir: string; + readonly agentId: string; + /** Defaults to a bare repository seeded from the day's `memory` inside the state directory. */ + readonly memoryUrl?: string | undefined; + readonly credentialHelper?: string | undefined; + readonly sshCommand?: string | undefined; + /** The home directory whose `.t3` is the live install; tests pass a temporary one. */ + readonly home?: string | undefined; +} + +interface RefChange { + readonly ref: string; + readonly before: string | null; + readonly after: string | null; +} + +interface DryRunReport { + readonly lines: ReadonlyArray; + readonly refChanges: ReadonlyArray; + readonly violations: ReadonlyArray; + readonly toolCalls: ReadonlyArray<{ readonly tool: string; readonly outcome: string }>; +} + +const orgId = KinOrgId.make("kin-default"); +const instanceId = ProviderInstanceId.make("codex"); +// Workers read only these fields to pick a model; at L0 no provider ever starts. +const codexInstance = { + instanceId, + driverKind: ProviderDriverKind.make("codex"), + enabled: true, +} as Pick as ProviderInstance; +const providers = Layer.mock(ProviderInstanceRegistry)({ + getInstance: Effect.fn("KinDryRun.getInstance")((id) => + Effect.succeed(id === instanceId ? codexInstance : undefined), + ), +}); +const ownerSession = { + sessionId: AuthSessionId.make("kin-dry-run-owner"), + subject: "kin-dry-run", + method: "browser-session-cookie" as const, + scopes: AuthStandardClientScopes, +}; +const isoAt = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(ms)); +const clockLabel = (ms: number) => isoAt(ms).slice(11, 16); +const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown)); +const decodeRoutineCard = Schema.decodeOption(Schema.fromJsonString(KinRoutineCard)); +const decodeSummaryCard = Schema.decodeOption(Schema.fromJsonString(KinShadowSummaryCard)); +const decodeReviewCard = Schema.decodeOption(Schema.fromJsonString(KinShadowReviewCard)); + +/** Refuses the live install: the state directory may not be `~/.t3` or anything below it. */ +const refuseLiveHome = Effect.fn("KinDryRun.refuseLiveHome")(function* ( + stateDir: string, + home: string, +) { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const real = (target: string) => + fs.realPath(target).pipe(Effect.orElseSucceed(() => path.resolve(target))); + // Resolve the deepest existing ancestor, so a symlink into ~/.t3 is caught before creation. + const resolve = Effect.fn("KinDryRun.resolve")(function* (target: string) { + let existing = path.resolve(target); + const rest: Array = []; + while (!(yield* fs.exists(existing))) { + const parent = path.dirname(existing); + if (parent === existing) break; + rest.unshift(path.basename(existing)); + existing = parent; + } + return path.join(yield* real(existing), ...rest); + }); + const state = yield* resolve(stateDir); + for (const live of new Set([ + path.join(path.resolve(home), ".t3"), + yield* resolve(path.join(home, ".t3")), + ])) + if (state === live || state.startsWith(live + path.sep)) + return yield* new KinDryRunError({ + message: `Refusing ${stateDir}: it is the live T3 home (${live}) or inside it. Use a temporary --state-dir.`, + }); + return state; +}); + +const git = Effect.fn("KinDryRun.git")(function* (cwd: string, args: ReadonlyArray) { + const result = yield* (yield* Vcs.VcsProcess).run({ + operation: "kin.dryRun.git", + command: "git", + cwd, + args: [ + "-c", + "user.name=Kin dry run", + "-c", + "user.email=dry-run@example.invalid", + "-c", + "commit.gpgsign=false", + ...args, + ], + allowNonZeroExit: true, + }); + if (result.exitCode !== 0) + return yield* new KinDryRunError({ message: `git ${args[0]} failed: ${result.stderr.trim()}` }); + return result.stdout; +}); + +/** A local bare remote holding the day's fixture memory, so no test touches a real repository. */ +const seedFixtureRemote = Effect.fn("KinDryRun.seedFixtureRemote")(function* ( + stateDir: string, + memory: RecordedDay["memory"], +) { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const seed = path.join(stateDir, "fixture-seed"); + const remote = path.join(stateDir, "fixture-memory.git"); + yield* fs.makeDirectory(seed, { recursive: true }); + yield* git(seed, ["init", "-q", "-b", "main"]); + for (const [file, text] of Object.entries(memory)) { + yield* fs.makeDirectory(path.dirname(path.join(seed, file)), { recursive: true }); + yield* fs.writeFileString(path.join(seed, file), text); + } + yield* git(seed, ["add", "--", "."]); + yield* git(seed, ["commit", "-q", "-m", "Fixture memory"]); + yield* git(stateDir, ["clone", "-q", "--bare", "--", seed, remote]); + yield* fs.remove(seed, { recursive: true }); + return remote; +}); + +const listRefs = Effect.fn("KinDryRun.listRefs")(function* (stateDir: string, url: string) { + const out = yield* memoryGit(stateDir, ["ls-remote", "--", url]); + const refs = new Map(); + for (const line of out.split("\n")) { + const [sha, ref] = line.trim().split("\t"); + if (sha && ref) refs.set(ref, sha); + } + return refs; +}); + +const diffRefs = (before: Map, after: Map) => + [...new Set([...before.keys(), ...after.keys()])] + .toSorted() + .map((ref) => ({ ref, before: before.get(ref) ?? null, after: after.get(ref) ?? null })) + .filter((change) => change.before !== change.after); + +const substitute = (value: unknown, vars: Record): unknown => + typeof value === "string" && value.startsWith("$") && vars[value.slice(1)] !== undefined + ? vars[value.slice(1)] + : Array.isArray(value) + ? value.map((item) => substitute(item, vars)) + : typeof value === "object" && value !== null + ? Object.fromEntries(Object.entries(value).map(([k, v]) => [k, substitute(v, vars)])) + : value; +const substituteArguments = ( + args: Readonly>, + vars: Record, +) => Object.fromEntries(Object.entries(args).map(([key, value]) => [key, substitute(value, vars)])); + +const outcomeOf = (result: McpSchema.CallToolResult) => { + const text = result.content + .map((part) => (part.type === "text" ? part.text : "")) + .join(" ") + .slice(0, 160); + const structured = JSON.stringify(result.structuredContent ?? {}); + if (result.isError === true) return `refused: ${text}`; + return structured.includes('"shadowed":true') ? "shadowed" : "ok"; +}; + +const renderWidget = (type: string, state: unknown): ReadonlyArray => { + const json = typeof state === "string" ? state : JSON.stringify(state); + if (type === "routine") { + const card = decodeRoutineCard(json); + return Option.match(card, { + onNone: () => [" [routine card]"], + onSome: (card) => [ + ` [${card.routine} card, ${card.day}]`, + ...card.rows.map( + (row) => ` ${row.section}: ${row.title}${row.note ? ` (${row.note})` : ""}`, + ), + ], + }); + } + const card = + type === "shadow_summary" + ? decodeSummaryCard(json) + : type === "shadow_review" + ? decodeReviewCard(json) + : Option.none(); + return Option.match(card, { + onNone: () => [` [${type} card]`], + onSome: (card) => [ + ` [${type} card] ${card.title}`, + ...card.entries.map( + (entry) => + ` - ${entry.tool} -> ${entry.wouldTarget || "(no target)"}: ${entry.preview.replaceAll("\n", " ")}`, + ), + ], + }); +}; + +/** Replays the day and returns the owner's view, the remote's ref changes and every violation. */ +export const runDryRun = Effect.fn("KinDryRun.run")( + function* (options: DryRunOptions) { + const fs = yield* FileSystem.FileSystem; + const path = yield* Path.Path; + const stateDir = yield* refuseLiveHome(options.stateDir, options.home ?? NodeOS.homedir()); + if ((yield* fs.exists(stateDir)) && (yield* fs.readDirectory(stateDir)).length > 0) + return yield* new KinDryRunError({ + message: `State directory ${stateDir} is not empty. Use a fresh one for each dry run.`, + }); + yield* fs.makeDirectory(stateDir, { recursive: true }); + const day = yield* decodeDay(yield* fs.readFileString(options.dayFile)).pipe( + Effect.mapError( + (error) => new KinDryRunError({ message: `Invalid day file: ${error.message}` }), + ), + ); + const agentId = KinAgentId.make(options.agentId); + const memoryUrl = options.memoryUrl ?? (yield* seedFixtureRemote(stateDir, day.memory)); + const memoryConfig = MemoryConfig.of({ + baseDirectory: path.join(stateDir, "kin"), + repositories: [{ orgId, repoUrl: memoryUrl, path: encodeURIComponent(orgId) }], + ...(options.credentialHelper === undefined + ? {} + : { credentialHelper: options.credentialHelper }), + ...(options.sshCommand === undefined ? {} : { sshCommand: options.sshCommand }), + }); + const refsBefore = yield* listRefs(stateDir, memoryUrl).pipe( + Effect.provideService(MemoryConfig, memoryConfig), + ); + const events = day.events.toSorted((a, b) => Date.parse(a.at) - Date.parse(b.at)); + const byId = new Map(events.map((event) => [event.id, event])); + const start = Date.parse(`${day.day}T00:00:00.000Z`); + + // The scripted provider: each lead turn replays the tool calls recorded for its events. + const turn = { run: (_threadId: ThreadId): Effect.Effect => Effect.void }; + const database = KinPersistence.layer.pipe( + Layer.provideMerge( + Sqlite.layerFromPath(path.join(stateDir, "userdata", "kin-dry-run.sqlite")), + ), + Layer.provide(NodeServices.layer), + ); + const stack = orchestrationStack({ + database, + onTurn: ({ threadId }) => Effect.suspend(() => turn.run(threadId)), + }); + const kinServer = Kin.layer.pipe( + Layer.provide(ConfigProvider.layer(ConfigProvider.fromUnknown({ KIN_ENABLED: true }))), + Layer.provideMerge(environment), + Layer.provideMerge(stack), + ); + + const lines: Array = []; + const toolCalls: Array<{ tool: string; outcome: string }> = []; + const violations: Array = []; + + yield* TestClock.setTime(start); + yield* Effect.gen(function* () { + const kin = yield* Kin.KinServer; + const services = Option.getOrThrow(kin.services); + const identity = Context.get(services, KinIdentity); + const chats = Context.get(services, KinChatService); + const queue = Context.get(services, KinEventQueue.KinEventQueue); + const repo = yield* KinChatRepository.KinChatRepository; + const sql = yield* SqlClient.SqlClient; + + const [owner] = yield* identity.resolve(ownerSession); + if (owner === undefined || owner._tag !== "person") + return yield* new KinDryRunError({ message: "No owner identity." }); + const createdAt = isoAt(start); + yield* repo.insertAgent({ + orgId, + agentId, + displayName: day.lead.name, + role: "lead", + ownerPersonId: owner.personId, + createdAt, + }); + const direct = yield* chats.createDirect(owner, { orgId, agentId }); + const models = yield* encodeJson({ + strong: { instanceId, model: "dry-run-strong" }, + cheap: { instanceId, model: "dry-run-cheap" }, + }); + const workerProjects = yield* encodeJson(day.workerProjects); + // Seeded at L0: the level the shadow week runs at, and the one this script checks. + yield* sql`INSERT INTO kin_leads (agent_id, org_id, name, level, level_since, models_json, worker_projects_json, owner_chat_id) + VALUES (${agentId}, ${orgId}, ${day.lead.name}, 'L0', ${start}, ${models}, ${workerProjects}, ${direct.chatId})`; + for (const person of day.people) + yield* sql`INSERT INTO kin_people (person_id, org_id, handle, display_name, created_at) + VALUES (${person.personId}, ${orgId}, ${person.handle}, ${person.displayName}, ${createdAt})`; + for (const group of day.groups) { + yield* sql`INSERT INTO kin_chats (chat_id, org_id, kind, last_seq, created_at) + VALUES (${group.chatId}, ${orgId}, 'team_group', 0, ${createdAt})`; + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, agent_id, role, joined_at) + VALUES (${`${group.chatId}:${agentId}`}, ${orgId}, ${group.chatId}, 'agent', ${agentId}, 'member', ${createdAt})`; + for (const personId of group.members) + yield* sql`INSERT INTO kin_chat_members (member_id, org_id, chat_id, principal_kind, person_id, role, joined_at) + VALUES (${`${group.chatId}:${personId}`}, ${orgId}, ${group.chatId}, 'person', ${personId}, 'member', ${createdAt})`; + } + + const recovery = Layer.succeed(Memory.MemoryRecoveryHooks, { + notify: Effect.fn("KinDryRun.recoveryNotice")((notice) => + Effect.sync(() => violations.push(`Memory recovery: ${notice.reason}`)), + ), + }); + const memory = Memory.layer.pipe(Layer.provide(recovery)); + const writer = Writer.layer.pipe( + Layer.provideMerge(LeadMemory.authority), + Layer.provide(Cache.layer), + Layer.provide(Scan.layer), + Layer.provide( + Layer.succeed(Writer.MemoryWriterHooks, { + notify: Effect.fn("KinDryRun.writerNotice")((notice) => + Effect.sync(() => + violations.push(`Memory writer refused a commit: ${notice.error._tag}`), + ), + ), + }), + ), + Layer.provide(recovery), + ); + const github = Layer.succeed(RoutineContent.KinRoutineGithubReader, { + read: Effect.fn("KinDryRun.githubSnapshot")(() => + Effect.succeed({ + reviews: day.github.reviews, + ciRed: day.github.ciRed, + failedRepos: 0, + truncatedRepos: 0, + repos: new Set([...day.github.reviews, ...day.github.ciRed].map((item) => item.repo)) + .size, + }), + ), + }); + // The dry run never reads GitHub: below L3 a request needs only the project's spelling. + const facts = Layer.succeed(RequestAction.KinPullRequestFacts, { + canonical: Effect.fn("KinDryRun.canonicalTarget")(({ target }) => Effect.succeed(target)), + read: Effect.fn("KinDryRun.readPullRequest")(function* () { + return yield* Effect.die("The dry run never reads pull requests from GitHub."); + }), + }); + const tools = Layer.mergeAll( + McpHttpServer.toolkitRegistration(KinLeadToolkit, leadHandlers), + McpHttpServer.toolkitRegistration(KinChatToolkit, chatHandlers), + KinApprovalsMcp.registrationWith(facts), + ).pipe(Layer.provideMerge(McpHttpServer.layerInProcessMcpServer)); + const lead = Layer.mergeAll(WakeupRunner.layer, tools).pipe( + Layer.provideMerge(Workers.layer), + Layer.provideMerge(LeadMemory.layer), + Layer.provideMerge(writer), + Layer.provideMerge(RoutineContent.layer.pipe(Layer.provide(github))), + Layer.provideMerge(KinLeadPrompt.layer), + Layer.provideMerge(Layer.mergeAll(memory, KinChatRepository.layer, KinLeadRegistry.layer)), + Layer.provide(Layer.succeed(MemoryConfig, memoryConfig)), + Layer.provide(Layer.succeedContext(services)), + ); + + yield* Effect.gen(function* () { + const runner = yield* WakeupRunner.WakeupRunner; + const registry = yield* KinLeadRegistry.KinLeadRegistry; + const server = yield* McpServer.McpServer; + const context = yield* Effect.context(); + const client = McpSchema.McpServerClient.of({ + clientId: 1, + clientCapabilities: {}, + clientInfo: { name: "kin-dry-run", version: "1" }, + protocolVersion: "2025-06-18", + initializePayload: { + protocolVersion: "2025-06-18", + capabilities: {}, + clientInfo: { name: "kin-dry-run", version: "1" }, + }, + getClient: Effect.die("unused"), + }); + const messages = new Map(); + + turn.run = Effect.fn("KinDryRun.leadTurn")( + function* (threadId: ThreadId) { + const caller = registry.lookup(threadId); + if (caller === undefined) return; + const [row] = yield* sql<{ eventIds: string }>`SELECT event_ids AS "eventIds" + FROM kin_wakeups WHERE org_id = ${orgId} AND wakeup_id = ${caller.wakeupId}`; + const scope: McpInvocationScope = { + environmentId: EnvironmentId.make("kin-dry-run"), + requestNamespace: "kin-dry-run", + issuedAt: 0, + capabilities: new Set(), + client: undefined, + thread: { + threadId, + providerSessionId: `dry-run:${caller.wakeupId}`, + providerInstanceId: instanceId, + }, + }; + for (const eventId of yield* decodeEventIds(row?.eventIds ?? "[]")) { + const event = byId.get(eventId); + const message = messages.get(eventId); + const vars: Record = { + ownerChat: direct.chatId, + event: eventId, + ...(message === undefined + ? {} + : { chat: message.chatId, message: message.messageId }), + }; + for (const call of event?.lead ?? []) { + const result = yield* server + .callTool({ + name: call.tool, + arguments: substituteArguments(call.arguments, vars), + }) + .pipe( + Effect.provideService(McpInvocationContext, scope), + Effect.provideService(McpSchema.McpServerClient, client), + Effect.provideService(Kin.KinServer, kin), + Effect.provideService(KinIdentity, identity), + Effect.provideService( + KinShadowSummary, + Context.get(services, KinShadowSummary), + ), + ); + const outcome = outcomeOf(result); + toolCalls.push({ tool: call.tool, outcome }); + lines.push(` ${call.tool}: ${outcome}`); + } + } + }, + Effect.provideContext(context), + Effect.catchCause((cause) => + Effect.sync(() => violations.push(`Lead turn failed: ${Cause.pretty(cause)}`)), + ), + ); + + const advanceTo = Effect.fn("KinDryRun.advanceTo")(function* (at: number) { + const now = yield* Clock.currentTimeMillis; + if (at > now) yield* TestClock.adjust(at - now); + }); + let wakeups = 0; + const drain = Effect.fn("KinDryRun.drain")(function* (limit: number) { + while (true) { + const next = yield* queue.nextReady(orgId); + if (next === undefined || !Number.isFinite(next.readyAt) || next.readyAt > limit) + return; + if (++wakeups > 200) + return yield* new KinDryRunError({ message: "The queue did not settle." }); + yield* advanceTo(next.readyAt); + lines.push(` ${clockLabel(yield* Clock.currentTimeMillis)} wake-up ${wakeups}`); + yield* runner.runOnce(orgId, next.agentId); + } + }); + const replay = Effect.fn("KinDryRun.replay")(function* (event: DayEvent) { + const at = isoAt(Date.parse(event.at)); + const base = { orgId, agentId, eventId: event.id, receivedAt: at, dedupeKey: event.id }; + lines.push(` ${clockLabel(Date.parse(at))} ${event._tag} ${event.id}`); + switch (event._tag) { + case "message": { + const chatId = event.chat === "owner" ? direct.chatId : KinChatId.make(event.chat); + const sent = yield* chats.send( + event.from === "owner" + ? owner + : { _tag: "person", orgId, personId: KinPersonId.make(event.from) }, + { chatId, body: event.body, clientMessageId: event.id }, + ); + messages.set(event.id, { chatId: sent.chatId, messageId: sent.messageId }); + return yield* decodeEvent({ + ...base, + _tag: "chat.message", + provenance: sent.author, + chatId: sent.chatId, + messageId: sent.messageId, + }); + } + case "routine": + return yield* decodeEvent({ + ...base, + _tag: "routine", + provenance: { _tag: "system" }, + routine: event.routine, + dueAt: at, + }); + case "github": + return yield* decodeEvent({ + ...base, + _tag: "github", + provenance: { _tag: "system" }, + deliveryId: event.id, + eventName: event.eventName, + repo: event.repo, + summary: event.summary, + scheduledTaskId: `kin-dry-run:${event.id}`, + webhookDeliveryId: `kin-dry-run:${event.id}`, + }); + case "watchdog": + return yield* decodeEvent({ + ...base, + _tag: "watchdog", + provenance: { _tag: "system" }, + finding: event.finding, + itemIds: [], + }); + } + }); + + lines.push( + `Kin shadow dry run: ${day.day}, lead ${agentId} at L0`, + `Memory remote: ${memoryUrl}`, + "", + "Replay:", + ); + for (const event of events) { + yield* drain(Date.parse(event.at)); + yield* advanceTo(Date.parse(event.at)); + yield* queue.enqueue(yield* replay(event)); + } + yield* drain(Infinity); + + const [running] = yield* sql<{ n: number }>`SELECT COUNT(*) AS n FROM kin_wakeups + WHERE org_id = ${orgId} AND status = 'running'`; + if ((running?.n ?? 0) > 0) violations.push("A wake-up is still running."); + const unfinished = yield* sql<{ + eventId: string; + state: string; + }>`SELECT event_id AS "eventId", state + FROM kin_events WHERE org_id = ${orgId} AND state <> 'done' ORDER BY event_id`; + for (const row of unfinished) violations.push(`Event ${row.eventId} ended ${row.state}.`); + const failed = yield* sql<{ + wakeupId: string; + status: string; + }>`SELECT wakeup_id AS "wakeupId", status + FROM kin_wakeups WHERE org_id = ${orgId} AND status <> 'completed' ORDER BY started_at, wakeup_id`; + for (const row of failed) violations.push(`Wake-up ${row.wakeupId} ended ${row.status}.`); + + lines.push("", "Owner's direct chat:"); + const posted = yield* sql<{ + createdAt: string; + authorKind: string; + body: string; + widgetId: string | null; + }>`SELECT created_at AS "createdAt", author_kind AS "authorKind", body, widget_id AS "widgetId" + FROM kin_messages WHERE org_id = ${orgId} AND chat_id = ${direct.chatId} ORDER BY seq`; + const widgets = new Map( + (yield* sql<{ + widgetId: string; + type: string; + state: string; + }>`SELECT widget_id AS "widgetId", type, state_json AS state + FROM kin_widgets WHERE org_id = ${orgId} AND chat_id = ${direct.chatId} ORDER BY widget_id`).map( + (row) => [row.widgetId, row], + ), + ); + for (const message of posted) { + const who = + message.authorKind === "human" + ? "Owner" + : message.authorKind === "agent" + ? day.lead.name + : "Kin"; + const [first = "", ...rest] = message.body.split("\n"); + lines.push( + ` ${message.createdAt.slice(11, 16)} ${who}: ${first}`, + ...rest.map((line) => ` ${line}`), + ); + const widget = message.widgetId === null ? undefined : widgets.get(message.widgetId); + if (widget !== undefined) lines.push(...renderWidget(widget.type, widget.state)); + } + + // Check 2: at L0 nothing but people's own messages lands outside the owner's direct chat. + const outside = yield* sql<{ + chatId: string; + authorKind: string; + status: string; + }>`SELECT chat_id AS "chatId", author_kind AS "authorKind", status + FROM kin_messages WHERE org_id = ${orgId} AND chat_id <> ${direct.chatId} AND author_kind <> 'human' ORDER BY seq`; + for (const row of outside) + violations.push( + `A ${row.authorKind} message (${row.status}) reached ${row.chatId}, not the owner's direct chat.`, + ); + // Check 3: nothing executed: no worker, no pending action, no thread but the lead's. + const [workers] = yield* sql<{ + n: number; + }>`SELECT COUNT(*) AS n FROM kin_workers WHERE org_id = ${orgId}`; + if ((workers?.n ?? 0) > 0) violations.push(`${workers?.n} worker(s) launched.`); + const actions = yield* sql<{ + actionId: string; + state: string; + }>`SELECT action_id AS "actionId", state + FROM kin_pending_actions WHERE org_id = ${orgId} ORDER BY action_id`; + for (const action of actions) + violations.push(`Pending action ${action.actionId} exists (${action.state}).`); + const strays = yield* sql<{ threadId: string }>`SELECT t.thread_id AS "threadId" + FROM orchestration_v2_projection_threads t + WHERE NOT EXISTS (SELECT 1 FROM kin_agent_threads a + WHERE a.org_id = ${orgId} AND a.agent_id = ${agentId} AND a.thread_id = t.thread_id) + ORDER BY t.thread_id`; + for (const row of strays) + violations.push(`Thread ${row.threadId} was started outside the lead.`); + }).pipe(Effect.provide(lead)); + }).pipe( + Effect.provide( + Layer.mergeAll(KinChatRepository.layer, providers, NodeCrypto.layer).pipe( + Layer.provideMerge(kinServer), + ), + ), + Effect.scoped, + ); + + // Check 1: the remote gained or changed only this lead's shadow branch. + const refChanges = yield* listRefs(stateDir, memoryUrl).pipe( + Effect.provideService(MemoryConfig, memoryConfig), + Effect.map((after) => diffRefs(refsBefore, after)), + ); + const shadow = `refs/heads/kin/shadow/${agentId}`; + lines.push("", "Memory remote refs:"); + if (refChanges.length === 0) lines.push(" (no change)"); + for (const change of refChanges) { + lines.push( + ` ${change.before === null ? "+" : change.after === null ? "-" : "~"} ${change.ref} ${change.before?.slice(0, 12) ?? "(new)"} -> ${change.after?.slice(0, 12) ?? "(deleted)"}`, + ); + if (change.ref !== shadow) + violations.push(`The remote ref ${change.ref} changed; only ${shadow} may.`); + } + if (!refChanges.some((change) => change.ref === shadow && change.after !== null)) + violations.push(`${shadow} was not written.`); + + lines.push("", "Checks:"); + lines.push( + violations.length === 0 + ? ` PASS: only ${shadow} written, nothing posted outside the owner's direct chat, nothing executed.` + : ` FAIL: ${violations.length} violation(s)`, + ...violations.map((violation) => ` - ${violation}`), + ); + return { lines, refChanges, violations, toolCalls } satisfies DryRunReport; + }, + (effect) => provideDeterministicTestRuntime(effect), +); + +const command = Command.make( + "kin-shadow-dry-run", + { + day: Flag.String("day").pipe(Flag.withDescription("Recorded day (JSON).")), + stateDir: Flag.String("state-dir").pipe( + Flag.withDescription("Fresh, empty directory for this run's database and checkouts."), + ), + agentId: Flag.String("agent-id").pipe( + Flag.withDefault("kin-dry-run"), + Flag.withDescription("Lead id. Writes go to kin/shadow/; use one no real lead has."), + ), + memoryUrl: Flag.String("memory-url").pipe( + Flag.withDescription( + "Memory remote. Defaults to a local fixture remote in the state directory.", + ), + Flag.optional, + ), + credentialHelper: Flag.String("credential-helper").pipe(Flag.optional), + sshCommand: Flag.String("ssh-command").pipe(Flag.optional), + verbose: Flag.Boolean("verbose").pipe(Flag.withDefault(false)), + }, + (flags) => + Effect.gen(function* () { + const report = yield* runDryRun({ + dayFile: flags.day, + stateDir: flags.stateDir, + agentId: flags.agentId, + memoryUrl: Option.getOrUndefined(flags.memoryUrl), + credentialHelper: Option.getOrUndefined(flags.credentialHelper), + sshCommand: Option.getOrUndefined(flags.sshCommand), + }).pipe(Effect.provideService(References.MinimumLogLevel, flags.verbose ? "Info" : "Error")); + yield* Console.log(report.lines.join("\n")); + if (report.violations.length > 0) + return yield* new KinDryRunError({ message: "The dry run found violations." }); + }), +); + +if (import.meta.main) { + Command.run(command, { version: "1" }).pipe( + Effect.provide(Vcs.layer.pipe(Layer.provideMerge(NodeServices.layer))), + NodeRuntime.runMain, + ); +} diff --git a/apps/server/src/kin/lead/WakeupRunner.testkit.ts b/apps/server/src/kin/lead/WakeupRunner.testkit.ts index b4072c970c32..f78815a1275e 100644 --- a/apps/server/src/kin/lead/WakeupRunner.testkit.ts +++ b/apps/server/src/kin/lead/WakeupRunner.testkit.ts @@ -84,7 +84,10 @@ const project = { updatedAt: timestamp, deletedAt: null, }; -const database = KinPersistence.layer.pipe(Layer.provideMerge(Sqlite.layerMemory)); +const defaultDatabase = KinPersistence.layer.pipe(Layer.provideMerge(Sqlite.layerMemory)); +type Database = NonNullable< + NonNullable[2]>["databaseLayer"] +>; export const seed = Effect.gen(function* () { const sql = yield* SqlClient.SqlClient; yield* sql`INSERT INTO kin_orgs VALUES ('org', 'Org', ${timestamp})`; @@ -130,6 +133,10 @@ type HarnessOptions = { readonly requestCapability?: "not_resumable"; /** Each turn stays open until it is interrupted, then ends `interrupted`. */ readonly untilInterrupted?: boolean; + /** Replaces the in-memory database, for example with a file in a state directory. */ + readonly database?: Database; + /** Runs inside each turn before it completes, as the provider's tool calls would. */ + readonly onTurn?: (input: { readonly threadId: ThreadId }) => Effect.Effect; }; export function harness(options: HarnessOptions = {}) { @@ -138,6 +145,18 @@ export function harness(options: HarnessOptions = {}) { /** The fake-provider orchestration stack without the wake-up runner. */ export function orchestrationHarness(options: HarnessOptions = {}) { + const { stack, kin, database } = parts(options); + return Layer.mergeAll(kin, stack).pipe(Layer.provideMerge(database)); +} + +/** The fake-provider orchestration stack alone, for callers that bring Kin's own services. */ +export function orchestrationStack(options: HarnessOptions = {}) { + const { stack, database } = parts(options); + return stack.pipe(Layer.provideMerge(database)); +} + +function parts(options: HarnessOptions) { + const database: Database = options.database ?? defaultDatabase; let nativeOrdinal = 0; const driver = ProviderDriverKind.make(options.claude ? "claudeAgent" : "codex"); const instanceId = options.claude ? ProviderInstanceId.make("claudeAgent") : selection.instanceId; @@ -195,6 +214,7 @@ export function orchestrationHarness(options: HarnessOptions = {}) { options.runtimeModes?.push(input.runtimePolicy.runtimeMode); if (options.entered !== undefined) yield* Deferred.succeed(options.entered, undefined); if (options.hold !== undefined) yield* Deferred.await(options.hold); + if (options.onTurn !== undefined) yield* options.onTurn({ threadId: input.threadId }); const time = yield* DateTime.now; const id = ProviderTurnId.make(`turn-${input.runOrdinal}`); if (!options.piUsage) @@ -444,8 +464,7 @@ export function orchestrationHarness(options: HarnessOptions = {}) { ensureCheckouts: () => Effect.succeed({ writer: "/private/tmp", read: "/private/tmp" }), }), ); - const services = Layer.mergeAll( - kin, + const stack = Layer.mergeAll( launch, management, projectLayer, @@ -469,6 +488,10 @@ export function orchestrationHarness(options: HarnessOptions = {}) { ), ), ), - ).pipe(Layer.provideMerge(database)); - return Layer.merge(services, (options.writer ?? Layer.empty).pipe(Layer.provide(database))); + ); + return { + database, + stack, + kin: Layer.merge(kin, (options.writer ?? Layer.empty).pipe(Layer.provide(database))), + }; } diff --git a/docs/operations/kin-shadow-dry-run.md b/docs/operations/kin-shadow-dry-run.md new file mode 100644 index 000000000000..7476201a9582 --- /dev/null +++ b/docs/operations/kin-shadow-dry-run.md @@ -0,0 +1,108 @@ +# Kin shadow dry run + +> For maintainers operating a Kin host. The task is LEAD-14 in [the lead spec](../kin/specs/lead.md#tasks). + +`apps/server/scripts/kin-shadow-dry-run.ts` replays a recorded day of events through the real Kin path at L0: the event queue and coalescer, the wake-up runner, the lead tools, the level gate, shadow entries, the memory writer, routine content and the summary cards. No model runs. Each lead turn replays the tool calls recorded in the day file, so a run costs nothing and gives the same result every time. + +It works in a fresh state directory with its own database, and never opens `~/.t3`. It refuses a `--state-dir` that is `~/.t3` or anything inside it, including through a symlink, and one that isn't empty. Its only outside write is to the memory remote: commits on `kin/shadow/`. It reads nothing from GitHub. The routine cards use the day file's GitHub snapshot, and `request_action` never reads a PR below L3. + +It exits non-zero unless all three checks pass: + +- the only remote ref it created or moved is `refs/heads/kin/shadow/`; +- no agent or system message reached any chat except the owner's direct chat; +- nothing ran: no worker, no pending action, and no thread except the lead's. + +## Run it against the fixture first + +On the Kin host, as `kin`, from a build that has had `vp i` (for example `~/kin-current`): + +```sh +cd ~/kin-current/apps/server +node scripts/kin-shadow-dry-run.ts \ + --day scripts/kin-shadow-dry-run.day.json \ + --state-dir "$(mktemp -d)/state" +``` + +With no `--memory-url`, the script makes a local bare remote from the day file's `memory` and pushes only to that. This proves the build before you touch the real repository. + +## Run it against `GLDRoger/kin-memory` + +The memory writer ignores system and global git config, so it can't use your `gh` login. Give it the `kin` user's memory credential by one of these flags. Never put a credential value in the day file, the repository or this page. + +- SSH: `--ssh-command`, an `ssh` command that names the deploy key with write access to `GLDRoger/kin-memory`. It becomes `GIT_SSH_COMMAND`. +- HTTPS: `--credential-helper`, a git credential helper command that answers with the GitHub App's installation token. + +Use an agent id that no real lead has, so the run can't touch a real lead's shadow week. First confirm that its branch doesn't exist yet. `git ls-remote` should print nothing: + +```sh +git ls-remote git@github.com:GLDRoger/kin-memory.git refs/heads/kin/shadow/kin-dry-run +``` + +Then run: + +```sh +cd ~/kin-current/apps/server +node scripts/kin-shadow-dry-run.ts \ + --day scripts/kin-shadow-dry-run.day.json \ + --state-dir "$(mktemp -d)/state" \ + --agent-id kin-dry-run \ + --memory-url git@github.com:GLDRoger/kin-memory.git \ + --ssh-command "ssh -i -o IdentitiesOnly=yes" +``` + +For HTTPS, use `--memory-url https://github.com/GLDRoger/kin-memory.git --credential-helper ''` instead. + +The lead's memory reads and the morning brief come from the real repository. The fixture day's writes are synthetic: a commitment, a deferral and journal lines, all committed to the shadow branch. A recorded call that names an item the real memory lacks is printed as `refused`. That doesn't fail the run. `--verbose` shows the server's logs. + +## What the output looks like + +```text +Kin shadow dry run: 2026-11-09, lead kin-dry-run at L0 +Memory remote: git@github.com:GLDRoger/kin-memory.git + +Replay: + 08:30 routine brief + 08:30 wake-up 1 + 09:05 message owner-morning + 09:05 wake-up 2 + kin_chat_post: ok + 10:15 message sam-review + 10:15 wake-up 3 + kin_chat_post: shadowed + request_action: shadowed + memory_write: ok + ... + +Owner's direct chat: + 08:30 Kin: Morning brief, Mon 9 Nov + [morning_brief card, 2026-11-09] + 09:05 Fixture Lead: Rate limits start today at 10:00, ... + 10:15 Kin: What Fixture Lead would have done today + [shadow_summary card] What Fixture Lead would have done today + - kin_chat_post -> team: I've asked the owner to review #7 before lunch. ... + 18:30 Kin: Evening summary, Mon 9 Nov + 18:30 Kin: Review what Fixture Lead would have done today: 0 of 3 reviewed, 3 unreviewed + +Memory remote refs: + + refs/heads/kin/shadow/kin-dry-run (new) -> 59e1f53feff1 + +Checks: + PASS: only refs/heads/kin/shadow/kin-dry-run written, nothing posted outside the owner's direct chat, nothing executed. +``` + +A failed run ends in `FAIL` and lists every violation, for example `The remote ref refs/heads/main changed; only refs/heads/kin/shadow/kin-dry-run may.` + +## Clean up + +Delete the dry run's shadow branch with the same credential, check that it's gone, and remove the state directory: + +```sh +GIT_SSH_COMMAND="ssh -i -o IdentitiesOnly=yes" \ + git push git@github.com:GLDRoger/kin-memory.git --delete kin/shadow/kin-dry-run +git ls-remote git@github.com:GLDRoger/kin-memory.git refs/heads/kin/shadow/kin-dry-run +rm -rf +``` + +## Recording another day + +The day file is JSON, and every value in it is invented. It has the lead's name, the people and group chats to seed, the worker projects, a GitHub snapshot for the routine cards, the fixture `memory` files, and `events`. Each event is a `message`, `routine`, `github` or `watchdog` at a UTC time. An event's `lead` list holds the tool calls the lead makes in the wake-up that handles it. In tool arguments, `$ownerChat`, `$event`, `$chat` and `$message` stand for the owner's direct chat, the event id, and the event's chat and message. See [`kin-shadow-dry-run.day.json`](../../apps/server/scripts/kin-shadow-dry-run.day.json). From 970576d72b8a86ce19d000d8ba789418b18c265f Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:33:17 +0530 Subject: [PATCH 2/4] fix(kin): dry run replays against a local mirror and pushes only the shadow branch The dry run now mirror-clones the memory remote into the state directory, replays and checks against the mirror, and only with --push and passing checks makes its single write: :refs/heads/kin/shadow/. It refuses an existing shadow branch, a refspec-bending agent id, inline credential values, an unset HOME, and ~/.T3 on case-folding filesystems. Co-Authored-By: Claude Opus 5.5 --- .../server/scripts/kin-shadow-dry-run.test.ts | 148 +++++++++++++-- apps/server/scripts/kin-shadow-dry-run.ts | 168 ++++++++++++++---- apps/server/src/kin/memory/purgePush.ts | 4 +- docs/operations/kin-shadow-dry-run.md | 68 ++++--- 4 files changed, 319 insertions(+), 69 deletions(-) diff --git a/apps/server/scripts/kin-shadow-dry-run.test.ts b/apps/server/scripts/kin-shadow-dry-run.test.ts index d179699cbaf0..23c693c654f4 100644 --- a/apps/server/scripts/kin-shadow-dry-run.test.ts +++ b/apps/server/scripts/kin-shadow-dry-run.test.ts @@ -1,14 +1,49 @@ import * as NodeServices from "@effect/platform-node/NodeServices"; +import * as HostProcess from "@t3tools/shared/HostProcess"; import { assert, it } from "@effect/vitest"; import * as Effect from "effect/Effect"; import * as FileSystem from "effect/FileSystem"; import * as Layer from "effect/Layer"; +import * as Schema from "effect/Schema"; import * as Vcs from "../src/vcs/VcsProcess.ts"; -import { runDryRun } from "./kin-shadow-dry-run.ts"; +import { runDryRun, seedFixtureRemote } from "./kin-shadow-dry-run.ts"; const day = new URL("./kin-shadow-dry-run.day.json", import.meta.url).pathname; const services = Vcs.layer.pipe(Layer.provideMerge(NodeServices.layer)); +const shadow = "refs/heads/kin/shadow/fixture-lead"; +const decodeMemory = Schema.decodeUnknownEffect( + Schema.fromJsonString(Schema.Struct({ memory: Schema.Record(Schema.String, Schema.String) })), +); + +const gitIn = Effect.fn("KinDryRunTest.git")(function* (cwd: string, args: ReadonlyArray) { + const result = yield* (yield* Vcs.VcsProcess).run({ + operation: "kin.dryRun.test", + command: "git", + cwd, + args: [`--git-dir=${cwd}`, ...args], + }); + return result.stdout; +}); +const refsOf = Effect.fn("KinDryRunTest.refsOf")(function* (remote: string) { + const out = yield* gitIn(remote, ["for-each-ref", "--format=%(refname) %(objectname)"]); + return Object.fromEntries( + out + .trim() + .split("\n") + .map((line) => line.split(" ")), + ); +}); + +/** A stand-in for the real memory remote, outside the state directory the script works in. */ +const realRemote = Effect.fn("KinDryRunTest.realRemote")(function* () { + const fs = yield* FileSystem.FileSystem; + const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped()); + yield* fs.makeDirectory(`${root}/remote`); + const { memory } = yield* decodeMemory(yield* fs.readFileString(day)); + const remote = yield* seedFixtureRemote(`${root}/remote`, memory); + return { root, remote, before: yield* refsOf(remote) }; +}); it.live( "replays the recorded day at L0: only the shadow branch moves, nothing leaves the owner's chat, nothing runs", @@ -25,8 +60,9 @@ it.live( assert.deepStrictEqual(report.violations, []); assert.deepStrictEqual( report.refChanges.map(({ ref, before }) => ({ ref, before })), - [{ ref: "refs/heads/kin/shadow/fixture-lead", before: null }], + [{ ref: shadow, before: null }], ); + assert.strictEqual(report.pushed, undefined); // The group reply, the merge request and the worker were drafted and held back. assert.deepStrictEqual( report.toolCalls.filter((call) => call.outcome !== "ok"), @@ -43,25 +79,113 @@ it.live( }).pipe(Effect.provide(services), Effect.scoped), ); +it.live("with --push the real remote gains exactly the shadow branch, after the checks", () => + Effect.gen(function* () { + const { root, remote, before } = yield* realRemote(); + const report = yield* runDryRun({ + dayFile: day, + stateDir: `${root}/state`, + agentId: "fixture-lead", + memoryUrl: remote, + home: `${root}/home`, + push: true, + }); + assert.deepStrictEqual(report.violations, []); + const sha = report.refChanges.find((change) => change.ref === shadow)?.after; + assert.deepStrictEqual(report.pushed, { ref: shadow, sha }); + assert.deepStrictEqual(yield* refsOf(remote), { ...before, [shadow]: sha }); + }).pipe(Effect.provide(services), Effect.scoped), +); + +it.live("a writer that moves main fails the checks and never reaches the real remote", () => + Effect.gen(function* () { + const { root, remote, before } = yield* realRemote(); + // Above L0 the writer commits to main, standing in for a writer bug at L0. + const report = yield* runDryRun({ + dayFile: day, + stateDir: `${root}/state`, + agentId: "fixture-lead", + memoryUrl: remote, + home: `${root}/home`, + push: true, + level: "L1", + }); + assert.include( + report.violations, + `The mirror ref refs/heads/main changed; only ${shadow} may.`, + ); + assert.strictEqual(report.pushed, undefined); + assert.deepStrictEqual(yield* refsOf(remote), before); + }).pipe(Effect.provide(services), Effect.scoped), +); + +it.live("refuses when the shadow branch already exists on the remote, before mirroring", () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const { root, remote } = yield* realRemote(); + yield* gitIn(remote, ["update-ref", shadow, "refs/heads/main"]); + const before = yield* refsOf(remote); + const error = yield* runDryRun({ + dayFile: day, + stateDir: `${root}/state`, + agentId: "fixture-lead", + memoryUrl: remote, + home: `${root}/home`, + push: true, + }).pipe(Effect.flip); + assert.include(error.message, `${shadow} already exists`); + assert.isFalse(yield* fs.exists(`${root}/state/memory-mirror.git`)); + assert.deepStrictEqual(yield* refsOf(remote), before); + }).pipe(Effect.provide(services), Effect.scoped), +); + +it.live( + "refuses an inline secret or a refspec-bending id in a flag, before creating anything", + () => + Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; + const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped()); + for (const unsafe of [ + { credentialHelper: "!f() { echo password=ghp_inline; }; f" }, + { sshCommand: "ssh -i key; echo $TOKEN" }, + { agentId: "x:refs/heads/main" }, + ]) { + const error = yield* runDryRun({ + dayFile: day, + stateDir: `${root}/state`, + agentId: "fixture-lead", + home: `${root}/home`, + ...unsafe, + }).pipe(Effect.flip); + assert.match(error.message, /^--(credential-helper|ssh-command|agent-id) takes/); + } + assert.isFalse(yield* fs.exists(`${root}/state`)); + }).pipe(Effect.provide(services), Effect.scoped), +); + it.live("refuses a state directory that is the live ~/.t3 or inside it, before creating it", () => Effect.gen(function* () { const fs = yield* FileSystem.FileSystem; const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped()); yield* fs.makeDirectory(`${root}/home/.t3`, { recursive: true }); yield* fs.symlink(`${root}/home/.t3`, `${root}/alias`); - for (const stateDir of [ - `${root}/home/.t3`, - `${root}/home/.t3/dry-run`, - `${root}/alias/dry-run`, + const home = `${root}/home`; + for (const refused of [ + { stateDir: `${home}/.t3`, home }, + { stateDir: `${home}/.t3/dry-run`, home }, + { stateDir: `${root}/alias/dry-run`, home }, + { stateDir: `${home}/.T3/dry-run`, home }, + { stateDir: `${root}/state`, home: undefined }, + { stateDir: `${root}/state`, home: "" }, ]) { - const error = yield* runDryRun({ - dayFile: day, - stateDir, - agentId: "fixture-lead", - home: `${root}/home`, - }).pipe(Effect.flip); + // macOS folds case, so ~/.T3 is the live ~/.t3 there. + const error = yield* runDryRun({ dayFile: day, agentId: "fixture-lead", ...refused }).pipe( + Effect.provideService(HostProcess.Platform, "darwin"), + Effect.flip, + ); assert.strictEqual(error._tag, "KinDryRunError"); } assert.deepStrictEqual(yield* fs.readDirectory(`${root}/home/.t3`), []); + assert.isFalse(yield* fs.exists(`${root}/state`)); }).pipe(Effect.provide(services), Effect.scoped), ); diff --git a/apps/server/scripts/kin-shadow-dry-run.ts b/apps/server/scripts/kin-shadow-dry-run.ts index 990bef2c98f8..4e551d907088 100644 --- a/apps/server/scripts/kin-shadow-dry-run.ts +++ b/apps/server/scripts/kin-shadow-dry-run.ts @@ -1,11 +1,12 @@ #!/usr/bin/env node // Ops only: replays a recorded Kin day through the full lead path at L0, with a scripted -// provider instead of a model, and checks that memory reached only kin/shadow/. +// provider instead of a model, against a local mirror of the memory remote. Only after the +// checks pass, and only with --push, does it push kin/shadow/ to the real remote. // Runbook: docs/operations/kin-shadow-dry-run.md. import * as NodeCrypto from "@effect/platform-node/NodeCrypto"; import * as NodeRuntime from "@effect/platform-node/NodeRuntime"; import * as NodeServices from "@effect/platform-node/NodeServices"; -import * as NodeOS from "node:os"; +import * as HostProcess from "@t3tools/shared/HostProcess"; import { AuthSessionId, AuthStandardClientScopes, @@ -13,6 +14,7 @@ import { KinAgentId, KinChatId, KinEvent, + type KinLevel, KinOrgId, KinPersonId, KinRoutineCard, @@ -24,6 +26,7 @@ import { } from "@t3tools/contracts"; import * as Cause from "effect/Cause"; import * as Clock from "effect/Clock"; +import * as Config from "effect/Config"; import * as Console from "effect/Console"; import * as ConfigProvider from "effect/ConfigProvider"; import * as Context from "effect/Context"; @@ -73,6 +76,7 @@ import * as Memory from "../src/kin/memory/Memory.ts"; import * as Cache from "../src/kin/memory/MemoryCache.ts"; import { MemoryConfig } from "../src/kin/memory/MemoryConfig.ts"; import * as Writer from "../src/kin/memory/MemoryWriter.ts"; +import { isCredentialHelperReference, isSshCommandReference } from "../src/kin/memory/purgePush.ts"; import * as Scan from "../src/kin/memory/secretScan.ts"; import * as KinPersistence from "../src/kin/persistence/KinPersistence.ts"; @@ -153,7 +157,11 @@ interface DryRunOptions { readonly credentialHelper?: string | undefined; readonly sshCommand?: string | undefined; /** The home directory whose `.t3` is the live install; tests pass a temporary one. */ - readonly home?: string | undefined; + readonly home: string | undefined; + /** Push the shadow branch to the memory remote once every check passes. */ + readonly push?: boolean | undefined; + /** Test seam for proving the push gate; the CLI always runs L0. */ + readonly level?: KinLevel | undefined; } interface RefChange { @@ -165,6 +173,7 @@ interface RefChange { interface DryRunReport { readonly lines: ReadonlyArray; readonly refChanges: ReadonlyArray; + readonly pushed: { readonly ref: string; readonly sha: string } | undefined; readonly violations: ReadonlyArray; readonly toolCalls: ReadonlyArray<{ readonly tool: string; readonly outcome: string }>; } @@ -198,12 +207,20 @@ const decodeReviewCard = Schema.decodeOption(Schema.fromJsonString(KinShadowRevi /** Refuses the live install: the state directory may not be `~/.t3` or anything below it. */ const refuseLiveHome = Effect.fn("KinDryRun.refuseLiveHome")(function* ( stateDir: string, - home: string, + home: string | undefined, ) { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; + if (home === undefined || !path.isAbsolute(home)) + return yield* new KinDryRunError({ + message: "HOME is unset or not absolute, so the live ~/.t3 can't be located. Set HOME.", + }); const real = (target: string) => fs.realPath(target).pipe(Effect.orElseSucceed(() => path.resolve(target))); + // macOS and Windows volumes usually fold case, so ~/.T3 is the live ~/.t3 there. + const platform = yield* HostProcess.Platform; + const fold = (target: string) => + platform === "darwin" || platform === "win32" ? target.toLowerCase() : target; // Resolve the deepest existing ancestor, so a symlink into ~/.t3 is caught before creation. const resolve = Effect.fn("KinDryRun.resolve")(function* (target: string) { let existing = path.resolve(target); @@ -221,13 +238,37 @@ const refuseLiveHome = Effect.fn("KinDryRun.refuseLiveHome")(function* ( path.join(path.resolve(home), ".t3"), yield* resolve(path.join(home, ".t3")), ])) - if (state === live || state.startsWith(live + path.sep)) + if (fold(state) === fold(live) || fold(state).startsWith(fold(live) + path.sep)) return yield* new KinDryRunError({ message: `Refusing ${stateDir}: it is the live T3 home (${live}) or inside it. Use a temporary --state-dir.`, }); return state; }); +/** Credential flags name a helper, a key file or a command, never a secret value. */ +const refuseUnsafeFlags = Effect.fn("KinDryRun.refuseUnsafeFlags")(function* ( + options: DryRunOptions, +) { + // The id becomes the one pushed ref, so it may not bend the refspec. + if (!/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(options.agentId)) + return yield* new KinDryRunError({ + message: "--agent-id takes letters, digits, '-' and '_' only.", + }); + if ( + options.credentialHelper !== undefined && + !isCredentialHelperReference(options.credentialHelper) + ) + return yield* new KinDryRunError({ + message: + "--credential-helper takes a helper name or an absolute path, never a token or an inline `!` script.", + }); + if (options.sshCommand !== undefined && !isSshCommandReference(options.sshCommand)) + return yield* new KinDryRunError({ + message: + "--ssh-command takes a plain ssh command naming a key file, such as `ssh -i /path/to/key -o IdentitiesOnly=yes`, with no shell syntax or secret.", + }); +}); + const git = Effect.fn("KinDryRun.git")(function* (cwd: string, args: ReadonlyArray) { const result = yield* (yield* Vcs.VcsProcess).run({ operation: "kin.dryRun.git", @@ -250,7 +291,7 @@ const git = Effect.fn("KinDryRun.git")(function* (cwd: string, args: ReadonlyArr }); /** A local bare remote holding the day's fixture memory, so no test touches a real repository. */ -const seedFixtureRemote = Effect.fn("KinDryRun.seedFixtureRemote")(function* ( +export const seedFixtureRemote = Effect.fn("KinDryRun.seedFixtureRemote")(function* ( stateDir: string, memory: RecordedDay["memory"], ) { @@ -347,7 +388,8 @@ export const runDryRun = Effect.fn("KinDryRun.run")( function* (options: DryRunOptions) { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; - const stateDir = yield* refuseLiveHome(options.stateDir, options.home ?? NodeOS.homedir()); + yield* refuseUnsafeFlags(options); + const stateDir = yield* refuseLiveHome(options.stateDir, options.home); if ((yield* fs.exists(stateDir)) && (yield* fs.readDirectory(stateDir)).length > 0) return yield* new KinDryRunError({ message: `State directory ${stateDir} is not empty. Use a fresh one for each dry run.`, @@ -359,18 +401,46 @@ export const runDryRun = Effect.fn("KinDryRun.run")( ), ); const agentId = KinAgentId.make(options.agentId); - const memoryUrl = options.memoryUrl ?? (yield* seedFixtureRemote(stateDir, day.memory)); + const shadow = `refs/heads/kin/shadow/${agentId}`; + const target = options.memoryUrl ?? (yield* seedFixtureRemote(stateDir, day.memory)); + const withCredentials = Effect.provideService( + MemoryConfig, + MemoryConfig.of({ + baseDirectory: path.join(stateDir, "kin"), + repositories: [], + ...(options.credentialHelper === undefined + ? {} + : { credentialHelper: options.credentialHelper }), + ...(options.sshCommand === undefined ? {} : { sshCommand: options.sshCommand }), + }), + ); + const refuseExistingShadow = Effect.fn("KinDryRun.refuseExistingShadow")(function* () { + const refs = yield* listRefs(stateDir, target).pipe( + withCredentials, + Effect.mapError( + (error) => + new KinDryRunError({ + message: `Could not list refs on ${target}: ${error.message}. Run the runbook's ls-remote pre-check with the same credential to see git's own error.`, + }), + ), + ); + const existing = refs.get(shadow); + if (existing !== undefined) + return yield* new KinDryRunError({ + message: `${shadow} already exists on ${target} at ${existing}. Delete it (see the runbook) or pick another --agent-id.`, + }); + }); + yield* refuseExistingShadow(); + // The replay only ever sees this local mirror; the one write to the real remote comes after the checks. + const memoryUrl = path.join(stateDir, "memory-mirror.git"); + yield* memoryGit(stateDir, ["clone", "-q", "--mirror", "--", target, memoryUrl]).pipe( + withCredentials, + ); const memoryConfig = MemoryConfig.of({ baseDirectory: path.join(stateDir, "kin"), repositories: [{ orgId, repoUrl: memoryUrl, path: encodeURIComponent(orgId) }], - ...(options.credentialHelper === undefined - ? {} - : { credentialHelper: options.credentialHelper }), - ...(options.sshCommand === undefined ? {} : { sshCommand: options.sshCommand }), }); - const refsBefore = yield* listRefs(stateDir, memoryUrl).pipe( - Effect.provideService(MemoryConfig, memoryConfig), - ); + const refsBefore = yield* listRefs(stateDir, memoryUrl); const events = day.events.toSorted((a, b) => Date.parse(a.at) - Date.parse(b.at)); const byId = new Map(events.map((event) => [event.id, event])); const start = Date.parse(`${day.day}T00:00:00.000Z`); @@ -427,7 +497,7 @@ export const runDryRun = Effect.fn("KinDryRun.run")( const workerProjects = yield* encodeJson(day.workerProjects); // Seeded at L0: the level the shadow week runs at, and the one this script checks. yield* sql`INSERT INTO kin_leads (agent_id, org_id, name, level, level_since, models_json, worker_projects_json, owner_chat_id) - VALUES (${agentId}, ${orgId}, ${day.lead.name}, 'L0', ${start}, ${models}, ${workerProjects}, ${direct.chatId})`; + VALUES (${agentId}, ${orgId}, ${day.lead.name}, ${options.level ?? "L0"}, ${start}, ${models}, ${workerProjects}, ${direct.chatId})`; for (const person of day.people) yield* sql`INSERT INTO kin_people (person_id, org_id, handle, display_name, created_at) VALUES (${person.personId}, ${orgId}, ${person.handle}, ${person.displayName}, ${createdAt})`; @@ -643,8 +713,9 @@ export const runDryRun = Effect.fn("KinDryRun.run")( }); lines.push( - `Kin shadow dry run: ${day.day}, lead ${agentId} at L0`, - `Memory remote: ${memoryUrl}`, + `Kin shadow dry run: ${day.day}, lead ${agentId} at ${options.level ?? "L0"}`, + `Memory remote: ${target}`, + `Local mirror: ${memoryUrl}`, "", "Replay:", ); @@ -745,23 +816,19 @@ export const runDryRun = Effect.fn("KinDryRun.run")( Effect.scoped, ); - // Check 1: the remote gained or changed only this lead's shadow branch. - const refChanges = yield* listRefs(stateDir, memoryUrl).pipe( - Effect.provideService(MemoryConfig, memoryConfig), - Effect.map((after) => diffRefs(refsBefore, after)), - ); - const shadow = `refs/heads/kin/shadow/${agentId}`; - lines.push("", "Memory remote refs:"); + // Check 1: the mirror gained or changed only this lead's shadow branch. + const refChanges = diffRefs(refsBefore, yield* listRefs(stateDir, memoryUrl)); + lines.push("", "Local mirror refs:"); if (refChanges.length === 0) lines.push(" (no change)"); for (const change of refChanges) { lines.push( - ` ${change.before === null ? "+" : change.after === null ? "-" : "~"} ${change.ref} ${change.before?.slice(0, 12) ?? "(new)"} -> ${change.after?.slice(0, 12) ?? "(deleted)"}`, + ` ${change.before === null ? "+" : change.after === null ? "-" : "~"} ${change.ref} ${change.before ?? "(new)"} -> ${change.after ?? "(deleted)"}`, ); if (change.ref !== shadow) - violations.push(`The remote ref ${change.ref} changed; only ${shadow} may.`); + violations.push(`The mirror ref ${change.ref} changed; only ${shadow} may.`); } - if (!refChanges.some((change) => change.ref === shadow && change.after !== null)) - violations.push(`${shadow} was not written.`); + const sha = refChanges.find((change) => change.ref === shadow)?.after ?? undefined; + if (sha === undefined) violations.push(`${shadow} was not written.`); lines.push("", "Checks:"); lines.push( @@ -770,7 +837,28 @@ export const runDryRun = Effect.fn("KinDryRun.run")( : ` FAIL: ${violations.length} violation(s)`, ...violations.map((violation) => ` - ${violation}`), ); - return { lines, refChanges, violations, toolCalls } satisfies DryRunReport; + + lines.push("", "Push:"); + let pushed: DryRunReport["pushed"]; + if (violations.length > 0 || sha === undefined) lines.push(` none: the checks failed.`); + else if (options.push !== true) + lines.push(` none (no --push). With --push: ${sha} -> ${target} ${shadow}`); + else { + yield* refuseExistingShadow(); + const source = path.join(stateDir, "push-source"); + yield* memoryGit(stateDir, ["clone", "-q", "--no-checkout", "--", memoryUrl, source]); + yield* memoryGit(source, ["push", "-q", "--", target, `${sha}:${shadow}`]).pipe( + withCredentials, + ); + const landed = (yield* listRefs(stateDir, target).pipe(withCredentials)).get(shadow); + if (landed !== sha) + return yield* new KinDryRunError({ + message: `Pushed ${sha} to ${shadow}, but the remote now reports ${landed ?? "no such ref"}.`, + }); + pushed = { ref: shadow, sha }; + lines.push(` + ${shadow} ${sha} -> ${target}`); + } + return { lines, refChanges, pushed, violations, toolCalls } satisfies DryRunReport; }, (effect) => provideDeterministicTestRuntime(effect), ); @@ -788,12 +876,24 @@ const command = Command.make( ), memoryUrl: Flag.String("memory-url").pipe( Flag.withDescription( - "Memory remote. Defaults to a local fixture remote in the state directory.", + "Memory remote, mirrored into the state directory for the replay. Defaults to a local fixture remote.", ), Flag.optional, ), - credentialHelper: Flag.String("credential-helper").pipe(Flag.optional), - sshCommand: Flag.String("ssh-command").pipe(Flag.optional), + push: Flag.Boolean("push").pipe( + Flag.withDefault(false), + Flag.withDescription( + "After every check passes, push kin/shadow/ to the memory remote. Its only write.", + ), + ), + credentialHelper: Flag.String("credential-helper").pipe( + Flag.withDescription("Git credential helper name or absolute path. Never a token."), + Flag.optional, + ), + sshCommand: Flag.String("ssh-command").pipe( + Flag.withDescription("ssh command naming the deploy key file. Never a secret."), + Flag.optional, + ), verbose: Flag.Boolean("verbose").pipe(Flag.withDefault(false)), }, (flags) => @@ -805,6 +905,8 @@ const command = Command.make( memoryUrl: Option.getOrUndefined(flags.memoryUrl), credentialHelper: Option.getOrUndefined(flags.credentialHelper), sshCommand: Option.getOrUndefined(flags.sshCommand), + home: Option.getOrUndefined(yield* Config.option(Config.String("HOME"))) || undefined, + push: flags.push, }).pipe(Effect.provideService(References.MinimumLogLevel, flags.verbose ? "Info" : "Error")); yield* Console.log(report.lines.join("\n")); if (report.violations.length > 0) diff --git a/apps/server/src/kin/memory/purgePush.ts b/apps/server/src/kin/memory/purgePush.ts index 2c80689fad72..d46da9de0660 100644 --- a/apps/server/src/kin/memory/purgePush.ts +++ b/apps/server/src/kin/memory/purgePush.ts @@ -82,9 +82,9 @@ const pushFailure = (stdout: string, stderr: string): KinPurgePushError["reason" }; // A helper name or absolute path, never an inline `!` script that could carry the secret itself. -const isCredentialHelperReference = (helper: string) => +export const isCredentialHelperReference = (helper: string) => /^(?:[A-Za-z0-9][A-Za-z0-9._-]*|\/[A-Za-z0-9._/-]+)$/.test(helper); -const isSshCommandReference = (command: string) => /^[A-Za-z0-9 ._/=,:@+-]+$/.test(command); +export const isSshCommandReference = (command: string) => /^[A-Za-z0-9 ._/=,:@+-]+$/.test(command); /** `file://` carries no credential; https needs the helper and SSH the owner's command. */ const remoteKind = (url: string) => /^https:\/\//i.test(url) diff --git a/docs/operations/kin-shadow-dry-run.md b/docs/operations/kin-shadow-dry-run.md index 7476201a9582..9d9d401545f6 100644 --- a/docs/operations/kin-shadow-dry-run.md +++ b/docs/operations/kin-shadow-dry-run.md @@ -4,13 +4,20 @@ `apps/server/scripts/kin-shadow-dry-run.ts` replays a recorded day of events through the real Kin path at L0: the event queue and coalescer, the wake-up runner, the lead tools, the level gate, shadow entries, the memory writer, routine content and the summary cards. No model runs. Each lead turn replays the tool calls recorded in the day file, so a run costs nothing and gives the same result every time. -It works in a fresh state directory with its own database, and never opens `~/.t3`. It refuses a `--state-dir` that is `~/.t3` or anything inside it, including through a symlink, and one that isn't empty. Its only outside write is to the memory remote: commits on `kin/shadow/`. It reads nothing from GitHub. The routine cards use the day file's GitHub snapshot, and `request_action` never reads a PR below L3. +It works in a fresh state directory with its own database, and never opens `~/.t3`. It refuses a `--state-dir` that is `~/.t3` or anything inside it (through a symlink or a different letter case too), one that isn't empty, and an unset `HOME`. It reads nothing from GitHub. The routine cards use the day file's GitHub snapshot, and `request_action` never reads a PR below L3. -It exits non-zero unless all three checks pass: +A run goes in this order: -- the only remote ref it created or moved is `refs/heads/kin/shadow/`; -- no agent or system message reached any chat except the owner's direct chat; -- nothing ran: no worker, no pending action, and no thread except the lead's. +1. It refuses if `refs/heads/kin/shadow/` already exists on the memory remote. +2. It mirror-clones the memory remote into `/memory-mirror.git`. +3. It replays the day against that local mirror. Nothing in the replay knows the real remote's URL or credential. +4. It runs three checks against the mirror, and exits non-zero unless all pass: + - the only ref created or moved is `refs/heads/kin/shadow/`; + - no agent or system message reached any chat except the owner's direct chat; + - nothing ran: no worker, no pending action, and no thread except the lead's. +5. Only with `--push`, and only if every check passed, it makes its one write to the real remote: `git push :refs/heads/kin/shadow/`, with no `+`. It prints the full SHA and confirms the remote reports it. + +Without `--push`, nothing outside the state directory changes. Run that first. ## Run it against the fixture first @@ -20,25 +27,30 @@ On the Kin host, as `kin`, from a build that has had `vp i` (for example `~/kin- cd ~/kin-current/apps/server node scripts/kin-shadow-dry-run.ts \ --day scripts/kin-shadow-dry-run.day.json \ - --state-dir "$(mktemp -d)/state" + --state-dir "$(mktemp -d)/state" \ + --push ``` -With no `--memory-url`, the script makes a local bare remote from the day file's `memory` and pushes only to that. This proves the build before you touch the real repository. +With no `--memory-url`, the script makes a local bare remote from the day file's `memory` inside the state directory, and `--push` writes only to that. This proves the build before you touch the real repository. ## Run it against `GLDRoger/kin-memory` -The memory writer ignores system and global git config, so it can't use your `gh` login. Give it the `kin` user's memory credential by one of these flags. Never put a credential value in the day file, the repository or this page. +The script ignores system and global git config, so it can't use your `gh` login. Give it the `kin` user's memory credential by one of these flags. Each takes a path or a name, never a secret: the script refuses a value with shell syntax, such as an inline `!` helper, `;`, `$` or `~`. Never put a credential in the day file, the repository or this page. -- SSH: `--ssh-command`, an `ssh` command that names the deploy key with write access to `GLDRoger/kin-memory`. It becomes `GIT_SSH_COMMAND`. -- HTTPS: `--credential-helper`, a git credential helper command that answers with the GitHub App's installation token. +- SSH: `--ssh-command`, a plain `ssh` command naming the deploy key with write access to `GLDRoger/kin-memory`. It becomes `GIT_SSH_COMMAND`. Keep the key outside `~/.ssh`, for example `/home/kin/.config/kin/kin-memory-deploy-key`, mode `0600`. The approvals credential hygiene check ([approvals spec, section 12](../kin/specs/approvals.md#12-credential-hygiene-check)) probes every key in `~/.ssh`, and a deploy key there fails it as `non_bot_identity`. +- HTTPS: `--credential-helper`, the name or absolute path of a git credential helper on the host. A GitHub App installation-token helper is not available yet. -Use an agent id that no real lead has, so the run can't touch a real lead's shadow week. First confirm that its branch doesn't exist yet. `git ls-remote` should print nothing: +Use an agent id that no real lead has. The script can't see the live lead registry, which is in `~/.t3`, so it only refuses an id whose shadow branch already exists. Before the run, check with the same credential: ```sh -git ls-remote git@github.com:GLDRoger/kin-memory.git refs/heads/kin/shadow/kin-dry-run +GIT_SSH_COMMAND="ssh -i /home/kin/.config/kin/kin-memory-deploy-key -o IdentitiesOnly=yes" \ + git ls-remote git@github.com:GLDRoger/kin-memory.git refs/heads/kin/shadow/kin-dry-run +echo "exit $?" ``` -Then run: +`exit 0` with no ref printed means the branch doesn't exist and the key works. An auth failure also prints no ref, so read the exit code: it prints `git@github.com: Permission denied (publickey).` or `ERROR: Repository not found.`, then `fatal: Could not read from remote repository.`, and exits `128`. + +Then do a first run with no push: ```sh cd ~/kin-current/apps/server @@ -47,18 +59,23 @@ node scripts/kin-shadow-dry-run.ts \ --state-dir "$(mktemp -d)/state" \ --agent-id kin-dry-run \ --memory-url git@github.com:GLDRoger/kin-memory.git \ - --ssh-command "ssh -i -o IdentitiesOnly=yes" + --ssh-command "ssh -i /home/kin/.config/kin/kin-memory-deploy-key -o IdentitiesOnly=yes" ``` -For HTTPS, use `--memory-url https://github.com/GLDRoger/kin-memory.git --credential-helper ''` instead. +If it ends in `PASS`, rerun it with a fresh `--state-dir` and `--push` to write the shadow branch. For HTTPS, use `--memory-url https://github.com/GLDRoger/kin-memory.git --credential-helper ` instead. The lead's memory reads and the morning brief come from the real repository. The fixture day's writes are synthetic: a commitment, a deferral and journal lines, all committed to the shadow branch. A recorded call that names an item the real memory lacks is printed as `refused`. That doesn't fail the run. `--verbose` shows the server's logs. +Git against a real remote can hang on a network stall, and the script's timeouts don't fire because it runs on a test clock. Press Ctrl-C to stop it. + +A passing run doesn't prove the live Kin server can reach `kin-memory`: the script passes its own credential. The server's own setting is `KIN_MEMORY_SSH_COMMAND` or `KIN_MEMORY_CREDENTIAL_HELPER`, described in [the Kin host README](../../ops/kin/host/README.md). + ## What the output looks like ```text Kin shadow dry run: 2026-11-09, lead kin-dry-run at L0 Memory remote: git@github.com:GLDRoger/kin-memory.git +Local mirror: /tmp/tmp.X/state/memory-mirror.git Replay: 08:30 routine brief @@ -83,26 +100,33 @@ Owner's direct chat: 18:30 Kin: Evening summary, Mon 9 Nov 18:30 Kin: Review what Fixture Lead would have done today: 0 of 3 reviewed, 3 unreviewed -Memory remote refs: - + refs/heads/kin/shadow/kin-dry-run (new) -> 59e1f53feff1 +Local mirror refs: + + refs/heads/kin/shadow/kin-dry-run (new) -> 46febb6a859b0bc043279f9fb32ca51105cfb226 Checks: PASS: only refs/heads/kin/shadow/kin-dry-run written, nothing posted outside the owner's direct chat, nothing executed. + +Push: + + refs/heads/kin/shadow/kin-dry-run 46febb6a859b0bc043279f9fb32ca51105cfb226 -> git@github.com:GLDRoger/kin-memory.git ``` -A failed run ends in `FAIL` and lists every violation, for example `The remote ref refs/heads/main changed; only refs/heads/kin/shadow/kin-dry-run may.` +A failed run ends its checks in `FAIL`, lists every violation, for example `The mirror ref refs/heads/main changed; only refs/heads/kin/shadow/kin-dry-run may.`, and pushes nothing. ## Clean up -Delete the dry run's shadow branch with the same credential, check that it's gone, and remove the state directory: +The push is the only write the script can make, so the shadow branch is the only thing to undo. Delete it with the same credential, naming the full SHA the run printed so you delete only what it pushed, then check that it's gone and remove the state directory: ```sh -GIT_SSH_COMMAND="ssh -i -o IdentitiesOnly=yes" \ - git push git@github.com:GLDRoger/kin-memory.git --delete kin/shadow/kin-dry-run -git ls-remote git@github.com:GLDRoger/kin-memory.git refs/heads/kin/shadow/kin-dry-run +GIT_SSH_COMMAND="ssh -i /home/kin/.config/kin/kin-memory-deploy-key -o IdentitiesOnly=yes" \ + git push --force-with-lease=refs/heads/kin/shadow/kin-dry-run: \ + git@github.com:GLDRoger/kin-memory.git :refs/heads/kin/shadow/kin-dry-run +GIT_SSH_COMMAND="ssh -i /home/kin/.config/kin/kin-memory-deploy-key -o IdentitiesOnly=yes" \ + git ls-remote git@github.com:GLDRoger/kin-memory.git refs/heads/kin/shadow/kin-dry-run rm -rf ``` +Over HTTPS, run the same two git commands as `git -c credential.helper= -c credential.helper= ...` against `https://github.com/GLDRoger/kin-memory.git`. + ## Recording another day The day file is JSON, and every value in it is invented. It has the lead's name, the people and group chats to seed, the worker projects, a GitHub snapshot for the routine cards, the fixture `memory` files, and `events`. Each event is a `message`, `routine`, `github` or `watchdog` at a UTC time. An event's `lead` list holds the tool calls the lead makes in the wake-up that handles it. In tool arguments, `$ownerChat`, `$event`, `$chat` and `$message` stand for the owner's direct chat, the event id, and the event's chat and message. See [`kin-shadow-dry-run.day.json`](../../apps/server/scripts/kin-shadow-dry-run.day.json). From 006b84a030ba8f0d70062a104274e4c2264648d3 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:35:39 +0530 Subject: [PATCH 3/4] test(kin): a failed dry-run check pushes nothing even after the shadow branch was written Co-Authored-By: Claude Opus 5.5 --- .../server/scripts/kin-shadow-dry-run.test.ts | 74 ++++++++++++++----- 1 file changed, 55 insertions(+), 19 deletions(-) diff --git a/apps/server/scripts/kin-shadow-dry-run.test.ts b/apps/server/scripts/kin-shadow-dry-run.test.ts index 23c693c654f4..357578ea3da4 100644 --- a/apps/server/scripts/kin-shadow-dry-run.test.ts +++ b/apps/server/scripts/kin-shadow-dry-run.test.ts @@ -12,8 +12,16 @@ import { runDryRun, seedFixtureRemote } from "./kin-shadow-dry-run.ts"; const day = new URL("./kin-shadow-dry-run.day.json", import.meta.url).pathname; const services = Vcs.layer.pipe(Layer.provideMerge(NodeServices.layer)); const shadow = "refs/heads/kin/shadow/fixture-lead"; -const decodeMemory = Schema.decodeUnknownEffect( - Schema.fromJsonString(Schema.Struct({ memory: Schema.Record(Schema.String, Schema.String) })), +const decodeRecord = Schema.decodeUnknownEffect( + Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)), +); +const decodeDay = Schema.decodeUnknownEffect( + Schema.fromJsonString( + Schema.Struct({ + memory: Schema.Record(Schema.String, Schema.String), + events: Schema.Array(Schema.Unknown), + }), + ), ); const gitIn = Effect.fn("KinDryRunTest.git")(function* (cwd: string, args: ReadonlyArray) { @@ -40,7 +48,7 @@ const realRemote = Effect.fn("KinDryRunTest.realRemote")(function* () { const fs = yield* FileSystem.FileSystem; const root = yield* fs.realPath(yield* fs.makeTempDirectoryScoped()); yield* fs.makeDirectory(`${root}/remote`); - const { memory } = yield* decodeMemory(yield* fs.readFileString(day)); + const { memory } = yield* decodeDay(yield* fs.readFileString(day)); const remote = yield* seedFixtureRemote(`${root}/remote`, memory); return { root, remote, before: yield* refsOf(remote) }; }); @@ -97,25 +105,53 @@ it.live("with --push the real remote gains exactly the shadow branch, after the }).pipe(Effect.provide(services), Effect.scoped), ); -it.live("a writer that moves main fails the checks and never reaches the real remote", () => +it.live("a failed check never reaches the real remote, even with --push", () => Effect.gen(function* () { + const fs = yield* FileSystem.FileSystem; const { root, remote, before } = yield* realRemote(); - // Above L0 the writer commits to main, standing in for a writer bug at L0. - const report = yield* runDryRun({ - dayFile: day, - stateDir: `${root}/state`, - agentId: "fixture-lead", - memoryUrl: remote, - home: `${root}/home`, - push: true, - level: "L1", - }); - assert.include( - report.violations, - `The mirror ref refs/heads/main changed; only ${shadow} may.`, + // A lead turn that fails after the shadow branch was written. + const text = yield* fs.readFileString(day); + const recorded = yield* decodeDay(text); + const brokenDay = `${root}/broken-day.json`; + yield* fs.writeFileString( + brokenDay, + JSON.stringify({ + ...(yield* decodeRecord(text)), + events: [ + ...recorded.events, + { + _tag: "watchdog", + id: "broken", + at: "2026-11-09T20:00:00.000Z", + finding: "Synthetic", + lead: [{ tool: "no_such_tool", arguments: {} }], + }, + ], + }), ); - assert.strictEqual(report.pushed, undefined); - assert.deepStrictEqual(yield* refsOf(remote), before); + for (const failing of [ + // Above L0 the writer commits to main, standing in for a writer bug at L0. + { + name: "l1", + dayFile: day, + level: "L1", + violation: `The mirror ref refs/heads/main changed; only ${shadow} may.`, + }, + { name: "broken", dayFile: brokenDay, level: "L0", violation: "Lead turn failed" }, + ] as const) { + const report = yield* runDryRun({ + dayFile: failing.dayFile, + stateDir: `${root}/state-${failing.name}`, + agentId: "fixture-lead", + memoryUrl: remote, + home: `${root}/home`, + push: true, + level: failing.level, + }); + assert.isTrue(report.violations.some((violation) => violation.startsWith(failing.violation))); + assert.strictEqual(report.pushed, undefined); + assert.deepStrictEqual(yield* refsOf(remote), before); + } }).pipe(Effect.provide(services), Effect.scoped), ); From ec972f5761dc4d1e4140cc654990d9d959350975 Mon Sep 17 00:00:00 2001 From: GLDRoger <130458023+GLDRoger@users.noreply.github.com> Date: Mon, 9 Nov 2026 12:51:30 +0530 Subject: [PATCH 4/4] docs(kin): note the live server memory credential lands separately Co-Authored-By: Claude Opus 5.5 --- docs/operations/kin-shadow-dry-run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/operations/kin-shadow-dry-run.md b/docs/operations/kin-shadow-dry-run.md index 9d9d401545f6..6422ac283a57 100644 --- a/docs/operations/kin-shadow-dry-run.md +++ b/docs/operations/kin-shadow-dry-run.md @@ -68,7 +68,7 @@ The lead's memory reads and the morning brief come from the real repository. The Git against a real remote can hang on a network stall, and the script's timeouts don't fire because it runs on a test clock. Press Ctrl-C to stop it. -A passing run doesn't prove the live Kin server can reach `kin-memory`: the script passes its own credential. The server's own setting is `KIN_MEMORY_SSH_COMMAND` or `KIN_MEMORY_CREDENTIAL_HELPER`, described in [the Kin host README](../../ops/kin/host/README.md). +A passing run doesn't prove the live Kin server can reach `kin-memory`: the script passes its own credential. The server's own setting is `KIN_MEMORY_SSH_COMMAND` or `KIN_MEMORY_CREDENTIAL_HELPER`, which a separate change adds to [the Kin host README](../../ops/kin/host/README.md). ## What the output looks like