crow-central-agency 0.26.15 → 0.27.1

package/README.md

@@ -95,6 +95,7 @@ See `.env.example` for the full list, including:
 - `HOST` / `PORT` — server bind address (defaults: `localhost:3101`). Keep `HOST=localhost` and front the server with a secure tunnel for remote access rather than binding to `0.0.0.0`.
 - `CORS_ORIGINS` — only needed when the frontend is served from a different origin (e.g. during frontend dev). Single-box deployments can leave it unset.
 - `LOG_LEVEL` — log verbosity (defaults to `debug` in development, `info` otherwise).
+- `LOG_PRETTY` — force human-readable, colorized logs (pino-pretty) even in production. Enabled automatically in development.
 - `CROW_SYSTEM_PATH` — directory for Crow's file-based storage. Defaults to `~/.crow`.
 - `CROW_SYSTEM_AGENT_NAME` — display name for the built-in Crow system agent (default: `Crow`).
 - `CROW_SYSTEM_AGENT_PROVIDER` — provider backing the built-in system agents: `claude` or `copilot` (default: `claude`). Forced to `claude` when `DISABLE_GITHUB_COPILOT` is set.

package/dist/_shared/auto-approve/auto-approve-rule-set.js

@@ -1,3 +1,4 @@
+import { SUBCOMMAND_MATCH_MODE } from "./command-decomposition.js";
 import { parseRule } from "./rule-format.js";
 import { getRuleStrategy } from "./rule-strategy-registry.js";
 /**
@@ -23,8 +24,8 @@ export class AutoApproveRuleSet {
             }
         }
     }
-    matches(toolName, input) {
-        return getRuleStrategy(toolName).matches(toolName, input, this.parsed);
+    matches(toolName, input, mode = SUBCOMMAND_MATCH_MODE.ALL) {
+        return getRuleStrategy(toolName).matches(toolName, input, this.parsed, mode);
     }
 }
 //# sourceMappingURL=auto-approve-rule-set.js.map

package/dist/_shared/auto-approve/command-decomposition.js

@@ -1,6 +1,14 @@
 import { matchesSpecifier, WORD_BOUNDARY_SUFFIX } from "./rule-format.js";
-/** Prefix depth for derived rules (first N tokens of a subcommand). */
-export const DEFAULT_PREFIX_DEPTH = 2;
+/** Number of non-flag tokens a derived prefix keeps before wildcarding the rest. */
+export const DEFAULT_PREFIX_DEPTH = 3;
+/**
+ * How a compound command aggregates per-subcommand matches. `ALL` (approve) requires every
+ * subcommand to match a specifier; `ANY` (deny) fires when a single subcommand matches.
+ */
+export const SUBCOMMAND_MATCH_MODE = {
+    ALL: "all",
+    ANY: "any",
+};
 /** Maximum number of rules derived from a single compound command, mirroring the SDK cap. */
 export const MAX_DERIVED_RULES = 5;
 /**
@@ -16,29 +24,7 @@ export const SINGLE_CHAR_SEPARATORS = [";", "|", "&", "\n", "\r"];
 export const PROCESS_WRAPPERS = new Set(["timeout", "time", "nice", "nohup", "stdbuf"]);
 const WRAPPERS_WITH_NUMERIC_ARG = new Set(["timeout", "nice"]);
 const XARGS_WRAPPER = "xargs";
-/**
- * Read-only shell builtins that run with no prompt. `cd` and `git` are handled separately
- * (in-cwd `cd` only; read-only `git` subcommands only).
- */
-export const READ_ONLY_BUILTINS = new Set([
-    "ls",
-    "cat",
-    "echo",
-    "pwd",
-    "head",
-    "tail",
-    "grep",
-    "find",
-    "wc",
-    "which",
-    "diff",
-    "stat",
-    "du",
-]);
-const CD_COMMAND = "cd";
-const IN_CWD_CD_ARGS = new Set([".", "./"]);
-const GIT_COMMAND = "git";
-const READ_ONLY_GIT_SUBCOMMANDS = new Set(["status", "log", "diff", "show"]);
+const OPTION_PREFIX = "-";
 const SINGLE_QUOTE = "'";
 const DOUBLE_QUOTE = '"';
 const REDIRECT_CHAR = ">";
