chapterhouse 0.3.26 → 0.4.1

package/dist/copilot/tools.js

@@ -7,7 +7,7 @@ import { homedir } from "os";
 import { listSkills, createSkill, removeSkill } from "./skills.js";
 import { config, persistModel } from "../config.js";
 import { agentEventBus } from "./agent-event-bus.js";
-import { getCurrentSourceChannel, getCurrentActivityCallback, getCurrentActiveProjectRules, getCurrentAuthenticatedUser, getLastAuthenticatedUser, getCurrentAuthorizationHeader, getCurrentSessionKey, switchSessionModel, } from "./orchestrator.js";
+import { getCurrentSourceChannel, getCurrentActivityCallback, getCurrentActiveProjectRules, getCurrentAuthenticatedUser, getLastAuthenticatedUser, getCurrentAuthorizationHeader, getCurrentSessionKey, invalidateOrchestratorSession, maybeScheduleScopeChangeCheckpoint, resetCheckpointSessionState, switchSessionModel, } from "./orchestrator.js";
 import { getRouterConfig, updateRouterConfig } from "./router.js";
 import { ensureWikiStructure, readPage, writePage, deletePage, writeRawSource, assertPagePath } from "../wiki/fs.js";
 import { searchIndex, addToIndex, removeFromIndex, buildIndexEntryForPage } from "../wiki/index-manager.js";
@@ -20,7 +20,8 @@ import { loadTaxonomy } from "../wiki/taxonomy.js";
 import { getCategoryDir, topicPagePath, slugify, entityCategories, FLAT_CATEGORIES } from "../wiki/topic-structure.js";
 import { withWikiWrite } from "../wiki/lock.js";
 import { readWikiPage, teamWikiSync } from "../wiki/team-sync.js";
-import { getAgentRegistry, getAgent, createEphemeralAgentSession, getAgentSessionStatus, getTask, registerTask, completeTask, failTask, createAgentFile, removeAgentFile, loadAgents, } from "./agents.js";
+import { getAgentRegistry, getAgent, createEphemeralAgentSession, getAgentSessionStatus, getTask, registerTask, completeTask, failTask, createTaskId, createAgentFile, removeAgentFile, loadAgents, } from "./agents.js";
+import * as agentsModule from "./agents.js";
 import { detectProjectRuleWarnings } from "./project-rule-warnings.js";
 import { renderDelegatedProjectRulesPreamble } from "./project-rules-injection.js";
 import { adoGetOkrs, adoOkrSummary, adoUpdateKr } from "../integrations/ado-skill.js";
@@ -28,6 +29,7 @@ import { TeamsNotifier } from "../integrations/teams-notify.js";
 import { TeamPushClient } from "../integrations/team-push.js";
 import { OKRMapper, parseOKRPageContent } from "./okr-mapper.js";
 import { childLogger } from "../util/logger.js";
