crow-central-agency 0.26.14 → 0.27.0

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, 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,7 +19,9 @@ 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";

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,10 +44,13 @@ 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({
-    type: z.literal("send_message"),
+    type: z.literal(CLIENT_MESSAGE_TYPE.SEND_MESSAGE),
     agentId: z.string(),
     message: z.string(),
 });
@@ -57,7 +60,7 @@ export const InjectMessageSchema = z.object({
     message: z.string(),
 });
 export const PermissionResponseWsSchema = z.object({
-    type: z.literal("permission_response"),
+    type: z.literal(CLIENT_MESSAGE_TYPE.PERMISSION_RESPONSE),
     agentId: z.string(),
     toolUseId: z.string(),
     decision: z.enum([PERMISSION_DECISION.ALLOW, PERMISSION_DECISION.DENY, PERMISSION_DECISION.ALLOW_ALWAYS]),
@@ -76,24 +79,24 @@ export const ClientMessageSchema = z.discriminatedUnion("type", [
     CommandMessageSchema,
 ]);
 export const AgentTextWsMessageSchema = z.object({
-    type: z.literal("agent_text"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_TEXT),
     agentId: z.string(),
     text: z.string(),
 });
 export const AgentActivityWsMessageSchema = z.object({
-    type: z.literal("agent_activity"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_ACTIVITY),
     agentId: z.string(),
     agentActivity: AgentActivitySchema,
 });
 export const AgentResultWsMessageSchema = z.object({
-    type: z.literal("agent_result"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_RESULT),
     agentId: z.string(),
     subtype: z.string(),
     totalCostUsd: z.number().optional(),
     durationMs: z.number().optional(),
 });
 export const AgentStatusWsMessageSchema = z.object({
-    type: z.literal("agent_status"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_STATUS),
     agentId: z.string(),
     status: z.enum([AGENT_STATUS.IDLE, AGENT_STATUS.ACTIVATING, AGENT_STATUS.STREAMING, AGENT_STATUS.COMPACTING]),
     messageSource: MessageSourceSchema.optional(),
@@ -113,7 +116,7 @@ export const AgentDeletedWsMessageSchema = z.object({
     agentId: z.string(),
 });
 export const AgentUsageWsMessageSchema = z.object({
-    type: z.literal("agent_usage"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_USAGE),
     agentId: z.string(),
     inputTokens: z.number(),
     outputTokens: z.number(),
@@ -122,7 +125,7 @@ export const AgentUsageWsMessageSchema = z.object({
     contextTotal: z.number(),
 });
 export const PermissionRequestWsMessageSchema = z.object({
-    type: z.literal("permission_request"),
+    type: z.literal(SERVER_MESSAGE_TYPE.PERMISSION_REQUEST),
     agentId: z.string(),
     toolUseId: z.string(),
     toolName: z.string(),
@@ -130,23 +133,23 @@ export const PermissionRequestWsMessageSchema = z.object({
     decisionReason: z.string().optional(),
 });
 export const PermissionCancelledWsMessageSchema = z.object({
-    type: z.literal("permission_cancelled"),
+    type: z.literal(SERVER_MESSAGE_TYPE.PERMISSION_CANCELLED),
     agentId: z.string(),
     toolUseId: z.string(),
 });
 export const ErrorWsMessageSchema = z.object({
-    type: z.literal("error"),
+    type: z.literal(SERVER_MESSAGE_TYPE.ERROR),
     agentId: z.string().optional(),
     code: z.string(),
     message: z.string(),
 });
 export const AgentMessageWsMessageSchema = z.object({
-    type: z.literal("agent_message"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_MESSAGE),
     agentId: z.string(),
     message: AgentMessageSchema,
 });
 export const AgentToolProgressWsMessageSchema = z.object({
-    type: z.literal("agent_tool_progress"),
+    type: z.literal(SERVER_MESSAGE_TYPE.AGENT_TOOL_PROGRESS),
     agentId: z.string(),
     toolName: z.string(),
     elapsedTimeSeconds: z.number(),
@@ -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,9 +237,20 @@ export const ServerMessageSchema = z.discriminatedUnion("type", [
     CircleDeletedWsMessageSchema,
     RelationshipCreatedWsMessageSchema,
     RelationshipDeletedWsMessageSchema,
+    FragmentCreatedWsMessageSchema,
+    FragmentUpdatedWsMessageSchema,
+    FragmentDeletedWsMessageSchema,
     AgentBuilderDraftUpdatedWsMessageSchema,
 ]);
 export function isAgentServerMessage(message) {
     return "agentId" in message && typeof message.agentId === "string";
 }
+const AGENT_LIFECYCLE_MESSAGE_TYPES = new Set([
+    SERVER_MESSAGE_TYPE.AGENT_CREATED,
+    SERVER_MESSAGE_TYPE.AGENT_UPDATED,
+    SERVER_MESSAGE_TYPE.AGENT_DELETED,
+]);
+export function isAgentLifecycleServerMessage(message) {
+    return AGENT_LIFECYCLE_MESSAGE_TYPES.has(message.type);
+}
 //# sourceMappingURL=websocket.schema.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

package/dist/bootstrap.js

@@ -16,6 +16,8 @@ import { PlacesManager } from "./services/places/places-manager.js";
 import { setupWebSocket } from "./server/setup-websocket.js";
 import { registerArtifactRoutes } from "./routes/artifact.routes.js";
 import { getArtifactsMcpServerDefinition } from "./mcp/artifacts/artifacts-mcp-server.js";
+import { getFragmentsMcpServerDefinition } from "./mcp/fragments/fragments-mcp-server.js";
+import { getFragmentsReflectionMcpServerDefinition } from "./mcp/fragments/fragments-reflection-mcp-server.js";
 import { getAgentsMcpServerDefinition } from "./mcp/agents/agents-mcp-server.js";
 import { getSuperAgentMcpServerDefinition } from "./mcp/agents/super-agent-mcp-server.js";
 import { getBuilderAgentMcpServerDefinition } from "./mcp/agents/builder-agent-mcp-server.js";
@@ -50,7 +52,12 @@ import { SensorManager } from "./sensors/sensor-manager.js";
 import { GeoLocationSensor } from "./sensors/geolocation-sensor.js";
 import { WeatherSensor } from "./sensors/weather-sensor.js";
 import { AgentCircleManager } from "./services/agent-circle-manager.js";
+import { RelationshipManager } from "./services/relationship-manager.js";
+import { FragmentManager } from "./services/fragment/fragment-manager.js";
+import { FragmentReflectionStateStore } from "./services/fragment/fragment-reflection-state-store.js";
+import { createFragmentReflectionRoutine } from "./routines/fragment-reflection-routine.js";
 import { registerCircleRoutes } from "./routes/circle.routes.js";
+import { registerFragmentRoutes } from "./routes/fragment.routes.js";
 import { registerGraphRoutes } from "./routes/graph.routes.js";
 import { DiscordBotManager } from "./bot-connectors/discord/discord-bot-manager.js";
 import { createDiscordRoutine } from "./routines/discord-routine.js";
@@ -82,7 +89,9 @@ export async function bootstrap(options) {
     const folderFileProvider = new FolderFileStoreProvider(env.CROW_SYSTEM_PATH);
     const storeProvider = new FileObjectStoreProvider(env.CROW_SYSTEM_PATH);
     const systemSettingsManager = new SystemSettingsManager(storeProvider);
-    const circleManager = new AgentCircleManager(storeProvider, broadcaster);
+    const relationshipManager = new RelationshipManager(storeProvider);
+    await relationshipManager.initialize();
+    const circleManager = new AgentCircleManager(storeProvider, relationshipManager, broadcaster);
     await circleManager.initialize();
     const registry = new AgentRegistry(storeProvider, folderFileProvider, broadcaster, circleManager);
     await registry.initialize();
@@ -94,7 +103,9 @@ export async function bootstrap(options) {
     await feedManager.initialize();
     const artifactManager = new ArtifactManager(storeProvider, registry, circleManager);
     await artifactManager.initialize();
-    const documentSearchService = new DocumentSearchService(artifactManager, taskManager, registry, circleManager);
+    const fragmentManager = new FragmentManager(folderFileProvider, storeProvider, relationshipManager, broadcaster);
+    await fragmentManager.initialize();
+    const documentSearchService = new DocumentSearchService(artifactManager, taskManager, registry, circleManager, fragmentManager);
     await documentSearchService.initialize();
     const placesManager = new PlacesManager();
     const connectorManager = new ConnectorManager(storeProvider, registry, crowScheduler);
@@ -108,7 +119,7 @@ export async function bootstrap(options) {
     const sensorManager = new SensorManager(storeProvider);
     sensorManager.registerSensor(new GeoLocationSensor(placesManager));
     sensorManager.registerSensor(new WeatherSensor());
-    const runtimeManager = new AgentRuntimeManager(storeProvider, broadcaster, registry, mcpManager, sessionManager, messageQueue, taskManager, sensorManager, circleManager);
+    const runtimeManager = new AgentRuntimeManager(storeProvider, broadcaster, registry, mcpManager, sessionManager, messageQueue, taskManager, sensorManager, circleManager, fragmentManager);
     await runtimeManager.initialize();
     const worldBuilderDraftStore = new WorldBuilderDraftStore(storeProvider);
     const worldBuilderService = new WorldBuilderService(runtimeManager, worldBuilderDraftStore, registry, circleManager, mcpManager, broadcaster);
@@ -127,6 +138,9 @@ export async function bootstrap(options) {
     routineManager.addRoutine(feedNewItemsRoutine);
     const gmailNotificationRoutine = createGmailNotificationRoutine(registry, taskManager, runtimeManager, connectorManager, sensorManager);
     routineManager.addRoutine(gmailNotificationRoutine);
+    const fragmentReflectionStateStore = new FragmentReflectionStateStore(storeProvider);
+    const fragmentReflectionRoutine = createFragmentReflectionRoutine(registry, runtimeManager, fragmentManager, fragmentReflectionStateStore);
+    routineManager.addRoutine(fragmentReflectionRoutine);
     // Discord bot manager — creates per-agent bots for agents with discordConfig
     const discordBotManager = new DiscordBotManager(registry, runtimeManager);
     await discordBotManager.initialize();
@@ -134,7 +148,9 @@ export async function bootstrap(options) {
     routineManager.addRoutine(discordRoutine);
     // Register built-in MCP servers
     mcpManager.registerMcpServer(getArtifactsMcpServerDefinition(artifactManager, registry, circleManager, sensorManager));
-    mcpManager.registerMcpServer(getAgentsMcpServerDefinition(registry, runtimeManager, taskManager, documentSearchService, circleManager));
+    mcpManager.registerMcpServer(getFragmentsMcpServerDefinition(fragmentManager, runtimeManager));
+    mcpManager.registerMcpServer(getFragmentsReflectionMcpServerDefinition(fragmentManager, runtimeManager, documentSearchService));
+    mcpManager.registerMcpServer(getAgentsMcpServerDefinition(registry, runtimeManager, taskManager, documentSearchService, circleManager, fragmentManager));
     mcpManager.registerMcpServer(getTasksMcpServerDefinition(taskManager, circleManager, sensorManager));
     mcpManager.registerMcpServer(getFeedMcpServerDefinition(registry, feedManager, sensorManager, systemSettingsManager));
     mcpManager.registerMcpServer(getAudioMcpServerDefinition(registry, artifactManager));
@@ -164,7 +180,8 @@ export async function bootstrap(options) {
     await registerMcpRoutes(server, mcpManager);
     await registerSensorRoutes(server, sensorManager);
     await registerCircleRoutes(server, circleManager, registry);
-    await registerGraphRoutes(server, circleManager, registry, runtimeManager);
+    await registerFragmentRoutes(server, fragmentManager, registry);
+    await registerGraphRoutes(server, circleManager, registry, runtimeManager, fragmentManager);
     await registerFeedRoutes(server, feedManager);
     await registerSystemSettingsRoutes(server, systemSettingsManager);
     await registerConnectorsRoutes(server, connectorManager);

package/dist/core/error/app-error.types.js

@@ -24,6 +24,7 @@ export const APP_ERROR_CODES = {
     SDK_ERROR: "sdk_error",
     WS_ERROR: "ws_error",
     CIRCLE_NOT_FOUND: "circle_not_found",
+    FRAGMENT_NOT_FOUND: "fragment_not_found",
     RELATIONSHIP_NOT_FOUND: "relationship_not_found",
     DUPLICATE_RELATIONSHIP: "duplicate_relationship",
     CIRCLE_IMMUTABLE: "circle_immutable",

package/dist/mcp/agents/agents-mcp-server.js

@@ -2,16 +2,16 @@ import { defineMcpTool } from "../crow-mcp-manager-utils.js";
 import { getListAgentsToolConfig } from "./list-agents.js";
 import { getInvokeAgentToolConfig } from "./invoke-agent.js";
 import { getSearchWorkspaceToolConfig } from "./search-workspace.js";
-import { CROW_NARRATIVE_ARCHITECT_AGENT_ID, CROW_WORLD_BUILDER_AGENT_ID } from "../../_shared/index.js";
+import { CROW_NARRATIVE_ARCHITECT_AGENT_ID, CROW_WORLD_BUILDER_AGENT_ID, FRAGMENT_REFLECTION_AGENT_ID, } from "../../_shared/index.js";
 export const CROW_AGENTS_MCP_SERVER_NAME = "crow-agents";
-export function getAgentsMcpServerDefinition(registry, runtimeManager, taskManager, documentSearchService, circleManager) {
+export function getAgentsMcpServerDefinition(registry, runtimeManager, taskManager, documentSearchService, circleManager, fragmentManager) {
     return {
         name: CROW_AGENTS_MCP_SERVER_NAME,
-        disallowedAgentIds: [CROW_NARRATIVE_ARCHITECT_AGENT_ID, CROW_WORLD_BUILDER_AGENT_ID],
+        disallowedAgentIds: [CROW_NARRATIVE_ARCHITECT_AGENT_ID, CROW_WORLD_BUILDER_AGENT_ID, FRAGMENT_REFLECTION_AGENT_ID],
         getTools: (agentId) => [
             defineMcpTool(getListAgentsToolConfig(agentId, registry)),
             defineMcpTool(getInvokeAgentToolConfig(agentId, registry, runtimeManager, taskManager)),
-            defineMcpTool(getSearchWorkspaceToolConfig(agentId, documentSearchService, taskManager, circleManager)),
+            defineMcpTool(getSearchWorkspaceToolConfig(agentId, documentSearchService, taskManager, circleManager, fragmentManager)),
         ],
     };
 }