@xopcai/xopc 0.0.124 → 0.0.126

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

@@ -3,6 +3,9 @@ import type { Config } from '../config/schema.js';
 import type { SessionStore } from '../session/store.js';
 import type { AutomationService } from '../automations/index.js';
 import type { ExtensionRegistryImpl as ExtensionRegistry } from '../extensions/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 { GatewayClarifyRequestFn } from './tools/clarify-tool.js';
 import type { ProgressStage } from './lifecycle/progress.js';
 import type { AgentSourceContextResolver } from './source-context/types.js';
@@ -24,6 +27,10 @@ export interface AgentServiceConfig {
         requestClarification: GatewayClarifyRequestFn;
     };
     getAutomationService?: () => AutomationService | undefined;
+    /** Gateway: exposes first-class xopc product objects for the `xopc_use` tool. */
+    getNotesService?: () => NotesService | undefined;
+    getProjectService?: () => ProjectService | undefined;
+    getWorkItemService?: () => WorkItemService | undefined;
     /**
      * Gateway: reuse the gateway `SessionManager` store so web API and agent share one index + files.
      * When omitted, `AgentService` creates its own `SessionStore` (CLI / embedded).

package/dist/src/agent/session/session-inspector.d.ts

@@ -31,10 +31,10 @@ export interface SessionInspectorOptions {
     /** Effective config snapshot accessor (honours runtime overrides). */
     getConfig: () => Config | undefined;
     /**
-     * Nominal context window the session is budgeted against. Currently derived
-     * from the active model metadata, defaulting to 128k.
+     * Nominal context window the session is budgeted against. Derived from the
+     * effective session model metadata, defaulting to 128k.
      */
