@abelxiaoxing/cadence 2.2.1 → 2.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -323,7 +323,9 @@ At sign-out or shutdown Windows ends the owner without orderly Stop: running wor
323
323
 
324
324
  - `alive` requires an authenticated exact-epoch reply.
325
325
  It is not a PID probe.
326
- `actions:false` can describe the unscoped owner model slot; conversation model readiness is separate, not permission to execute a plan.
326
+ In `status` and `diagnose`, `actions:false` can describe an empty unscoped owner model slot.
327
+ It does not disable conversation Send; the WebUI session reports workbench availability independently and each Send checks its own conversation model.
328
+ Neither flag is permission to execute a plan.
327
329
  - Disconnect this page (the WebUI More menu), browser close and Pi quit detach clients; admitted work continues.
328
330
  Use the client's **Cancel** for a run or management **stop** for the service.
329
331
  - Stop closes admission and waits original processes, credential writes, history writes, already-started publication continuations, owned networking and listener closure before releasing fences.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@abelxiaoxing/cadence",
3
- "version": "2.2.1",
3
+ "version": "2.2.2",
4
4
  "description": "Conversation-driven Pi workspace: persistent native and WebUI workflows, explicit plan approval, checks and local delivery.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -20,6 +20,7 @@ import { CadencePreferences } from "./cadence-preferences.ts";
20
20
  import {
21
21
  DESIGN_PARAMETERS,
22
22
  KNOWLEDGE_PARAMETERS,
23
+ knowledgeToolInput,
23
24
  PLAN_PARAMETERS,
24
25
  RESEARCH_PARAMETERS,
25
26
  } from "./coordinator-tools.mjs";
@@ -40,10 +41,7 @@ import {
40
41
  selectDesign,
41
42
  } from "./service/contracts/design.ts";
42
43
  import { decodeSessionId } from "./service/contracts/models.ts";
