ytdb-slate 0.2.1 → 0.4.0

package/extension/index.ts

@@ -20,12 +20,14 @@
  * Optional config at <config dir>/slate.json (config dir = CONFIG_DIR_NAME,
  * ".pi" by default), honored ONLY when the project is trusted — untrusted
  * projects run on built-in defaults with no project file injection:
- *   { "episodeModel": "provider/id", "workerTools": [...], "maxConcurrent": 4,
+ *   { "episodeModel": "provider/id", "workerTools": [...],
+ *     "workerExtensions": ["regex", ...], "maxConcurrent": 4,
  *     "contextBudget": 256000, "orchestratorModeDefault": true,
  *     "orchestratorPromptDocs": ["docs/orchestrator-guidelines.md"],
  *     "workerPromptDocs": ["docs/thread-guidelines.md"],
  *     "workflow": { "draftPRs": false },
  *     "modelFailover": { "provider/id": "provider/id" },
+ *     "preserveGlobalModelDefault": true,
  *     "doctrineExtraPath": "docs/project-doctrine.md",
  *     "reviewPerspectivesPath": "docs/review-perspectives.md" }
  * contextBudget also takes { "tokens": N, "overrides": [{ "match": "regex",
@@ -45,6 +47,12 @@ import { registerSlateMode } from "./mode.ts";
 import { SlateStore, type SlateConfig } from "./state.ts";
 import { ThreadManager } from "./threads.ts";
 import { registerSlateTools } from "./tools.ts";
+import {
+	createWorkerExtensionResolver,
+	EMPTY_WORKER_EXTENSION_SET,
+	sanitizeWorkerExtensions,
+	type WorkerExtensionSet,
+} from "./worker-extensions.ts";
 
 function loadConfig(cwd: string): SlateConfig {
 	const file = join(cwd, CONFIG_DIR_NAME, "slate.json");
@@ -67,7 +75,16 @@ function loadConfig(cwd: string): SlateConfig {
 
 export default function (pi: ExtensionAPI) {
 	const store = new SlateStore(pi);
-	let manager = new ThreadManager(store, {});
+	// One worker-extension resolver per session (AD41), reassigned every
+	// session_start below. The DOCTRINE consumer (registerSlateMode) reads it
+	// through the live `() => resolveWorkerExtensionSet()` indirection because it
+	// always belongs to the CURRENT session. ThreadManager instead binds the
+	// resolver instance BY VALUE at construction (CN20): a manager orphaned by a
+	// session swap must keep resolving against ITS OWN session's frozen set, not a
+	// later session's — the live indirection would leak the newer set into the
+	// stale manager. Starts as the empty set (feature off) until session_start.
+	let resolveWorkerExtensionSet: () => WorkerExtensionSet = () => EMPTY_WORKER_EXTENSION_SET;
+	let manager = new ThreadManager(store, {}, resolveWorkerExtensionSet);
 
 	registerSlateTools(pi, store, () => manager);
 
@@ -77,15 +94,24 @@ export default function (pi: ExtensionAPI) {
 		// it is honored only for trusted projects; untrusted → built-in defaults.
 		const config = ctx.isProjectTrusted() ? loadConfig(ctx.cwd) : {};
 		const warn = (msg: string) => (ctx.hasUI ? ctx.ui.notify(msg, "warning") : console.warn(msg));
-		// modelFailover and contextBudget are validated eagerly: a malformed
-		// value would otherwise fail silently mid-dispatch / exactly when the
-		// auto-pause was supposed to save the orchestrator's context.
+		// modelFailover, contextBudget and workerExtensions are validated eagerly:
+		// a malformed value would otherwise fail silently mid-dispatch / exactly
+		// when the auto-pause was supposed to save the orchestrator's context.
 		config.modelFailover = sanitizeModelFailover(config.modelFailover, warn);
 		config.contextBudget = sanitizeContextBudget(config.contextBudget, warn);
+		config.workerExtensions = sanitizeWorkerExtensions(config.workerExtensions, warn);
 		if (config.contextBudget !== undefined && config.pauseThresholdPercent !== undefined) {
 			warn("slate: contextBudget is set — the deprecated pauseThresholdPercent is ignored");
 		}
-		manager = new ThreadManager(store, config);
+		// Fresh resolver AFTER sanitization (reads the cleaned patterns) and per
+		// session_start (a restart re-resolves). Same warn as the sanitizers so a
+		// withheld colliding unit surfaces the same way. First use is later, in a
+		// worker open or a doctrine build — after session_start finishes, so tools
+		// registered during session_start are captured (AD41).
+		resolveWorkerExtensionSet = createWorkerExtensionResolver(pi, () => config.workerExtensions ?? [], warn);
+		// Bound BY VALUE (CN20): this manager keeps this session's resolver even if a
+		// later session_start replaces the module variable above.
+		manager = new ThreadManager(store, config, resolveWorkerExtensionSet);
 		store.restore(ctx);
 	});
 
@@ -103,5 +129,5 @@ export default function (pi: ExtensionAPI) {
 	// order-critical relative to the handlers above (different trigger events).
 	registerOrchestratorFailover(pi, () => manager.getConfig());
 
-	registerSlateMode(pi, store, handoff, () => manager.getConfig());
+	registerSlateMode(pi, store, handoff, () => manager.getConfig(), () => resolveWorkerExtensionSet());
 }

package/extension/mode.ts

@@ -27,6 +27,7 @@ import {
 } from "./paths.ts";
 import { loadPromptDocs } from "./prompt-docs.ts";
 import { orchestratorCostUsd, type SlateConfig, type SlateStore } from "./state.ts";
+import type { WorkerExtensionSet, WorkerExtensionUnit } from "./worker-extensions.ts";
 
 const ORCHESTRATOR_TOOLS = ["read", "grep", "find", "ls", "thread", "threads", "episode"];
 
@@ -40,7 +41,68 @@ const ORCHESTRATOR_TOOLS = ["read", "grep", "find", "ls", "thread", "threads", "
  * the file exists (cwd-resolved) — missing files are skipped silently like
  * every other project doc.
  */
-function buildDoctrine(cwd: string, config: SlateConfig, trusted: boolean): string {
+// A source spec that names WHICH extension (e.g. "npm:foo") is worth showing;
+// the generic scope-ish sources are not, so rule 11 falls back to the unit path.
+const UNINFORMATIVE_SOURCES = new Set(["", "auto", "local", "cli", "project", "user", "temporary", "builtin", "sdk"]);
+
+function unitLabel(unit: WorkerExtensionUnit): string {
+	return UNINFORMATIVE_SOURCES.has(unit.source) ? unit.path : unit.source;
+}
+
+// Per-field caps for the doctrine interpolations (WB21): a tool name is an
+// identifier, a unit label is a package spec or path, a description is a
+// sentence. Caps keep a pathological 2000-char value from bloating every turn.
+const DOCTRINE_NAME_MAX = 64;
+const DOCTRINE_LABEL_MAX = 128;
+const DOCTRINE_DESC_MAX = 140;
+
+// ONE sanitizer for every extension-supplied string interpolated into the
+// orchestrator doctrine — tool names, unit labels and descriptions (WB20/WB21/
+// WB22). The doctrine is a numbered, indented plain-text block inside the
+// system prompt, so a raw value must not be able to: (WB20) inject a newline
+// that forges a new numbered directive; (WB21) run on for thousands of
+// characters; or (WB22) carry backticks/markdown that break the block's
+// structure or read as an instruction. Control characters and newlines collapse
+// to spaces, backticks and markdown structural markers are dropped, remaining
+// whitespace is collapsed, and the result is capped with an ellipsis.
+function sanitizeForDoctrine(value: string, max: number): string {
+	const cleaned = value
+		.replace(/[\u0000-\u001f\u007f\u009b]/g, " ") // control chars + newlines → space (WB20)
+		.replace(/[`*_~#>|]/g, " ") // code fences / markdown structure → space (WB22)
+		.replace(/\s+/g, " ")
+		.trim();
+	return cleaned.length > max ? `${cleaned.slice(0, max - 1)}\u2026` : cleaned;
+}
+
+/**
+ * Rule 11 (worker-extension awareness): appended ONLY when workers load extra
+ * pi extensions. With no units it returns "" so the doctrine is byte-identical
+ * to the pre-feature output (feature-off is unchanged). Phrased to match the
+ * imperative register of rules 1–10 (WS20/WS21/WS22): it LEADS with the action
+ * (delegate to a thread), states the constraint in the doctrine's own "cannot"
+ * voice, and CLOSES with an instruction. The extension/tool listing in the
+ * middle is data and renders verbatim.
+ */
+function buildWorkerExtensionsRule(extensions: WorkerExtensionSet): string {
+	if (extensions.units.length === 0) return "";
+	const lines = [
+		"11. Delegate any action that needs one of these worker-loaded pi extensions to a",
+		"   thread; you cannot call their tools yourself:",
+	];
+	for (const unit of extensions.units) {
+		lines.push(`   - ${sanitizeForDoctrine(unitLabel(unit), DOCTRINE_LABEL_MAX)}`);
+		for (const tool of unit.tools) {
+			lines.push(`     ${sanitizeForDoctrine(tool.name, DOCTRINE_NAME_MAX)}: ${sanitizeForDoctrine(tool.description, DOCTRINE_DESC_MAX)}`);
+		}
+	}
+	lines.push(
+		"   Assume every worker already has them — you need not pass them in a thread's",
+		"   `tools` allowlist.",
+	);
+	return `\n${lines.join("\n")}`;
+}
+
+function buildDoctrine(cwd: string, config: SlateConfig, trusted: boolean, extensions: WorkerExtensionSet): string {
 	// Rule 8 tail: with draft-PR publishing enabled, the umbrella draft PR is
 	// one of the gates; otherwise durable records live in the workflow log.
 	const rule8Tail =
@@ -92,7 +154,7 @@ threads execute. Rules:
    Read that file only when you must reason about slate itself (explaining
    it, changing the extension, or an unusual routing/compaction decision) —
    never for routine dispatching. Skip the read if it is already in your
-   context.`;
+   context.${buildWorkerExtensionsRule(extensions)}`;
 }
 
 /**
@@ -130,6 +192,7 @@ export function registerSlateMode(
 	store: SlateStore,
 	hooks: SlateHandoffHooks,
 	getConfig: () => SlateConfig,
+	getExtensions: () => WorkerExtensionSet,
 ): void {
 	let savedTools: string[] | undefined;
 	let uiCtx: ExtensionContext | undefined;
@@ -229,7 +292,7 @@ export function registerSlateMode(
 		// addendum goes LAST so the pause directive is the final word in the
 		// prompt, undiluted by the role guidelines.
 		const parts = [
-			buildDoctrine(ctx.cwd, config, trusted),
+			buildDoctrine(ctx.cwd, config, trusted, getExtensions()),
 			...loadDoctrineExtra(ctx.cwd, config, trusted).map((d) => `\n\n${d}`),
 			...docs.map((d) => `\n\n${d}`),
 		];