@xopcai/xopc 0.0.124 → 0.0.126

package/dist/src/agent/tools/xopc-use-tool.js

@@ -0,0 +1,636 @@
+import { runWithActivityContext } from "../../activity/context.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import "../../storage/sqlite/index.js";
+import "../../activity/index.js";
+import { isValidProjectAgentId, normalizeProjectAgentId } from "../../projects/project-agent.js";
+import "../../projects/index.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/xopc-use-tool.ts
+const XopcUseToolSchema = Type.Object({
+	mode: Type.Union([
+		Type.Literal("project"),
+		Type.Literal("note"),
+		Type.Literal("work_item")
+	]),
+	command: Type.String({ description: "Object command. Supports project list/get/create/update/resolve_workspace, note list/get/create/append/update/preview_edit, and work_item list/get/create/update." }),
+	args: Type.Optional(Type.Record(Type.String(), Type.Any())),
+	dryRun: Type.Optional(Type.Boolean({ description: "Validate and preview the action without mutating xopc state." }))
+});
+const PROJECT_STATUSES = new Set([
+	"active",
+	"paused",
+	"archived"
+]);
+const NOTE_KINDS = new Set([
+	"thought",
+	"todo",
+	"voice",
+	"media",
+	"bookmark",
+	"mixed",
+	"task"
+]);
+const NOTE_STATUSES = new Set([
+	"inbox",
+	"processed",
+	"archived",
+	"trashed"
+]);
+const WORK_ITEM_STATUSES = new Set([
+	"backlog",
+	"todo",
+	"in_progress",
+	"blocked",
+	"needs_input",
+	"in_review",
+	"done",
+	"cancelled"
+]);
+const WORK_ITEM_PRIORITIES = new Set([
+	"urgent",
+	"high",
+	"normal",
+	"low"
+]);
+function okText(details) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(details.result ?? {}, null, 2)
+		}],
+		details
+	};
+}
+function errorText(message, details) {
+	return {
+		content: [{
+			type: "text",
+			text: `Error: ${message}`
+		}],
+		details: {
+			...details,
+			result: {
+				ok: false,
+				error: message
+			}
+		}
+	};
+}
+function trimString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function optionalString(value) {
+	if (value === null) return null;
+	if (typeof value === "string") return value;
+}
+function boundedLimit(value, fallback = 20, max = 100) {
+	const raw = typeof value === "number" ? value : typeof value === "string" ? Number(value) : fallback;
+	if (!Number.isFinite(raw)) return fallback;
+	return Math.max(1, Math.min(max, Math.floor(raw)));
+}
+function offset(value) {
+	const raw = typeof value === "number" ? value : typeof value === "string" ? Number(value) : void 0;
+	return raw !== void 0 && Number.isFinite(raw) ? Math.max(0, Math.floor(raw)) : void 0;
+}
+function enumValue(value, allowed) {
+	return typeof value === "string" && allowed.has(value) ? value : void 0;
+}
+function finiteNumber(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		if (Number.isFinite(parsed)) return parsed;
+	}
+}
+function stringArray(value) {
+	if (!Array.isArray(value)) return void 0;
+	return value.filter((item) => typeof item === "string");
+}
+function nullableNumber(value) {
+	if (value === null) return null;
+	return finiteNumber(value);
+}
+function ensureArgs(input) {
+	return input.args && typeof input.args === "object" && !Array.isArray(input.args) ? input.args : {};
+}
+function currentProjectId(args, deps) {
+	const explicit = trimString(args.projectId);
+	if (explicit) return explicit;
+	const sessionKey = trimString(args.sessionKey) ?? deps.getCurrentSessionKey?.();
+	return sessionKey ? getSessionMetadata(sessionKey)?.projectId : void 0;
+}
+function projectWorkspaceRootArg(args) {
+	return trimString(args.workspaceRoot) ?? trimString(args.workspacePath) ?? trimString(args.path);
+}
+function optionalProjectWorkspaceRootArg(args) {
+	if (args.workspaceRoot !== void 0) return optionalString(args.workspaceRoot);
+	if (args.workspacePath !== void 0) return optionalString(args.workspacePath);
+	if (args.path !== void 0) return optionalString(args.path);
+}
+function validateDefaultAgentId(raw, config) {
+	if (raw === null) return null;
+	const normalized = normalizeProjectAgentId(trimString(raw));
+	if (!normalized) return void 0;
+	if (config && !isValidProjectAgentId(config, normalized)) throw new Error(`Default agent not found: ${normalized}`);
+	return normalized;
+}
+async function handleProject(command, args, deps, dryRun) {
+	const projects = deps.getProjectService?.();
+	if (!projects) return {
+		ok: false,
+		error: "Project service is unavailable"
+	};
+	if (command === "list") return {
+		ok: true,
+		...projects.list({
+			status: enumValue(args.status, PROJECT_STATUSES),
+			search: trimString(args.search),
+			sortBy: enumValue(args.sortBy, new Set([
+				"updatedAt",
+				"createdAt",
+				"name"
+			])),
+			sortOrder: enumValue(args.sortOrder, new Set(["asc", "desc"])),
+			limit: boundedLimit(args.limit),
+			offset: offset(args.offset)
+		})
+	};
+	if (command === "get") {
+		const id = trimString(args.projectId) ?? trimString(args.id);
+		if (!id) return {
+			ok: false,
+			error: "projectId is required"
+		};
+		const project = projects.getWithDetails(id);
+		return project ? {
+			ok: true,
+			project
+		} : {
+			ok: false,
+			error: `Project not found: ${id}`
+		};
+	}
+	if (command === "resolve_workspace") {
+		const workspacePath = projectWorkspaceRootArg(args);
+		if (!workspacePath) return {
+			ok: false,
+			error: "workspacePath is required"
+		};
+		const defaultAgentId = args.defaultAgentId !== void 0 ? validateDefaultAgentId(args.defaultAgentId, deps.getConfig?.()) ?? void 0 : void 0;
+		const input = {
+			workspacePath,
+			agentId: trimString(args.agentId),
+			defaultAgentId,
+			autoCreate: args.autoCreate === true
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "resolve_project_workspace",
+			input
+		};
+		const match = projects.resolveOrCreateForWorkspacePath(input);
+		return match ? {
+			ok: true,
+			match
+		} : {
+			ok: false,
+			error: "No project matched workspace path"
+		};
+	}
+	if (command === "create") {
+		const name = trimString(args.name);
+		const workspaceRoot = projectWorkspaceRootArg(args);
+		if (!name && !workspaceRoot) return {
+			ok: false,
+			error: "name or workspaceRoot is required"
+		};
+		const input = {
+			name,
+			description: trimString(args.description),
+			defaultAgentId: validateDefaultAgentId(args.defaultAgentId, deps.getConfig?.()) ?? void 0,
+			workspaceRoot,
+			createWorkspaceRoot: args.createWorkspaceRoot === true,
+			projectKind: trimString(args.projectKind),
+			brief: trimString(args.brief),
+			instructions: trimString(args.instructions)
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "create_project",
+			input
+		};
+		return {
+			ok: true,
+			project: projects.create(input)
+		};
+	}
+	if (command === "update") {
+		const id = trimString(args.projectId) ?? trimString(args.id);
+		if (!id) return {
+			ok: false,
+			error: "projectId is required"
+		};
+		const workspaceRoot = optionalProjectWorkspaceRootArg(args);
+		const patch = {
+			...args.name !== void 0 ? { name: trimString(args.name) ?? "" } : {},
+			...args.description !== void 0 ? { description: optionalString(args.description) } : {},
+			...args.status !== void 0 ? { status: enumValue(args.status, PROJECT_STATUSES) } : {},
+			...args.defaultAgentId !== void 0 ? { defaultAgentId: validateDefaultAgentId(args.defaultAgentId, deps.getConfig?.()) } : {},
+			...workspaceRoot !== void 0 ? { workspaceRoot } : {},
+			...args.createWorkspaceRoot === true ? { createWorkspaceRoot: true } : {},
+			...args.brief !== void 0 ? { brief: optionalString(args.brief) } : {},
+			...args.instructions !== void 0 ? { instructions: optionalString(args.instructions) } : {}
+		};
+		if (args.status !== void 0 && patch.status === void 0) return {
+			ok: false,
+			error: "Invalid project status"
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "update_project",
+			projectId: id,
+			patch
+		};
+		return {
+			ok: true,
+			project: projects.update(id, patch)
+		};
+	}
+	return {
+		ok: false,
+		error: `Unsupported project command: ${command}`
+	};
+}
+async function handleNote(command, args, deps, dryRun) {
+	const notes = deps.getNotesService?.();
+	if (!notes) return {
+		ok: false,
+		error: "Notes service is unavailable"
+	};
+	if (command === "list") return {
+		ok: true,
+		...await notes.listNotes({
+			status: enumValue(args.status, NOTE_STATUSES),
+			kind: enumValue(args.kind, NOTE_KINDS),
+			tag: trimString(args.tag),
+			search: trimString(args.search),
+			pinned: typeof args.pinned === "boolean" ? args.pinned : void 0,
+			limit: boundedLimit(args.limit),
+			offset: offset(args.offset),
+			sortBy: enumValue(args.sortBy, new Set([
+				"createdAt",
+				"updatedAt",
+				"lastOpenedAt"
+			])),
+			sortOrder: enumValue(args.sortOrder, new Set(["asc", "desc"]))
+		})
+	};
+	if (command === "get") {
+		const id = trimString(args.noteId) ?? trimString(args.id);
+		if (!id) return {
+			ok: false,
+			error: "noteId is required"
+		};
+		const note = await notes.getNote(id);
+		return note ? {
+			ok: true,
+			note
+		} : {
+			ok: false,
+			error: `Note not found: ${id}`
+		};
+	}
+	if (command === "create") {
+		const markdown = typeof args.markdown === "string" ? args.markdown : trimString(args.content) ?? "";
+		const input = {
+			title: trimString(args.title),
+			markdown,
+			kind: enumValue(args.kind, NOTE_KINDS),
+			tags: stringArray(args.tags),
+			capturedVia: { channel: "web" },
+			pinned: args.pinned === true
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "create_note",
+			input
+		};
+		return {
+			ok: true,
+			note: await notes.createNote(input)
+		};
+	}
+	if (command === "append") {
+		const id = trimString(args.noteId) ?? trimString(args.id);
+		const content = trimString(args.content);
+		if (!id) return {
+			ok: false,
+			error: "noteId is required"
+		};
+		if (!content) return {
+			ok: false,
+			error: "content is required"
+		};
+		const heading = trimString(args.heading);
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "append_note",
+			noteId: id,
+			heading,
+			content
+		};
+		const note = await notes.appendTextToNote(id, content, heading);
+		return note ? {
+			ok: true,
+			note
+		} : {
+			ok: false,
+			error: `Note not found: ${id}`
+		};
+	}
+	if (command === "preview_edit") {
+		const id = trimString(args.noteId) ?? trimString(args.id);
+		const instruction = trimString(args.instruction);
+		if (!id) return {
+			ok: false,
+			error: "noteId is required"
+		};
+		if (!instruction) return {
+			ok: false,
+			error: "instruction is required"
+		};
+		const markdown = typeof args.markdown === "string" ? args.markdown : void 0;
+		const result = await notes.createAiEditPatch(id, instruction, markdown);
+		return result ? {
+			ok: true,
+			...result
+		} : {
+			ok: false,
+			error: `Note not found: ${id}`
+		};
+	}
+	if (command === "update") {
+		const id = trimString(args.noteId) ?? trimString(args.id);
+		if (!id) return {
+			ok: false,
+			error: "noteId is required"
+		};
+		if (args.title !== void 0 && typeof args.title !== "string") return {
+			ok: false,
+			error: "Invalid note title"
+		};
+		if (args.markdown !== void 0 && typeof args.markdown !== "string") return {
+			ok: false,
+			error: "Invalid note markdown"
+		};
+		if (args.tags !== void 0 && !Array.isArray(args.tags)) return {
+			ok: false,
+			error: "Invalid note tags"
+		};
+		const title = args.title;
+		const markdown = args.markdown;
+		const patch = {
+			...args.title !== void 0 ? { title } : {},
+			...args.markdown !== void 0 ? { markdown } : {},
+			...args.kind !== void 0 ? { kind: enumValue(args.kind, NOTE_KINDS) } : {},
+			...args.status !== void 0 ? { status: enumValue(args.status, NOTE_STATUSES) } : {},
+			...args.tags !== void 0 ? { tags: stringArray(args.tags) ?? [] } : {},
+			...typeof args.pinned === "boolean" ? { pinned: args.pinned } : {}
+		};
+		if (args.kind !== void 0 && patch.kind === void 0) return {
+			ok: false,
+			error: "Invalid note kind"
+		};
+		if (args.status !== void 0 && patch.status === void 0) return {
+			ok: false,
+			error: "Invalid note status"
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "update_note",
+			noteId: id,
+			patch
+		};
+		const note = await notes.updateNote(id, patch, "ai_edit");
+		return note ? {
+			ok: true,
+			note
+		} : {
+			ok: false,
+			error: `Note not found: ${id}`
+		};
+	}
+	return {
+		ok: false,
+		error: `Unsupported note command: ${command}`
+	};
+}
+async function handleWorkItem(command, args, deps, dryRun) {
+	const workItems = deps.getWorkItemService?.();
+	if (!workItems) return {
+		ok: false,
+		error: "Work item service is unavailable"
+	};
+	if (command === "list") {
+		const projectId = currentProjectId(args, deps);
+		if (!projectId) return {
+			ok: false,
+			error: "projectId is required"
+		};
+		return {
+			ok: true,
+			...workItems.listProjectWorkItems(projectId, {
+				status: enumValue(args.status, WORK_ITEM_STATUSES),
+				priority: enumValue(args.priority, WORK_ITEM_PRIORITIES),
+				includeArchived: args.includeArchived === true,
+				search: trimString(args.search),
+				sortBy: enumValue(args.sortBy, new Set([
+					"updatedAt",
+					"createdAt",
+					"priority",
+					"status"
+				])),
+				sortOrder: enumValue(args.sortOrder, new Set(["asc", "desc"])),
+				limit: boundedLimit(args.limit),
+				offset: offset(args.offset)
+			})
+		};
+	}
+	if (command === "get") {
+		const id = trimString(args.workItemId) ?? trimString(args.id);
+		if (!id) return {
+			ok: false,
+			error: "workItemId is required"
+		};
+		const item = workItems.getWorkItem(id);
+		return item ? {
+			ok: true,
+			item
+		} : {
+			ok: false,
+			error: `Work item not found: ${id}`
+		};
+	}
+	if (command === "create") {
+		const projectId = currentProjectId(args, deps);
+		const title = trimString(args.title);
+		if (!projectId) return {
+			ok: false,
+			error: "projectId is required"
+		};
+		if (!title) return {
+			ok: false,
+			error: "title is required"
+		};
+		const input = {
+			title,
+			description: trimString(args.description),
+			status: enumValue(args.status, WORK_ITEM_STATUSES),
+			priority: enumValue(args.priority, WORK_ITEM_PRIORITIES),
+			ownerAgentId: trimString(args.ownerAgentId),
+			nextAction: trimString(args.nextAction),
+			blockedReason: trimString(args.blockedReason),
+			dueAt: finiteNumber(args.dueAt)
+		};
+		if (args.status !== void 0 && input.status === void 0) return {
+			ok: false,
+			error: "Invalid work item status"
+		};
+		if (args.priority !== void 0 && input.priority === void 0) return {
+			ok: false,
+			error: "Invalid work item priority"
+		};
+		if (args.dueAt !== void 0 && input.dueAt === void 0) return {
+			ok: false,
+			error: "Invalid dueAt"
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "create_work_item",
+			projectId,
+			input
+		};
+		return {
+			ok: true,
+			item: workItems.createProjectWorkItem(projectId, input)
+		};
+	}
+	if (command === "update") {
+		const id = trimString(args.workItemId) ?? trimString(args.id);
+		if (!id) return {
+			ok: false,
+			error: "workItemId is required"
+		};
+		const dueAt = args.dueAt !== void 0 ? nullableNumber(args.dueAt) : void 0;
+		const archivedAt = args.archivedAt !== void 0 ? nullableNumber(args.archivedAt) : void 0;
+		const patch = {
+			...args.title !== void 0 ? { title: trimString(args.title) ?? "" } : {},
+			...args.description !== void 0 ? { description: optionalString(args.description) } : {},
+			...args.status !== void 0 ? { status: enumValue(args.status, WORK_ITEM_STATUSES) } : {},
+			...args.priority !== void 0 ? { priority: enumValue(args.priority, WORK_ITEM_PRIORITIES) } : {},
+			...args.ownerAgentId !== void 0 ? { ownerAgentId: optionalString(args.ownerAgentId) } : {},
+			...args.nextAction !== void 0 ? { nextAction: optionalString(args.nextAction) } : {},
+			...args.blockedReason !== void 0 ? { blockedReason: optionalString(args.blockedReason) } : {},
+			...args.dueAt !== void 0 ? { dueAt } : {},
+			...args.archivedAt !== void 0 ? { archivedAt } : {}
+		};
+		if (args.status !== void 0 && patch.status === void 0) return {
+			ok: false,
+			error: "Invalid work item status"
+		};
+		if (args.priority !== void 0 && patch.priority === void 0) return {
+			ok: false,
+			error: "Invalid work item priority"
+		};
+		if (args.dueAt !== void 0 && dueAt === void 0) return {
+			ok: false,
+			error: "Invalid dueAt"
+		};
+		if (args.archivedAt !== void 0 && archivedAt === void 0) return {
+			ok: false,
+			error: "Invalid archivedAt"
+		};
+		if (dryRun) return {
+			ok: true,
+			dryRun: true,
+			action: "update_work_item",
+			workItemId: id,
+			patch
+		};
+		const item = workItems.updateWorkItem(id, patch);
+		return item ? {
+			ok: true,
+			item
+		} : {
+			ok: false,
+			error: `Work item not found: ${id}`
+		};
+	}
+	return {
+		ok: false,
+		error: `Unsupported work_item command: ${command}`
+	};
+}
+function createXopcUseTool(deps) {
+	return {
+		name: "xopc_use",
+		label: "XOPC Use",
+		description: "Operate first-class xopc objects through one safe entry point. Use for projects, notes, and project work items instead of editing storage files directly. For non-trivial object changes, load the built-in manual first with tool_manual({ tool: \"xopc_use\" }).",
+		parameters: XopcUseToolSchema,
+		mutatesWorkspace: true,
+		mutationScope: "external",
+		requiresExclusiveWorkspaceLock: true,
+		finalGuardRelevant: true,
+		async execute(toolCallId, input) {
+			const mode = input.mode;
+			const command = input.command.trim();
+			const dryRun = input.dryRun === true;
+			const args = ensureArgs(input);
+			const details = {
+				mode,
+				command,
+				dryRun
+			};
+			if (!command) return errorText("command is required", details);
+			try {
+				const sessionKey = deps.getCurrentSessionKey?.();
+				const agentId = deps.getCurrentAgentId?.();
+				const result = await runWithActivityContext({
+					actor: {
+						kind: "agent",
+						agentId,
+						sessionKey
+					},
+					initiator: {
+						kind: "user",
+						sessionKey
+					},
+					source: {
+						kind: "xopc_use",
+						toolCallId
+					}
+				}, async () => mode === "project" ? await handleProject(command, args, deps, dryRun) : mode === "note" ? await handleNote(command, args, deps, dryRun) : mode === "work_item" ? await handleWorkItem(command, args, deps, dryRun) : {
+					ok: false,
+					error: `Unsupported mode: ${String(mode)}`
+				});
+				return okText({
+					...details,
+					result
+				});
+			} catch (err) {
+				return errorText(err instanceof Error ? err.message : String(err), details);
+			}
+		}
+	};
+}
+//#endregion
+export { createXopcUseTool };
+
+//# sourceMappingURL=xopc-use-tool.js.map