ytdb-slate 0.1.0

package/extension/tools.ts

@@ -0,0 +1,134 @@
+/**
+ * Slate orchestrator tools (ExecPlan D3): thread / threads / episode.
+ */
+
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { renderThreadCall, renderThreadResult } from "./render.ts";
+import type { SlateStore } from "./state.ts";
+import type { DispatchProgress, ThreadManager } from "./threads.ts";
+
+export function registerSlateTools(pi: ExtensionAPI, store: SlateStore, getManager: () => ThreadManager): void {
+	pi.registerTool({
+		name: "thread",
+		label: "Thread",
+		description: [
+			"Dispatch ONE bounded action to a persistent worker thread and receive back an episode",
+			"(a compressed, structured record of what the thread did).",
+			"Omit `thread` to create a new thread (give it a short `name`); pass an existing thread id",
+			"to continue that thread — it retains the context of all its previous actions.",
+			"Use `context` to inject prior episodes (by id, from any thread) into the action.",
+			"Threads are serial; to parallelize, dispatch to DIFFERENT threads in one message.",
+			"`model` (\"provider/id\") and `tools` apply only when creating a new thread.",
+			"An episode header of STATUS: FAILED means the action failed — read it and adapt.",
+			"Tasks that modify repository files require the track workflow's pre-implementation gates to have run first.",
+		].join(" "),
+		promptSnippet: "Dispatch one bounded action to a persistent worker thread; returns a compressed episode",
+		promptGuidelines: [
+			"Use the thread tool to delegate bounded tactical actions to worker threads; dispatch independent actions to different threads in the same message to run them in parallel.",
+			"Pass prior episode ids in the thread tool's context parameter instead of restating their content.",
+		],
+		parameters: Type.Object({
+			thread: Type.Optional(Type.String({ description: "Existing thread id to continue (e.g. \"t1\")" })),
+			name: Type.Optional(Type.String({ description: "Short name for a NEW thread (e.g. \"recon\")" })),
+			task: Type.String({ description: "The single bounded action to execute" }),
+			context: Type.Optional(
+				Type.Array(Type.String(), { description: "Episode ids to inject as context (e.g. [\"t1.e2\"])" }),
+			),
+			model: Type.Optional(Type.String({ description: "Worker model \"provider/id\" (new threads only)" })),
+			tools: Type.Optional(Type.Array(Type.String(), { description: "Worker tool allowlist (new threads only)" })),
+		}),
+
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			const onProgress = (p: DispatchProgress) => {
+				onUpdate?.({
+					content: [
+						{
+							type: "text",
+							text: `[${p.threadName}] ${p.done ? (p.status ?? "done") : "running"}\n${p.lines.slice(-8).join("\n")}`,
+						},
+					],
+					details: { threadId: p.threadId, threadName: p.threadName, lines: p.lines, usage: p.usage, done: p.done },
+				});
+			};
+
+			const result = await getManager().dispatch(
+				{
+					threadId: params.thread,
+					name: params.name,
+					task: params.task,
+					contextEpisodeIds: params.context,
+					model: params.model,
+					tools: params.tools,
+				},
+				ctx,
+				signal,
+				onProgress,
+			);
+
+			const headline = `[episode ${result.episode.id} | thread ${result.thread.id} "${result.thread.name}" | STATUS: ${result.episode.status === "ok" ? "OK" : "FAILED"}]`;
+			return {
+				content: [{ type: "text", text: `${headline}\n\n${result.episodeText}` }],
+				details: {
+					threadId: result.thread.id,
+					threadName: result.thread.name,
+					episodeId: result.episode.id,
+					status: result.episode.status,
+					episodeFile: result.episode.file,
+					usage: result.usage,
+					done: true,
+				},
+			};
+		},
+
+		renderCall(args, theme) {
+			return renderThreadCall(args as never, theme as never);
+		},
+		renderResult(result, options, theme) {
+			return renderThreadResult(result as never, options as never, theme as never);
+		},
+	});
+
+	pi.registerTool({
+		name: "threads",
+		label: "Threads",
+		description:
+			"List all worker threads: id, name, status, episodes so far, and last activity. " +
+			"Use this to decide whether to continue an existing thread or create a new one.",
+		promptSnippet: "List worker threads and their episodes",
+		parameters: Type.Object({}),
+		async execute() {
+			const threads = [...store.threads.values()];
+			if (threads.length === 0) {
+				return { content: [{ type: "text", text: "No threads yet. Use the thread tool to create one." }], details: { count: 0 } };
+			}
+			const lines = threads.map((t) => {
+				const episodes = t.episodeIds.length > 0 ? t.episodeIds.join(", ") : "(none)";
+				return `${t.id} "${t.name}" [${t.status}]${t.model ? ` model=${t.model}` : ""} — episodes: ${episodes} — updated ${new Date(t.updatedAt).toISOString()}`;
+			});
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { count: threads.length } };
+		},
+	});
+
+	pi.registerTool({
+		name: "episode",
+		label: "Episode",
+		description: "Fetch the full text of a stored episode by id (e.g. \"t1.e2\").",
+		promptSnippet: "Fetch a stored episode's full text by id",
+		parameters: Type.Object({
+			id: Type.String({ description: "Episode id, e.g. \"t1.e2\"" }),
+		}),
+		async execute(_toolCallId, params) {
+			const episode = store.episodes.get(params.id);
+			if (!episode) {
+				const known = [...store.episodes.keys()].join(", ") || "none";
+				throw new Error(`Unknown episode "${params.id}". Known episodes: ${known}`);
+			}
+			return {
+				content: [{ type: "text", text: readFileSync(episode.file, "utf8") }],
+				details: { id: episode.id, threadId: episode.threadId, status: episode.status },
+			};
+		},
+	});
+}

