@tiagojct/subsub 0.5.0

package/src/preview.ts

@@ -0,0 +1,107 @@
+/**
+ * Turn a dry-run result from the Zotero servers into a short text that the user
+ * reads in the approval dialog. Plain ASCII, at most about 20 lines.
+ */
+
+const MAX_LINES = 14;
+
+type Obj = Record<string, unknown>;
+
+function s(v: unknown, n = 90): string {
+	const t = typeof v === "string" ? v : JSON.stringify(v);
+	return t.length > n ? `${t.slice(0, n - 3)}...` : t;
+}
+
+function list(rows: string[], total?: number): string[] {
+	const out = rows.slice(0, MAX_LINES);
+	const rest = (total ?? rows.length) - out.length;
+	if (rest > 0) out.push(`... and ${rest} more`);
+	return out;
+}
+
+function describeChange(c: Obj): string {
+	const parts: string[] = [];
+	if (Array.isArray(c.added) && c.added.length) parts.push(`+ ${c.added.join(", ")}`);
+	if (Array.isArray(c.removed) && c.removed.length) parts.push(`- ${c.removed.join(", ")}`);
+	for (const [k, v] of Object.entries(c)) {
+		if (["key", "item", "added", "removed", "tags_after"].includes(k)) continue;
+		if (v && typeof v === "object" && "after" in (v as Obj)) {
+			const b = (v as Obj).before;
+			parts.push(`${k}: ${s(b || "(empty)", 40)} -> ${s((v as Obj).after, 60)}`);
+		}
+	}
+	return `${s(c.item ?? c.key, 60)}: ${parts.join("; ") || "(change)"}`;
+}
+
+export function formatPreview(tool: string, preview: unknown): string {
+	if (!preview || typeof preview !== "object") return s(preview, 1500);
+	const p = preview as Obj;
+	const lines: string[] = [];
+	if (p.undoing && typeof p.undoing === "object") {
+		const u = p.undoing as Obj;
+		lines.push(`Undo ${u.op}: ${s(u.summary, 80)}`);
+	}
+	if (Array.isArray(p.already_applied) && p.already_applied.length) {
+		lines.push(`ALREADY APPLIED: ${p.already_applied.join(", ")}`);
+	}
+	const drift = p.changed_since_note as Obj | undefined;
+	if (drift && typeof drift === "object" && typeof drift.count === "number") {
+		lines.push(`${drift.count} item(s) changed after the note was written; the note overwrites them:`);
+		const items = Object.entries((drift.items as Obj) ?? {}).map(
+			([k, v]) => `  ${k} now: ${((v as Obj).now as string[] | undefined)?.join(", ") || "(none)"}`,
+		);
+		lines.push(...items.slice(0, 4));
+	}
+	if (typeof p.would_change === "number") {
+		lines.push(`${p.would_change} item(s) would change.`);
+		const changes = (p.changes as Obj[]) ?? [];
+		lines.push(...list(changes.map(describeChange), p.would_change as number));
+	}
+	if (Array.isArray(p.would_import)) {
+		lines.push(`${p.would_import.length} item(s) would be imported:`);
+		lines.push(
+			...list(
+				(p.would_import as Obj[]).map(
+					(r) => `${r.citekey}  ${s(r.item, 70)}${r.has_abstract ? "" : "  (no abstract)"}`,
+				),
+			),
+		);
+	}
+	if (Array.isArray(p.would_attach)) {
+		lines.push(`${p.would_attach.length} PDF(s) would be attached:`);
+		lines.push(
+			...list(
+				(p.would_attach as Obj[]).map(
+					(r) => `${s(r.item, 60)}  [${r.host_type ?? "?"}, ${r.version ?? "?"}${r.license ? `, ${r.license}` : ""}]`,
+				),
+			),
+		);
+	}
+	if (p.would_create && typeof p.would_create === "object") {
+		const w = p.would_create as Obj;
+		lines.push(`New collection: ${w.name}${w.parent ? ` (inside ${w.parent})` : ""}`);
+	}
+	if (tool.endsWith("attach_note") || tool.endsWith("create_note")) {
+		if (p.item || p.parent) lines.push(`Note on: ${s(p.item ?? p.parent, 90)}`);
+		if (p.summary || p.note_preview) lines.push(s(p.summary ?? p.note_preview, 600));
+		if (p.link) lines.push(`Link: ${p.link}`);
+	}
+	const skipped = p.skipped as Obj | undefined;
+	if (skipped && typeof skipped === "object" && Object.keys(skipped).length) {
+		lines.push(`Skipped: ${Object.keys(skipped).length}`);
+		lines.push(...list(Object.entries(skipped).map(([k, v]) => `  ${k}: ${s(v, 70)}`)).slice(0, 5));
+	}
+	const errors = p.errors as Obj | undefined;
+	if (errors && typeof errors === "object" && Object.keys(errors).length) {
+		lines.push(`Errors: ${Object.keys(errors).length}`);
+		lines.push(...Object.entries(errors).slice(0, 5).map(([k, v]) => `  ${k}: ${s(v, 70)}`));
+	}
+	if (!lines.length) lines.push(s(p, 1500));
+	return lines.join("\n");
+}
+
+export function describeArgs(input: Record<string, unknown>): string {
+	return Object.entries(input)
+		.map(([k, v]) => `${k}: ${s(v, 120)}`)
+		.join("\n");
+}

