opencode-wiki-historian 0.6.3 → 0.7.0

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.
Files changed (56) hide show
  1. package/README.en.md +156 -42
  2. package/README.md +127 -360
  3. package/dist/anchor.js +4 -4
  4. package/dist/config.d.ts +3 -3
  5. package/dist/config.js +3 -3
  6. package/dist/index.d.ts +14 -4
  7. package/dist/index.js +21 -52
  8. package/dist/lint.d.ts +2 -2
  9. package/dist/lint.js +2 -2
  10. package/dist/maintain.d.ts +2 -2
  11. package/dist/maintain.js +7 -7
  12. package/dist/map.d.ts +1 -1
  13. package/dist/map.js +1 -1
  14. package/dist/migrate-apply.d.ts +1 -1
  15. package/dist/migrate-apply.js +1 -1
  16. package/dist/migrate-score.d.ts +2 -2
  17. package/dist/migrate-score.js +3 -3
  18. package/dist/migrate-store.d.ts +1 -1
  19. package/dist/migrate-store.js +1 -1
  20. package/dist/migrate.d.ts +2 -2
  21. package/dist/migrate.js +2 -2
  22. package/dist/prompts.d.ts +20 -0
  23. package/dist/prompts.js +46 -0
  24. package/dist/skills.d.ts +33 -0
  25. package/dist/skills.js +88 -0
  26. package/dist/surface.d.ts +1 -1
  27. package/dist/surface.js +2 -2
  28. package/dist/templates/evidence.d.ts +1 -1
  29. package/dist/templates/evidence.js +1 -1
  30. package/dist/templates/genres.d.ts +5 -5
  31. package/dist/templates/genres.js +7 -7
  32. package/dist/templates/skeletons.d.ts +3 -3
  33. package/dist/templates/skeletons.js +3 -3
  34. package/dist/tools/anchor.js +2 -2
  35. package/dist/tools/create.js +1 -1
  36. package/dist/tools/local.js +1 -1
  37. package/dist/tools/mutate.d.ts +1 -1
  38. package/dist/tools/mutate.js +1 -1
  39. package/dist/tools/shared.d.ts +3 -3
  40. package/dist/tools/shared.js +10 -10
  41. package/dist/tools.d.ts +2 -2
  42. package/dist/tools.js +2 -2
  43. package/dist/translate.d.ts +1 -1
  44. package/dist/translate.js +1 -1
  45. package/dist/v2.d.ts +114 -0
  46. package/dist/v2.js +249 -0
  47. package/dist/wiki/assets.d.ts +1 -1
  48. package/dist/wiki/assets.js +1 -1
  49. package/dist/wiki/client.d.ts +2 -3
  50. package/dist/wiki/client.js +2 -3
  51. package/dist/wiki/locale.d.ts +1 -1
  52. package/dist/wiki/locale.js +3 -3
  53. package/dist/wiki/pages.read.d.ts +1 -1
  54. package/dist/wiki/pages.write.d.ts +1 -1
  55. package/package.json +1 -1
  56. package/skills/historian/SKILL.md +2 -2
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Machine-tier evidence page skeleton (v3 todo 5).
2
+ * Machine-tier evidence page skeleton.
3
3
  *
4
4
  * Evidence pages live under the internal namespaces (`_meta/`, `_evidence/`),
