@xopcai/xopc 0.0.125 → 0.0.127

package/dist/src/agent/skills/skill-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-manager.js","names":[],"sources":["../../../../src/agent/skills/skill-manager.ts"],"sourcesContent":["/**\n * Skill Manager - Manages skills loading and expansion\n *\n * Handles skill initialization, reloading, and command expansion.\n */\n\nimport { createSkillLoader } from './index.js';\nimport { resolveBundledSkillsDir, resolveStateDir } from '../../config/paths.js';\nimport { createLogger } from '../../utils/logger.js';\nimport { createSkillConfigManager, isSkillEnabled } from './config.js';\nimport { formatSkillsForPrompt, selectSkillsVisibleInPrompt } from './format-skills-prompt.js';\nimport type {\n  LoadSkillsResult,\n  Skill,\n  SkillDiagnostic,\n  SkillRuntimeStatus,\n} from './types.js';\n\nconst log = createLogger('SkillManager');\n\nexport interface SkillLoadResult {\n  skills: Skill[];\n  prompt: string;\n  diagnostics: SkillDiagnostic[];\n}\n\nexport class SkillManager {\n  private skillPrompt: string = '';\n  private skills: Skill[] = [];\n  private skillLoader = createSkillLoader();\n  private workspace: string;\n  private bundledSkillsDir: string;\n  private version = 0;\n  private loadedAt = 0;\n  private reloadInProgress = false;\n  private reloadPending = false;\n  private lastReloadStartedAt: number | undefined;\n  private lastReloadFinishedAt: number | undefined;\n  private lastReloadReason: SkillRuntimeStatus['lastReloadReason'];\n  private lastReloadOk: boolean | undefined;\n  private lastReloadError: string | undefined;\n\n  constructor(workspace: string, bundledSkillsDir?: string) {\n    this.workspace = workspace;\n    this.bundledSkillsDir = bundledSkillsDir || resolveBundledSkillsDir();\n    this.initialize();\n  }\n\n  /**\n   * Initialize skills from workspace and bundled directories\n   */\n  private initialize(): void {\n    this.runReload('initial', () => this.skillLoader.init(this.workspace, this.bundledSkillsDir));\n  }\n\n  /**\n   * Recompute skill XML prompt from current skills.json (no disk rescan).\n   */\n  refreshPromptFromConfig(): void {\n    this.skillLoader.refreshPromptFromConfig();\n    this.skillPrompt = this.skillLoader.getPrompt();\n    this.version += 1;\n    this.loadedAt = Date.now();\n    this.lastReloadReason = 'config';\n    this.lastReloadOk = true;\n    this.lastReloadError = undefined;\n  }\n\n  /**\n   * Reload skills from disk\n   */\n  reload(): void {\n    this.runReload('disk', () => this.skillLoader.reload());\n  }\n\n  private runReload(reason: NonNullable<SkillRuntimeStatus['lastReloadReason']>, load: () => LoadSkillsResult): void {\n    if (this.reloadInProgress) {\n      this.reloadPending = true;\n      return;\n    }\n\n    do {\n      this.reloadPending = false;\n      this.reloadInProgress = true;\n      this.lastReloadStartedAt = Date.now();\n      this.lastReloadReason = reason;\n      try {\n        const result = load();\n        this.applyLoadResult(result);\n        this.lastReloadOk = true;\n        this.lastReloadError = undefined;\n        log.info({ count: result.skills.length, version: this.version }, 'Skills reloaded');\n      } catch (err) {\n        const errorMessage = err instanceof Error ? err.message : String(err);\n        this.lastReloadOk = false;\n        this.lastReloadError = errorMessage;\n        log.error({ err, errorMessage }, `Skills reload failed: ${errorMessage}`);\n      } finally {\n        this.lastReloadFinishedAt = Date.now();\n        this.reloadInProgress = false;\n      }\n    } while (this.reloadPending);\n  }\n\n  private applyLoadResult(result: LoadSkillsResult): void {\n    this.skillPrompt = result.prompt;\n    this.skills = result.skills;\n    this.version += 1;\n    this.loadedAt = Date.now();\n\n    for (const diag of result.diagnostics) {\n      if (diag.type === 'collision') {\n        log.warn({ skill: diag.skillName, path: diag.path, message: diag.message }, 'Skill collision');\n      } else if (diag.type === 'warning') {\n        log.warn({ skill: diag.skillName, path: diag.path, message: diag.message }, 'Skill warning');\n      } else if (diag.type === 'error') {\n        log.error({ skill: diag.skillName, path: diag.path, message: diag.message }, 'Skill error');\n      }\n    }\n  }\n\n  /**\n   * Get the skill prompt to append to system prompt\n   */\n  getPrompt(): string {\n    return this.skillPrompt;\n  }\n\n  /**\n   * `<available_skills>` XML with optional per-agent allowlist and/or tool-based gating.\n   * When both arguments are omitted, returns the cached prompt from disk load (no tool gating).\n   */\n  getPromptForSkillAllowlist(\n    allowlist: string[] | undefined,\n    registeredToolNames?: string[],\n  ): string {\n    if (allowlist === undefined && registeredToolNames === undefined) {\n      return this.getPrompt();\n    }\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return formatSkillsForPrompt(this.getSkills(), skillsConfig, {\n      skillAllowlist: allowlist,\n      registeredToolNames,\n    });\n  }\n\n  /** Skills visible for prompts and skills_list given the same indexing options as {@link getPromptForSkillAllowlist}. */\n  selectSkillsForAgentIndexing(options?: {\n    skillAllowlist?: string[];\n    registeredToolNames?: string[];\n  }): Skill[] {\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return selectSkillsVisibleInPrompt(this.getSkills(), skillsConfig, options);\n  }\n\n  /**\n   * Get all loaded skills\n   */\n  getSkills(): Skill[] {\n    return [...this.skills];\n  }\n\n  getDiagnostics(): SkillDiagnostic[] {\n    return this.skillLoader.getDiagnostics();\n  }\n\n  getVersion(): string {\n    return String(this.version);\n  }\n\n  getLoadedAt(): number {\n    return this.loadedAt;\n  }\n\n  getStatus(): SkillRuntimeStatus {\n    return {\n      version: this.getVersion(),\n      loadedAt: this.loadedAt,\n      reloadInProgress: this.reloadInProgress,\n      reloadPending: this.reloadPending,\n      ...(this.lastReloadStartedAt !== undefined ? { lastReloadStartedAt: this.lastReloadStartedAt } : {}),\n      ...(this.lastReloadFinishedAt !== undefined ? { lastReloadFinishedAt: this.lastReloadFinishedAt } : {}),\n      ...(this.lastReloadReason !== undefined ? { lastReloadReason: this.lastReloadReason } : {}),\n      ...(this.lastReloadOk !== undefined ? { lastReloadOk: this.lastReloadOk } : {}),\n      ...(this.lastReloadError !== undefined ? { lastReloadError: this.lastReloadError } : {}),\n    };\n  }\n\n  /**\n   * Get skill names\n   */\n  getSkillNames(): string[] {\n    return this.skills.map((s) => s.name);\n  }\n\n  /** Names of skills included in the agent system prompt (`<available_skills>`). */\n  getSkillNamesForPrompt(): string[] {\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return this.getSkills()\n      .filter((s) => !s.disableModelInvocation && isSkillEnabled(s, skillsConfig))\n      .map((s) => s.name);\n  }\n\n  /**\n   * Skills that are enabled for model discovery (respects skills.json and requirement checks).\n   */\n  getEnabledSkills(): Skill[] {\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return this.getSkills().filter(\n      (s) => !s.disableModelInvocation && isSkillEnabled(s, skillsConfig),\n    );\n  }\n\n  /**\n   * Like {@link getEnabledSkills} plus optional allowlist and tool gating (matches `<available_skills>`).\n   */\n  getEnabledSkillsForAgentSession(options?: {\n    skillAllowlist?: string[];\n    registeredToolNames?: string[];\n  }): Skill[] {\n    return this.selectSkillsForAgentIndexing(options);\n  }\n\n  /**\n   * Find a skill by name\n   */\n  findSkill(name: string): Skill | undefined {\n    return this.skills.find(s => s.name === name);\n  }\n\n  /**\n   * Check if a skill exists\n   */\n  hasSkill(name: string): boolean {\n    return this.skills.some(s => s.name === name);\n  }\n\n  /**\n   * Expand a skill command into a full skill block\n   */\n  expandCommand(text: string, options?: { skillAllowlist?: string[]; registeredToolNames?: string[] }): string {\n    if (!text.startsWith('/skill:')) {\n      return text;\n    }\n\n    const { skillName, args } = this.parseSkillCommand(text);\n    const visible = this.selectSkillsForAgentIndexing(options);\n    const skill = visible.find((s) => s.name === skillName);\n\n    if (!skill) {\n      log.warn({ skillName }, 'Skill not visible for expansion');\n      return text;\n    }\n\n    return this.buildSkillBlock(skill, args);\n  }\n\n  /**\n   * Parse a /skill: command\n   */\n  private parseSkillCommand(text: string): { skillName: string; args?: string } {\n    // Format: /skill:name args...\n    const withoutPrefix = text.slice(7); // Remove '/skill:'\n    const spaceIndex = withoutPrefix.indexOf(' ');\n\n    if (spaceIndex === -1) {\n      return { skillName: withoutPrefix.trim() };\n    }\n\n    return {\n      skillName: withoutPrefix.slice(0, spaceIndex).trim(),\n      args: withoutPrefix.slice(spaceIndex + 1).trim(),\n    };\n  }\n\n  /**\n   * Build a skill block for inclusion in the prompt\n   */\n  private buildSkillBlock(skill: Skill, args?: string): string {\n    let block = `\\n\\n## Skill: ${skill.name}\\n\\n`;\n    \n    if (skill.description) {\n      block += `${skill.description}\\n\\n`;\n    }\n\n    // Include raw skill content (SKILL.md content)\n    if (skill.content) {\n      block += `${skill.content}\\n\\n`;\n    }\n\n    if (args) {\n      block += `**Arguments**: ${args}\\n\\n`;\n    }\n\n    return block;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"skill-manager.js","names":[],"sources":["../../../../src/agent/skills/skill-manager.ts"],"sourcesContent":["/**\n * Skill Manager - Manages skills loading and expansion\n *\n * Handles skill initialization, reloading, and command expansion.\n */\n\nimport { createSkillLoader } from './index.js';\nimport { resolveBundledSkillsDir, resolveStateDir } from '../../config/paths.js';\nimport { createLogger } from '../../utils/logger.js';\nimport { createSkillConfigManager, isSkillEnabled } from './config.js';\nimport { formatSkillsForPrompt, selectSkillsVisibleInPrompt } from './format-skills-prompt.js';\nimport type {\n  LoadSkillsResult,\n  Skill,\n  SkillDiagnostic,\n  SkillRuntimeStatus,\n} from './types.js';\n\nconst log = createLogger('SkillManager');\nconst SKILL_TOKEN_RE = /\\/skill:([A-Za-z0-9][A-Za-z0-9._-]*)/g;\n\nexport interface SkillLoadResult {\n  skills: Skill[];\n  prompt: string;\n  diagnostics: SkillDiagnostic[];\n}\n\nexport class SkillManager {\n  private skillPrompt: string = '';\n  private skills: Skill[] = [];\n  private skillLoader = createSkillLoader();\n  private workspace: string;\n  private bundledSkillsDir: string;\n  private version = 0;\n  private loadedAt = 0;\n  private reloadInProgress = false;\n  private reloadPending = false;\n  private lastReloadStartedAt: number | undefined;\n  private lastReloadFinishedAt: number | undefined;\n  private lastReloadReason: SkillRuntimeStatus['lastReloadReason'];\n  private lastReloadOk: boolean | undefined;\n  private lastReloadError: string | undefined;\n\n  constructor(workspace: string, bundledSkillsDir?: string) {\n    this.workspace = workspace;\n    this.bundledSkillsDir = bundledSkillsDir || resolveBundledSkillsDir();\n    this.initialize();\n  }\n\n  /**\n   * Initialize skills from workspace and bundled directories\n   */\n  private initialize(): void {\n    this.runReload('initial', () => this.skillLoader.init(this.workspace, this.bundledSkillsDir));\n  }\n\n  /**\n   * Recompute skill XML prompt from current skills.json (no disk rescan).\n   */\n  refreshPromptFromConfig(): void {\n    this.skillLoader.refreshPromptFromConfig();\n    this.skillPrompt = this.skillLoader.getPrompt();\n    this.version += 1;\n    this.loadedAt = Date.now();\n    this.lastReloadReason = 'config';\n    this.lastReloadOk = true;\n    this.lastReloadError = undefined;\n  }\n\n  /**\n   * Reload skills from disk\n   */\n  reload(): void {\n    this.runReload('disk', () => this.skillLoader.reload());\n  }\n\n  private runReload(reason: NonNullable<SkillRuntimeStatus['lastReloadReason']>, load: () => LoadSkillsResult): void {\n    if (this.reloadInProgress) {\n      this.reloadPending = true;\n      return;\n    }\n\n    do {\n      this.reloadPending = false;\n      this.reloadInProgress = true;\n      this.lastReloadStartedAt = Date.now();\n      this.lastReloadReason = reason;\n      try {\n        const result = load();\n        this.applyLoadResult(result);\n        this.lastReloadOk = true;\n        this.lastReloadError = undefined;\n        log.info({ count: result.skills.length, version: this.version }, 'Skills reloaded');\n      } catch (err) {\n        const errorMessage = err instanceof Error ? err.message : String(err);\n        this.lastReloadOk = false;\n        this.lastReloadError = errorMessage;\n        log.error({ err, errorMessage }, `Skills reload failed: ${errorMessage}`);\n      } finally {\n        this.lastReloadFinishedAt = Date.now();\n        this.reloadInProgress = false;\n      }\n    } while (this.reloadPending);\n  }\n\n  private applyLoadResult(result: LoadSkillsResult): void {\n    this.skillPrompt = result.prompt;\n    this.skills = result.skills;\n    this.version += 1;\n    this.loadedAt = Date.now();\n\n    for (const diag of result.diagnostics) {\n      if (diag.type === 'collision') {\n        log.warn({ skill: diag.skillName, path: diag.path, message: diag.message }, 'Skill collision');\n      } else if (diag.type === 'warning') {\n        log.warn({ skill: diag.skillName, path: diag.path, message: diag.message }, 'Skill warning');\n      } else if (diag.type === 'error') {\n        log.error({ skill: diag.skillName, path: diag.path, message: diag.message }, 'Skill error');\n      }\n    }\n  }\n\n  /**\n   * Get the skill prompt to append to system prompt\n   */\n  getPrompt(): string {\n    return this.skillPrompt;\n  }\n\n  /**\n   * `<available_skills>` XML with optional per-agent allowlist and/or tool-based gating.\n   * When both arguments are omitted, returns the cached prompt from disk load (no tool gating).\n   */\n  getPromptForSkillAllowlist(\n    allowlist: string[] | undefined,\n    registeredToolNames?: string[],\n  ): string {\n    if (allowlist === undefined && registeredToolNames === undefined) {\n      return this.getPrompt();\n    }\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return formatSkillsForPrompt(this.getSkills(), skillsConfig, {\n      skillAllowlist: allowlist,\n      registeredToolNames,\n    });\n  }\n\n  /** Skills visible for prompts and skills_list given the same indexing options as {@link getPromptForSkillAllowlist}. */\n  selectSkillsForAgentIndexing(options?: {\n    skillAllowlist?: string[];\n    registeredToolNames?: string[];\n  }): Skill[] {\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return selectSkillsVisibleInPrompt(this.getSkills(), skillsConfig, options);\n  }\n\n  /**\n   * Get all loaded skills\n   */\n  getSkills(): Skill[] {\n    return [...this.skills];\n  }\n\n  getDiagnostics(): SkillDiagnostic[] {\n    return this.skillLoader.getDiagnostics();\n  }\n\n  getVersion(): string {\n    return String(this.version);\n  }\n\n  getLoadedAt(): number {\n    return this.loadedAt;\n  }\n\n  getStatus(): SkillRuntimeStatus {\n    return {\n      version: this.getVersion(),\n      loadedAt: this.loadedAt,\n      reloadInProgress: this.reloadInProgress,\n      reloadPending: this.reloadPending,\n      ...(this.lastReloadStartedAt !== undefined ? { lastReloadStartedAt: this.lastReloadStartedAt } : {}),\n      ...(this.lastReloadFinishedAt !== undefined ? { lastReloadFinishedAt: this.lastReloadFinishedAt } : {}),\n      ...(this.lastReloadReason !== undefined ? { lastReloadReason: this.lastReloadReason } : {}),\n      ...(this.lastReloadOk !== undefined ? { lastReloadOk: this.lastReloadOk } : {}),\n      ...(this.lastReloadError !== undefined ? { lastReloadError: this.lastReloadError } : {}),\n    };\n  }\n\n  /**\n   * Get skill names\n   */\n  getSkillNames(): string[] {\n    return this.skills.map((s) => s.name);\n  }\n\n  /** Names of skills included in the agent system prompt (`<available_skills>`). */\n  getSkillNamesForPrompt(): string[] {\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return this.getSkills()\n      .filter((s) => !s.disableModelInvocation && isSkillEnabled(s, skillsConfig))\n      .map((s) => s.name);\n  }\n\n  /**\n   * Skills that are enabled for model discovery (respects skills.json and requirement checks).\n   */\n  getEnabledSkills(): Skill[] {\n    const skillsConfig = createSkillConfigManager(resolveStateDir()).load();\n    return this.getSkills().filter(\n      (s) => !s.disableModelInvocation && isSkillEnabled(s, skillsConfig),\n    );\n  }\n\n  /**\n   * Like {@link getEnabledSkills} plus optional allowlist and tool gating (matches `<available_skills>`).\n   */\n  getEnabledSkillsForAgentSession(options?: {\n    skillAllowlist?: string[];\n    registeredToolNames?: string[];\n  }): Skill[] {\n    return this.selectSkillsForAgentIndexing(options);\n  }\n\n  getActivatedCapabilitiesForText(\n    text: string,\n    options?: { skillAllowlist?: string[]; registeredToolNames?: string[] },\n  ): string[] {\n    if (!text.includes('/skill:')) return [];\n    const selected = new Set<string>();\n    for (const match of text.matchAll(SKILL_TOKEN_RE)) {\n      if (match[1]) selected.add(match[1]);\n    }\n    if (selected.size === 0) return [];\n\n    const visible = this.selectSkillsForAgentIndexing(options);\n    const activeCapabilities = new Set<string>();\n    for (const skill of visible) {\n      if (!selected.has(skill.name)) continue;\n      for (const capabilityName of skill.metadata.xopc?.activatesCapabilities ?? []) {\n        const trimmed = capabilityName.trim();\n        if (trimmed) activeCapabilities.add(trimmed);\n      }\n    }\n    return [...activeCapabilities];\n  }\n\n  /**\n   * Find a skill by name\n   */\n  findSkill(name: string): Skill | undefined {\n    return this.skills.find(s => s.name === name);\n  }\n\n  /**\n   * Check if a skill exists\n   */\n  hasSkill(name: string): boolean {\n    return this.skills.some(s => s.name === name);\n  }\n\n  /**\n   * Expand a skill command into a full skill block\n   */\n  expandCommand(text: string, options?: { skillAllowlist?: string[]; registeredToolNames?: string[] }): string {\n    if (!text.startsWith('/skill:')) {\n      return text;\n    }\n\n    const { skillName, args } = this.parseSkillCommand(text);\n    const visible = this.selectSkillsForAgentIndexing(options);\n    const skill = visible.find((s) => s.name === skillName);\n\n    if (!skill) {\n      log.warn({ skillName }, 'Skill not visible for expansion');\n      return text;\n    }\n\n    return this.buildSkillBlock(skill, args);\n  }\n\n  /**\n   * Parse a /skill: command\n   */\n  private parseSkillCommand(text: string): { skillName: string; args?: string } {\n    // Format: /skill:name args...\n    const withoutPrefix = text.slice(7); // Remove '/skill:'\n    const spaceIndex = withoutPrefix.indexOf(' ');\n\n    if (spaceIndex === -1) {\n      return { skillName: withoutPrefix.trim() };\n    }\n\n    return {\n      skillName: withoutPrefix.slice(0, spaceIndex).trim(),\n      args: withoutPrefix.slice(spaceIndex + 1).trim(),\n    };\n  }\n\n  /**\n   * Build a skill block for inclusion in the prompt\n   */\n  private buildSkillBlock(skill: Skill, args?: string): string {\n    let block = `\\n\\n## Skill: ${skill.name}\\n\\n`;\n    \n    if (skill.description) {\n      block += `${skill.description}\\n\\n`;\n    }\n\n    // Include raw skill content (SKILL.md content)\n    if (skill.content) {\n      block += `${skill.content}\\n\\n`;\n    }\n\n    if (args) {\n      block += `**Arguments**: ${args}\\n\\n`;\n    }\n\n    return block;\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/skills/types.d.ts

@@ -60,6 +60,11 @@ export interface SkillMetadata {
         requires?: SkillRequires;
         install?: SkillInstallSpec[];
         os?: Array<'darwin' | 'linux' | 'win32'>;
+        /**
+         * Lazy capability packs to inject only when this skill is explicitly selected for a turn.
+         * Parsed from `metadata.xopc.activates_capabilities`.
+         */
+        activatesCapabilities?: string[];
     };
 }
 export interface SkillConfig {

package/dist/src/agent/tool-manuals/index.js

@@ -1,11 +1,20 @@
 import { browserUseManual } from "./browser.js";
+import { xopcUseManual } from "./xopc-use.js";
 //#region src/agent/tool-manuals/index.ts
-const TOOL_MANUALS = { browser_use: {
-	toolName: "browser_use",
-	title: "Browser Tool Manual",
-	description: "Usage guide for browser navigation, inspection, interaction, screenshots, and pipelines.",
-	content: browserUseManual
-} };
+const TOOL_MANUALS = {
+	browser_use: {
+		toolName: "browser_use",
+		title: "Browser Tool Manual",
+		description: "Usage guide for browser navigation, inspection, interaction, screenshots, and pipelines.",
+		content: browserUseManual
+	},
+	xopc_use: {
+		toolName: "xopc_use",
+		title: "XOPC Use Tool Manual",
+		description: "Usage guide for operating XOPC projects, notes, and project work items.",
+		content: xopcUseManual
+	}
+};
 function normalizeToolName(toolName) {
 	return toolName.trim().toLowerCase();
 }

package/dist/src/agent/tool-manuals/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../../src/agent/tool-manuals/index.ts"],"sourcesContent":["import { browserUseManual } from './browser.js';\n\nexport interface ToolManual {\n  toolName: string;\n  title: string;\n  description: string;\n  content: string;\n}\n\nexport type ToolManualSummary = Omit<ToolManual, 'content'>;\n\nconst TOOL_MANUALS: Record<string, ToolManual> = {\n  browser_use: {\n    toolName: 'browser_use',\n    title: 'Browser Tool Manual',\n    description: 'Usage guide for browser navigation, inspection, interaction, screenshots, and pipelines.',\n    content: browserUseManual,\n  },\n};\n\nfunction normalizeToolName(toolName: string): string {\n  return toolName.trim().toLowerCase();\n}\n\nexport function getToolManual(toolName: string): ToolManual | null {\n  return TOOL_MANUALS[normalizeToolName(toolName)] ?? null;\n}\n\nexport function hasToolManual(toolName: string): boolean {\n  return getToolManual(toolName) !== null;\n}\n\nexport function listToolManuals(): ToolManualSummary[] {\n  return Object.values(TOOL_MANUALS)\n    .map(({ toolName, title, description }) => ({ toolName, title, description }))\n    .sort((a, b) => a.toolName.localeCompare(b.toolName));\n}\n"],"mappings":";;AAWA,MAAM,eAA2C,EAC/C,aAAa;CACX,UAAU;CACV,OAAO;CACP,aAAa;CACb,SAAS;CACV,EACF;AAED,SAAS,kBAAkB,UAA0B;AACnD,QAAO,SAAS,MAAM,CAAC,aAAa;;AAGtC,SAAgB,cAAc,UAAqC;AACjE,QAAO,aAAa,kBAAkB,SAAS,KAAK;;AAGtD,SAAgB,cAAc,UAA2B;AACvD,QAAO,cAAc,SAAS,KAAK;;AAGrC,SAAgB,kBAAuC;AACrD,QAAO,OAAO,OAAO,aAAa,CAC/B,KAAK,EAAE,UAAU,OAAO,mBAAmB;EAAE;EAAU;EAAO;EAAa,EAAE,CAC7E,MAAM,GAAG,MAAM,EAAE,SAAS,cAAc,EAAE,SAAS,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/agent/tool-manuals/index.ts"],"sourcesContent":["import { browserUseManual } from './browser.js';\nimport { xopcUseManual } from './xopc-use.js';\n\nexport interface ToolManual {\n  toolName: string;\n  title: string;\n  description: string;\n  content: string;\n}\n\nexport type ToolManualSummary = Omit<ToolManual, 'content'>;\n\nconst TOOL_MANUALS: Record<string, ToolManual> = {\n  browser_use: {\n    toolName: 'browser_use',\n    title: 'Browser Tool Manual',\n    description: 'Usage guide for browser navigation, inspection, interaction, screenshots, and pipelines.',\n    content: browserUseManual,\n  },\n  xopc_use: {\n    toolName: 'xopc_use',\n    title: 'XOPC Use Tool Manual',\n    description: 'Usage guide for operating XOPC projects, notes, and project work items.',\n    content: xopcUseManual,\n  },\n};\n\nfunction normalizeToolName(toolName: string): string {\n  return toolName.trim().toLowerCase();\n}\n\nexport function getToolManual(toolName: string): ToolManual | null {\n  return TOOL_MANUALS[normalizeToolName(toolName)] ?? null;\n}\n\nexport function hasToolManual(toolName: string): boolean {\n  return getToolManual(toolName) !== null;\n}\n\nexport function listToolManuals(): ToolManualSummary[] {\n  return Object.values(TOOL_MANUALS)\n    .map(({ toolName, title, description }) => ({ toolName, title, description }))\n    .sort((a, b) => a.toolName.localeCompare(b.toolName));\n}\n"],"mappings":";;;AAYA,MAAM,eAA2C;CAC/C,aAAa;EACX,UAAU;EACV,OAAO;EACP,aAAa;EACb,SAAS;EACV;CACD,UAAU;EACR,UAAU;EACV,OAAO;EACP,aAAa;EACb,SAAS;EACV;CACF;AAED,SAAS,kBAAkB,UAA0B;AACnD,QAAO,SAAS,MAAM,CAAC,aAAa;;AAGtC,SAAgB,cAAc,UAAqC;AACjE,QAAO,aAAa,kBAAkB,SAAS,KAAK;;AAGtD,SAAgB,cAAc,UAA2B;AACvD,QAAO,cAAc,SAAS,KAAK;;AAGrC,SAAgB,kBAAuC;AACrD,QAAO,OAAO,OAAO,aAAa,CAC/B,KAAK,EAAE,UAAU,OAAO,mBAAmB;EAAE;EAAU;EAAO;EAAa,EAAE,CAC7E,MAAM,GAAG,MAAM,EAAE,SAAS,cAAc,EAAE,SAAS,CAAC"}

package/dist/src/agent/tool-manuals/xopc-use.d.ts

@@ -0,0 +1 @@
+export declare const xopcUseManual = "# XOPC Use Tool Manual\n\n## Overview\n\n`xopc_use` is the unified tool for operating XOPC product objects. Use it instead of editing storage files or database rows directly.\n\nBasic shape:\n\n```json\n{\n  \"mode\": \"project | note | work_item\",\n  \"command\": \"list | get | create | update | append | preview_edit | resolve_workspace\",\n  \"args\": { \"...\": \"...\" },\n  \"dryRun\": false\n}\n```\n\n## General Rules\n\n- Use `list` or `get` first when the target object is ambiguous.\n- Use `dryRun: true` before a broad or risky change.\n- Prefer additive operations over destructive replacement.\n- Do not invent ids. If an id is not known, search/list first.\n- Do not attempt delete/archive workflows through this tool unless the command is explicitly supported.\n- For non-trivial note rewrites, use `note.preview_edit` before `note.update`.\n\n## Projects\n\nProjects group sessions, work items, goals, workflows, files, and project instructions.\n\n### Find projects\n\n```json\n{ \"mode\": \"project\", \"command\": \"list\", \"args\": { \"search\": \"release\", \"limit\": 10 } }\n```\n\n### Read project detail\n\n```json\n{ \"mode\": \"project\", \"command\": \"get\", \"args\": { \"projectId\": \"project_id\" } }\n```\n\n### Create a project\n\nUse when the user asks to start or formalize a project. Include `workspaceRoot` when the project maps to a local repository or directory. Include `brief` for the concise product idea and `instructions` for agent-operating guidance.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"AI Product Research\",\n    \"workspaceRoot\": \"/path/to/repo\",\n    \"brief\": \"Explore demand and feasibility for an AI product.\",\n    \"instructions\": \"Keep decisions and open questions current.\"\n  }\n}\n```\n\n### Update a project\n\nUse for metadata, brief, status, or instructions. Use `dryRun` first when changing `workspaceRoot` or broad instructions.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"status\": \"active\",\n    \"instructions\": \"Prioritize safe previews before changing notes.\"\n  }\n}\n```\n\n### Resolve workspace\n\nUse when a file path or current working directory should be mapped to a project.\n\n```json\n{\n  \"mode\": \"project\",\n  \"command\": \"resolve_workspace\",\n  \"args\": { \"workspacePath\": \"/path/to/repo\", \"autoCreate\": false }\n}\n```\n\n## Notes\n\nNotes are user-owned markdown objects. Treat them as durable user content.\n\n### Find notes\n\n```json\n{ \"mode\": \"note\", \"command\": \"list\", \"args\": { \"search\": \"pricing\", \"limit\": 10 } }\n```\n\n### Create a note\n\n```json\n{\n  \"mode\": \"note\",\n  \"command\": \"create\",\n  \"args\": {\n    \"title\": \"Product direction\",\n    \"markdown\": \"Initial notes...\",\n    \"tags\": [\"product\"]\n  }\n}\n```\n\n### Append to a note\n\nPrefer append when preserving original user notes and adding AI output.\n\n```json\n{\n  \"mode\": \"note\",\n  \"command\": \"append\",\n  \"args\": {\n    \"noteId\": \"note_id\",\n    \"heading\": \"AI synthesis\",\n    \"content\": \"Key points...\"\n  }\n}\n```\n\n### Preview an edit\n\nUse before rewriting or restructuring a note.\n\n```json\n{\n  \"mode\": \"note\",\n  \"command\": \"preview_edit\",\n  \"args\": {\n    \"noteId\": \"note_id\",\n    \"instruction\": \"Summarize this as action items\"\n  }\n}\n```\n\n### Update a note\n\nUse only when the user clearly wants the canonical note changed. Prefer `append` or `preview_edit` otherwise.\n\n```json\n{\n  \"mode\": \"note\",\n  \"command\": \"update\",\n  \"args\": {\n    \"noteId\": \"note_id\",\n    \"status\": \"processed\",\n    \"tags\": [\"product\", \"validated\"]\n  }\n}\n```\n\n## Work Items\n\nWork items are project-scoped tasks. If `projectId` is omitted, the tool may inherit the current session's project binding.\n\n### Create a work item\n\n```json\n{\n  \"mode\": \"work_item\",\n  \"command\": \"create\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"title\": \"Validate technical feasibility\",\n    \"description\": \"Check API, storage, UI, and safety implications.\",\n    \"priority\": \"high\",\n    \"status\": \"todo\"\n  }\n}\n```\n\n### Update a work item\n\n```json\n{\n  \"mode\": \"work_item\",\n  \"command\": \"update\",\n  \"args\": {\n    \"workItemId\": \"work_item_id\",\n    \"status\": \"in_progress\",\n    \"nextAction\": \"Prototype the xopc_use tool path.\"\n  }\n}\n```\n\n## Safety\n\n- `note.update` can replace canonical user content. Use `preview_edit` first for content rewrites.\n- `project.update.workspaceRoot` changes project-file scope. Use `dryRun` and ask the user if intent is unclear.\n- `work_item.update.archivedAt` hides work from normal active views. Confirm before archiving.\n- If the user asks for deletion, explain that deletion is not exposed through `xopc_use` yet.\n";

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

@@ -0,0 +1,204 @@
+//#region src/agent/tool-manuals/xopc-use.ts
+const xopcUseManual = `# XOPC Use Tool Manual
+
+## Overview
+
+\`xopc_use\` is the unified tool for operating XOPC product objects. Use it instead of editing storage files or database rows directly.
+
+Basic shape:
+
+\`\`\`json
+{
+  "mode": "project | note | work_item",
+  "command": "list | get | create | update | append | preview_edit | resolve_workspace",
+  "args": { "...": "..." },
+  "dryRun": false
+}
+\`\`\`
+
+## General Rules
+
+- Use \`list\` or \`get\` first when the target object is ambiguous.
+- Use \`dryRun: true\` before a broad or risky change.
+- Prefer additive operations over destructive replacement.
+- Do not invent ids. If an id is not known, search/list first.
+- Do not attempt delete/archive workflows through this tool unless the command is explicitly supported.
+- For non-trivial note rewrites, use \`note.preview_edit\` before \`note.update\`.
+
+## Projects
+
+Projects group sessions, work items, goals, workflows, files, and project instructions.
+
+### Find projects
+
+\`\`\`json
+{ "mode": "project", "command": "list", "args": { "search": "release", "limit": 10 } }
+\`\`\`
+
+### Read project detail
+
+\`\`\`json
+{ "mode": "project", "command": "get", "args": { "projectId": "project_id" } }
+\`\`\`
+
+### Create a project
+
+Use when the user asks to start or formalize a project. Include \`workspaceRoot\` when the project maps to a local repository or directory. Include \`brief\` for the concise product idea and \`instructions\` for agent-operating guidance.
+
+\`\`\`json
+{
+  "mode": "project",
+  "command": "create",
+  "args": {
+    "name": "AI Product Research",
+    "workspaceRoot": "/path/to/repo",
+    "brief": "Explore demand and feasibility for an AI product.",
+    "instructions": "Keep decisions and open questions current."
+  }
+}
+\`\`\`
+
+### Update a project
+
+Use for metadata, brief, status, or instructions. Use \`dryRun\` first when changing \`workspaceRoot\` or broad instructions.
+
+\`\`\`json
+{
+  "mode": "project",
+  "command": "update",
+  "args": {
+    "projectId": "project_id",
+    "status": "active",
+    "instructions": "Prioritize safe previews before changing notes."
+  }
+}
+\`\`\`
+
+### Resolve workspace
+
+Use when a file path or current working directory should be mapped to a project.
+
+\`\`\`json
+{
+  "mode": "project",
+  "command": "resolve_workspace",
+  "args": { "workspacePath": "/path/to/repo", "autoCreate": false }
+}
+\`\`\`
+
+## Notes
+
+Notes are user-owned markdown objects. Treat them as durable user content.
+
+### Find notes
+
+\`\`\`json
+{ "mode": "note", "command": "list", "args": { "search": "pricing", "limit": 10 } }
+\`\`\`
+
+### Create a note
+
+\`\`\`json
+{
+  "mode": "note",
+  "command": "create",
+  "args": {
+    "title": "Product direction",
+    "markdown": "Initial notes...",
+    "tags": ["product"]
+  }
+}
+\`\`\`
+
+### Append to a note
+
+Prefer append when preserving original user notes and adding AI output.
+
+\`\`\`json
+{
+  "mode": "note",
+  "command": "append",
+  "args": {
+    "noteId": "note_id",
+    "heading": "AI synthesis",
+    "content": "Key points..."
+  }
+}
+\`\`\`
+
+### Preview an edit
+
+Use before rewriting or restructuring a note.
+
+\`\`\`json
+{
+  "mode": "note",
+  "command": "preview_edit",
+  "args": {
+    "noteId": "note_id",
+    "instruction": "Summarize this as action items"
+  }
+}
+\`\`\`
+
+### Update a note
+
+Use only when the user clearly wants the canonical note changed. Prefer \`append\` or \`preview_edit\` otherwise.
+
+\`\`\`json
+{
+  "mode": "note",
+  "command": "update",
+  "args": {
+    "noteId": "note_id",
+    "status": "processed",
+    "tags": ["product", "validated"]
+  }
+}
+\`\`\`
+
+## Work Items
+
+Work items are project-scoped tasks. If \`projectId\` is omitted, the tool may inherit the current session's project binding.
+
+### Create a work item
+
+\`\`\`json
+{
+  "mode": "work_item",
+  "command": "create",
+  "args": {
+    "projectId": "project_id",
+    "title": "Validate technical feasibility",
+    "description": "Check API, storage, UI, and safety implications.",
+    "priority": "high",
+    "status": "todo"
+  }
+}
+\`\`\`
+
+### Update a work item
+
+\`\`\`json
+{
+  "mode": "work_item",
+  "command": "update",
+  "args": {
+    "workItemId": "work_item_id",
+    "status": "in_progress",
+    "nextAction": "Prototype the xopc_use tool path."
+  }
+}
+\`\`\`
+
+## Safety
+
+- \`note.update\` can replace canonical user content. Use \`preview_edit\` first for content rewrites.
+- \`project.update.workspaceRoot\` changes project-file scope. Use \`dryRun\` and ask the user if intent is unclear.
+- \`work_item.update.archivedAt\` hides work from normal active views. Confirm before archiving.
+- If the user asks for deletion, explain that deletion is not exposed through \`xopc_use\` yet.
+`;
+//#endregion
+export { xopcUseManual };
+
+//# sourceMappingURL=xopc-use.js.map

package/dist/src/agent/tool-manuals/xopc-use.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xopc-use.js","names":[],"sources":["../../../../src/agent/tool-manuals/xopc-use.ts"],"sourcesContent":["export const xopcUseManual = `# XOPC Use Tool Manual\n\n## Overview\n\n\\`xopc_use\\` is the unified tool for operating XOPC product objects. Use it instead of editing storage files or database rows directly.\n\nBasic shape:\n\n\\`\\`\\`json\n{\n  \"mode\": \"project | note | work_item\",\n  \"command\": \"list | get | create | update | append | preview_edit | resolve_workspace\",\n  \"args\": { \"...\": \"...\" },\n  \"dryRun\": false\n}\n\\`\\`\\`\n\n## General Rules\n\n- Use \\`list\\` or \\`get\\` first when the target object is ambiguous.\n- Use \\`dryRun: true\\` before a broad or risky change.\n- Prefer additive operations over destructive replacement.\n- Do not invent ids. If an id is not known, search/list first.\n- Do not attempt delete/archive workflows through this tool unless the command is explicitly supported.\n- For non-trivial note rewrites, use \\`note.preview_edit\\` before \\`note.update\\`.\n\n## Projects\n\nProjects group sessions, work items, goals, workflows, files, and project instructions.\n\n### Find projects\n\n\\`\\`\\`json\n{ \"mode\": \"project\", \"command\": \"list\", \"args\": { \"search\": \"release\", \"limit\": 10 } }\n\\`\\`\\`\n\n### Read project detail\n\n\\`\\`\\`json\n{ \"mode\": \"project\", \"command\": \"get\", \"args\": { \"projectId\": \"project_id\" } }\n\\`\\`\\`\n\n### Create a project\n\nUse when the user asks to start or formalize a project. Include \\`workspaceRoot\\` when the project maps to a local repository or directory. Include \\`brief\\` for the concise product idea and \\`instructions\\` for agent-operating guidance.\n\n\\`\\`\\`json\n{\n  \"mode\": \"project\",\n  \"command\": \"create\",\n  \"args\": {\n    \"name\": \"AI Product Research\",\n    \"workspaceRoot\": \"/path/to/repo\",\n    \"brief\": \"Explore demand and feasibility for an AI product.\",\n    \"instructions\": \"Keep decisions and open questions current.\"\n  }\n}\n\\`\\`\\`\n\n### Update a project\n\nUse for metadata, brief, status, or instructions. Use \\`dryRun\\` first when changing \\`workspaceRoot\\` or broad instructions.\n\n\\`\\`\\`json\n{\n  \"mode\": \"project\",\n  \"command\": \"update\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"status\": \"active\",\n    \"instructions\": \"Prioritize safe previews before changing notes.\"\n  }\n}\n\\`\\`\\`\n\n### Resolve workspace\n\nUse when a file path or current working directory should be mapped to a project.\n\n\\`\\`\\`json\n{\n  \"mode\": \"project\",\n  \"command\": \"resolve_workspace\",\n  \"args\": { \"workspacePath\": \"/path/to/repo\", \"autoCreate\": false }\n}\n\\`\\`\\`\n\n## Notes\n\nNotes are user-owned markdown objects. Treat them as durable user content.\n\n### Find notes\n\n\\`\\`\\`json\n{ \"mode\": \"note\", \"command\": \"list\", \"args\": { \"search\": \"pricing\", \"limit\": 10 } }\n\\`\\`\\`\n\n### Create a note\n\n\\`\\`\\`json\n{\n  \"mode\": \"note\",\n  \"command\": \"create\",\n  \"args\": {\n    \"title\": \"Product direction\",\n    \"markdown\": \"Initial notes...\",\n    \"tags\": [\"product\"]\n  }\n}\n\\`\\`\\`\n\n### Append to a note\n\nPrefer append when preserving original user notes and adding AI output.\n\n\\`\\`\\`json\n{\n  \"mode\": \"note\",\n  \"command\": \"append\",\n  \"args\": {\n    \"noteId\": \"note_id\",\n    \"heading\": \"AI synthesis\",\n    \"content\": \"Key points...\"\n  }\n}\n\\`\\`\\`\n\n### Preview an edit\n\nUse before rewriting or restructuring a note.\n\n\\`\\`\\`json\n{\n  \"mode\": \"note\",\n  \"command\": \"preview_edit\",\n  \"args\": {\n    \"noteId\": \"note_id\",\n    \"instruction\": \"Summarize this as action items\"\n  }\n}\n\\`\\`\\`\n\n### Update a note\n\nUse only when the user clearly wants the canonical note changed. Prefer \\`append\\` or \\`preview_edit\\` otherwise.\n\n\\`\\`\\`json\n{\n  \"mode\": \"note\",\n  \"command\": \"update\",\n  \"args\": {\n    \"noteId\": \"note_id\",\n    \"status\": \"processed\",\n    \"tags\": [\"product\", \"validated\"]\n  }\n}\n\\`\\`\\`\n\n## Work Items\n\nWork items are project-scoped tasks. If \\`projectId\\` is omitted, the tool may inherit the current session's project binding.\n\n### Create a work item\n\n\\`\\`\\`json\n{\n  \"mode\": \"work_item\",\n  \"command\": \"create\",\n  \"args\": {\n    \"projectId\": \"project_id\",\n    \"title\": \"Validate technical feasibility\",\n    \"description\": \"Check API, storage, UI, and safety implications.\",\n    \"priority\": \"high\",\n    \"status\": \"todo\"\n  }\n}\n\\`\\`\\`\n\n### Update a work item\n\n\\`\\`\\`json\n{\n  \"mode\": \"work_item\",\n  \"command\": \"update\",\n  \"args\": {\n    \"workItemId\": \"work_item_id\",\n    \"status\": \"in_progress\",\n    \"nextAction\": \"Prototype the xopc_use tool path.\"\n  }\n}\n\\`\\`\\`\n\n## Safety\n\n- \\`note.update\\` can replace canonical user content. Use \\`preview_edit\\` first for content rewrites.\n- \\`project.update.workspaceRoot\\` changes project-file scope. Use \\`dryRun\\` and ask the user if intent is unclear.\n- \\`work_item.update.archivedAt\\` hides work from normal active views. Confirm before archiving.\n- If the user asks for deletion, explain that deletion is not exposed through \\`xopc_use\\` yet.\n`;\n"],"mappings":";AAAA,MAAa,gBAAgB"}

package/dist/src/agent/tools/desktop-pet-tool.d.ts

@@ -0,0 +1,24 @@
+import type { AgentToolWithMetadata } from './metadata.js';
+declare const DesktopPetCreateSchema: import("@sinclair/typebox/build/cjs/index.js").TObject<{
+    mode: import("@sinclair/typebox/build/cjs/index.js").TOptional<import("@sinclair/typebox/build/cjs/index.js").TUnion<[import("@sinclair/typebox/build/cjs/index.js").TLiteral<"create">, import("@sinclair/typebox/build/cjs/index.js").TLiteral<"update">]>>;
+    petId: import("@sinclair/typebox/build/cjs/index.js").TOptional<import("@sinclair/typebox/build/cjs/index.js").TString>;
+    prompt: import("@sinclair/typebox/build/cjs/index.js").TString;
+    name: import("@sinclair/typebox/build/cjs/index.js").TOptional<import("@sinclair/typebox/build/cjs/index.js").TString>;
+    description: import("@sinclair/typebox/build/cjs/index.js").TOptional<import("@sinclair/typebox/build/cjs/index.js").TString>;
+    overwrite: import("@sinclair/typebox/build/cjs/index.js").TOptional<import("@sinclair/typebox/build/cjs/index.js").TBoolean>;
+}>;
+export type DesktopPetCreateDetails = {
+    ok: true;
+    id: string;
+    name: string;
+    dir: string;
+    manifestPath: string;
+    thumbnailPath: string;
+    spritesheetPath: string;
+    mode: 'create' | 'update';
+} | {
+    ok: false;
+    error: string;
+};
+export declare function createDesktopPetTool(): AgentToolWithMetadata<typeof DesktopPetCreateSchema, DesktopPetCreateDetails>;
+export {};

package/dist/src/agent/tools/desktop-pet-tool.js

@@ -0,0 +1,90 @@
+import { createDesktopPetPackage } from "../../pets/factory.js";
+import { Type } from "@sinclair/typebox";
+//#region src/agent/tools/desktop-pet-tool.ts
+const DesktopPetCreateSchema = Type.Object({
+	mode: Type.Optional(Type.Union([Type.Literal("create"), Type.Literal("update")], { description: "create installs a new pet package. update overwrites an existing custom pet package identified by petId." })),
+	petId: Type.Optional(Type.String({ description: "Existing custom pet id to update. Accepts either \"custom:<id>\" from Settings or the folder id under ~/.xopc/pets." })),
+	prompt: Type.String({ description: "Full description of the desired pet character, visual style, personality, colors, motifs, and requested changes." }),
+	name: Type.Optional(Type.String({ description: "Optional display name for the pet." })),
+	description: Type.Optional(Type.String({ description: "Optional short description shown in Settings." })),
+	overwrite: Type.Optional(Type.Boolean({ description: "When true, reuse the folder derived from the pet name. Default false creates a unique folder if one exists." }))
+});
+function createDesktopPetTool() {
+	return {
+		name: "create_desktop_pet",
+		label: "Create Pet",
+		description: "Create or update a custom animated desktop pet from a natural-language description. Packages are written under ~/.xopc/pets and can be selected in Settings > Pet. Use mode=update with petId when iterating on an existing custom pet.",
+		parameters: DesktopPetCreateSchema,
+		mutatesWorkspace: false,
+		mutationScope: "external",
+		supportsParallel: false,
+		idempotent: false,
+		requiresExclusiveWorkspaceLock: false,
+		finalGuardRelevant: false,
+		async execute(_toolCallId, params) {
+			const prompt = typeof params.prompt === "string" ? params.prompt.trim() : "";
+			if (!prompt) return {
+				content: [{
+					type: "text",
+					text: "prompt is required."
+				}],
+				details: {
+					ok: false,
+					error: "prompt is required"
+				}
+			};
+			const mode = params.mode === "update" ? "update" : "create";
+			const petId = typeof params.petId === "string" ? params.petId.trim() : "";
+			if (mode === "update" && !petId) return {
+				content: [{
+					type: "text",
+					text: "petId is required when mode is update."
+				}],
+				details: {
+					ok: false,
+					error: "petId is required when mode is update"
+				}
+			};
+			try {
+				const result = await createDesktopPetPackage({
+					...mode === "update" ? { id: petId } : {},
+					prompt,
+					...typeof params.name === "string" && params.name.trim() ? { name: params.name.trim() } : {},
+					...typeof params.description === "string" && params.description.trim() ? { description: params.description.trim() } : {},
+					overwrite: mode === "update" ? true : params.overwrite === true
+				});
+				return {
+					content: [{
+						type: "text",
+						text: [
+							`${mode === "update" ? "Updated" : "Created"} desktop pet "${result.name}".`,
+							`Installed at: ${result.dir}`,
+							"Open Settings > Pet, refresh if needed, and select the new custom pet."
+						].join("\n")
+					}],
+					details: {
+						ok: true,
+						mode,
+						...result
+					}
+				};
+			} catch (e) {
+				const error = e instanceof Error ? e.message : String(e);
+				return {
+					content: [{
+						type: "text",
+						text: `Failed to create desktop pet: ${error}`
+					}],
+					details: {
+						ok: false,
+						error
+					}
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { createDesktopPetTool };
+
+//# sourceMappingURL=desktop-pet-tool.js.map

package/dist/src/agent/tools/desktop-pet-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-pet-tool.js","names":[],"sources":["../../../../src/agent/tools/desktop-pet-tool.ts"],"sourcesContent":["import { Type } from '@sinclair/typebox';\nimport type { AgentToolResult } from '@earendil-works/pi-agent-core';\n\nimport { createDesktopPetPackage } from '../../pets/factory.js';\nimport type { AgentToolWithMetadata } from './metadata.js';\n\nconst DesktopPetCreateSchema = Type.Object({\n  mode: Type.Optional(\n    Type.Union([Type.Literal('create'), Type.Literal('update')], {\n      description:\n        'create installs a new pet package. update overwrites an existing custom pet package identified by petId.',\n    }),\n  ),\n  petId: Type.Optional(\n    Type.String({\n      description:\n        'Existing custom pet id to update. Accepts either \"custom:<id>\" from Settings or the folder id under ~/.xopc/pets.',\n    }),\n  ),\n  prompt: Type.String({\n    description:\n      'Full description of the desired pet character, visual style, personality, colors, motifs, and requested changes.',\n  }),\n  name: Type.Optional(Type.String({ description: 'Optional display name for the pet.' })),\n  description: Type.Optional(Type.String({ description: 'Optional short description shown in Settings.' })),\n  overwrite: Type.Optional(\n    Type.Boolean({\n      description:\n        'When true, reuse the folder derived from the pet name. Default false creates a unique folder if one exists.',\n    }),\n  ),\n});\n\nexport type DesktopPetCreateDetails =\n  | {\n      ok: true;\n      id: string;\n      name: string;\n      dir: string;\n      manifestPath: string;\n      thumbnailPath: string;\n      spritesheetPath: string;\n      mode: 'create' | 'update';\n    }\n  | {\n      ok: false;\n      error: string;\n    };\n\nexport function createDesktopPetTool(): AgentToolWithMetadata<typeof DesktopPetCreateSchema, DesktopPetCreateDetails> {\n  return {\n    name: 'create_desktop_pet',\n    label: 'Create Pet',\n    description:\n      'Create or update a custom animated desktop pet from a natural-language description. Packages are written under ~/.xopc/pets and can be selected in Settings > Pet. Use mode=update with petId when iterating on an existing custom pet.',\n    parameters: DesktopPetCreateSchema,\n    mutatesWorkspace: false,\n    mutationScope: 'external',\n    supportsParallel: false,\n    idempotent: false,\n    requiresExclusiveWorkspaceLock: false,\n    finalGuardRelevant: false,\n    async execute(\n      _toolCallId: string,\n      params: Record<string, unknown>,\n    ): Promise<AgentToolResult<DesktopPetCreateDetails>> {\n      const prompt = typeof params.prompt === 'string' ? params.prompt.trim() : '';\n      if (!prompt) {\n        return {\n          content: [{ type: 'text', text: 'prompt is required.' }],\n          details: { ok: false, error: 'prompt is required' },\n        };\n      }\n      const mode = params.mode === 'update' ? 'update' : 'create';\n      const petId = typeof params.petId === 'string' ? params.petId.trim() : '';\n      if (mode === 'update' && !petId) {\n        return {\n          content: [{ type: 'text', text: 'petId is required when mode is update.' }],\n          details: { ok: false, error: 'petId is required when mode is update' },\n        };\n      }\n\n      try {\n        const result = await createDesktopPetPackage({\n          ...(mode === 'update' ? { id: petId } : {}),\n          prompt,\n          ...(typeof params.name === 'string' && params.name.trim() ? { name: params.name.trim() } : {}),\n          ...(typeof params.description === 'string' && params.description.trim()\n            ? { description: params.description.trim() }\n            : {}),\n          overwrite: mode === 'update' ? true : params.overwrite === true,\n        });\n        return {\n          content: [\n            {\n              type: 'text',\n              text: [\n                `${mode === 'update' ? 'Updated' : 'Created'} desktop pet \"${result.name}\".`,\n                `Installed at: ${result.dir}`,\n                'Open Settings > Pet, refresh if needed, and select the new custom pet.',\n              ].join('\\n'),\n            },\n          ],\n          details: { ok: true, mode, ...result },\n        };\n      } catch (e) {\n        const error = e instanceof Error ? e.message : String(e);\n        return {\n          content: [{ type: 'text', text: `Failed to create desktop pet: ${error}` }],\n          details: { ok: false, error },\n        };\n      }\n    },\n  };\n}\n"],"mappings":";;;AAMA,MAAM,yBAAyB,KAAK,OAAO;CACzC,MAAM,KAAK,SACT,KAAK,MAAM,CAAC,KAAK,QAAQ,SAAS,EAAE,KAAK,QAAQ,SAAS,CAAC,EAAE,EAC3D,aACE,4GACH,CAAC,CACH;CACD,OAAO,KAAK,SACV,KAAK,OAAO,EACV,aACE,uHACH,CAAC,CACH;CACD,QAAQ,KAAK,OAAO,EAClB,aACE,oHACH,CAAC;CACF,MAAM,KAAK,SAAS,KAAK,OAAO,EAAE,aAAa,sCAAsC,CAAC,CAAC;CACvF,aAAa,KAAK,SAAS,KAAK,OAAO,EAAE,aAAa,iDAAiD,CAAC,CAAC;CACzG,WAAW,KAAK,SACd,KAAK,QAAQ,EACX,aACE,+GACH,CAAC,CACH;CACF,CAAC;AAkBF,SAAgB,uBAAsG;AACpH,QAAO;EACL,MAAM;EACN,OAAO;EACP,aACE;EACF,YAAY;EACZ,kBAAkB;EAClB,eAAe;EACf,kBAAkB;EAClB,YAAY;EACZ,gCAAgC;EAChC,oBAAoB;EACpB,MAAM,QACJ,aACA,QACmD;GACnD,MAAM,SAAS,OAAO,OAAO,WAAW,WAAW,OAAO,OAAO,MAAM,GAAG;AAC1E,OAAI,CAAC,OACH,QAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;KAAuB,CAAC;IACxD,SAAS;KAAE,IAAI;KAAO,OAAO;KAAsB;IACpD;GAEH,MAAM,OAAO,OAAO,SAAS,WAAW,WAAW;GACnD,MAAM,QAAQ,OAAO,OAAO,UAAU,WAAW,OAAO,MAAM,MAAM,GAAG;AACvE,OAAI,SAAS,YAAY,CAAC,MACxB,QAAO;IACL,SAAS,CAAC;KAAE,MAAM;KAAQ,MAAM;KAA0C,CAAC;IAC3E,SAAS;KAAE,IAAI;KAAO,OAAO;KAAyC;IACvE;AAGH,OAAI;IACF,MAAM,SAAS,MAAM,wBAAwB;KAC3C,GAAI,SAAS,WAAW,EAAE,IAAI,OAAO,GAAG,EAAE;KAC1C;KACA,GAAI,OAAO,OAAO,SAAS,YAAY,OAAO,KAAK,MAAM,GAAG,EAAE,MAAM,OAAO,KAAK,MAAM,EAAE,GAAG,EAAE;KAC7F,GAAI,OAAO,OAAO,gBAAgB,YAAY,OAAO,YAAY,MAAM,GACnE,EAAE,aAAa,OAAO,YAAY,MAAM,EAAE,GAC1C,EAAE;KACN,WAAW,SAAS,WAAW,OAAO,OAAO,cAAc;KAC5D,CAAC;AACF,WAAO;KACL,SAAS,CACP;MACE,MAAM;MACN,MAAM;OACJ,GAAG,SAAS,WAAW,YAAY,UAAU,gBAAgB,OAAO,KAAK;OACzE,iBAAiB,OAAO;OACxB;OACD,CAAC,KAAK,KAAK;MACb,CACF;KACD,SAAS;MAAE,IAAI;MAAM;MAAM,GAAG;MAAQ;KACvC;YACM,GAAG;IACV,MAAM,QAAQ,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE;AACxD,WAAO;KACL,SAAS,CAAC;MAAE,MAAM;MAAQ,MAAM,iCAAiC;MAAS,CAAC;KAC3E,SAAS;MAAE,IAAI;MAAO;MAAO;KAC9B;;;EAGN"}

package/dist/src/agent/tools/factory.d.ts

@@ -14,6 +14,9 @@ import type { MemoryManager } from '../memory/manager.js';
 import type { SessionStore } from '../../session/store.js';
 import type { GatewayClarifyRequestFn } from './clarify-tool.js';
 import type { AutomationService } from '../../automations/index.js';
+import type { NotesService } from '../../notes/index.js';
+import type { ProjectService } from '../../projects/index.js';
+import type { WorkItemService } from '../../work-items/index.js';
 import type { WorkflowRunServiceLike } from '../../workflows/service/workflow-run-service.types.js';
 import type { SkillManager } from '../skills/skill-manager.js';
 import { type ToolExecutorConfig } from './executor.js';
@@ -42,6 +45,10 @@ export interface ToolFactoryDeps {
     };
     /** Gateway: enables the `automation` tool. */
     getAutomationService?: () => AutomationService | undefined;
+    /** Gateway: enables the `xopc_use` product-object tool. */
+    getNotesService?: () => NotesService | undefined;
+    getProjectService?: () => ProjectService | undefined;
+    getWorkItemService?: () => WorkItemService | undefined;
     /** Gateway: starts persisted workflow runs (dedicated chat session per run). */
     getWorkflowRunService?: () => WorkflowRunServiceLike | undefined;
     /** Current session skill indexing (tool gating + allowlist); used by skills_list / skill_view. */
@@ -92,5 +99,7 @@ export declare class AgentToolsFactory {
     /** Drop the tab for a session when its agent instance is removed. */
     closeBrowserPageForSession(sessionKey: string): Promise<void>;
     createCoreTools(options?: CreateCoreToolsOptions): AgentTool<any, any>[];
+    createCapabilityTools(capabilityNames: readonly string[], options?: Pick<CreateCoreToolsOptions, 'disabledTools'>): AgentTool<any, any>[];
+    getLazyCapabilityToolNames(): string[];
     createAllTools(coreOptions?: CreateCoreToolsOptions): AgentTool<any, any>[];
 }

package/dist/src/agent/tools/factory.js

@@ -33,9 +33,11 @@ import { createWorkflowTool } from "./workflow-tool.js";
 import "./execute-code-tool.js";
 import { createAutomationTool } from "./automation-tool.js";
 import { createGoalTool } from "./goal-tool.js";
+import { createXopcUseTool } from "./xopc-use-tool.js";
 import { createSkillViewTool, createSkillsListTool } from "./skills-tools.js";
 import { createSkillManageTool } from "./skill-manage-tool.js";
 import { createToolManualTool } from "./tool-manual-tool.js";
+import { createDesktopPetTool } from "./desktop-pet-tool.js";
 import { createImageTool } from "./image-tool.js";
 import { createImageGenerateTool } from "./image-generate-tool.js";
 import "./index.js";
@@ -46,6 +48,8 @@ import { wrapToolsWithProtection } from "./executor.js";
 import { mergeTtsConfigFromAppConfig } from "../../voice/tts/merge-config.js";
 import { createTextToSpeechTool } from "./tts-tool.js";
 import { createGoalEvidenceRecorder } from "./goal-evidence-recorder.js";
+import { getAgentCapabilityToolNames } from "../capabilities/registry.js";
+import "../capabilities/index.js";
 //#region src/agent/tools/factory.ts
 init_logger();
 const log = createLogger("AgentToolsFactory");
@@ -254,6 +258,14 @@ var AgentToolsFactory = class {
 				getCurrentSessionKey: () => this.deps.getCurrentContext()?.sessionKey
 			})] : [],
 			...this.deps.getAutomationService ? [createAutomationTool({ getAutomationService: this.deps.getAutomationService })] : [],
+			...this.deps.getProjectService || this.deps.getNotesService || this.deps.getWorkItemService ? [createXopcUseTool({
+				getConfig: () => this.deps.getConfig?.(),
+				getCurrentAgentId: () => options.agentId,
+				getCurrentSessionKey: () => this.deps.getCurrentContext()?.sessionKey,
+				getNotesService: this.deps.getNotesService,
+				getProjectService: this.deps.getProjectService,
+				getWorkItemService: this.deps.getWorkItemService
+			})] : [],
 			createGoalTool({ getCurrentSessionKey: () => this.deps.getCurrentContext()?.sessionKey }),
 			...browserEnabled ? [createBrowserUseTool({
 				getManager: () => this.ensureBrowserManager(),
@@ -276,6 +288,20 @@ var AgentToolsFactory = class {
 			...optionalTools
 		], disabled);
 	}
+	createCapabilityTools(capabilityNames, options) {
+		const disabled = options?.disabledTools;
+		const raw = [];
+		const toolNames = /* @__PURE__ */ new Set();
+		for (const toolName of getAgentCapabilityToolNames(capabilityNames)) {
+			if (disabled?.has(toolName) || toolNames.has(toolName)) continue;
+			toolNames.add(toolName);
+			if (toolName === "create_desktop_pet") raw.push(createDesktopPetTool());
+		}
+		return wrapToolsWithProtection(raw, this.deps.toolExecutorConfig);
+	}
+	getLazyCapabilityToolNames() {
+		return ["create_desktop_pet"];
+	}
 	createAllTools(coreOptions) {
 		const coreTools = this.createCoreTools(coreOptions);
 		const disableExtensions = coreOptions?.disabledTools?.has("extensions");