@@ -109,7 +95,7 @@ function stripWrappers(tokens) {
         if (head === XARGS_WRAPPER) {
             // Only bare `xargs` (no flags) is transparent; flagged xargs stays and simply won't match.
             const next = remaining[1];
-            if (next !== undefined && next.startsWith("-")) {
+            if (next !== undefined && next.startsWith(OPTION_PREFIX)) {
                 break;
             }
             remaining = remaining.slice(1);
@@ -119,7 +105,7 @@ function stripWrappers(tokens) {
             break;
         }
         remaining = remaining.slice(1);
-        while (remaining.length > 0 && remaining[0].startsWith("-")) {
+        while (remaining.length > 0 && remaining[0].startsWith(OPTION_PREFIX)) {
             remaining = remaining.slice(1);
         }
         if (WRAPPERS_WITH_NUMERIC_ARG.has(head) && remaining.length > 0 && /^[0-9]/.test(remaining[0])) {
@@ -174,26 +160,31 @@ export function splitSubcommands(command) {
     }
     return subcommands;
 }
-/** Whether a normalized subcommand is a read-only builtin, in-cwd `cd`, or read-only `git`. */
-export function isReadOnlyCommand(subcommand) {
-    const tokens = tokenize(subcommand);
-    const head = tokens[0];
-    if (head === undefined) {
-        return false;
-    }
-    if (head === CD_COMMAND) {
-        const target = tokens[1];
-        return target === undefined || IN_CWD_CD_ARGS.has(target);
-    }
-    if (head === GIT_COMMAND) {
-        const gitSubcommand = tokens[1];
-        return gitSubcommand !== undefined && READ_ONLY_GIT_SUBCOMMANDS.has(gitSubcommand);
+function derivePrefixTokens(tokens, depth) {
+    const prefix = [];
+    let counted = 0;
+    let index = 0;
+    while (index < tokens.length && counted < depth) {
+        const token = tokens[index];
+        if (token.startsWith(OPTION_PREFIX)) {
+            prefix.push(token);
+            index += 1;
+            if (index < tokens.length && !tokens[index].startsWith(OPTION_PREFIX)) {
+                prefix.push(tokens[index]);
+                index += 1;
+            }
+            continue;
+        }
+        prefix.push(token);
+        counted += 1;
+        index += 1;
     }
-    return READ_ONLY_BUILTINS.has(head);
+    return counted === 0 ? undefined : prefix;
 }
 /**
- * Capture side: derive one prefix-`depth` specifier per non-read-only subcommand (in-cwd `cd` and
- * read-only builtins contribute nothing), deduped and capped at {@link MAX_DERIVED_RULES}.
+ * Capture side: derive one flag-aware prefix specifier per subcommand, deduped and capped at
+ * {@link MAX_DERIVED_RULES}. A subcommand with no non-flag token (e.g. a lone `--flag`) contributes
+ * nothing. User config is the only auto-approve authority — there is no read-only skip.
  */
 export function deriveRules(command, depth = DEFAULT_PREFIX_DEPTH) {
     const specifiers = [];
@@ -201,15 +192,11 @@ export function deriveRules(command, depth = DEFAULT_PREFIX_DEPTH) {
         if (specifiers.length >= MAX_DERIVED_RULES) {
             break;
         }
-        if (isReadOnlyCommand(subcommand)) {
-            continue;
-        }
-        const tokens = tokenize(subcommand);
-        if (tokens.length === 0) {
+        const prefixTokens = derivePrefixTokens(tokenize(subcommand), depth);
+        if (prefixTokens === undefined) {
             continue;
         }
-        const prefix = tokens.slice(0, depth).join(" ");
-        const specifier = `${prefix}${WORD_BOUNDARY_SUFFIX}`;
+        const specifier = `${prefixTokens.join(" ")}${WORD_BOUNDARY_SUFFIX}`;
         if (!specifiers.includes(specifier)) {
             specifiers.push(specifier);
         }
@@ -217,22 +204,19 @@ export function deriveRules(command, depth = DEFAULT_PREFIX_DEPTH) {
     return specifiers;
 }
 /**
- * Match side: fails closed. Every subcommand must be a read-only builtin or match one of the
- * specifiers. Empty/unparseable input yields `false`.
+ * Match side: fails closed. Each raw subcommand is matched against the specifiers via literal-prefix
+ * `matchesSpecifier` (no flag logic on this side). `ALL` (approve) requires every subcommand to
+ * match; `ANY` (deny) fires when a single subcommand matches. Empty/unparseable input yields `false`
+ * in both modes.
  */
-export function matchesRules(command, specifiers) {
+export function matchesRules(command, specifiers, mode = SUBCOMMAND_MATCH_MODE.ALL) {
     const subcommands = splitSubcommands(command);
     if (subcommands.length === 0) {
         return false;
     }
-    for (const subcommand of subcommands) {
-        if (isReadOnlyCommand(subcommand)) {
-            continue;
-        }
-        if (!specifiers.some((specifier) => matchesSpecifier(subcommand, specifier))) {
-            return false;
-        }
-    }
-    return true;
+    const subcommandMatches = (subcommand) => specifiers.some((specifier) => matchesSpecifier(subcommand, specifier));
+    return mode === SUBCOMMAND_MATCH_MODE.ANY
+        ? subcommands.some(subcommandMatches)
+        : subcommands.every(subcommandMatches);
 }
 //# sourceMappingURL=command-decomposition.js.map

package/dist/_shared/auto-approve/rule-strategies.js

@@ -12,20 +12,22 @@ const COMMAND_TOOL_BASE_NAMES = new Set([
     CLAUDE_CODE_TOOL.POWER_SHELL.toLowerCase(),
 ]);
 /**
- * Whole-tool matching, preserving the legacy `isToolAutoApproved` behavior: exact tool-name match,
- * plus a trailing `*` (including a bare `*` and MCP prefixes like `mcp__crow-artifacts__*`) as a
- * prefix match.
+ * Whole-tool matching: case-insensitive exact tool-name match, plus a trailing `*` (including a bare
+ * `*` and MCP prefixes like `mcp__crow-artifacts__*`) as a prefix match. Case-insensitivity aligns
+ * with the command strategy (which lowercases the tool name) so a `Bash` rule covers Copilot's
+ * `bash`, for both allow and deny.
  */
 function wholeToolMatches(toolName, rules) {
+    const targetTool = toolName.toLowerCase();
     for (const rule of rules) {
         if (rule.specifier !== undefined) {
             continue;
         }
-        const pattern = rule.tool;
-        if (pattern === toolName) {
+        const pattern = rule.tool.toLowerCase();
+        if (pattern === targetTool) {
             return true;
         }
-        if (pattern.endsWith(GLOB_STAR) && toolName.startsWith(pattern.slice(0, -GLOB_STAR.length))) {
+        if (pattern.endsWith(GLOB_STAR) && targetTool.startsWith(pattern.slice(0, -GLOB_STAR.length))) {
             return true;
         }
     }
@@ -51,7 +53,7 @@ export const commandRuleStrategy = {
         }
         return deriveCommandRules(command).map((specifier) => formatRule({ tool: toolName, specifier }));
     },
-    matches: (toolName, input, rules) => {
+    matches: (toolName, input, rules, mode) => {
         if (wholeToolMatches(toolName, rules)) {
             return true;
         }
@@ -66,7 +68,7 @@ export const commandRuleStrategy = {
                 specifiers.push(rule.specifier);
             }
         }
-        return matchesCommandRules(command, specifiers);
+        return matchesCommandRules(command, specifiers, mode);
     },
 };
 //# sourceMappingURL=rule-strategies.js.map

package/dist/_shared/constants/system-agent.js

@@ -3,4 +3,5 @@ export const CROW_SYSTEM_AGENT_ID = "__super_crow__";
 export const CROW_TASK_DISPATCHER_AGENT_ID = "__crow_task_dp__";
 export const CROW_NARRATIVE_ARCHITECT_AGENT_ID = "__crow_narrative_architect__";
 export const CROW_WORLD_BUILDER_AGENT_ID = "__crow_world_builder__";
+export const FRAGMENT_REFLECTION_AGENT_ID = "__crow_fragment_reflection__";
 //# sourceMappingURL=system-agent.js.map

package/dist/_shared/index.js

@@ -2,10 +2,10 @@ export { CLAUDE_MODELS, GITHUB_COPILOT_MODELS, CLAUDE_CODE_MODEL_OPTIONS, ModelO
 export { SchedulerTimeSchema, DAY_OF_WEEK, DayOfWeekSchema, TimeModeSchema, TIME_MODE, } from "./schemas/scheduler.schema.js";
 export { createApiSuccessSchema, ApiErrorSchema, } from "./schemas/api-response.schema.js";
 export { SessionUsageSchema, PendingPermissionInfoSchema, PendingInstructionReminderSchema, AgentRuntimeStateSchema, AgentActivitySchema, AGENT_ACTIVITY_TYPE, AGENT_STATUS, MAX_INPUT_HISTORY, } from "./schemas/agent-runtime-state.schema.js";
-export { ClientMessageSchema, ServerMessageSchema, SendMessageSchema, InjectMessageSchema, PermissionResponseWsSchema, CommandMessageSchema, AgentTextWsMessageSchema, AgentActivityWsMessageSchema, AgentResultWsMessageSchema, AgentStatusWsMessageSchema, AgentCreatedWsMessageSchema, AgentUpdatedWsMessageSchema, AgentDeletedWsMessageSchema, AgentUsageWsMessageSchema, PermissionRequestWsMessageSchema, PermissionCancelledWsMessageSchema, ErrorWsMessageSchema, AgentMessageWsMessageSchema, AgentToolProgressWsMessageSchema, TaskAddedWsMessageSchema, TaskUpdatedWsMessageSchema, TaskAssignedWsMessageSchema, TaskStateChangedWsMessageSchema, TaskDeletedWsMessageSchema, CircleCreatedWsMessageSchema, CircleUpdatedWsMessageSchema, CircleDeletedWsMessageSchema, RelationshipCreatedWsMessageSchema, RelationshipDeletedWsMessageSchema, AgentBuilderDraftUpdatedWsMessageSchema, isAgentServerMessage, isAgentLifecycleServerMessage, CLIENT_MESSAGE_TYPE, SERVER_MESSAGE_TYPE, } from "./schemas/websocket.schema.js";
+export { ClientMessageSchema, ServerMessageSchema, SendMessageSchema, InjectMessageSchema, PermissionResponseWsSchema, CommandMessageSchema, AgentTextWsMessageSchema, AgentActivityWsMessageSchema, AgentResultWsMessageSchema, AgentStatusWsMessageSchema, AgentCreatedWsMessageSchema, AgentUpdatedWsMessageSchema, AgentDeletedWsMessageSchema, AgentUsageWsMessageSchema, PermissionRequestWsMessageSchema, PermissionCancelledWsMessageSchema, ErrorWsMessageSchema, AgentMessageWsMessageSchema, AgentToolProgressWsMessageSchema, TaskAddedWsMessageSchema, TaskUpdatedWsMessageSchema, TaskAssignedWsMessageSchema, TaskStateChangedWsMessageSchema, TaskDeletedWsMessageSchema, CircleCreatedWsMessageSchema, CircleUpdatedWsMessageSchema, CircleDeletedWsMessageSchema, RelationshipCreatedWsMessageSchema, RelationshipDeletedWsMessageSchema, FragmentCreatedWsMessageSchema, FragmentUpdatedWsMessageSchema, FragmentDeletedWsMessageSchema, AgentBuilderDraftUpdatedWsMessageSchema, isAgentServerMessage, isAgentLifecycleServerMessage, CLIENT_MESSAGE_TYPE, SERVER_MESSAGE_TYPE, } from "./schemas/websocket.schema.js";
 export { PERMISSION_DECISION, PermissionRequestSchema, PermissionResponseSchema, } from "./schemas/permission.schema.js";
 export { AgentMessageSchema, MessageAnnotationSchema, AGENT_MESSAGE_ROLE, AGENT_MESSAGE_TYPE, } from "./schemas/agent-message.schema.js";
-export { ARTIFACT_TYPE, ARTIFACT_CONTENT_TYPE, ArtifactTypeSchema, ArtifactContentTypeSchema, ArtifactMetadataSchema, ArtifactUpdateSchema, } from "./schemas/artifact.schema.js";
+export { ARTIFACT_TYPE, ARTIFACT_CONTENT_TYPE, ArtifactTypeSchema, ArtifactContentTypeSchema, ArtifactEntityTypeSchema, ArtifactMetadataSchema, ArtifactUpdateSchema, } from "./schemas/artifact.schema.js";
 export { AGENT_TASK_STATE, AGENT_TASK_SOURCE_TYPE, AgentTaskStateSchema, AgentTaskSourceSchema, AgentTaskItemSchema, AgentTaskDatabaseSchema, CreateTaskInputSchema, UpdateTaskInputSchema, UpdateTaskStateInputSchema, AssignTaskInputSchema, } from "./schemas/agent-task.schema.js";
 export { MCP_CONFIG_TYPE, InternalMcpConfigSchema, McpServerConfigSchema, CreateMcpConfigInputSchema, UpdateMcpConfigInputSchema, } from "./schemas/mcp-config.schema.js";
 export { SensorInfoSchema } from "./schemas/sensor.schema.js";
@@ -19,14 +19,17 @@ export { applyAgentOrder } from "./utils/apply-agent-order.js";
 export { MODEL_ALIASES, resolveModel, modelSupportsAdaptiveThinking } from "./utils/resolve-model.js";
 export { BASE_CIRCLE_ID, BASE_CIRCLE_NAME } from "./constants/system-circle.js";
 export { ENTITY_TYPE, RELATIONSHIP_TYPE, AgentCircleSchema, CreateAgentCircleInputSchema, UpdateAgentCircleInputSchema, EntityTypeSchema, RelationshipTypeSchema, RelationshipSchema, CreateRelationshipInputSchema, CircleMemberSchema, } from "./schemas/agent-circle.schema.js";
-export { CROW_SYSTEM_AGENT_ID, CROW_TASK_DISPATCHER_AGENT_ID, CROW_NARRATIVE_ARCHITECT_AGENT_ID, CROW_WORLD_BUILDER_AGENT_ID, } from "./constants/system-agent.js";
+export { CROW_SYSTEM_AGENT_ID, CROW_TASK_DISPATCHER_AGENT_ID, CROW_NARRATIVE_ARCHITECT_AGENT_ID, CROW_WORLD_BUILDER_AGENT_ID, FRAGMENT_REFLECTION_AGENT_ID, } from "./constants/system-agent.js";
+export { CreateFragmentAssociationInputSchema, FRAGMENT_KIND, FRAGMENT_FIRST_LEVEL_TARGET, FRAGMENT_MAX_WORDS, FragmentKindSchema, FragmentSchema, } from "./schemas/fragment.schema.js";
+export { REFLECTION_AGENT_REF, REFLECTION_TEMP_PREFIX, REFLECTION_OP, ReflectionOpSchema, ReflectionPlanSchema, } from "./schemas/fragment-reflection.schema.js";
 export { MESSAGE_SOURCE_TYPE, MessageSourceSchema, } from "./schemas/message-source.schema.js";
 export { AGENT_COMMAND, AgentCommandSchema } from "./schemas/agent-command.schema.js";
 export { GraphNodeSchema, GraphEdgeSchema, GraphDataSchema, } from "./schemas/graph.schema.js";
 export { ConnectorConnectionSchema, ConnectorInfoSchema, ConnectConnectorResponseSchema, } from "./schemas/connector.schema.js";
 export { parseRule, parseRules, formatRule, matchesSpecifier, GLOB_STAR, WORD_BOUNDARY_SUFFIX, PREFIX_STAR_SUFFIX, } from "./auto-approve/rule-format.js";
-export { splitSubcommands, deriveRules, matchesRules, isReadOnlyCommand, DEFAULT_PREFIX_DEPTH, MAX_DERIVED_RULES, READ_ONLY_BUILTINS, PROCESS_WRAPPERS, } from "./auto-approve/command-decomposition.js";
+export { splitSubcommands, deriveRules, matchesRules, DEFAULT_PREFIX_DEPTH, MAX_DERIVED_RULES, PROCESS_WRAPPERS, SUBCOMMAND_MATCH_MODE, } from "./auto-approve/command-decomposition.js";
 export { defaultRuleStrategy, commandRuleStrategy } from "./auto-approve/rule-strategies.js";
 export { getRuleStrategy } from "./auto-approve/rule-strategy-registry.js";
 export { AutoApproveRuleSet } from "./auto-approve/auto-approve-rule-set.js";
+export { normalizeMcpName } from "./utils/mcp-utils.js";
 //# sourceMappingURL=index.js.map

package/dist/_shared/schemas/agent-circle.schema.js

@@ -5,13 +5,18 @@ import { z } from "zod";
 export const ENTITY_TYPE = {
     AGENT: "AGENT",
     AGENT_CIRCLE: "AGENT_CIRCLE",
+    FRAGMENT: "FRAGMENT",
 };
 /**
  * Relationship types between entities.
- * MEMBERSHIP means "source contains target as a member".
+ * MEMBERSHIP means "source contains target as a member" (agent ↔ circle only).
+ * ASSOCIATION anchors an agent to a fragment (agent → fragment).
+ * LINK connects fragments (fragment → fragment).
  */
 export const RELATIONSHIP_TYPE = {
     MEMBERSHIP: "MEMBERSHIP",
+    ASSOCIATION: "ASSOCIATION",
+    LINK: "LINK",
 };
 export const AgentCircleSchema = z.object({
     /** Unique identifier - UUID for user-created circles, well-known string for system circles */
@@ -37,8 +42,12 @@ export const UpdateAgentCircleInputSchema = z.object({
     convention: z.string().optional(),
     displayOrder: z.number().optional(),
 });
-export const EntityTypeSchema = z.enum([ENTITY_TYPE.AGENT, ENTITY_TYPE.AGENT_CIRCLE]);
-export const RelationshipTypeSchema = z.enum([RELATIONSHIP_TYPE.MEMBERSHIP]);
+export const EntityTypeSchema = z.enum([ENTITY_TYPE.AGENT, ENTITY_TYPE.AGENT_CIRCLE, ENTITY_TYPE.FRAGMENT]);
+export const RelationshipTypeSchema = z.enum([
+    RELATIONSHIP_TYPE.MEMBERSHIP,
+    RELATIONSHIP_TYPE.ASSOCIATION,
+    RELATIONSHIP_TYPE.LINK,
+]);
 export const RelationshipSchema = z.object({
     /** Unique identifier - UUID except for virtual relationship with system agents */
     id: z.string().min(1),

package/dist/_shared/schemas/agent-runtime-state.schema.js

@@ -77,13 +77,13 @@ export const AgentRuntimeStateSchema = z.object({
     messageSource: MessageSourceSchema.optional(),
     discordDmChannelId: z.string().optional(),
     sessionId: z.string().optional(),
+    activeDomainFragmentIds: z.array(z.string()).default([]),
     sessionUsage: SessionUsageSchema,
     prevLoopMessageTimestamp: z.number().optional(),
     lastGmailCheckTimestamp: z.number().optional(),
     lastError: z.string().optional(),
     pendingPermissions: z.array(PendingPermissionInfoSchema).optional(),
     pendingInstructionReminder: PendingInstructionReminderSchema.optional(),
-    /** Recent user message inputs (oldest first) for compose-box Up/Down recall; survives new sessions. */
     inputHistory: z.array(z.string()).optional(),
 });
 //# sourceMappingURL=agent-runtime-state.schema.js.map

package/dist/_shared/schemas/artifact.schema.js

@@ -1,6 +1,8 @@
 import { z } from "zod";
-import { EntityTypeSchema } from "./agent-circle.schema.js";
+import { ENTITY_TYPE } from "./agent-circle.schema.js";
 import { AgentTaskSourceSchema } from "./agent-task.schema.js";
+/** Entity types that can own artifacts — fragments are never artifact-bearing */
+export const ArtifactEntityTypeSchema = z.enum([ENTITY_TYPE.AGENT, ENTITY_TYPE.AGENT_CIRCLE]);
 /**
  * TODO: layered memory system via artifacts.
  */
@@ -41,7 +43,7 @@ export const ArtifactMetadataSchema = z.object({
     type: ArtifactTypeSchema,
     contentType: ArtifactContentTypeSchema,
     entityId: z.string(),
-    entityType: EntityTypeSchema,
+    entityType: ArtifactEntityTypeSchema,
     size: z.number(),
     tags: z.array(z.string()).optional(),
     createdTimestamp: z.number(),

package/dist/_shared/schemas/fragment-reflection.schema.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { FragmentKindSchema } from "./fragment.schema.js";
+/**
+ * A plan node reference is a single string.
+ * `REFLECTION_AGENT_REF` names the target agent (top-level anchor).
+ * A string starting with `REFLECTION_TEMP_PREFIX` names a node created earlier in the same plan by its tempId.
+ * Anything else is an existing fragment id.
+ */
+export const REFLECTION_AGENT_REF = "agent";
+export const REFLECTION_TEMP_PREFIX = "$";
+const NodeRefSchema = z.string().min(1);
+/**
+ * Reflection plan operations, applied in order against the target agent's memory fragments.
+ * CREATE - a new node (theme/sub-domain) hanging under `parent`.
+ * LINK - add an edge, or move when `from` names the edge to drop.
+ * UNLINK - remove one named edge (last-edge removal cascade-deletes).
+ * UPDATE - content only (cue/body).
+ */
+export const REFLECTION_OP = {
+    CREATE: "create",
+    LINK: "link",
+    UNLINK: "unlink",
+    UPDATE: "update",
+};
+const CreateReflectionOpSchema = z.object({
+    op: z.literal(REFLECTION_OP.CREATE),
+    /** Handle later operations in the same plan use to reference this node — must start with `$` */
+    tempId: z.string().regex(/^\$/),
+    kind: FragmentKindSchema,
+    cue: z.string().min(1),
+    body: z.string().min(1),
+    parent: NodeRefSchema,
+});
+const LinkReflectionOpSchema = z.object({
+    op: z.literal(REFLECTION_OP.LINK),
+    fragment: NodeRefSchema,
+    parent: NodeRefSchema,
+    /** When given, the move drops this original parent edge after the new one is added */
+    from: NodeRefSchema.optional(),
+});
+const UnlinkReflectionOpSchema = z.object({
+    op: z.literal(REFLECTION_OP.UNLINK),
+    fragment: NodeRefSchema,
+    parent: NodeRefSchema,
+});
+const UpdateReflectionOpSchema = z.object({
+    op: z.literal(REFLECTION_OP.UPDATE),
+    fragment: NodeRefSchema,
+    cue: z.string().min(1).optional(),
+    body: z.string().min(1).optional(),
+});
+export const ReflectionOpSchema = z.discriminatedUnion("op", [
+    CreateReflectionOpSchema,
+    LinkReflectionOpSchema,
+    UnlinkReflectionOpSchema,
+    UpdateReflectionOpSchema,
+]);
+/** The single-pass reorganization plan the reflection agent returns between its output markers */
+export const ReflectionPlanSchema = z.object({
+    operations: z.array(ReflectionOpSchema),
+});
+//# sourceMappingURL=fragment-reflection.schema.js.map

package/dist/_shared/schemas/fragment.schema.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+/**
+ * Fragment kinds.
+ * DOMAIN - an organizing topic others nest under.
+ * KNOWLEDGE - a fact (even one a user tells you); leaf under a DOMAIN.
+ * LESSON - a how-to-act rule from the agent's own reflection.
+ * FEEDBACK - a correction or preference from the user.
+ */
+export const FRAGMENT_KIND = {
+    FEEDBACK: "FEEDBACK",
+    LESSON: "LESSON",
+    DOMAIN: "DOMAIN",
+    KNOWLEDGE: "KNOWLEDGE",
+};
+export const FragmentKindSchema = z.enum([
+    FRAGMENT_KIND.FEEDBACK,
+    FRAGMENT_KIND.LESSON,
+    FRAGMENT_KIND.DOMAIN,
+    FRAGMENT_KIND.KNOWLEDGE,
+]);
+/** Maximum number of words in a fragment body, kind-agnostic, enforced on write */
+export const FRAGMENT_MAX_WORDS = 100;
+/** Target ceiling for a first-level bucket or any parent's direct children before reflection consolidates */
+export const FRAGMENT_FIRST_LEVEL_TARGET = 20;
+/**
+ * An atomic unit of agent experience.
+ * Pure: no agent reference and no link fields — agent↔fragment and
+ * fragment↔fragment relations are relationship-graph edges only.
+ */
+export const FragmentSchema = z.object({
+    id: z.string().min(1),
+    kind: FragmentKindSchema,
+    /** Level-1: short one-line relevance descriptor, always cheap to surface */
+    cue: z.string().min(1),
+    /** Level-2: the lesson itself, pulled on demand */
+    body: z.string().min(1),
+    /** Times the fragment has been recalled */
+    usageCount: z.number(),
+    lastRecalledTimestamp: z.number().optional(),
+    createdTimestamp: z.number(),
+    updatedTimestamp: z.number(),
+});
+/** Input for the user-facing sharing route: associate an agent to a fragment */
+export const CreateFragmentAssociationInputSchema = z.object({
+    agentId: z.string().min(1),
+});
+//# sourceMappingURL=fragment.schema.js.map

package/dist/_shared/schemas/graph.schema.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { EntityTypeSchema, RelationshipTypeSchema } from "./agent-circle.schema.js";
 import { AGENT_STATUS } from "./agent-runtime-state.schema.js";
-/** A node in the relationship graph — represents either an agent or a circle */
+import { FragmentKindSchema } from "./fragment.schema.js";
+/** A node in the relationship graph — represents an agent, a circle, or a fragment */
 export const GraphNodeSchema = z.object({
     id: z.string(),
     name: z.string(),
@@ -9,6 +10,7 @@ export const GraphNodeSchema = z.object({
     isSystemAgent: z.boolean().optional(),
     isPinned: z.boolean().optional(),
     isSystemCircle: z.boolean().optional(),
+    kind: FragmentKindSchema.optional(),
     status: z
         .enum([AGENT_STATUS.IDLE, AGENT_STATUS.ACTIVATING, AGENT_STATUS.STREAMING, AGENT_STATUS.COMPACTING])
         .optional(),

package/dist/_shared/schemas/websocket.schema.js

@@ -44,6 +44,9 @@ export const SERVER_MESSAGE_TYPE = {
     CIRCLE_DELETED: "circle_deleted",
     RELATIONSHIP_CREATED: "relationship_created",
     RELATIONSHIP_DELETED: "relationship_deleted",
+    FRAGMENT_CREATED: "fragment_created",
+    FRAGMENT_UPDATED: "fragment_updated",
+    FRAGMENT_DELETED: "fragment_deleted",
     AGENT_BUILDER_DRAFT_UPDATED: "agent_builder_draft_updated",
 };
 export const SendMessageSchema = z.object({
@@ -192,6 +195,18 @@ export const RelationshipDeletedWsMessageSchema = z.object({
     type: z.literal(SERVER_MESSAGE_TYPE.RELATIONSHIP_DELETED),
     relationshipId: z.string(),
 });
+export const FragmentCreatedWsMessageSchema = z.object({
+    type: z.literal(SERVER_MESSAGE_TYPE.FRAGMENT_CREATED),
+    fragmentId: z.string(),
+});
+export const FragmentUpdatedWsMessageSchema = z.object({
+    type: z.literal(SERVER_MESSAGE_TYPE.FRAGMENT_UPDATED),
+    fragmentId: z.string(),
+});
+export const FragmentDeletedWsMessageSchema = z.object({
+    type: z.literal(SERVER_MESSAGE_TYPE.FRAGMENT_DELETED),
+    fragmentId: z.string(),
+});
 /** The single agent-builder draft changed; carries the resolved view, or null when it was cleared. */
 export const AgentBuilderDraftUpdatedWsMessageSchema = z.object({
     type: z.literal(SERVER_MESSAGE_TYPE.AGENT_BUILDER_DRAFT_UPDATED),
@@ -222,6 +237,9 @@ export const ServerMessageSchema = z.discriminatedUnion("type", [
     CircleDeletedWsMessageSchema,
     RelationshipCreatedWsMessageSchema,
     RelationshipDeletedWsMessageSchema,
+    FragmentCreatedWsMessageSchema,
+    FragmentUpdatedWsMessageSchema,
+    FragmentDeletedWsMessageSchema,
     AgentBuilderDraftUpdatedWsMessageSchema,
 ]);
 export function isAgentServerMessage(message) {

package/dist/_shared/utils/mcp-utils.js

@@ -0,0 +1,4 @@
+export function normalizeMcpName(name) {
+    return name.toLowerCase().replaceAll(" ", "_");
+}
+//# sourceMappingURL=mcp-utils.js.map

package/dist/agents/crow-fragment-reflection-agent.js

@@ -0,0 +1,98 @@
+import { PERMISSION_MODE, TOOL_MODE, CLAUDE_MODELS, FRAGMENT_REFLECTION_AGENT_ID, FRAGMENT_FIRST_LEVEL_TARGET, FRAGMENT_MAX_WORDS, REFLECTION_AGENT_REF, REFLECTION_TEMP_PREFIX, } from "../_shared/index.js";
+import path from "node:path";
+import { env } from "../config/env.js";
+import { SYSTEM_AGENT_TYPE, resolveSystemAgentModel } from "./system-agent-provider.js";
+import { createMessageContentFromTemplate, getDefaultPromptContext } from "../utils/message-template.js";
+import { SYSTEM_AGENTS_PROJECT_DIR_NAME } from "../config/constants.js";
+import { FRAGMENT_REFLECTION_BEGIN, FRAGMENT_REFLECTION_END, } from "../services/fragment/fragment-reflection.constants.js";
+const CROW_FRAGMENT_REFLECTION_AGENT_NAME = "Crow Fragment Reflection";
+/**
+ * Planner charter for the fragment reflection agent. Substituted with
+ * {maxWords}/{firstLevelTarget} from the shared fragment constants at agent build time.
+ */
+export const CROW_FRAGMENT_REFLECTION_AGENT_PERSONA = {
+    role: "system",
+    content: [
+        {
+            content: [
+                "You are the reflective memory steward for crow central agency — an invisible background role that reviews another agent's long-term memory. Each run you step back and study ONE target agent's fragments: what it has newly learned, and how that sits against everything it already holds. From that reflection you return a plan that settles each fragment where it truly belongs. You never talk to a user, never mutate the memory yourself, and never emit anything but the plan.",
+                "",
+                "A fragment is one atomic memory: a short `cue` plus a `body` of at most {maxWords} words, typed DOMAIN, KNOWLEDGE, FEEDBACK, or LESSON. Fragments form a DAG — a fragment can hang under multiple parents by LINK, and top-level fragments are anchored to the agent. KNOWLEDGE is a leaf that only hangs under a DOMAIN.",
+                "",
+                "Your job: examine every fragment and settle each under the parents where it truly belongs, whether a DOMAIN it concerns or a broader FEEDBACK or LESSON it refines. When any parent's direct children grow past about {firstLevelTarget}, introduce an intermediate parent of the fitting kind and move the related members under it. Merge duplicates by folding unique content into the survivor before removing the loser, and prune stale or superseded fragments. Make minimal, high-confidence changes — under-organizing is far safer than scrambling sound structure.",
+                "",
+                "Use `read_fragment(id)` to pull any body the context did not front-load, and `search_fragment(targetAgentId, query)` to find near-duplicates elsewhere in the target's memory before you decide.",
+                "",
+                "## OUTPUT",
+                "",
+                "Emit exactly one JSON object between the markers below and nothing else — no preamble, no commentary, no code fences.",
+                "",
+                "Every node reference in the plan is a single string:",
+                `- \`"${REFLECTION_AGENT_REF}"\` — the target agent (top-level anchor).`,
+                `- \`"${REFLECTION_TEMP_PREFIX}…"\` (starts with \`${REFLECTION_TEMP_PREFIX}\`, e.g. \`"${REFLECTION_TEMP_PREFIX}1"\`) — a node created earlier in this same plan, by the tempId that create gave it.`,
+                "- anything else — an existing fragment id.",
+                "",
+                "Operand names are the same across ops: `fragment` = the node being operated on, `parent` = the node it hangs under, `from` = the old parent in a move.",
+                "",
+                "The plan:",
+                "```",
+                '{ "operations": [',
+                `  { "op": "create", "tempId": "${REFLECTION_TEMP_PREFIX}1", "kind": "DOMAIN|KNOWLEDGE|FEEDBACK|LESSON", "cue": "...", "body": "...", "parent": <ref> },`,
+                '  { "op": "link",   "fragment": <ref>, "parent": <ref>, "from": <ref> },   // "from" optional — include to MOVE off that parent',
+                '  { "op": "unlink", "fragment": <ref>, "parent": <ref> },                  // removing the last parent cascade-deletes the fragment + orphaned children',
+                '  { "op": "update", "fragment": <ref>, "cue": "...", "body": "..." }       // cue/body optional — include only what changes',
+                "] }",
+                "```",
+                "",
+                "Rules:",
+                `- \`tempId\` must start with \`${REFLECTION_TEMP_PREFIX}\` and be unique within the plan; reference it in later ops as that same \`"${REFLECTION_TEMP_PREFIX}…"\` string.`,
+                "- Respect the structure rules — KNOWLEDGE only under a DOMAIN, bodies within {maxWords} words, no cycles. Invalid ops are rejected on apply, so plan only valid moves.",
+                '- If you have no confident changes to make, return `{ "operations": [] }`.',
+                "",
+                "Shape of every response:",
+                FRAGMENT_REFLECTION_BEGIN,
+                "<the plan JSON object>",
+                FRAGMENT_REFLECTION_END,
+            ],
+        },
+    ],
+    keys: ["maxWords", "firstLevelTarget"],
+};
+const CROW_FRAGMENT_REFLECTION_BIRTHDAY = "1970-01-01T00:00:00Z";
+const CROW_FRAGMENT_REFLECTION_TOOLS = [];
+/**
+ * Build the fragment reflection agent config - an invisible background agent that performs
+ * retrospection on one target agent's long-term memory per run and returns a single
+ * marker-wrapped reorganization plan.
+ */
+export function getFragmentReflectionAgent() {
+    const persona = createMessageContentFromTemplate(CROW_FRAGMENT_REFLECTION_AGENT_PERSONA, getDefaultPromptContext({
+        maxWords: String(FRAGMENT_MAX_WORDS),
+        firstLevelTarget: String(FRAGMENT_FIRST_LEVEL_TARGET),
+    }));
+    return {
+        id: FRAGMENT_REFLECTION_AGENT_ID,
+        type: SYSTEM_AGENT_TYPE,
+        name: CROW_FRAGMENT_REFLECTION_AGENT_NAME,
+        description: "Reflection agent that reviews a target agent's long-term memory and plans its reorganization. Not user-facing.",
+        workspace: path.join(env.CROW_SYSTEM_PATH, SYSTEM_AGENTS_PROJECT_DIR_NAME),
+        persona,
+        model: resolveSystemAgentModel(CLAUDE_MODELS.SONNET),
+        permissionMode: PERMISSION_MODE.DEFAULT,
+        settingSources: [],
+        availableTools: [],
+        toolConfig: {
+            mode: TOOL_MODE.RESTRICTED,
+            tools: CROW_FRAGMENT_REFLECTION_TOOLS,
+            autoApprovedTools: CROW_FRAGMENT_REFLECTION_TOOLS,
+        },
+        mcpServerIds: [],
+        persistSession: false,
+        excludeClaudeCodeSystemPrompt: true,
+        isSystemAgent: true,
+        isBackgroundAgent: true,
+        createdAt: CROW_FRAGMENT_REFLECTION_BIRTHDAY,
+        updatedAt: CROW_FRAGMENT_REFLECTION_BIRTHDAY,
+    };
+}
+//# sourceMappingURL=crow-fragment-reflection-agent.js.map