43
- import {
44
- type ChatTurn,
45
- decodeKnowledgeLookup,
46
- } from "./service/contracts/workbench.ts";
44
+ import type { ChatTurn } from "./service/contracts/workbench.ts";
47
45
  import {
48
46
  investigationId,
49
47
  readableDelivery,
@@ -396,7 +394,7 @@ export function registerCadenceMode(pi: ExtensionAPI): void {
396
394
  context = ctx;
397
395
  };
398
396
  const summarize = (run: WorkflowRun) =>
399
- `Cadence ${run.status} • ${run.goal}\nRun: ${run.id} · route revision ${run.revision ?? 0} · stepsBefore ${run.stepsBefore ?? 0}\n${workflowDiagnostics(run)}\n${readableDeliveryRun(run.delivery)}\n${run.steps.map((s) => `${s.kind} ${s.id}${s.kind === "research" && s.status === "completed" ? ` · investigation ${s.childRunId ?? investigationId(s.id)}` : ""}: ${s.status}${s.exitCode === null ? "" : ` (exit ${s.exitCode})`}\n${s.text}${s.truncated ? "\n[Preview truncated; full result retained by owner.]" : ""}`).join("\n")}\n${run.notice}${run.mergedCommit ? `\nLocal merge: ${run.mergedCommit}` : ""}${run.status === "unknown" ? "\nOutcome unknown: neither completed nor failed. Its actual effects are not inferred, and the owner keeps any fences." : ""}\nAutomatic review is not human review. Cadence mode remains enabled.`;
397
+ `Cadence ${run.status} • ${run.goal}\nRun: ${run.id} · route revision ${run.revision ?? 0} · stepsBefore ${run.stepsBefore ?? 0}\n${workflowDiagnostics(run)}\n${readableDeliveryRun(run)}\n${run.steps.map((s) => `${s.kind} ${s.id}${s.kind === "research" && s.status === "completed" ? ` · investigation ${s.childRunId ?? investigationId(s.id)}` : ""}: ${s.status}${s.exitCode === null ? "" : ` (exit ${s.exitCode})`}\n${s.text}${s.truncated ? "\n[Preview truncated; full result retained by owner.]" : ""}`).join("\n")}\n${run.notice}${run.mergedCommit ? `\nLocal merge: ${run.mergedCommit}` : ""}${run.status === "unknown" ? "\nOutcome unknown: neither completed nor failed. Its actual effects are not inferred, and the owner keeps any fences." : ""}\nAutomatic review is not human review. Cadence mode remains enabled.`;
400
398
  const agentDir = () => getAgentDir();
401
399
  /** The project's route table for this turn's system prompt. A turn never
402
400
  * fails because the table, or the workspace it is in, cannot be read. */
@@ -1074,9 +1072,10 @@ export function registerCadenceMode(pi: ExtensionAPI): void {
1074
1072
  description:
1075
1073
  "Read current checkout preparation facts, a project heading, a literal in a named source file, or a retained investigation without a research worker.",
1076
1074
  parameters: KNOWLEDGE_PARAMETERS,
1075
+ prepareArguments: knowledgeToolInput,
1077
1076
  async execute(_id, input, _signal, _update, ctx) {
1078
1077
  active(ctx);
1079
- const source = decodeKnowledgeLookup(input);
1078
+ const source = knowledgeToolInput(input);
1080
1079
  await connect(ctx, false);
1081
1080
  const observed = value(
1082
1081
  await client().workbenchRead({ kind: "project-knowledge", source }),
@@ -1,6 +1,6 @@
1
1
  /** Serialized private child/owner bridge. Never a browser API or shell executor. */
2
2
  import { Type } from "typebox";
3
- import { LIMITS } from "./worker-public.mjs";
3
+ import { closed, knowledgeFields, LIMITS } from "./worker-public.mjs";
4
4
 
5
5
  /** The parameters of the two tools a coordinator calls, declared once for the
6
6
  * native extension and the browser coordinator. They state shape only: counts,
@@ -52,6 +52,75 @@ export const RESEARCH_PARAMETERS = Type.Object({
52
52
  ),
53
53
  ),
54
54
  });
55
+ const lookupExample =
56
+ 'Use {checkout:["node_modules"]}, {checkout:[]}, {path:"docs.md"} with optional section or match, or {investigation:"<retained UUID>"}.';
57
+ /** Only model arguments may contain empty placeholders. Validate before the SDK
58
+ * coerces scalar types, and again at direct tool entry (no caller is trusted). */
59
+ export function knowledgeToolInput(input) {
60
+ const bad = (field, why) => {
61
+ throw new Error(`${field}: ${why}. ${lookupExample}`);
62
+ };
63
+ const keys = Object.keys(input ?? {});
64
+ let raw;
65
+ try {
66
+ raw = closed(input, keys);
67
+ } catch {
68
+ bad("cadence_knowledge", "expected an object with named lookup fields");
69
+ }
70
+ const fields = Object.create(null);
71
+ for (const key of keys) {
72
+ if (!Object.hasOwn(knowledgeFields, key))
73
+ bad(JSON.stringify(key.slice(0, 80)), "unknown field; omit it");
74
+ if (key !== "checkout" && raw[key] === "") continue;
75
+ try {
76
+ fields[key] = knowledgeFields[key](raw[key]);
77
+ } catch {
78
+ bad(
79
+ key,
80
+ key === "checkout"
81
+ ? "give an array of up to eight nonempty dependency paths (each at most 1024 bytes)"
82
+ : key === "investigation"
83
+ ? "give a retained investigation UUID"
84
+ : "give a nonblank string within the field limit",
85
+ );
86
+ }
87
+ }
88
+ const { checkout, path, section, match, investigation } = fields;
89
+ if ((section || match) && !path)
90
+ bad(
91
+ section ? "section/path" : "match/path",
92
+ "name the source file in path",
93
+ );
94
+ if (section && match) bad("section/match", "choose one selector");
95
+ if (checkout?.length && (path || investigation))
96
+ bad("checkout", "cannot combine dependencies with path or investigation");
97
+ if (investigation && path) bad("investigation/path", "choose one source");
98
+ const relative = (name) =>
99
+ !/[\\:\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(name) &&
100
+ name
101
+ .split("/")
102
+ .every(
103
+ (part) =>
104
+ part &&
105
+ part !== "." &&
106
+ part !== ".." &&
107
+ part.toLowerCase() !== ".git",
108
+ );
109
+ if (path && !relative(path))
110
+ bad("path", "give a plain checkout-relative file path");
111
+ if (
112
+ checkout?.some(
113
+ (name) =>
114
+ !relative(name) || name.split("/").some((part) => part.startsWith(".")),
115
+ )
116
+ )
117
+ bad("checkout", "give plain checkout-relative dependency names");
118
+ if (investigation) return { investigation };
119
+ if (path)
120
+ return match ? { path, match } : section ? { path, section } : { path };
121
+ if (checkout) return { checkout };
122
+ bad("path/checkout/investigation", "no lookup selected");
123
+ }
55
124
  export const KNOWLEDGE_PARAMETERS = Type.Object({
56
125
  checkout: Type.Optional(
57
126
  Type.Array(Type.String(), {
@@ -254,6 +323,7 @@ export function createCoordinatorTools() {
254
323
  description:
255
324
  "Read current checkout preparation facts, a project heading, a literal in one source file, or a retained investigation with its citations rechecked.",
256
325
  parameters: KNOWLEDGE_PARAMETERS,
326
+ prepareArguments: knowledgeToolInput,
257
327
  },
258
328
  {
259
329
  name: "cadence_design",
@@ -180,6 +180,13 @@ function decodeId(v) {
180
180
  invalid();
181
181
  return s;
182
182
  }
183
+ var knowledgeFields = Object.freeze({
184
+ checkout: (v) => list(v, 8, (entry) => text(entry, 1024, true)),
185
+ path: (v) => text(v, 1024, true),
186
+ section: (v) => text(v, 512, true),
187
+ match: (v) => text(v, 256, true),
188
+ investigation: decodeId
189
+ });
183
190
  function decodeHash(v) {
184
191
  const s = text(v, 64);
185
192
  if (!/^[0-9a-f]{64}$/.test(s))
@@ -2,5 +2,5 @@
2
2
  export const nativeBuild = {
3
3
  kind: "native",
4
4
  contractHash:
5
- "190a21e723f753a233225a9f4bcf12a99d71b294a58728961846cd110cd60a17",
5
+ "80875479add4b7830419060b7e5018a39de200665edfbdec20fc10d50861bfea",
6
6
  } as const;
@@ -31,7 +31,7 @@ export async function workflowDetails(
31
31
  throw new ContractError("invalid");
32
32
  const run = view.response.run;
33
33
  await ui.show(
34
- `${run.goal}\n${run.id} • ${run.status} / ${run.phase}\n${run.notice}\n${workflowDiagnostics(run)}\n${readableDeliveryRun(run.delivery)}\nMerged commit: ${run.mergedCommit ?? "none"}\nAutomatic Agent review is not human review. Step summaries are previews; select a step for its retained result.\n${pretty(run.steps)}`,
34
+ `${run.goal}\n${run.id} • ${run.status} / ${run.phase}\n${run.notice}\n${workflowDiagnostics(run)}\n${readableDeliveryRun(run)}\nMerged commit: ${run.mergedCommit ?? "none"}\nAutomatic Agent review is not human review. Step summaries are previews; select a step for its retained result.\n${pretty(run.steps)}`,
35
35
  );
36
36
  const labels = run.steps.map(
37
37
  (s, i) => `${i + 1}. ${s.kind} • ${s.id} • ${s.status}`,
@@ -1,5 +1,9 @@
1
1
  import { IMAGE_LIMITS, IMAGE_TYPES } from "../../image-content.mjs";
2
- import { decodeModelRetry, type ModelRetry } from "../../worker-public.mjs";
2
+ import {
3
+ decodeModelRetry,
4
+ knowledgeFields,
5
+ type ModelRetry,
6
+ } from "../../worker-public.mjs";
3
7
  /** Finite, authenticated workbench API. Ordinary chat is not task admission. */
4
8
  import {
5
9
  bool,
@@ -117,17 +121,19 @@ export type KnowledgeLookup =
117
121
  export function decodeKnowledgeLookup(v: unknown): KnowledgeLookup {
118
122
  if (Object.hasOwn(v ?? {}, "checkout")) {
119
123
  const { checkout } = closed(v, ["checkout"]);
120
- return { checkout: list(checkout, 8, (path) => text(path, 1024, true)) };
124
+ return { checkout: knowledgeFields.checkout(checkout) };
121
125
  }
122
126
  if (Object.hasOwn(v ?? {}, "investigation"))
123
127
  return {
124
- investigation: decodeId(closed(v, ["investigation"]).investigation),
128
+ investigation: knowledgeFields.investigation(
129
+ closed(v, ["investigation"]).investigation,
130
+ ),
125
131
  };
126
132
  if (Object.hasOwn(v ?? {}, "match")) {
127
133
  const raw = closed(v, ["path", "match"]);
128
134
  return {
129
- path: text(raw.path, 1024, true),
130
- match: text(raw.match, 256, true),
135
+ path: knowledgeFields.path(raw.path),
136
+ match: knowledgeFields.match(raw.match),
131
137
  };
132
138
  }
133
139
  const raw = closed(v, [
@@ -135,10 +141,10 @@ export function decodeKnowledgeLookup(v: unknown): KnowledgeLookup {
135
141
  ...(Object.hasOwn(v ?? {}, "section") ? ["section"] : []),
136
142
  ]);
137
143
  return {
138
- path: text(raw.path, 1024, true),
144
+ path: knowledgeFields.path(raw.path),
139
145
  ...(raw.section === undefined
140
146
  ? {}
141
- : { section: text(raw.section, 512, true) }),
147
+ : { section: knowledgeFields.section(raw.section) }),
142
148
  };
143
149
  }
144
150
  export type WorkbenchRead =
@@ -1098,9 +1098,37 @@ export function readableDelivery(binding?: DeliveryBinding): string {
1098
1098
  const t = binding.target;
1099
1099
  return `Target: ${t.branch} @ ${t.head}\nTarget checkout: ${t.checkoutRoot}\nExecution: new cadence/<goal>-<run-id> branch and one stable isolated worktree after approval. Assignments that can run side by side each work in a temporary worktree of their own beside it; the service commits that work and picks it onto the candidate. Independent conversations may use separate candidates concurrently.\nAcceptance: checks and automatic Agent review of the exact candidate. A verified, non-overlapping sibling delivery may be merged into the isolated candidate, followed by fresh checks and review.\nDelivery: serialized fast-forward only into the bound target at its approved, verified-sibling or own last confirmed baseline. Keep the task branch; remove only owned worktrees without any residue, including ignored files. No source/profile/dependency copying, push or deployment.`;
1100
1100
  }
1101
- export function readableDeliveryRun(d?: DeliveryObservation): string {
1101
+ /** Display projection only. A missing seal is not proof of missing edits.
1102
+ * In an interrupted run pending facts may simply not have been recorded. */
1103
+ export function deliveryLabels(
1104
+ d: DeliveryObservation,
1105
+ status: WorkflowRun["status"],
1106
+ ) {
1107
+ const finished = status !== "running" && status !== "queued";
1108
+ const settled = finished && status !== "unknown";
1109
+ const beforeWorkspace =
1110
+ settled && d.workspace === null && d.preparation === "pending";
1111
+ const pending = (value: string) =>
1112
+ value !== "pending" || !finished
1113
+ ? value
1114
+ : settled
1115
+ ? "Not executed"
1116
+ : "Not recorded";
1117
+ return {
1118
+ preparation:
1119
+ d.preparation === "pending" && finished && !beforeWorkspace
1120
+ ? "Not recorded"
1121
+ : pending(d.preparation),
1122
+ missingCandidate: beforeWorkspace ? "Not executed" : "Not recorded",
1123
+ integration: pending(d.integration.status),
1124
+ cleanup: pending(d.cleanup.status),
1125
+ } as const;
1126
+ }
1127
+ export function readableDeliveryRun(run: WorkflowRun): string {
1128
+ const d = run.delivery;
1102
1129
  if (!d) return "";
1103
- return `Task branch: ${d.taskBranch}\nWorktree: ${d.worktreeRoot}\nTarget: ${d.binding.target.branch} @ ${d.binding.target.head}\nPreparation: ${d.preparation}\nCandidate: ${d.candidate ?? "not recorded"}\nAcceptance: ${d.acceptance ? `checks + automatic Agent review of ${d.acceptance.candidate}` : "not recorded"}\nIntegration: ${d.integration.status}${d.integration.after ? ` @ ${d.integration.after}` : ""}${d.integration.reason ? ` — ${d.integration.reason}` : ""}\nPost-merge checks: ${d.postChecks}\nWorktree cleanup: ${d.cleanup.status}${d.cleanup.reason ? ` — ${d.cleanup.reason}` : ""}\nPolicy: keep the task branch; no push or deployment.`;
1130
+ const labels = deliveryLabels(d, run.status);
1131
+ return `Task branch: ${d.taskBranch}\nWorktree: ${d.worktreeRoot}\nTarget: ${d.binding.target.branch} @ ${d.binding.target.head}\nPreparation: ${labels.preparation}\nCandidate: ${d.candidate ?? labels.missingCandidate}\nAcceptance: ${d.acceptance ? `checks + automatic Agent review of ${d.acceptance.candidate}` : labels.missingCandidate}\nIntegration: ${labels.integration}${d.integration.after ? ` @ ${d.integration.after}` : ""}${d.integration.reason ? ` — ${d.integration.reason}` : ""}\nPost-merge checks: ${d.postChecks}\nWorktree cleanup: ${labels.cleanup}${d.cleanup.reason ? ` — ${d.cleanup.reason}` : ""}\nPolicy: keep the task branch; no push or deployment.`;
1104
1132
  }
1105
1133
  export function decodeWorkflowProposal(v: unknown): WorkflowProposal {
1106
1134
  const modern =
@@ -46,7 +46,7 @@ const CHUNK = 1024 * 1024;
46
46
  /** A refusal with an explanation; the public code stays one of ERROR_CODES. */
47
47
  export class WorkflowRefusal extends ContractError {
48
48
  constructor(
49
- code: "conflict" | "stale" | "forbidden" | "invalid",
49
+ code: "conflict" | "stale" | "forbidden" | "invalid" | "unavailable",
50
50
  readonly detail: string,
51
51
  ) {
52
52
  super(code);
@@ -668,20 +668,40 @@ export function workflowObservation(
668
668
  identity: hash(JSON.stringify({ head, branch, contents })),
669
669
  };
670
670
  }
671
+ /** Observe the target checkout, never the isolated candidate. Keep both Git
672
+ * answers even when one is unavailable. No later reread supplies failure facts. */
673
+ export async function assertTargetPosition(
674
+ cwd: string,
675
+ expected: { head: string; branch: string },
676
+ stage: string,
677
+ ): Promise<void> {
678
+ const [ref, oid] = await Promise.all([
679
+ gitRun(cwd, ["symbolic-ref", "--quiet", "HEAD"]).catch(() => null),
680
+ gitRun(cwd, ["rev-parse", "--verify", "HEAD"]).catch(() => null),
681
+ ]);
682
+ const branch =
683
+ ref?.code === 0
684
+ ? ref.stdout.trim()
685
+ : ref?.code === 1
686
+ ? "(detached HEAD)"
687
+ : null;
688
+ const head = oid?.code === 0 ? oid.stdout.trim() : null;
689
+ if (head === expected.head && branch === expected.branch) return;
690
+ const unreadable = !head || !branch;
691
+ throw new WorkflowRefusal(
692
+ unreadable ? "unavailable" : "stale",
693
+ `${stage}: target ${unreadable ? "identity could not be verified" : "position changed"}; expected ${expected.branch} at ${expected.head}, observed ${branch || "(unreadable ref)"} at ${head || "(unreadable HEAD)"}. Refused to proceed; this check made no merge.`,
694
+ );
695
+ }
671
696
  /** Only what a safe fast-forward needs: the same branch and HEAD, and no dirty
672
697
  * declared/generated target. Unrelated user changes are left to `merge --ff-only`. */
673
698
  export async function assertTarget(
674
699
  cwd: string,
675
700
  expected: { head: string; branch: string },
676
701
  scope: readonly string[],
702
+ stage: string,
677
703
  ): Promise<void> {
678
- const head = await gitHead(cwd);
679
- const branch = (await gitText(cwd, ["symbolic-ref", "HEAD"])).trim();
680
- if (head !== expected.head || branch !== expected.branch)
681
- throw new WorkflowRefusal(
682
- "stale",
683
- `The target branch changed during the run (expected ${expected.branch} at ${expected.head.slice(0, 12)}); nothing was integrated.`,
684
- );
704
+ await assertTargetPosition(cwd, expected, stage);
685
705
  assertVisibleIndex(
686
706
  overlapping(scope, indexHidden(await gitText(cwd, INDEX_FLAGS))),
687
707
  );
@@ -347,6 +347,13 @@ function decodeId(v) {
347
347
  invalid();
348
348
  return s;
349
349
  }
350
+ var knowledgeFields = Object.freeze({
351
+ checkout: (v) => list(v, 8, (entry) => text(entry, 1024, true)),
352
+ path: (v) => text(v, 1024, true),
353
+ section: (v) => text(v, 512, true),
354
+ match: (v) => text(v, 256, true),
355
+ investigation: decodeId
356
+ });
350
357
  function decodeHash(v) {
351
358
  const s = text(v, 64);
352
359
  if (!/^[0-9a-f]{64}$/.test(s))