-    getContextWindow: () => number;
+    getContextWindow: (sessionKey: string) => number;
 }
 export interface SessionContextUsage {
     estimatedTokens: number;
@@ -52,6 +52,8 @@ export interface SessionAgentConfigView {
 export declare class SessionInspector {
     private readonly opts;
     constructor(opts: SessionInspectorOptions);
+    private ensureEffectiveSessionModel;
+    private contextWindowForSession;
     /**
      * Manual compaction triggered by a user / API. Always forces a compaction
      * pass (`force: true` by default) and evicts the in-memory agent so the

package/dist/src/agent/session/session-inspector.js

@@ -1,6 +1,6 @@
-import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { effectiveWorkspacePathForSession, projectWorkspacePath } from "../../session/session-workspace.js";
 import { getProjectForSession } from "../../projects/workspace.js";
 import { resolveVerboseLevel } from "../../session/config-store.js";
@@ -16,6 +16,18 @@ var SessionInspector = class {
 	constructor(opts) {
 		this.opts = opts;
 	}
+	async ensureEffectiveSessionModel(sessionKey) {
+		await this.opts.sessionHydrator.model(sessionKey);
+		const cfg = this.opts.getConfig();
+		if (!cfg) return;
+		const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);
+		const profileModelRef = profile.primaryModelRef?.trim();
+		if (profileModelRef) this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef, profile.fallbacks);
+	}
+	async contextWindowForSession(sessionKey) {
+		await this.ensureEffectiveSessionModel(sessionKey);
+		return this.opts.getContextWindow(sessionKey);
+	}
 	/**
 	* Manual compaction triggered by a user / API. Always forces a compaction
 	* pass (`force: true` by default) and evicts the in-memory agent so the
@@ -23,7 +35,7 @@ var SessionInspector = class {
 	*/
 	async compact(sessionKey, options) {
 		const messages = await this.opts.sessionStore.load(sessionKey);
-		const contextWindow = this.opts.getContextWindow();
+		const contextWindow = await this.contextWindowForSession(sessionKey);
 		const result = await this.opts.sessionStore.compact(sessionKey, messages, contextWindow, options?.instructions, options?.force ?? true);
 		if (result.compacted) this.opts.agentManager.removeAgent(sessionKey);
 		log.info({
@@ -53,7 +65,7 @@ var SessionInspector = class {
 	/** Rough context usage for TUI footer (estimated tokens vs nominal budget). */
 	async contextUsage(sessionKey) {
 		const messages = await this.opts.sessionStore.load(sessionKey);
-		const contextWindow = this.opts.getContextWindow();
+		const contextWindow = await this.contextWindowForSession(sessionKey);
 		const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);
 		return {
 			estimatedTokens,
@@ -66,7 +78,7 @@ var SessionInspector = class {
 		const cfg = this.opts.getConfig();
 		if (!cfg) throw new Error("SessionInspector requires a config snapshot to render report");
 		const messages = await this.opts.sessionStore.load(sessionKey);
-		const cw = this.opts.getContextWindow();
+		const cw = await this.contextWindowForSession(sessionKey);
 		const computed = this.stats(sessionKey, messages);
 		const model = this.opts.modelManager.getModelForSession(sessionKey);
 		const workspace = effectiveWorkspacePathForSession(cfg, sessionKey, await this.opts.sessionConfigStore.get(sessionKey), getProjectForSession(sessionKey));
@@ -94,13 +106,10 @@ var SessionInspector = class {
 	}
 	/** Resolved thinking / model / workspace for the Web UI. */
 	async agentConfig(sessionKey) {
-		await this.opts.sessionHydrator.model(sessionKey);
+		await this.ensureEffectiveSessionModel(sessionKey);
 		const cfg = this.opts.getConfig();
 		if (!cfg) throw new Error("SessionInspector requires a config snapshot to resolve agent config");
 		const sc = await this.opts.sessionConfigStore.get(sessionKey);
-		const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);
-		const profileModelRef = profile.primaryModelRef?.trim();
-		if (profileModelRef) this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef, profile.fallbacks);
 		const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, null, "medium");
 		const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, sessionKey, "stream");
 		const verboseLevel = await resolveVerboseLevel(this.opts.sessionConfigStore, sessionKey, "full");

package/dist/src/agent/session/session-inspector.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-inspector.js","names":[],"sources":["../../../../src/agent/session/session-inspector.ts"],"sourcesContent":["/**\n * SessionInspector — read-only / introspection-oriented operations on a session.\n *\n * Owns the five methods previously scattered across `AgentService` that all\n * compute a \"summary view\" of one session:\n *   - `compact` (manual user-triggered compaction)\n *   - `btwQuery` (one-shot LLM answer with transcript as background)\n *   - `report` (Markdown / JSON `/context` summary)\n *   - `agentConfig` (resolved thinking + model + workspace for the Web UI)\n *   - `contextUsage` (rough token budget vs estimated transcript)\n *\n * The shared helper `computeStats` keeps the three callsites that need\n * `getWindowStats` / `getCompactionStats` / `estimateTokenUsage` in lockstep.\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\nimport type { ThinkingLevel } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveEffectiveAgentProfileForSession } from '../../config/agent-profile.js';\nimport {\n  effectiveWorkspacePathForSession,\n  projectWorkspacePath,\n  resolveEffectiveReasoningLevel,\n  resolveEffectiveThinkingLevel,\n  resolveVerboseLevel,\n  type SessionConfigStore,\n} from '../../session/index.js';\nimport { getProjectForSession } from '../../projects/workspace.js';\nimport type { SessionStore } from '../../session/store.js';\nimport type { CompactionResult } from '../memory/compaction.js';\nimport type { ModelManager } from '../models/index.js';\nimport type { AgentInstanceGateway } from '../agent-instance-gateway.js';\nimport { runBtwQuery } from '../service/btw-query.js';\nimport { formatSessionContextReport } from '../service/session-context-report.js';\nimport type { ReasoningLevel, VerboseLevel } from '../transcript/thinking-types.js';\nimport { createLogger } from '../../utils/logger.js';\nimport type { SessionHydrator } from './session-hydrator.js';\n\nconst log = createLogger('SessionInspector');\n\nexport interface SessionInspectorOptions {\n  sessionStore: SessionStore;\n  sessionConfigStore: SessionConfigStore;\n  modelManager: ModelManager;\n  agentManager: AgentInstanceGateway;\n  sessionHydrator: SessionHydrator;\n  /** Effective config snapshot accessor (honours runtime overrides). */\n  getConfig: () => Config | undefined;\n  /**\n   * Nominal context window the session is budgeted against. Currently derived\n   * from the active model metadata, defaulting to 128k.\n   */\n  getContextWindow: () => number;\n}\n\nexport interface SessionContextUsage {\n  estimatedTokens: number;\n  contextWindow: number;\n  usagePercent: number | null;\n}\n\nexport interface SessionAgentConfigView {\n  thinkingLevel: ThinkingLevel;\n  model: string;\n  reasoningLevel: ReasoningLevel;\n  verboseLevel: VerboseLevel;\n  effectiveWorkspacePath: string;\n  workingDirectoryLocked: boolean;\n}\n\nexport class SessionInspector {\n  private readonly opts: SessionInspectorOptions;\n\n  constructor(opts: SessionInspectorOptions) {\n    this.opts = opts;\n  }\n\n  /**\n   * Manual compaction triggered by a user / API. Always forces a compaction\n   * pass (`force: true` by default) and evicts the in-memory agent so the\n   * next turn reloads from the compacted transcript.\n   */\n  async compact(\n    sessionKey: string,\n    options?: { instructions?: string; force?: boolean },\n  ): Promise<CompactionResult> {\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const contextWindow = this.opts.getContextWindow();\n    const result = await this.opts.sessionStore.compact(\n      sessionKey,\n      messages,\n      contextWindow,\n      options?.instructions,\n      options?.force ?? true,\n    );\n    if (result.compacted) {\n      this.opts.agentManager.removeAgent(sessionKey);\n    }\n    log.info({ sessionKey, result }, 'Manual compaction complete');\n    return result;\n  }\n\n  /** One-shot LLM answer for `/btw`: transcript as background, not persisted. */\n  btwQuery(sessionKey: string, question: string): Promise<{ text: string; error?: string }> {\n    return runBtwQuery({\n      sessionKey,\n      question,\n      sessionStore: this.opts.sessionStore,\n      modelForSession: this.opts.modelManager.getModelForSession(sessionKey),\n      log,\n    });\n  }\n\n  /** Cheap stats used by both the report and other callers. */\n  stats(sessionKey: string, messages: AgentMessage[]): {\n    windowStats: ReturnType<SessionStore['getWindowStats']>;\n    compactionStats: ReturnType<SessionStore['getCompactionStats']>;\n    tokenEstimate: ReturnType<SessionStore['estimateTokenUsage']>;\n  } {\n    return {\n      windowStats: this.opts.sessionStore.getWindowStats(messages),\n      compactionStats: this.opts.sessionStore.getCompactionStats(sessionKey),\n      tokenEstimate: this.opts.sessionStore.estimateTokenUsage(sessionKey, messages),\n    };\n  }\n\n  /** Rough context usage for TUI footer (estimated tokens vs nominal budget). */\n  async contextUsage(sessionKey: string): Promise<SessionContextUsage> {\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const contextWindow = this.opts.getContextWindow();\n    const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);\n    const usagePercent =\n      contextWindow > 0 ? Math.min(100, Math.round((estimatedTokens / contextWindow) * 100)) : null;\n    return { estimatedTokens, contextWindow, usagePercent };\n  }\n\n  /** Markdown or JSON summary for `/context`. */\n  async report(sessionKey: string, mode: 'list' | 'detail' | 'json'): Promise<string> {\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      throw new Error('SessionInspector requires a config snapshot to render report');\n    }\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const cw = this.opts.getContextWindow();\n    const computed = this.stats(sessionKey, messages);\n    const model = this.opts.modelManager.getModelForSession(sessionKey);\n    const sc = await this.opts.sessionConfigStore.get(sessionKey);\n    const project = getProjectForSession(sessionKey);\n    const workspace = effectiveWorkspacePathForSession(cfg, sessionKey, sc, project);\n    const estTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);\n    const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);\n    const deniedTools = [...profile.tools.denied].sort((a, b) => a.localeCompare(b));\n    const toolsSummary = deniedTools.length > 0 ? `denied: ${deniedTools.join(', ')}` : '(no denied tools)';\n\n    return formatSessionContextReport({\n      sessionKey,\n      mode,\n      model,\n      workspacePath: workspace,\n      agentId: profile.agentId,\n      messageCount: messages.length,\n      contextWindowNominal: cw,\n      estimatedTranscriptTokens: estTokens,\n      thinkingDefault: undefined,\n      reasoningDefault: undefined,\n      verboseDefault: undefined,\n      compaction: undefined,\n      toolsFlagsSummary: toolsSummary,\n      windowStats: computed.windowStats,\n      compactionRunStats: computed.compactionStats,\n    });\n  }\n\n  /** Resolved thinking / model / workspace for the Web UI. */\n  async agentConfig(sessionKey: string): Promise<SessionAgentConfigView> {\n    await this.opts.sessionHydrator.model(sessionKey);\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      throw new Error('SessionInspector requires a config snapshot to resolve agent config');\n    }\n    const sc = await this.opts.sessionConfigStore.get(sessionKey);\n\n    // Ensure model display matches the effective agent profile even before an Agent instance exists.\n    // Otherwise `ModelManager.getModelForSession()` falls back to the global default until the first turn creates the agent.\n    const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);\n    const profileModelRef = profile.primaryModelRef?.trim();\n    if (profileModelRef) {\n      this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef, profile.fallbacks);\n    }\n\n    const defThink = 'medium';\n    const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, null, defThink);\n    const defReason = 'stream' as ReasoningLevel;\n    const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, sessionKey, defReason);\n    const defVerbose = 'full' as VerboseLevel;\n    const verboseLevel = await resolveVerboseLevel(this.opts.sessionConfigStore, sessionKey, defVerbose);\n    const model = this.opts.modelManager.getModelForSession(sessionKey);\n    const project = getProjectForSession(sessionKey);\n    const projectWorkspace = projectWorkspacePath(project);\n    return {\n      thinkingLevel: level,\n      model,\n      reasoningLevel,\n      verboseLevel,\n      effectiveWorkspacePath: effectiveWorkspacePathForSession(cfg, sessionKey, sc, project),\n      workingDirectoryLocked: Boolean(projectWorkspace || sc?.workingDirectoryOverride?.trim()),\n    };\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"session-inspector.js","names":[],"sources":["../../../../src/agent/session/session-inspector.ts"],"sourcesContent":["/**\n * SessionInspector — read-only / introspection-oriented operations on a session.\n *\n * Owns the five methods previously scattered across `AgentService` that all\n * compute a \"summary view\" of one session:\n *   - `compact` (manual user-triggered compaction)\n *   - `btwQuery` (one-shot LLM answer with transcript as background)\n *   - `report` (Markdown / JSON `/context` summary)\n *   - `agentConfig` (resolved thinking + model + workspace for the Web UI)\n *   - `contextUsage` (rough token budget vs estimated transcript)\n *\n * The shared helper `computeStats` keeps the three callsites that need\n * `getWindowStats` / `getCompactionStats` / `estimateTokenUsage` in lockstep.\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\nimport type { ThinkingLevel } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveEffectiveAgentProfileForSession } from '../../config/agent-profile.js';\nimport {\n  effectiveWorkspacePathForSession,\n  projectWorkspacePath,\n  resolveEffectiveReasoningLevel,\n  resolveEffectiveThinkingLevel,\n  resolveVerboseLevel,\n  type SessionConfigStore,\n} from '../../session/index.js';\nimport { getProjectForSession } from '../../projects/workspace.js';\nimport type { SessionStore } from '../../session/store.js';\nimport type { CompactionResult } from '../memory/compaction.js';\nimport type { ModelManager } from '../models/index.js';\nimport type { AgentInstanceGateway } from '../agent-instance-gateway.js';\nimport { runBtwQuery } from '../service/btw-query.js';\nimport { formatSessionContextReport } from '../service/session-context-report.js';\nimport type { ReasoningLevel, VerboseLevel } from '../transcript/thinking-types.js';\nimport { createLogger } from '../../utils/logger.js';\nimport type { SessionHydrator } from './session-hydrator.js';\n\nconst log = createLogger('SessionInspector');\n\nexport interface SessionInspectorOptions {\n  sessionStore: SessionStore;\n  sessionConfigStore: SessionConfigStore;\n  modelManager: ModelManager;\n  agentManager: AgentInstanceGateway;\n  sessionHydrator: SessionHydrator;\n  /** Effective config snapshot accessor (honours runtime overrides). */\n  getConfig: () => Config | undefined;\n  /**\n   * Nominal context window the session is budgeted against. Derived from the\n   * effective session model metadata, defaulting to 128k.\n   */\n  getContextWindow: (sessionKey: string) => number;\n}\n\nexport interface SessionContextUsage {\n  estimatedTokens: number;\n  contextWindow: number;\n  usagePercent: number | null;\n}\n\nexport interface SessionAgentConfigView {\n  thinkingLevel: ThinkingLevel;\n  model: string;\n  reasoningLevel: ReasoningLevel;\n  verboseLevel: VerboseLevel;\n  effectiveWorkspacePath: string;\n  workingDirectoryLocked: boolean;\n}\n\nexport class SessionInspector {\n  private readonly opts: SessionInspectorOptions;\n\n  constructor(opts: SessionInspectorOptions) {\n    this.opts = opts;\n  }\n\n  private async ensureEffectiveSessionModel(sessionKey: string): Promise<void> {\n    await this.opts.sessionHydrator.model(sessionKey);\n    const cfg = this.opts.getConfig();\n    if (!cfg) return;\n\n    const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);\n    const profileModelRef = profile.primaryModelRef?.trim();\n    if (profileModelRef) {\n      this.opts.modelManager.setSessionProfileDefault(sessionKey, profileModelRef, profile.fallbacks);\n    }\n  }\n\n  private async contextWindowForSession(sessionKey: string): Promise<number> {\n    await this.ensureEffectiveSessionModel(sessionKey);\n    return this.opts.getContextWindow(sessionKey);\n  }\n\n  /**\n   * Manual compaction triggered by a user / API. Always forces a compaction\n   * pass (`force: true` by default) and evicts the in-memory agent so the\n   * next turn reloads from the compacted transcript.\n   */\n  async compact(\n    sessionKey: string,\n    options?: { instructions?: string; force?: boolean },\n  ): Promise<CompactionResult> {\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const contextWindow = await this.contextWindowForSession(sessionKey);\n    const result = await this.opts.sessionStore.compact(\n      sessionKey,\n      messages,\n      contextWindow,\n      options?.instructions,\n      options?.force ?? true,\n    );\n    if (result.compacted) {\n      this.opts.agentManager.removeAgent(sessionKey);\n    }\n    log.info({ sessionKey, result }, 'Manual compaction complete');\n    return result;\n  }\n\n  /** One-shot LLM answer for `/btw`: transcript as background, not persisted. */\n  btwQuery(sessionKey: string, question: string): Promise<{ text: string; error?: string }> {\n    return runBtwQuery({\n      sessionKey,\n      question,\n      sessionStore: this.opts.sessionStore,\n      modelForSession: this.opts.modelManager.getModelForSession(sessionKey),\n      log,\n    });\n  }\n\n  /** Cheap stats used by both the report and other callers. */\n  stats(sessionKey: string, messages: AgentMessage[]): {\n    windowStats: ReturnType<SessionStore['getWindowStats']>;\n    compactionStats: ReturnType<SessionStore['getCompactionStats']>;\n    tokenEstimate: ReturnType<SessionStore['estimateTokenUsage']>;\n  } {\n    return {\n      windowStats: this.opts.sessionStore.getWindowStats(messages),\n      compactionStats: this.opts.sessionStore.getCompactionStats(sessionKey),\n      tokenEstimate: this.opts.sessionStore.estimateTokenUsage(sessionKey, messages),\n    };\n  }\n\n  /** Rough context usage for TUI footer (estimated tokens vs nominal budget). */\n  async contextUsage(sessionKey: string): Promise<SessionContextUsage> {\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const contextWindow = await this.contextWindowForSession(sessionKey);\n    const estimatedTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);\n    const usagePercent =\n      contextWindow > 0 ? Math.min(100, Math.round((estimatedTokens / contextWindow) * 100)) : null;\n    return { estimatedTokens, contextWindow, usagePercent };\n  }\n\n  /** Markdown or JSON summary for `/context`. */\n  async report(sessionKey: string, mode: 'list' | 'detail' | 'json'): Promise<string> {\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      throw new Error('SessionInspector requires a config snapshot to render report');\n    }\n    const messages = await this.opts.sessionStore.load(sessionKey);\n    const cw = await this.contextWindowForSession(sessionKey);\n    const computed = this.stats(sessionKey, messages);\n    const model = this.opts.modelManager.getModelForSession(sessionKey);\n    const sc = await this.opts.sessionConfigStore.get(sessionKey);\n    const project = getProjectForSession(sessionKey);\n    const workspace = effectiveWorkspacePathForSession(cfg, sessionKey, sc, project);\n    const estTokens = await this.opts.sessionStore.estimateTokenUsage(sessionKey, messages);\n    const profile = resolveEffectiveAgentProfileForSession(cfg, sessionKey);\n    const deniedTools = [...profile.tools.denied].sort((a, b) => a.localeCompare(b));\n    const toolsSummary = deniedTools.length > 0 ? `denied: ${deniedTools.join(', ')}` : '(no denied tools)';\n\n    return formatSessionContextReport({\n      sessionKey,\n      mode,\n      model,\n      workspacePath: workspace,\n      agentId: profile.agentId,\n      messageCount: messages.length,\n      contextWindowNominal: cw,\n      estimatedTranscriptTokens: estTokens,\n      thinkingDefault: undefined,\n      reasoningDefault: undefined,\n      verboseDefault: undefined,\n      compaction: undefined,\n      toolsFlagsSummary: toolsSummary,\n      windowStats: computed.windowStats,\n      compactionRunStats: computed.compactionStats,\n    });\n  }\n\n  /** Resolved thinking / model / workspace for the Web UI. */\n  async agentConfig(sessionKey: string): Promise<SessionAgentConfigView> {\n    await this.ensureEffectiveSessionModel(sessionKey);\n    const cfg = this.opts.getConfig();\n    if (!cfg) {\n      throw new Error('SessionInspector requires a config snapshot to resolve agent config');\n    }\n    const sc = await this.opts.sessionConfigStore.get(sessionKey);\n\n    const defThink = 'medium';\n    const level = await resolveEffectiveThinkingLevel(this.opts.sessionConfigStore, sessionKey, null, defThink);\n    const defReason = 'stream' as ReasoningLevel;\n    const reasoningLevel = await resolveEffectiveReasoningLevel(this.opts.sessionConfigStore, sessionKey, defReason);\n    const defVerbose = 'full' as VerboseLevel;\n    const verboseLevel = await resolveVerboseLevel(this.opts.sessionConfigStore, sessionKey, defVerbose);\n    const model = this.opts.modelManager.getModelForSession(sessionKey);\n    const project = getProjectForSession(sessionKey);\n    const projectWorkspace = projectWorkspacePath(project);\n    return {\n      thinkingLevel: level,\n      model,\n      reasoningLevel,\n      verboseLevel,\n      effectiveWorkspacePath: effectiveWorkspacePathForSession(cfg, sessionKey, sc, project),\n      workingDirectoryLocked: Boolean(projectWorkspace || sc?.workingDirectoryOverride?.trim()),\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/src/agent/skills/hub-pull.js

@@ -6,8 +6,8 @@ import { computeSkillTreeHashSync } from "./hub-hash.js";
 import { tmpdir } from "node:os";
 import { basename, join, normalize, resolve } from "node:path";
 import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
 import { fetch } from "undici";
 //#region src/agent/skills/hub-pull.ts
 /**

package/dist/src/agent/source-context/types.d.ts

@@ -1,6 +1,6 @@
 import type { ImageContent } from '@earendil-works/pi-ai';
 export interface SessionSourceBinding {
-    kind: 'note';
+    kind: 'note' | 'work_item';
     sourceId: string;
     version: string;
     attachedAt: number;

package/dist/src/agent/source-context/types.js

@@ -2,7 +2,7 @@
 function isSessionSourceBinding(value) {
 	if (!value || typeof value !== "object") return false;
 	const row = value;
-	return row.kind === "note" && typeof row.sourceId === "string" && row.sourceId.trim().length > 0 && typeof row.version === "string" && typeof row.attachedAt === "number";
+	return (row.kind === "note" || row.kind === "work_item") && typeof row.sourceId === "string" && row.sourceId.trim().length > 0 && typeof row.version === "string" && typeof row.attachedAt === "number";
 }
 //#endregion
 export { isSessionSourceBinding };

package/dist/src/agent/source-context/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":[],"sources":["../../../../src/agent/source-context/types.ts"],"sourcesContent":["import type { ImageContent } from '@earendil-works/pi-ai';\n\nexport interface SessionSourceBinding {\n  kind: 'note';\n  sourceId: string;\n  version: string;\n  attachedAt: number;\n}\n\nexport interface AgentSourceContext {\n  kind: SessionSourceBinding['kind'];\n  sourceId: string;\n  version: string;\n  title: string;\n  text: string;\n  images?: ImageContent[];\n  tokenEstimate?: number;\n  truncated?: boolean;\n}\n\nexport type AgentSourceContextResolver = (\n  binding: SessionSourceBinding,\n  sessionKey: string,\n) => Promise<AgentSourceContext | null>;\n\nexport function isSessionSourceBinding(value: unknown): value is SessionSourceBinding {\n  if (!value || typeof value !== 'object') return false;\n  const row = value as Record<string, unknown>;\n  return row.kind === 'note'\n    && typeof row.sourceId === 'string'\n    && row.sourceId.trim().length > 0\n    && typeof row.version === 'string'\n    && typeof row.attachedAt === 'number';\n}\n"],"mappings":";AAyBA,SAAgB,uBAAuB,OAA+C;AACpF,KAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;CAChD,MAAM,MAAM;AACZ,QAAO,IAAI,SAAS,UACf,OAAO,IAAI,aAAa,YACxB,IAAI,SAAS,MAAM,CAAC,SAAS,KAC7B,OAAO,IAAI,YAAY,YACvB,OAAO,IAAI,eAAe"}
+{"version":3,"file":"types.js","names":[],"sources":["../../../../src/agent/source-context/types.ts"],"sourcesContent":["import type { ImageContent } from '@earendil-works/pi-ai';\n\nexport interface SessionSourceBinding {\n  kind: 'note' | 'work_item';\n  sourceId: string;\n  version: string;\n  attachedAt: number;\n}\n\nexport interface AgentSourceContext {\n  kind: SessionSourceBinding['kind'];\n  sourceId: string;\n  version: string;\n  title: string;\n  text: string;\n  images?: ImageContent[];\n  tokenEstimate?: number;\n  truncated?: boolean;\n}\n\nexport type AgentSourceContextResolver = (\n  binding: SessionSourceBinding,\n  sessionKey: string,\n) => Promise<AgentSourceContext | null>;\n\nexport function isSessionSourceBinding(value: unknown): value is SessionSourceBinding {\n  if (!value || typeof value !== 'object') return false;\n  const row = value as Record<string, unknown>;\n  return (row.kind === 'note' || row.kind === 'work_item')\n    && typeof row.sourceId === 'string'\n    && row.sourceId.trim().length > 0\n    && typeof row.version === 'string'\n    && typeof row.attachedAt === 'number';\n}\n"],"mappings":";AAyBA,SAAgB,uBAAuB,OAA+C;AACpF,KAAI,CAAC,SAAS,OAAO,UAAU,SAAU,QAAO;CAChD,MAAM,MAAM;AACZ,SAAQ,IAAI,SAAS,UAAU,IAAI,SAAS,gBACvC,OAAO,IAAI,aAAa,YACxB,IAAI,SAAS,MAAM,CAAC,SAAS,KAC7B,OAAO,IAAI,YAAY,YACvB,OAAO,IAAI,eAAe"}

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"}