+import { getActiveScope as getMemoryActiveScope, getScope as getMemoryScope, inferScopeFromText, demoteToCold, demoteToWarm, queueMemoryProposal, recall as recallMemory, recordDecision, recordObservation, runHousekeeping, setActiveScope as setMemoryActiveScope, promoteToHot, upsertEntity, } from "../memory/index.js";
 const log = childLogger("tools");
 /** Escape a string for safe inclusion as a single-line YAML scalar value. */
 function yamlEscape(value) {
@@ -56,6 +58,81 @@ function isTimeoutError(err) {
 function hasAdoPat() {
     return (process.env.ADO_PAT?.trim() || config.adoPat).length > 0;
 }
+function requireOrchestratorMemoryWrite() {
+    const agentSlug = agentsModule.getCurrentToolAgentSlug?.();
+    if (agentSlug && agentSlug !== "chapterhouse") {
+        return "Memory writes are orchestrator-only. Use memory_propose instead.";
+    }
+    return null;
+}
+function resolveMemoryScopeForWrite(explicitScope, content) {
+    const explicit = explicitScope ? getMemoryScope(explicitScope) : undefined;
+    if (explicitScope && !explicit) {
+        throw new Error(`Unknown memory scope '${explicitScope}'.`);
+    }
+    if (explicit) {
+        return { scopeId: explicit.id, scopeSlug: explicit.slug };
+    }
+    const active = getMemoryActiveScope();
+    if (active) {
+        return { scopeId: active.id, scopeSlug: active.slug };
+    }
+    const inferred = inferScopeFromText(content);
+    if (inferred) {
+        const inferredScope = getMemoryScope(inferred.scope_id);
+        if (inferredScope) {
+            return { scopeId: inferredScope.id, scopeSlug: inferredScope.slug };
+        }
+    }
+    const validScopes = getDb().prepare(`
+    SELECT slug
+    FROM mem_scopes
+    WHERE active = 1
+    ORDER BY slug
+  `).all();
+    const activeScope = getMemoryActiveScope()?.slug ?? "none";
+    throw new Error(`No scope inferred. Active scope: ${activeScope}. Valid scopes: [${validScopes.map((row) => row.slug).join(", ")}]. `
+        + "Set active scope with memory_set_scope or pass scope explicitly.");
+}
+const observationProposalPayloadSchema = z.object({
+    content: z.string(),
+    entity_id: z.number().int().positive().optional(),
+    source: z.string().optional(),
+});
+const decisionProposalPayloadSchema = z.object({
+    title: z.string(),
+    rationale: z.string().optional(),
+    decided_at: z.string().optional(),
+});
+const entityProposalPayloadSchema = z.object({
+    name: z.string(),
+    kind: z.string(),
+    summary: z.string().optional(),
+});
+const memoryProposeArgsSchema = z.object({
+    kind: z.enum(["observation", "decision", "entity"]),
+    scope_slug: z.string().optional(),
+    payload: z.record(z.string(), z.unknown()),
+    confidence: z.number().min(0).max(1).optional(),
+    reason: z.string().optional(),
+}).superRefine((value, context) => {
+    const schema = value.kind === "observation"
+        ? observationProposalPayloadSchema
+        : value.kind === "decision"
+            ? decisionProposalPayloadSchema
+            : entityProposalPayloadSchema;
+    const parsed = schema.safeParse(value.payload);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: issue.message,
+                path: ["payload", ...issue.path],
+            });
+        }
+    }
+});
+const memoryTierTableSchema = z.enum(["observation", "decision", "entity"]);
 function getCurrentQuarter(now = new Date()) {
     return `${now.getUTCFullYear()}-Q${Math.floor(now.getUTCMonth() / 3) + 1}`;
 }
@@ -110,16 +187,17 @@ export function createTools(deps) {
                     return `Agent '${args.agent_name}' not found. Available agents: ${available}`;
                 }
                 const delegatedSlug = agent.slug;
+                const taskId = createTaskId();
                 let session;
                 try {
                     const allTools = createTools(deps);
-                    session = await createEphemeralAgentSession(agent.slug, deps.client, allTools, args.model_override);
+                    session = await createEphemeralAgentSession(agent.slug, deps.client, allTools, args.model_override, undefined, taskId);
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     return `Failed to create session for @${delegatedSlug}: ${msg}`;
                 }
-                const task = registerTask(delegatedSlug, args.summary, getCurrentSourceChannel());
+                const task = registerTask(delegatedSlug, args.summary, getCurrentSourceChannel(), taskId);
                 const activeProjectRules = getCurrentActiveProjectRules();
                 const warningLines = activeProjectRules
                     ? detectProjectRuleWarnings(args.task, activeProjectRules.rules.hard)
@@ -689,6 +767,275 @@ export function createTools(deps) {
                 return `Auto-routing disabled. Using fixed model: ${config.copilotModel}`;
             },
         }),