package/src/profiles.ts

@@ -0,0 +1,99 @@
+/**
+ * Profiles: how much Sub-Sub does for the user. Named after the work, not the
+ * person: a professor new to a field can choose Reader, a student can choose
+ * Scholar. A profile is the user's own choice (/profile changes it), not a lock.
+ *
+ * - reader:  explains each step; reading notes are quotes with page numbers and
+ *            questions; no summaries or syntheses; no bulk library changes.
+ * - scholar: literature notes, syntheses, searches, alerts; the full librarian.
+ * - author:  scholar plus manuscript work: citation check, bibliography, comments
+ *            on the argument. Does not write the manuscript's paragraphs.
+ * - editor:  everything, including drafting text for a manuscript on request.
+ */
+
+import type { Profile } from "./config.ts";
+
+export interface ProfileSpec {
+	name: Profile;
+	label: string;
+	summary: string;
+	/** Tools this profile does not offer (full names). */
+	without: string[];
+	/** Items per review note and per batch. */
+	batch: number;
+	/** Added to the system prompt. {{user}} is the user's name or "the user". */
+	rules: string;
+}
+
+const BULK_LIBRARY = ["rename_tags", "remove_tags", "remove_automatic_tags", "trash_items", "update_fields", "repair_metadata"].map(
+	(n) => `zotero_${n}`,
+);
+const MANUSCRIPT = ["scholar_check_manuscript", "scholar_export_bibliography"];
+
+export const PROFILE_SPECS: Record<Profile, ProfileSpec> = {
+	reader: {
+		name: "reader",
+		label: "Reader",
+		summary: "explains each step; reading notes are quotes and questions; no summaries; no bulk library changes",
+		without: [...BULK_LIBRARY, ...MANUSCRIPT],
+		batch: 10,
+		rules: [
+			"Profile: Reader. {{User}} is learning to work with the literature and wants to do the reading and the writing.",
+			"- Before each step, say in one or two lines what you will do and why.",
+			"- A literature note is a reading note: the full reference, then direct quotes with page numbers (or section names), and under each quote one question for {{user}} to answer. Do not write summaries, syntheses, conclusions or paragraphs that {{user}} could hand in as their own text. When a prompt or the shared rules ask for a literature note or a synthesis, make a reading note instead and say so.",
+			"- For searches, list works with one line each on what they study, not on what they conclude.",
+			"- If {{user}} asks for a summary, a synthesis or text for an assignment, say that the Reader profile does not write these, and offer quotes and questions. {{User}} can change the profile with /profile.",
+			"- Librarian: at most 10 items per review note. Explain each proposed tag in the Reason column.",
+		].join("\n"),
+	},
+	scholar: {
+		name: "scholar",
+		label: "Scholar",
+		summary: "literature notes, syntheses, searches and alerts; the full librarian",
+		without: MANUSCRIPT,
+		batch: 25,
+		rules: [
+			"Profile: Scholar.",
+			"- Write literature notes and syntheses from what you read, with a source for every claim.",
+			"- Do not draft text for {{user}}'s manuscripts, theses or assignments. If asked, say that the Author and Editor profiles help with manuscripts (/profile).",
+			"- Librarian: 25 items per review note.",
+		].join("\n"),
+	},
+	author: {
+		name: "author",
+		label: "Author",
+		summary: "Scholar plus manuscripts: citation check, bibliography, comments on the argument",
+		without: [],
+		batch: 25,
+		rules: [
+			"Profile: Author.",
+			"- Write literature notes and syntheses from what you read, with a source for every claim.",
+			"- Help with {{user}}'s manuscripts: check citations against the library, export the bibliography, and comment on the argument, the structure and the evidence that is missing, with the sources that could support each point.",
+			"- Do not write the manuscript's paragraphs. Say what is missing and where the support is; {{user}} writes the text. The Editor profile drafts text (/profile).",
+			"- Librarian: 25 items per review note.",
+		].join("\n"),
+	},
+	editor: {
+		name: "editor",
+		label: "Editor",
+		summary: "everything, including drafting manuscript text on request",
+		without: [],
+		batch: 25,
+		rules: [
+			"Profile: Editor. All tools.",
+			"- Write literature notes and syntheses from what you read, with a source for every claim.",
+			"- When {{user}} asks, draft text for a manuscript: cite library items as [@citekey], use only claims from sources you read, and mark drafted text clearly so that {{user}} can check it.",
+			"- Librarian: 25 items per review note unless {{user}} asks for more.",
+		].join("\n"),
+	},
+};
+
+export function profileSpec(p: Profile): ProfileSpec {
+	return PROFILE_SPECS[p];
+}
+
+export function profileList(current?: Profile): string {
+	return Object.values(PROFILE_SPECS)
+		.map((s) => `${s.name === current ? "*" : " "} ${s.label.padEnd(8)} ${s.summary}`)
+		.join("\n");
+}