package/extension/worker.ts

@@ -0,0 +1,119 @@
+/**
+ * Worker sessions: in-process pi SDK AgentSessions with the recursion guard.
+ *
+ * A worker loads NO extensions, skills, prompt templates, or themes
+ * (DefaultResourceLoader no* options) — so a worker can never see slate tools
+ * (ExecPlan D7, depth-1 guard) — and inherits the HOST session's project-trust
+ * state via an explicit SettingsManager, so untrusted projects get neither
+ * project-local settings nor the project SYSTEM.md override in workers.
+ * Worker conversations persist under
+ * <config dir>/slate/threads/*.jsonl (CONFIG_DIR_NAME, ".pi" by default)
+ * and are reopened via SessionManager.open.
+ */
+
+import { mkdirSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+	AuthStorage,
+	CONFIG_DIR_NAME,
+	createAgentSession,
+	DefaultResourceLoader,
+	getAgentDir,
+	ModelRegistry,
+	SessionManager,
+	SettingsManager,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { loadPromptDocs } from "./prompt-docs.ts";
+
+export type WorkerSession = Awaited<ReturnType<typeof createAgentSession>>["session"];
+
+export const DEFAULT_WORKER_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+
+const WORKER_PREAMBLE = [
+	"You are a worker thread executing ONE bounded action for an orchestrator.",
+	"Do the action fully, then stop.",
+	"Your final message must state: what you did, what you found, files you touched,",
+	"and anything the orchestrator must know.",
+].join(" ");
+
+export function threadsDir(cwd: string): string {
+	return resolve(cwd, CONFIG_DIR_NAME, "slate", "threads");
+}
+
+export function episodesDir(cwd: string): string {
+	return resolve(cwd, CONFIG_DIR_NAME, "slate", "episodes");
+}
+
+/** Resolve a "provider/id" model string against the registry; throws a clear error if unknown. */
+export function resolveModel(ctx: ExtensionContext, spec: string) {
+	const slash = spec.indexOf("/");
+	if (slash <= 0) throw new Error(`Invalid model spec "${spec}" — expected "provider/id"`);
+	const model = ctx.modelRegistry.find(spec.slice(0, slash), spec.slice(slash + 1));
+	if (!model) throw new Error(`Unknown model "${spec}" — not found in the model registry`);
+	return model;
+}
+
+export async function openWorkerSession(opts: {
+	ctx: ExtensionContext;
+	sessionFile?: string; // resume when provided, else create new under <config dir>/slate/threads/
+	model?: string; // "provider/id"
+	tools?: string[];
+	promptDocs?: string[]; // role-guideline doc paths, cwd-relative (default none)
+}): Promise<WorkerSession> {
+	const { ctx } = opts;
+	const dir = threadsDir(ctx.cwd);
+	mkdirSync(dir, { recursive: true });
+
+	const agentDir = getAgentDir();
+	const authStorage = AuthStorage.create();
+	const modelRegistry = ModelRegistry.create(authStorage);
+
+	// Trust propagation (mirrors vanilla pi's runtime SettingsManager): when no
+	// settingsManager is passed, the SDK default-constructs one with
+	// projectTrusted=true, which would make workers honor project-local
+	// settings and the <config dir>/SYSTEM.md override even in projects the
+	// user has NOT trusted. Carry the host session's actual trust decision into
+	// both the resource loader and the session.
+	const settingsManager = SettingsManager.create(ctx.cwd, agentDir, {
+		projectTrusted: ctx.isProjectTrusted(),
+	});
+
+	// Role-guideline doc content is captured when this session object is
+	// created: a live session keeps its system prompt until disposed; a
+	// thread reopened later (e.g. after a pi restart) re-reads the docs at
+	// their then-current content. Blocks go in separator-free — pi core
+	// joins appendSystemPrompt entries with "\n\n". Trust gate: project files
+	// are never injected into worker prompts for untrusted projects.
+	const promptDocs = ctx.isProjectTrusted() ? loadPromptDocs(ctx.cwd, opts.promptDocs ?? []) : [];
+	const loader = new DefaultResourceLoader({
+		cwd: ctx.cwd,
+		agentDir,
+		settingsManager,
+		noExtensions: true, // recursion guard (D7)
+		noSkills: true,
+		noPromptTemplates: true,
+		noThemes: true,
+		appendSystemPrompt: [WORKER_PREAMBLE, ...promptDocs],
+	});
+	await loader.reload();
+
+	const model = opts.model ? resolveModel(ctx, opts.model) : ctx.model;
+
+	const sessionManager = opts.sessionFile
+		? SessionManager.open(opts.sessionFile)
+		: SessionManager.create(ctx.cwd, dir);
+
+	const { session } = await createAgentSession({
+		cwd: ctx.cwd,
+		agentDir,
+		authStorage,
+		modelRegistry,
+		model: model ?? undefined,
+		tools: opts.tools && opts.tools.length > 0 ? opts.tools : DEFAULT_WORKER_TOOLS,
+		resourceLoader: loader,
+		sessionManager,
+		settingsManager,
+	});
+	return session;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "ytdb-slate",
+  "version": "0.1.0",
+  "description": "Slate: a thread-weaving orchestration extension for the pi coding agent — bounded worker actions, compressed episodes, mandatory research/design/adversarial/track review workflow, optional draft-PR publishing.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "extension",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extension/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}