+        defineTool("memory_remember", {
+            description: "Write scoped agent memory (observation or decision) into the SQLite memory store. " +
+                "Use this for the new agent-memory system, not the legacy wiki-backed remember tool.",
+            parameters: z.object({
+                content: z.string().describe("Observation content or decision rationale."),
+                scope: z.string().optional().describe("Optional memory scope slug. Defaults to active scope, then keyword inference."),
+                kind: z.enum(["observation", "decision"]).optional().describe("Memory entry kind. Defaults to observation."),
+                entity_name: z.string().optional().describe("Optional entity name to attach. Auto-upserts the entity if provided."),
+                entity_kind: z.string().optional().describe("Required when entity_name is provided."),
+                title: z.string().optional().describe("Required for decision entries."),
+                decided_at: z.string().optional().describe("Decision date. Defaults to today."),
+                tier: z.enum(["hot", "warm", "cold"]).optional().describe("Storage tier. Defaults to warm."),
+            }),
+            handler: async (args) => {
+                const denied = requireOrchestratorMemoryWrite();
+                if (denied)
+                    return denied;
+                if (args.entity_name && !args.entity_kind) {
+                    return "entity_kind is required when entity_name is provided.";
+                }
+                try {
+                    const { scopeId, scopeSlug } = resolveMemoryScopeForWrite(args.scope, args.content);
+                    const kind = args.kind ?? "observation";
+                    const entity = args.entity_name
+                        ? upsertEntity({
+                            scope_id: scopeId,
+                            kind: args.entity_kind,
+                            name: args.entity_name,
+                            tier: args.tier ?? "warm",
+                        })
+                        : undefined;
+                    if (kind === "decision") {
+                        if (!args.title) {
+                            return "title is required when kind='decision'.";
+                        }
+                        const decision = recordDecision({
+                            scope_id: scopeId,
+                            entity_id: entity?.id,
+                            title: args.title,
+                            rationale: args.content,
+                            decided_at: args.decided_at ?? new Date().toISOString().slice(0, 10),
+                            tier: args.tier ?? "warm",
+                        });
+                        return {
+                            ok: true,
+                            id: decision.id,
+                            scope: scopeSlug,
+                            kind,
+                            entity_id: entity?.id,
+                        };
+                    }
+                    const observation = recordObservation({
+                        scope_id: scopeId,
+                        entity_id: entity?.id,
+                        content: args.content,
+                        source: `agent:${agentsModule.getCurrentToolAgentSlug?.() ?? "chapterhouse"}`,
+                        tier: args.tier ?? "warm",
+                    });
+                    return {
+                        ok: true,
+                        id: observation.id,
+                        scope: scopeSlug,
+                        kind,
+                        entity_id: entity?.id,
+                    };
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
+        defineTool("memory_propose", {
+            description: "Queue a proposed scoped memory item for orchestrator review at end-of-task. " +
+                "Available to all agents; writes land in mem_inbox as pending proposals.",
+            parameters: memoryProposeArgsSchema,
+            handler: async (args) => {
+                try {
+                    const parsedArgs = memoryProposeArgsSchema.parse(args);
+                    const payload = parsedArgs.kind === "observation"
+                        ? observationProposalPayloadSchema.parse(parsedArgs.payload)
+                        : parsedArgs.kind === "decision"
+                            ? decisionProposalPayloadSchema.parse(parsedArgs.payload)
+                            : entityProposalPayloadSchema.parse(parsedArgs.payload);
+                    const proposal = queueMemoryProposal({
+                        kind: parsedArgs.kind,
+                        scopeSlug: parsedArgs.scope_slug,
+                        payload,
+                        confidence: parsedArgs.confidence ?? 0.5,
+                        reason: parsedArgs.reason,
+                        sourceAgent: agentsModule.getCurrentToolAgentSlug?.() ?? "chapterhouse",
+                        sourceTaskId: agentsModule.getCurrentToolTaskId?.(),
+                    });
+                    return {
+                        proposal_id: proposal.id,
+                        status: "queued",
+                    };
+                }
+                catch (err) {
+                    if (err instanceof z.ZodError) {
+                        return err.issues.map((issue) => issue.message).join("; ");
+                    }
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
+        defineTool("memory_recall", {
+            description: "Search scoped agent memory with FTS-backed recall. Use this for the new agent-memory store, not the wiki-backed recall tool.",
+            parameters: z.object({
+                query: z.string().describe("Query text to search for."),
+                scope: z.string().optional().describe("Optional scope slug. Defaults to the active scope when available."),
+                kinds: z.array(z.enum(["observation", "decision", "entity"])).optional()
+                    .describe("Optional filter for memory entry kinds."),
+                limit: z.number().int().positive().optional().describe("Maximum number of ranked hits to return. Defaults to 10."),
+                includeSuperseded: z.boolean().optional().describe("Include superseded observations and decisions. Defaults to false."),
+                includeArchived: z.boolean().optional().describe("Include archived observations and decisions. Defaults to false."),
+                includeCold: z.boolean().optional().describe("Include cold-tier rows. Defaults to false."),
+            }),
+            handler: async (args) => {
+                const requestedScope = args.scope ? getMemoryScope(args.scope) : undefined;
+                if (args.scope && !requestedScope) {
+                    return `Unknown memory scope '${args.scope}'.`;
+                }
+                const result = recallMemory({
+                    query: args.query,
+                    scope_id: requestedScope?.id,
+                    kinds: args.kinds,
+                    limit: args.limit ?? 10,
+                    includeSuperseded: args.includeSuperseded,
+                    includeArchived: args.includeArchived,
+                    includeCold: args.includeCold,
+                });
+                return {
+                    active_scope: result.activeScope
+                        ? { slug: result.activeScope.slug, title: result.activeScope.title }
+                        : null,
+                    hot_tier: result.hotTier,
+                    hits: result.hits.map((hit) => ({
+                        kind: hit.kind,
+                        id: hit.id,
+                        scope: hit.scope,
+                        content: hit.content,
+                        decided_at: hit.decidedAt,
+                        score: hit.score,
+                        snippet: hit.snippet,
+                    })),
+                };
+            },
+        }),
+        defineTool("memory_housekeep", {
+            description: "Run the scoped agent-memory housekeeping pipeline. Orchestrator-only write-tier maintenance tool.",
+            parameters: z.object({
+                scope_slug: z.string().optional().describe("Optional scope slug. Defaults to the active scope."),
+                all_scopes: z.boolean().optional().describe("Run scoped passes for all active scopes instead of one scope."),
+                passes: z.array(z.string()).optional().describe("Optional pass names: dedup_observations, dedup_decisions, orphan_cleanup, decay, compact_inbox."),
+            }),
+            handler: async (args) => {
+                const denied = requireOrchestratorMemoryWrite();
+                if (denied)
+                    return denied;
+                if (args.scope_slug && args.all_scopes) {
+                    return "Pass either scope_slug or all_scopes, not both.";
+                }
+                try {
+                    const requestedScope = args.scope_slug ? getMemoryScope(args.scope_slug) : undefined;
+                    if (args.scope_slug && !requestedScope) {
+                        return `Unknown memory scope '${args.scope_slug}'.`;
+                    }
+                    const result = runHousekeeping({
+                        scopeIds: requestedScope ? [requestedScope.id] : undefined,
+                        allScopes: args.all_scopes,
+                        passes: args.passes,
+                    });
+                    return {
+                        ok: result.summaries.every((summary) => summary.errors.length === 0),
+                        scope_ids: result.scopeIds,
+                        total_examined: result.totalExamined,
+                        total_modified: result.totalModified,
+                        duration_ms: result.durationMs,
+                        summaries: result.summaries,
+                    };
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
+        defineTool("memory_promote", {
+            description: "Promote a memory row to the hot tier. Orchestrator-only manual override.",
+            parameters: z.object({
+                table: memoryTierTableSchema,
+                id: z.number().int().positive(),
+                reason: z.string().min(1),
+            }),
+            handler: async (args) => {
+                const denied = requireOrchestratorMemoryWrite();
+                if (denied)
+                    return denied;
+                try {
+                    promoteToHot(args.table, args.id, args.reason);
+                    return { ok: true, table: args.table, id: args.id, tier: "hot" };
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
+        defineTool("memory_demote", {
+            description: "Demote a memory row to warm or cold tier. Orchestrator-only manual override.",
+            parameters: z.object({
+                table: memoryTierTableSchema,
+                id: z.number().int().positive(),
+                reason: z.string().min(1),
+                tier: z.enum(["warm", "cold"]).optional().describe("Target demotion tier. Defaults to warm."),
+            }),
+            handler: async (args) => {
+                const denied = requireOrchestratorMemoryWrite();
+                if (denied)
+                    return denied;
+                try {
+                    if (args.tier === "cold") {
+                        demoteToCold(args.table, args.id, args.reason);
+                        return { ok: true, table: args.table, id: args.id, tier: "cold" };
+                    }
+                    demoteToWarm(args.table, args.id, args.reason);
+                    return { ok: true, table: args.table, id: args.id, tier: "warm" };
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
+        defineTool("memory_set_scope", {
+            description: "Set or clear the active scope for the agent-memory system. This affects default routing for memory_remember and memory_recall.",
+            parameters: z.object({
+                slug: z.string().nullable().describe("Scope slug to activate, or null to clear the active scope."),
+            }),
+            handler: async (args) => {
+                const denied = requireOrchestratorMemoryWrite();
+                if (denied)
+                    return denied;
+                try {
+                    const previousScope = getMemoryActiveScope();
+                    const nextScope = args.slug === null ? null : (getMemoryScope(args.slug) ?? null);
+                    if (args.slug !== null && !nextScope) {
+                        return `Unknown memory scope '${args.slug}'.`;
+                    }
+                    const previousSlug = previousScope?.slug ?? null;
+                    const nextSlug = nextScope?.slug ?? null;
+                    const didChange = previousSlug !== nextSlug;
+                    const sessionKey = getCurrentSessionKey();
+                    if (didChange) {
+                        maybeScheduleScopeChangeCheckpoint(sessionKey, previousScope, nextScope);
+                    }
+                    const activeScope = setMemoryActiveScope(args.slug);
+                    if (didChange) {
+                        invalidateOrchestratorSession(sessionKey);
+                        resetCheckpointSessionState(sessionKey);
+                    }
+                    return {
+                        active_scope: activeScope
+                            ? { slug: activeScope.slug, title: activeScope.title }
+                            : null,
+                    };
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            },
+        }),
         // ----- Wiki-backed memory facades (preserve existing remember/recall/forget UX) -----
         defineTool("remember", {
             description: "Save a fact, preference, or detail to the wiki. Routes to topic pages automatically. " +