5
5
  * are hidden and monolingual — the wiki is their only store (no local mirror,
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Page-genre system: bilingual G1–G5 templates, deterministic genre
3
- * classification, and the 10-item self-review gate (plan todo 9).
3
+ * classification, and the 10-item self-review gate.
4
4
  *
5
5
  * The five genres (digest "Genre templates", cross-cultural-wiki-writing):
6
6
  * G1 事件/复盘页 — incident postmortem (summary → metadata → background →
@@ -21,7 +21,7 @@
21
21
  *
22
22
  * Every skeleton embeds the harness rubric dimension-C anatomy (status block,
23
23
  * one-line scope, Related Pages tail) and wiki.js expression pieces only —
24
- * see skeletons.ts for the raw strings. Consumers (tools.ts, todo 14/15 pilot)
24
+ * see skeletons.ts for the raw strings. Consumers (tools.ts, the migrate pilot)
25
25
  * import everything from this barrel.
26
26
  */
27
27
  export { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, G6_EN, G6_ZH, } from './skeletons.js';
@@ -39,13 +39,13 @@ export interface ClassifyResult {
39
39
  /** The keyword cues that were matched (deterministic order, no duplicates). */
40
40
  readonly signals: readonly string[];
41
41
  }
42
- /** One gate item of the 10-item self-review checklist (plan todo 9). */
42
+ /** One gate item of the 10-item self-review checklist. */
43
43
  export interface ChecklistItem {
44
44
  /** 1..10 — items are always returned as the full contiguous gate. */
45
45
  readonly id: number;
46
46
  readonly label: string;
47
47
  /** kind='genre-specific' items are scored N/A=PASS when the page's genre is
48
- * not in `appliesTo` (pilot scoring, todo 14/15). */
48
+ * not in `appliesTo` (pilot scoring). */
49
49
  readonly kind: 'content' | 'post-write' | 'genre-specific';
50
50
  readonly appliesTo: readonly Genre[] | 'all';
51
51
  }
@@ -60,6 +60,6 @@ export declare function genreSkeleton(genre: Genre, lang: GenreLang): string;
60
60
  * - a tie between the two top scores (both > 0) → G4/medium (generalist
61
61
  * genre wins the ambiguous case);
62
62
  * - otherwise the top genre wins; confidence = margin ≥ 3 → high, else medium.
63
- * `signals` names the matched cues (used by the pilot engine, todo 14/15). */
63
+ * `signals` names the matched cues (used by the pilot engine). */
64
64
  export declare function classifyGenre(input: ClassifyInput): ClassifyResult;
65
65
  export declare function selfReviewChecklist(genre: Genre): readonly ChecklistItem[];
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Page-genre system: bilingual G1–G5 templates, deterministic genre
3
- * classification, and the 10-item self-review gate (plan todo 9).
3
+ * classification, and the 10-item self-review gate.
4
4
  *
5
5
  * The five genres (digest "Genre templates", cross-cultural-wiki-writing):
6
6
  * G1 事件/复盘页 — incident postmortem (summary → metadata → background →
@@ -21,12 +21,12 @@
21
21
  *
22
22
  * Every skeleton embeds the harness rubric dimension-C anatomy (status block,
23
23
  * one-line scope, Related Pages tail) and wiki.js expression pieces only —
24
- * see skeletons.ts for the raw strings. Consumers (tools.ts, todo 14/15 pilot)
24
+ * see skeletons.ts for the raw strings. Consumers (tools.ts, the migrate pilot)
25
25
  * import everything from this barrel.
26
26
  */
27
27
  import { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, G6_EN, G6_ZH, } from './skeletons.js';
28
28
  // Contract re-exports: raw skeleton data stays reachable through the barrel
29
- // (todo 13 renders these double-checked strings into skill references).
29
+ // (the skill loader renders these double-checked strings into skill references).
30
30
  export { G1_EN, G1_ZH, G2_EN, G2_ZH, G3_EN, G3_ZH, G4_EN, G4_ZH, G5_EN, G5_ZH, G6_EN, G6_ZH, } from './skeletons.js';
31
31
  export const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5', 'G6'];
32
32
  // --- genreSkeleton ----------------------------------------------------------
@@ -90,7 +90,7 @@ function countMatches(haystack, keyword) {
90
90
  * - a tie between the two top scores (both > 0) → G4/medium (generalist
91
91
  * genre wins the ambiguous case);
92
92
  * - otherwise the top genre wins; confidence = margin ≥ 3 → high, else medium.
93
- * `signals` names the matched cues (used by the pilot engine, todo 14/15). */
93
+ * `signals` names the matched cues (used by the pilot engine). */
94
94
  export function classifyGenre(input) {
95
95
  const title = input.title.toLowerCase();
96
96
  const rawBody = input.body;
@@ -122,8 +122,8 @@ export function classifyGenre(input) {
122
122
  }
123
123
  // --- selfReviewChecklist ----------------------------------------------------
124
124
  /**
125
- * The 10-item self-review gate (plan todo 9). The FULL gate is always
126
- * returned (ids 1..10 contiguous); the pilot engine (todo 15) applies items
125
+ * The 10-item self-review gate. The FULL gate is always
126
+ * returned (ids 1..10 contiguous); the pilot engine applies items
127
127
  * via the kind/appliesTo contract:
128
128
  * - content items (1–3, 7, 8) — scored on the rewritten draft (dry-run);
129
129
  * - genre-specific items (4–6) — N/A=PASS when the page's genre is not in
@@ -160,7 +160,7 @@ const G5_CHECKLIST_VARIANTS = {
160
160
  },
161
161
  };
162
162
  /** G6 swaps the genre-specific items 4–6 for how-to gates (goal-titled H1,
163
- * step triples, D4 freshness metadata); everything else is shared. */
163
+ * step triples, freshness metadata); everything else is shared. */
164
164
  const G6_CHECKLIST_VARIANTS = {
165
165
  4: {
166
166
  id: 4,
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Bilingual G1–G4 page skeletons (template data).
3
3
  *
4
- * Provenance: `.omo/research/cross-cultural-wiki-writing-digest.md` (Genre
5
- * templates + SYN-1..20) and `.omo/research/wikijs-2x-capabilities-digest.md`
6
- * (expression syntax), vendored at `docs/research/*`.
4
+ * Provenance: `docs/research/cross-cultural-wiki-writing-digest.md` (Genre
5
+ * templates + SYN-1..20) and `docs/research/wikijs-2x-capabilities-digest.md`
6
+ * (expression syntax) — both digests are vendored in this repo under `docs/research/`.
7
7
  *
8
8
  * Contract of every skeleton constant:
9
9
  * - Rubric dimension C anatomy: H1 placeholder → status line
@@ -1,9 +1,9 @@
1
1
  /**
2
2
  * Bilingual G1–G4 page skeletons (template data).
3
3
  *
4
- * Provenance: `.omo/research/cross-cultural-wiki-writing-digest.md` (Genre
5
- * templates + SYN-1..20) and `.omo/research/wikijs-2x-capabilities-digest.md`
6
- * (expression syntax), vendored at `docs/research/*`.
4
+ * Provenance: `docs/research/cross-cultural-wiki-writing-digest.md` (Genre
5
+ * templates + SYN-1..20) and `docs/research/wikijs-2x-capabilities-digest.md`
6
+ * (expression syntax) — both digests are vendored in this repo under `docs/research/`.
7
7
  *
8
8
  * Contract of every skeleton constant:
9
9
  * - Rubric dimension C anatomy: H1 placeholder → status line
@@ -33,7 +33,7 @@ function extractReceipt(content) {
33
33
  }
34
34
  export function makeAnchorTool(deps) {
35
35
  return tool({
36
- description: 'Historian anchor (g12b-3 in the memory seat): action:"seal" locates a human order/approval message in the engine session store ' +
36
+ description: 'Historian anchor: action:"seal" locates a human order/approval message in the engine session store ' +
37
37
  '(by session_id/session_title + index or unique body match), hashes it (raw + canonical, closed normalization list) and writes an ' +
38
38
  '_evidence/anchors/<slug> receipt page; action:"verify" re-reads the store against a sealed page and returns MATCH/MISMATCH/ABSENT with drift fields. ' +
39
39
  'Read-only against the store; the wiki page is the durable receipt. ' + URL_MANDATE,
@@ -62,7 +62,7 @@ export function makeAnchorTool(deps) {
62
62
  locale: 'en',
63
63
  title: `Anchor seal ${slug}${a.label !== undefined ? ` — ${a.label}` : ''}`,
64
64
  content: renderSealPage(r, a.label),
65
- tags: ['anchor-seal', 'g12b-3'],
65
+ tags: ['anchor-seal'],
66
66
  isPublished: true,
67
67
  twin: false,
68
68
  });
@@ -75,7 +75,7 @@ export function makeCreateTool(deps) {
75
75
  const localeHint = isEvidence && args.locale === 'zh'
76
76
  ? 'evidence pages are monolingual en — the locale argument was forced to "en"'
77
77
  : undefined;
78
- // Genre is resolved ONCE, above the template/content fork (v4 todo 4):
78
+ // Genre is resolved ONCE, above the template/content fork:
79
79
  // the template branch feeds it the skeleton, the content branch the
80
80
  // pre-write checklist gate. Explicit arg wins over classification.
81
81
  const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
@@ -86,7 +86,7 @@ async function scanStatusTokenConflicts(rows, readBody, baseUrl) {
86
86
  /** maintain: light tier is map rows + ONE read-only pages.list pass per locale
87
87
  * (the mirror's MapRow carries no tags; the list join restores the vocab view);
88
88
  * deep additionally reads each body via readPage. Reserved-path pages (e.g.
89
- * 'home', probe p1) answer null instead of killing the sweep. Read-only. */
89
+ * 'home') answer null instead of killing the sweep. Read-only. */
90
90
  async function runMaintain(deps, mapDeps, snapshot, deep) {
91
91
  const client = deps.getClient();
92
92
  const tagIndex = new Map();
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * historian_delete + historian_move + historian_migrate: destructive ops are
3
- * gated on confirm:"yes" BEFORE any fetch; migrate runs the todo-14 engine —
3
+ * gated on confirm:"yes" BEFORE any fetch; migrate runs the migration engine —
4
4
  * dry-run (LLM restyle + deterministic checklist, no writes) or apply
5
5
  * (pre-image backup first, per-locale upsert, checkpoint, verification).
6
6
  */
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * historian_delete + historian_move + historian_migrate: destructive ops are
3
- * gated on confirm:"yes" BEFORE any fetch; migrate runs the todo-14 engine —
3
+ * gated on confirm:"yes" BEFORE any fetch; migrate runs the migration engine —
4
4
  * dry-run (LLM restyle + deterministic checklist, no writes) or apply
5
5
  * (pre-image backup first, per-locale upsert, checkpoint, verification).
6
6
  */
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Shared plumbing for the historian_* tool surface (todo 11): the tool
2
+ * Shared plumbing for the historian_* tool surface: the tool
3
3
  * dependency bag, locale-aware URL helpers (reserved-path safe), the uniform
4
4
  * JSON envelope helpers and the error → envelope mapping.
5
5
  *
@@ -74,7 +74,7 @@ export declare function tierMismatchJson(message: string): ToolResult;
74
74
  /** Evidence-tier zh-side input → refusal envelope (monolingual invariant). */
75
75
  export declare function monolingualRefusalJson(toolName: string, argumentName: string): ToolResult;
76
76
  /** historian_page_append got a non-empty `content` that `section` does not carry →
77
- * refuse loudly instead of silently dropping it (infra handoff 2026-10-23). */
77
+ * refuse loudly instead of silently dropping it. */
78
78
  export declare function contentArgRefusalJson(): ToolResult;
79
79
  /** Soft-gate advisory for front-tier raw dumps: null when nothing to say
80
80
  * (evidence tier NEVER checked — machine pages are the raw-material home;
@@ -106,7 +106,7 @@ export interface CollisionInput {
106
106
  * namespaces (_meta/, _evidence/) never surface as duplicates. */
107
107
  export declare function collisionAdvisory(input: CollisionInput): string | null;
108
108
  /**
109
- * Pre-write self-check advisory (plan todo 4): score the draft with the SAME
109
+ * Pre-write self-check advisory: score the draft with the SAME
110
110
  * 10-item gate the migrate pipeline uses (scoreChecklist — no duplicated
111
111
  * scoring logic), purely locally, zero network. 3+ failing items produce a
112
112
  * hint naming them; items 9-10 are 'deferred' pre-write by the scorer's own
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Shared plumbing for the historian_* tool surface (todo 11): the tool
2
+ * Shared plumbing for the historian_* tool surface: the tool
3
3
  * dependency bag, locale-aware URL helpers (reserved-path safe), the uniform
4
4
  * JSON envelope helpers and the error → envelope mapping.
5
5
  *
@@ -90,7 +90,7 @@ function hintFor(errorKind) {
90
90
  return 'Inspect the message and retry.';
91
91
  }
92
92
  }
93
- // --- Tier plumbing (v3 todo 4) ------------------------------------------------
93
+ // --- Tier plumbing ------------------------------------------------------------
94
94
  /** Machine namespaces: pages whose first path segment lives here are hidden
95
95
  * machine-tier pages (the `_meta/page-map` cache precedent in src/map.ts —
96
96
  * isPublished:false + isPrivate:true + tags + twin:false). */
@@ -143,7 +143,7 @@ export function monolingualRefusalJson(toolName, argumentName) {
143
143
  });
144
144
  }
145
145
  /** historian_page_append got a non-empty `content` that `section` does not carry →
146
- * refuse loudly instead of silently dropping it (infra handoff 2026-10-23). */
146
+ * refuse loudly instead of silently dropping it. */
147
147
  export function contentArgRefusalJson() {
148
148
  return dump({
149
149
  ok: false,
@@ -153,7 +153,7 @@ export function contentArgRefusalJson() {
153
153
  actionableHint: 'Re-call with section set to the full text to append (title + body). A content already contained in section is accepted and ignored.',
154
154
  });
155
155
  }
156
- // --- Front-tier raw-dump soft gate (v3 todo 6) --------------------------------
156
+ // --- Front-tier raw-dump soft gate --------------------------------------------
157
157
  /** Contract band (SKILL.md SYN-16): a human page stays a 5-10 line excerpt;
158
158
  * longer raw material belongs on an evidence page. Strictly ABOVE this many
159
159
  * fence-interior lines triggers the advisory — 30 is the soft gate, never a
@@ -201,7 +201,7 @@ export function frontDumpAdvisory(tier, content) {
201
201
  return (`content contains a ${lines}-line fenced block; per contract, move raw material to a ` +
202
202
  `tier:"evidence" page under _evidence/ and link it from the human page (SYN-16)`);
203
203
  }
204
- // --- Create-path collision advisory (v4 todo 3) --------------------------------
204
+ // --- Create-path collision advisory -------------------------------------------
205
205
  /** Title equality for duplicate detection: trim, collapse internal whitespace,
206
206
  * casefold — 'LLM Eval' == ' llm\neval '. */
207
207
  function normalizeTitle(title) {
@@ -242,9 +242,9 @@ export function collisionAdvisory(input) {
242
242
  }
243
243
  return parts.length === 0 ? null : parts.join('\n');
244
244
  }
245
- // --- Create-path pre-write checklist gate (v4 todo 4) --------------------------
245
+ // --- Create-path pre-write checklist gate --------------------------------------
246
246
  /** Failing items needed to speak up: 1-2 stragglers are noise, 3+ is a draft
247
- * worth flagging. Threshold per the plan (todo 4). */
247
+ * worth flagging. */
248
248
  const CHECKLIST_FAIL_TRIGGER = 3;
249
249
  /** The zh short name of a checklist item: its label up to the first
250
250
  * full-width/latin colon or bracket — '导言占比 10–15%'. */
@@ -253,7 +253,7 @@ function itemShortName(label) {
253
253
  return cut === '' ? label.trim() : cut;
254
254
  }
255
255
  /**
256
- * Pre-write self-check advisory (plan todo 4): score the draft with the SAME
256
+ * Pre-write self-check advisory: score the draft with the SAME
257
257
  * 10-item gate the migrate pipeline uses (scoreChecklist — no duplicated
258
258
  * scoring logic), purely locally, zero network. 3+ failing items produce a
259
259
  * hint naming them; items 9-10 are 'deferred' pre-write by the scorer's own
@@ -269,7 +269,7 @@ export function checklistAdvisory(genre, draft) {
269
269
  const names = failed.map((v) => `#${v.id} ${itemShortName(labels.get(v.id) ?? '?')}`).join('; ');
270
270
  return `自检 ${failed.length}/10 未通过: ${names} (不阻断, 发布前请补齐)`;
271
271
  }
272
- // --- options.sections enforcement (v4 todo 5) ---------------------------------
272
+ // --- options.sections enforcement ----------------------------------------------
273
273
  /** Config-level write refusal, paralleling PathValidationError's shape. The
274
274
  * class NAME is the routing key errEnvelope dispatches on: this shares the
275
275
  * 'ConfigError' hint case with jsonc.ConfigError (which adds a code field
@@ -318,7 +318,7 @@ export function sectionRefusalJson(path, allowedSections) {
318
318
  const violation = sectionGuard(path, allowedSections);
319
319
  return violation === null ? null : errEnvelope(new ConfigError(violation));
320
320
  }
321
- // --- publish gate (V6.1, HANDOFF #5.1 / #6.1) --------------------------------
321
+ // --- publish gate ---------------------------------------------------------------
322
322
  export class PublishGateError extends Error {
323
323
  constructor(message) {
324
324
  super(message);
package/dist/tools.d.ts CHANGED
@@ -1,12 +1,12 @@
1
1
  /**
2
- * historian_* tool surface (todo 11) — barrel + composition.
2
+ * historian_* tool surface — barrel + composition.
3
3
  *
4
4
  * buildTools wires the 11 custom tools from the engine modules; this file
5
5
  * holds no engine logic, only wiring. Per-call construction (no module-level
6
6
  * cache — each buildTools call resolves a fresh client/translator), and the
7
7
  * client is resolved LAZILY: a missing/invalid wiki key surfaces as a
8
8
  * ConfigError envelope on first execution, never as a buildTools crash that
9
- * would kill plugin registration (todo 12).
9
+ * would kill plugin registration.
10
10
  */
11
11
  import type { ToolDefinition } from '@opencode-ai/plugin';
12
12
  import { type GqlClient } from './wiki/client.js';
package/dist/tools.js CHANGED
@@ -1,12 +1,12 @@
1
1
  /**
2
- * historian_* tool surface (todo 11) — barrel + composition.
2
+ * historian_* tool surface — barrel + composition.
3
3
  *
4
4
  * buildTools wires the 11 custom tools from the engine modules; this file
5
5
  * holds no engine logic, only wiring. Per-call construction (no module-level
6
6
  * cache — each buildTools call resolves a fresh client/translator), and the
7
7
  * client is resolved LAZILY: a missing/invalid wiki key surfaces as a
8
8
  * ConfigError envelope on first execution, never as a buildTools crash that
9
- * would kill plugin registration (todo 12).
9
+ * would kill plugin registration.
10
10
  */
11
11
  import { homedir } from 'node:os';
12
12
  import { createClient } from './wiki/client.js';
@@ -33,7 +33,7 @@ export interface TranslateDeps {
33
33
  }
34
34
  /** One raw Anthropic-compatible messages call: caller-supplied system + user
35
35
  * prompt, shared URL/auth/timeout/error-taxonomy with the translation engine.
36
- * The migrate reformatter (todo 14) reuses this path with its own prompt; a
36
+ * The migrate reformatter reuses this path with its own prompt; a
37
37
  * reformat call is never chunked (a restyle must see the whole page). */
38
38
  export interface MessagesCall {
39
39
  readonly system: string;
package/dist/translate.js CHANGED
@@ -134,7 +134,7 @@ export async function callMessages(opts, deps, call) {
134
134
  if (opts.translate.model.trim() === '') {
135
135
  throw new TranslateError('config', 'translate.model not configured — set plugin option translate.model or ' +
136
136
  'env HISTORIAN_TRANSLATE_MODEL to a model YOUR device is authorized for ' +
137
- '(L-MACHINE-LOCAL: the package ships no device model defaults).');
137
+ '(the package ships no device model defaults).');
138
138
  }
139
139
  if (opts.translate.apiKey.trim() === '') {
140
140
  const hint = opts.translate.providerKey !== ''
package/dist/v2.d.ts ADDED
@@ -0,0 +1,114 @@
1
+ /**
2
+ * V2 plugin generation: `setup(ctx)` adapter for the opencode v2 host
3
+ * (engine >= 2.2, default export `{id, setup, server}`).
4
+ *
5
+ * Ground truth for every host call below was probed against the installed
6
+ * engine binary (2.2.7/2.3.0), not against the v1-shaped public SDK:
7
+ * - ctx.tool.transform(editor => editor.add({name, description, input:
8
+ * <JSON Schema>, execute: async (args) => ({content})})) — registered and
9
+ * model-invocable (smoke-verified 11/11).
10
+ * - ctx.command.transform: editor exposes add() only; same-name add would
11
+ * shadow a user command, so the list-first check preserves the V1 ??=
12
+ * semantics (user-defined /historian-capture wins).
13
+ * - ctx.skill.transform: editor.add requires {id,name,description,path,
14
+ * content} (host throws SchemaError Missing key ["id"] otherwise).
15
+ * - ctx.session.hook('context', ev => ev.system is an array of typed
16
+ * parts): the advisory is merged into the LAST text part — the block
17
+ * count never grows, keeping strict chat templates (vLLM) happy, same
18
+ * invariant as the V1 system.transform hook.
19
+ * - ctx.event.subscribe({types}) returns an async iterable.
20
+ *
21
+ * Named gaps vs V1 (failures are logged, never silent):
22
+ * - Capture reminder: the v2 server surface has no toast channel (ctx.rpc
23
+ * is a definition factory, not a caller; there is no ctx.tui/client), so
24
+ * the idle reminder degrades to a one-time console.error per session.
25
+ * `session.idle` fires on busy→idle transitions (TUI sessions); headless
26
+ * `opencode run` streams do not emit it — same limitation class as V1.
27
+ * - skills.paths has no v2 config hook; skills ship through skill.transform
28
+ * instead (probe-verified surface).
29
+ *
30
+ * Options fail-closed: invalid/missing options log once and register
31
+ * NOTHING (no half-wired tool surface aimed at an unresolvable wiki key) —
32
+ * matching the sibling sibyl-system plugin's v2 precedent and stricter than
33
+ * V1's empty-hooks return.
34
+ */
35
+ import { type BuildDeps } from './tools.js';
36
+ /** Minimal structural surface of the v2 plugin context actually consumed.
37
+ * Deliberately local (no @opencode/plugin dependency — its published types
38
+ * lag the host): every access is still feature-detected at runtime, so an
39
+ * older/newer host without a given sub-surface degrades with a log line
40
+ * instead of a setup crash. */
41
+ export interface V2ToolCtx {
42
+ readonly sessionID: string;
43
+ readonly messageID?: string;
44
+ readonly abort?: AbortSignal;
45
+ }
46
+ export interface V2Ctx {
47
+ readonly options?: unknown;
48
+ readonly tool?: {
49
+ transform(fn: (editor: {
50
+ add: (def: {
51
+ name: string;
52
+ description: string;
53
+ input: Record<string, unknown>;
54
+ execute: (args: Record<string, unknown>, ctx: V2ToolCtx) => Promise<{
55
+ content: string;
56
+ }>;
57
+ }) => unknown;
58
+ }) => unknown | Promise<unknown>): unknown;
59
+ };
60
+ readonly command?: {
61
+ list(): Promise<ReadonlyArray<{
62
+ name: string;
63
+ }> | null | undefined>;
64
+ transform(fn: (editor: {
65
+ add: (def: {
66
+ name: string;
67
+ description: string;
68
+ template: string;
69
+ }) => unknown;
70
+ }) => unknown | Promise<unknown>): unknown;
71
+ };
72
+ readonly skill?: {
73
+ transform(fn: (editor: {
74
+ add: (def: {
75
+ id: string;
76
+ name: string;
77
+ description: string;
78
+ path: string;
79
+ content: string;
80
+ }) => unknown;
81
+ }) => unknown | Promise<unknown>): unknown;
82
+ };
83
+ readonly session?: {
84
+ hook(name: 'context', handler: (ev: {
85
+ system?: Array<Record<string, unknown>>;
86
+ }) => void | Promise<void>): unknown;
87
+ };
88
+ readonly event?: {
89
+ subscribe(filter: {
90
+ types?: string[];
91
+ }): AsyncIterable<{
92
+ type?: string;
93
+ properties?: Record<string, unknown>;
94
+ }>;
95
+ };
96
+ }
97
+ export interface SetupDeps {
98
+ /** Test seam: where the reading-loop confirmation sentinel lives (V1 uses
99
+ * homedir()). */
100
+ readonly homeDir?: string;
101
+ /** Test seam: env source forwarded to resolveOptions (defaults process.env). */
102
+ readonly env?: NodeJS.ProcessEnv;
103
+ /** Test seam: dependency bag forwarded to buildTools (client/translator
104
+ * injection). Production stays `{}` — buildTools resolves lazily. */
105
+ readonly buildDeps?: BuildDeps;
106
+ readonly log?: (message: string) => void;
107
+ }
108
+ /** Convert a V1 tool's zod raw arg shape to JSON Schema through the SDK's
109
+ * nested zod (tool.schema) — single source, no per-tool schema duplicates.
110
+ * On conversion failure, a permissive object schema is registered and
111
+ * logged; execute still validates with the strict zod parse inside the V1
112
+ * tool body, so a loose registration can never corrupt inputs. */
113
+ export declare function argsToJsonSchema(args: Record<string, unknown> | undefined): Record<string, unknown>;
114
+ export declare function setup(ctx: V2Ctx, deps?: SetupDeps): Promise<void>;