package/src/prompt.ts

@@ -0,0 +1,81 @@
+/**
+ * The Sub-Sub part of the system prompt: role text for the current mode, the
+ * profile rules, the shared Zotero rules from the notes folder, the vault
+ * conventions when pi runs inside the notes folder, and the language rule.
+ *
+ * Role and profile texts use placeholders: {{user}} / {{User}} (the user's name,
+ * or "the user"), {{about}} (one line about the user) and {{batch}}.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { type Mode, type SubsubConfig, who } from "./config.ts";
+import { profileSpec } from "./profiles.ts";
+
+const ROLE_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "roles");
+
+function readIf(path: string | undefined): string | undefined {
+	if (!path || !existsSync(path)) return undefined;
+	try {
+		return readFileSync(path, "utf8").trim();
+	} catch {
+		return undefined;
+	}
+}
+
+export function languageRule(language: string, user = "the user"): string {
+	if (language.toLowerCase() === "auto") {
+		return `Reply in the language ${user} writes in. Write notes in the language of ${user}'s other notes; if unsure, ask once. Keep quotations, titles of works and proper names in their original language.`;
+	}
+	return `Always reply in ${language}, even when ${user} writes in another language and even when the sources or notes you read are in another language. Write the notes you create in ${language} too, including their titles. Keep quotations, titles of works and proper names in their original language.`;
+}
+
+export function inside(child: string, parent: string | undefined): boolean {
+	if (!parent) return false;
+	const rel = relative(resolve(parent), resolve(child));
+	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function capital(s: string): string {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+export function fill(text: string, cfg: Pick<SubsubConfig, "userName" | "about" | "profile">): string {
+	const user = who(cfg);
+	const about = cfg.about ? `${capital(user)} is ${cfg.about}.` : "";
+	return text
+		.replaceAll("{{User}}", capital(user))
+		.replaceAll("{{user}}", user)
+		.replaceAll("{{about}}", about)
+		.replaceAll("{{batch}}", String(profileSpec(cfg.profile).batch))
+		.replace(/[ \t]+\n/g, "\n");
+}
+
+export function roleText(mode: Mode, cfg?: Pick<SubsubConfig, "userName" | "about" | "profile">): string {
+	const raw = readIf(join(ROLE_DIR, `${mode}.md`)) ?? `You are the ${mode}.`;
+	return cfg ? fill(raw, cfg) : raw;
+}
+
+export function systemAddition(mode: Mode, cfg: SubsubConfig, cwd: string): string {
+	const user = who(cfg);
+	const parts = [`# Sub-Sub: ${mode} mode`, roleText(mode, cfg)];
+	const shared = readIf(cfg.sharedRules);
+	if (shared) {
+		parts.push(
+			"# Shared Zotero rules (from the notes folder)",
+			shared,
+			`Sub-Sub note: in Sub-Sub you do not need a separate dry run before a change. Call the write tool with dry_run=false; Sub-Sub shows ${user} the server's preview and applies it only on approval. This replaces the dry-run steps above.`,
+		);
+	}
+	if (inside(cwd, cfg.vault)) {
+		for (const f of cfg.vaultContext) {
+			const t = readIf(f);
+			if (t) parts.push(`# Vault conventions (${f})`, t);
+		}
+	}
+	// The profile and the language rule come last, so they win over the shared rules and the vault conventions.
+	parts.push("# Profile", fill(profileSpec(cfg.profile).rules, cfg));
+	parts.push("# Language", languageRule(cfg.language, user));
+	return parts.join("\n\n");
+}

package/src/roles.ts

@@ -0,0 +1,83 @@
+/**
+ * Which tools each mode may use, and which calls need the user's approval.
+ */
+
+import type { Mode, Profile } from "./config.ts";
+import { profileSpec } from "./profiles.ts";
+
+export const FILE_TOOLS = ["read", "edit", "write", "grep", "find", "ls"];
+
+export const ZOTERO_READ = [
+	"status",
+	"library_overview",
+	"find_items",
+	"get_item",
+	"get_fulltext",
+	"list_tags",
+	"get_vocabulary",
+	"list_collections",
+	"history",
+].map((n) => `zotero_${n}`);
+
+/** Write tools that support dry_run: the gate previews them and asks. */
+export const PREVIEW_WRITES = new Set([
+	...[
+		"tag_items",
+		"apply_tag_review",
+		"rename_tags",
+		"remove_tags",
+		"remove_automatic_tags",
+		"set_citekeys",
+		"update_fields",
+		"file_items",
+		"create_collection",
+		"create_note",
+		"trash_items",
+		"undo",
+		"import_identifiers",
+		"import_queue",
+		"repair_metadata",
+		"attach_oa_pdfs",
+	].map((n) => `zotero_${n}`),
+	"scholar_attach_note",
+]);
+
+/** Writes without a dry run that still need a yes. */
+export const CONFIRM_WRITES = new Set(["scholar_export_bibliography"]);
+
+export function toolsFor(mode: Mode, registered: string[], profile: Profile = "editor"): string[] {
+	const has = new Set(registered);
+	const without = new Set(profileSpec(profile).without);
+	const wanted =
+		mode === "librarian"
+			? [...registered.filter((n) => n.startsWith("zotero_")), ...FILE_TOOLS]
+			: [...ZOTERO_READ, ...registered.filter((n) => n.startsWith("scholar_")), ...FILE_TOOLS];
+	return [...new Set(wanted)].filter((n) => has.has(n) && !without.has(n));
+}
+
+/** Why a Sub-Sub tool is not available now, or undefined when it is. */
+export function unavailableReason(name: string, mode: Mode, registered: string[], profile: Profile): string | undefined {
+	if (toolsFor(mode, registered, profile).includes(name)) return undefined;
+	if (profileSpec(profile).without.includes(name)) {
+		return `${name} is not part of the ${profileSpec(profile).label} profile. The user can change the profile with /profile.`;
+	}
+	return `${name} is not available in ${mode} mode. The user can switch with /${otherMode(mode)}.`;
+}
+
+export type GateKind = "preview" | "confirm" | "path" | null;
+
+/** A dry run only when dry_run is absent (server default true) or clearly true. */
+export function isDryRun(value: unknown): boolean {
+	return value === undefined || value === true || value === "true";
+}
+
+export function gateKind(toolName: string, input: Record<string, unknown>): GateKind {
+	if (PREVIEW_WRITES.has(toolName)) return isDryRun(input.dry_run) ? null : "preview";
+	if (CONFIRM_WRITES.has(toolName)) return "confirm";
+	if (toolName === "write" || toolName === "edit") return "path";
+	return null;
+}
+
+export function otherMode(mode: Mode): Mode {
+	return mode === "librarian" ? "researcher" : "librarian";
+}