@compilr-dev/sdk 0.9.23 → 0.9.25

package/dist/index.d.ts

@@ -74,7 +74,7 @@ export { PROJECT_TYPES, getProjectTypeConfig, getEnrichedProjectTypeConfig, getP
 export type { ActionMeta, SkillMeta } from './project-types/index.js';
 export type { ProjectTypeConfig, ProjectPhase, SuggestedAgent, DocumentTemplate, } from './project-types/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
-export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
+export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, PermissionHandlerResponse, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
 export { DEFAULT_PERMISSION_RULES, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
 export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';
 export { readMCPConfigFile, writeMCPConfigFile, resolveServerEntry, loadMCPServers, saveMCPServerEntry, deleteMCPServerEntry, getServerNames, } from './mcp-config.js';

package/dist/system-prompt/modules.js

@@ -168,10 +168,11 @@ export const TOOL_USAGE_HINTS_MODULE = {
 export const PLATFORM_TOOL_HINTS_MODULE = {
     id: 'platform-tool-hints',
     name: 'Platform Tool Hints',
-    estimatedTokens: 120,
+    estimatedTokens: 200,
     conditions: { enableMetaTools: true },
     content: `## Platform Tool Hints
 
+- **CRITICAL — Filesystem vs Database**: Project documents (PRD, design, outline, analysis, plan, session-notes) and backlog items live in the **database**, not the filesystem. Use \`project_document_*\` and \`workitem_*\` tools — NEVER \`write_file\` / \`bash mkdir\` / \`edit\` for project artifacts. Source code uses filesystem tools as normal. See the "Filesystem vs Database (Hard Rule)" section below for the wrong-vs-right table.
 - **workitem_* vs todo_***: workitem_* tools manage PERSISTENT backlog items (database). todo_* tools manage ephemeral session tasks (footer display). Use workitem_claim/workitem_handoff for persistent ownership, todo_claim/todo_handoff for session tasks.
 - **project_id**: All project/workitem/document/plan tools default to the active project. Only pass project_id to target a different project.
 - **Plan status flow**: draft → approved → in_progress → completed. Any → abandoned. abandoned → draft.
@@ -206,7 +207,7 @@ Common operations:
 export const TOOL_USAGE_META_MODULE = {
     id: 'tool-usage-meta',
     name: 'Tool Usage (Meta)',
-    estimatedTokens: 250,
+    estimatedTokens: 450,
     conditions: { enableMetaTools: true },
     content: `### Specialized Tools
 
@@ -221,20 +222,44 @@ Key categories:
 - **Runners**: run_tests, run_lint
 - **Anchors**: anchor_add, anchor_list, anchor_remove
 
-### Document Storage (CRITICAL)
-
-Project documents (drafts, outlines, analyses, plans) are stored in the **database**, not the filesystem.
-- **Read**: \`project_document_get({ doc_type: "outline" })\` or \`project_document_list()\`
-- **Write (new)**: \`project_document_add({ doc_type: "outline", title: "...", content: "..." })\`
-- **Patch (update without reading)**: \`project_document_patch({ doc_type: "draft", operation: "append", content: "## New Section\\n..." })\`
-  - Operations: \`append\`, \`prepend\`, \`replace_section\` (with \`section_heading\`)
-  - Prefer patch over add when updating large documents — avoids reading the full content into context
-- Do NOT use write_file or edit for project documents — always use these database tools
-- **Software doc_types**: prd, architecture, design, notes, plan
-- **Research doc_types**: outline, literature-review, abstract, methodology, bibliography
-- **Business doc_types**: executive-summary, market-analysis, financial-model, pitch
-- **Content doc_types**: editorial-calendar, article
-- **General doc_types**: draft, review, session-notes, chapter, notes`,
+### CRITICAL: Filesystem vs Database (Hard Rule)
+
+**Project documents and project data live in the DATABASE. Source code lives in the FILESYSTEM. Never mix these.**
+
+This is a non-negotiable project standard. Using filesystem tools (\`write_file\`, \`edit\`, \`bash mkdir\`) for project artifacts is a violation that breaks the integration with the rest of the workspace (no Documents panel visibility, no agent shared context, no exports, no version tracking).
+
+**Decision heuristic — ask before writing:**
+
+1. *"Is this source code or a config file (e.g., \`src/main.ts\`, \`package.json\`, \`.env\`)?"*
+   → If YES, use filesystem tools (\`write_file\`, \`edit\`, \`bash\`).
+2. *"Is this a project artifact (PRD, design doc, draft, outline, analysis, plan, backlog item, session notes)?"*
+   → If YES, you **MUST** use the corresponding database tool (\`project_document_*\`, \`workitem_*\`). Filesystem ops for these are forbidden.
+
+**Wrong vs Right:**
+
+| Task | ❌ WRONG | ✅ RIGHT |
+|------|----------|---------|
+| Create PRD | \`bash mkdir -p .compilr/requirements\` + \`write_file ".compilr/PRD.md"\` | \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\` |
+| Read design doc | \`read_file "docs/design.md"\` | \`project_document_get({ doc_type: "design" })\` |
+| Update outline | \`edit "outline.md" ...\` | \`project_document_patch({ doc_type: "outline", operation: "append", content: "..." })\` |
+| Save session notes | \`write_file "notes.md" ...\` | \`project_document_add({ doc_type: "session-notes", ... })\` |
+| List backlog | \`read_file "backlog.csv"\` | \`workitem_query()\` |
+| Add backlog item | \`edit "backlog.md" ...\` | \`workitem_add({ ... })\` |
+
+**Operations:**
+- **Read**: \`project_document_get({ doc_type: "..." })\` or \`project_document_list()\`
+- **Write (new)**: \`project_document_add({ doc_type: "...", title: "...", content: "..." })\`
+- **Patch (update without reading)**: \`project_document_patch({ doc_type: "...", operation: "append" | "prepend" | "replace_section", content: "...", section_heading?: "..." })\`
+  - Prefer patch over add when updating large documents — avoids loading full content into context
+
+**Always query before writing.** Before adding a document or work item, run \`project_document_list()\` or \`workitem_query()\` first to check for existing entries — avoids duplicates.
+
+**doc_types by project type:**
+- **Software**: prd, architecture, design, notes, plan
+- **Research**: outline, literature-review, abstract, methodology, bibliography
+- **Business**: executive-summary, market-analysis, financial-model, pitch
+- **Content**: editorial-calendar, article
+- **General**: draft, review, session-notes, chapter, notes`,
 };
 /**
  * Token delegation module - always included

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.9.23",
+  "version": "0.9.25",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@compilr-dev/agents": "^0.5.5",
+    "@compilr-dev/agents": "^0.5.7",
     "@compilr-dev/logger": "^0.1.0",
     "ajv": "^6.14.0"
   },