crow-central-agency 0.26.6 → 0.26.8

package/README.md

@@ -107,6 +107,9 @@ See `.env.example` for the full list, including:
 - `FEED_TEXT_GENERATION_*` — optional OpenAI-compatible endpoint used by the feed manager to summarize feed items into a consistent length for better agent consumption.
 - `FEED_MAX_SUMMARIZATION_ITEMS` — cap on items summarized per refresh (default: `50`). Items left unsummarized become retry candidates on the next refresh; when the retry backlog exceeds the cap, retries are skipped so a feed isn't permanently blocked by hundreds or thousands of stuck unsummarized items.
 - `AUDIO_GENERATION_*` — optional Gemini TTS configuration that powers the play-message button on the agent console. See [Audio generation](#audio-generation) below.
+- `PLACES_DEFAULT_SOURCE` — default provider for the Places tools when a lookup doesn't request one explicitly: `OSM` (default, no key needed) or `GOOGLE`. `GOOGLE` requires `GOOGLE_PLACES_API_KEY`; without it, lookups fall back to OSM. See [Places](#places) below.
+- `GOOGLE_PLACES_API_KEY` — Google API key that registers the Google Places adapter alongside the default OSM source. See [Places](#places) below.
+- `PHOTON_API_URL` / `OVERPASS_INTERPRETER_URL` — override the geocoding / nearby-search endpoints the OSM places source calls (default to the public Photon and Overpass instances).
 - `GOOGLE_CONNECTOR_CLIENT_ID` / `GOOGLE_CONNECTOR_CLIENT_SECRET` / `CONNECTOR_CALLBACK_URL` — OAuth credentials for the Google connector. Required if you want agents to access Gmail / Calendar / Contacts. See [Connectors](#connectors) below.
 - `OAUTH_PENDING_STATE_TTL_MS` — how long an unfinished OAuth flow stays valid before being swept (default: `600_000`, i.e. 10 minutes).
 - `OTEL_*` — optional OpenTelemetry export.
@@ -139,6 +142,73 @@ The `AUDIO_GENERATION_API_KEY` must be a Google API key with access to the
 You can use the same key as `TEXT_GENERATION_API_KEY` if that is also a
 Gemini-backed configuration, but the two are read independently.
 
+## Places
+
+The **Places** MCP server gives agents location tools — `geocode_place`,
+`search_nearby_places`, and `get_place_details`. It is enabled per-agent from
+the **MCP Servers** section of the agent editor.
+
+Two providers back these tools:
+
+- **OSM** (default) — uses the public OpenStreetMap-based services (Photon for
+  geocoding, Overpass for nearby search). No API key required, so the Places
+  tools work out of the box.
+- **GOOGLE** — uses the Google Places API (New) and Geocoding API for richer
+  results. Opt in by setting `GOOGLE_PLACES_API_KEY`.
+
+`PLACES_DEFAULT_SOURCE` selects which provider serves lookups that don't name a
+source explicitly (`OSM` or `GOOGLE`, defaulting to `OSM`). When
+`GOOGLE_PLACES_API_KEY` is set, the Google adapter is registered alongside OSM;
+if `PLACES_DEFAULT_SOURCE=GOOGLE` is set without a key, lookups fall back to OSM.
+
+### Configuration
+
+```bash
+PLACES_DEFAULT_SOURCE=GOOGLE
+GOOGLE_PLACES_API_KEY=<your Google API key>
+```
+
+### Getting a Google Places API key
+
+The key is a plain Google API key (not an OAuth client — unrelated to the
+Google connector setup below).
+
+**1. Sign in to Google Cloud Console.**
+
+Go to [console.cloud.google.com](https://console.cloud.google.com/) and select
+(or create) a project. Unlike the OAuth connector, the Places and Geocoding
+APIs are **paid** and require a billing account on the project. Google provides
+a recurring monthly free allotment, but you must still enable billing to use
+the key.
+
+**2. Enable the required APIs.**
+
+Open **APIs & Services → Library** and enable both:
+
+- **Places API (New)** — powers `search_nearby_places` and `get_place_details`.
+- **Geocoding API** — powers reverse geocoding for `geocode_place`.
+
+Click each result, then click **Enable**.
+
+**3. Create the API key.**
+
+Open **APIs & Services → Credentials → Create Credentials → API key**. Copy the
+generated key.
+
+> [!NOTE]
+> Restrict the key to just the **Places API (New)** and **Geocoding API** under
+> the key's **API restrictions** so a leaked key can't be used against other
+> Google services.
+
+**4. Add the key to your `.env` and restart Crow.**
+
+```bash
+GOOGLE_PLACES_API_KEY=<paste the API key>
+PLACES_DEFAULT_SOURCE=GOOGLE
+```
+
+Restart the server so it picks up the new env vars.
+
 ## Connectors
 
 Connectors are a framework-level capability - they are not tools agents call

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

@@ -1,4 +1,6 @@
 /** Well-known ID for the Crow system agent */
 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__";
 //# sourceMappingURL=system-agent.js.map

package/dist/_shared/index.js

@@ -1,8 +1,8 @@
-export { CLAUDE_MODELS, GITHUB_COPILOT_MODELS, CLAUDE_CODE_MODEL_OPTIONS, ModelOptionSchema, REASONING_EFFORT, ReasoningEffortSchema, CLAUDE_DEFAULT_MODEL, COPILOT_DEFAULT_MODEL, AgentIdSchema, AgentConfigSchema, AgentConfigTemplateSchema, CreateAgentInputSchema, UpdateAgentInputSchema, ToolConfigSchema, PermissionModeSchema, SettingSourceSchema, DiscoveredSkillSchema, LoopConfigSchema, ConfiguredFeedSchema, MAX_LOOP_TIMES, PERMISSION_MODE, SETTING_SOURCE, DEFAULT_SETTING_SOURCES, TOOL_MODE, DEFAULT_CLAUDE_CODE_AVAILABLE_TOOLS, DEFAULT_GITHUB_COPILOT_AVAILABLE_TOOLS, DEFAULT_AVAILABLE_TOOLS_BY_TYPE, SUBAGENT_TOOL_NAME, AGENT_TYPE, } from "./schemas/agent.schema.js";
+export { CLAUDE_MODELS, GITHUB_COPILOT_MODELS, CLAUDE_CODE_MODEL_OPTIONS, ModelOptionSchema, REASONING_EFFORT, ReasoningEffortSchema, CLAUDE_DEFAULT_MODEL, COPILOT_DEFAULT_MODEL, AgentIdSchema, AgentConfigSchema, AgentConfigTemplateSchema, CreateAgentInputSchema, UpdateAgentInputSchema, ToolConfigSchema, PermissionModeSchema, SettingSourceSchema, DiscoveredSkillSchema, LoopConfigSchema, ConfiguredFeedSchema, MAX_LOOP_TIMES, PERMISSION_MODE, SETTING_SOURCE, DEFAULT_SETTING_SOURCES, TOOL_MODE, DEFAULT_CLAUDE_CODE_AVAILABLE_TOOLS, DEFAULT_GITHUB_COPILOT_AVAILABLE_TOOLS, DEFAULT_AVAILABLE_TOOLS_BY_TYPE, SUBAGENT_TOOL_NAME, AGENT_TYPE, AgentTypeSchema, DEFAULT_AGENT_TYPE, AGENT_NAME_MAX_LENGTH, } from "./schemas/agent.schema.js";
 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, } 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, 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, AgentBuilderDraftUpdatedWsMessageSchema, isAgentServerMessage, 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, ArtifactTagsUpdateSchema, } from "./schemas/artifact.schema.js";
@@ -13,11 +13,13 @@ export { AddFeedInputSchema, DetectFeedsInputSchema, } from "./schemas/feed.sche
 export { DiscordConfigSchema } from "./schemas/discord-config.schema.js";
 export { SuperCrowSettingsSchema, UpdateSuperCrowSettingsInputSchema, DashboardSettingsSchema, UpdateDashboardSettingsInputSchema, } from "./schemas/system-settings.schema.js";
 export { SystemCapabilitiesSchema } from "./schemas/system-capabilities.schema.js";
+export { GENERATION_TYPE, GenerationTypeSchema, GenerateRequestSchema, } from "./schemas/generation.schema.js";
+export { AGENT_BUILDER_LIMITS, AGENT_BUILDER_WORD_BUDGET, AGENT_BUILDER_DRAFT_STATUS, AgentBuilderDraftStatusSchema, AgentBuilderBuiltAgentSchema, AgentBuilderBuildResultSchema, FleetAgentSchema, FleetResponseSchema, AgentBuilderDraftSchema, AgentBuilderDesignRequestSchema, AgentBuilderPatchRequestSchema, FleetNamedRefSchema, FleetAgentViewSchema, AgentBuilderDraftViewSchema, AgentBuilderDraftResponseSchema, AgentBuilderDraftMutationResponseSchema, } from "./schemas/agent-builder.schema.js";
 export { applyAgentOrder } from "./utils/apply-agent-order.js";
 export { MODEL_ALIASES, resolveModel } 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 } 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, } from "./constants/system-agent.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-builder.schema.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { AGENT_NAME_MAX_LENGTH, AgentTypeSchema } from "./agent.schema.js";
+export const AgentBuilderBuiltAgentSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+});
+/**
+ * Outcome of a best-effort fleet build: agents that were created and agents that failed. A
+ * backend-produced response type, not a request contract. On full success the draft goes COMPLETED;
+ * on partial failure the failed agents stay so the build can be retried.
+ */
+export const AgentBuilderBuildResultSchema = z.object({
+    created: z.array(AgentBuilderBuiltAgentSchema),
+    failed: z.array(z.object({ name: z.string(), error: z.string() })),
+});
+/**
+ * Lifecycle of the single active draft.
+ */
+export const AGENT_BUILDER_DRAFT_STATUS = {
+    READY: "ready",
+    BUILDING: "building",
+    COMPLETED: "completed",
+};
+export const AgentBuilderDraftStatusSchema = z.enum([
+    AGENT_BUILDER_DRAFT_STATUS.READY,
+    AGENT_BUILDER_DRAFT_STATUS.BUILDING,
+    AGENT_BUILDER_DRAFT_STATUS.COMPLETED,
+]);
+/**
+ * Word budgets the World Builder is asked to stay within.
+ */
+export const AGENT_BUILDER_WORD_BUDGET = {
+    DESCRIPTION: 30,
+    PERSONA_BRIEF: 50,
+    AGENT_MD_BRIEF: 150,
+};
+export const AGENT_BUILDER_LIMITS = {
+    NAME: AGENT_NAME_MAX_LENGTH,
+    DESCRIPTION: 400,
+    PERSONA_BRIEF: 600,
+    AGENT_MD_BRIEF: 2000,
+    PROJECT_PATH: 1000,
+    INPUT: 4000,
+};
+/**
+ * A single agent designed by the World Builder.
+ */
+export const FleetAgentSchema = z.object({
+    name: z.string().min(1).max(AGENT_BUILDER_LIMITS.NAME),
+    description: z.string().min(1).max(AGENT_BUILDER_LIMITS.DESCRIPTION),
+    personaBrief: z.string().min(1).max(AGENT_BUILDER_LIMITS.PERSONA_BRIEF),
+    agentMdBrief: z.string().min(1).max(AGENT_BUILDER_LIMITS.AGENT_MD_BRIEF).optional(),
+    mcpServerIds: z.array(z.string().min(1)).optional(),
+    circleIds: z.array(z.string().min(1)).optional(),
+});
+/** The World Builder's JSON output */
+export const FleetResponseSchema = z.object({
+    agents: z.array(FleetAgentSchema),
+    existingAgents: z.array(AgentBuilderBuiltAgentSchema).optional(),
+});
+export const AgentBuilderDraftSchema = z.object({
+    projectPath: z.string().min(1).max(AGENT_BUILDER_LIMITS.PROJECT_PATH).optional(),
+    agentType: AgentTypeSchema.optional(),
+    status: AgentBuilderDraftStatusSchema.default(AGENT_BUILDER_DRAFT_STATUS.READY),
+    lastBuildResult: AgentBuilderBuildResultSchema.optional(),
+    existingAgents: z.array(AgentBuilderBuiltAgentSchema).optional(),
+    builtAgents: z.array(AgentBuilderBuiltAgentSchema).optional(),
+    agents: z.array(FleetAgentSchema),
+});
+export const AgentBuilderDesignRequestSchema = z.object({
+    input: z.string().min(1).max(AGENT_BUILDER_LIMITS.INPUT),
+});
+export const AgentBuilderPatchRequestSchema = z.object({
+    projectPath: z.string().max(AGENT_BUILDER_LIMITS.PROJECT_PATH).optional(),
+    agentType: AgentTypeSchema.optional(),
+});
+export const FleetNamedRefSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+});
+export const FleetAgentViewSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    personaBrief: z.string(),
+    agentMdBrief: z.string().optional(),
+    mcpServers: z.array(FleetNamedRefSchema),
+    circles: z.array(FleetNamedRefSchema),
+});
+/**
+ * The active draft prepared for display: a resolved view of {@link AgentBuilderDraft} whose agents
+ * carry friendly names instead of raw ids, plus the lifecycle `status` and the most recent
+ * `lastBuildResult`. Backend-produced response type, not a request contract.
+ */
+export const AgentBuilderDraftViewSchema = z.object({
+    projectPath: z.string().optional(),
+    agentType: AgentTypeSchema.optional(),
+    status: AgentBuilderDraftStatusSchema,
+    lastBuildResult: AgentBuilderBuildResultSchema.optional(),
+    existingAgents: z.array(AgentBuilderBuiltAgentSchema).optional(),
+    builtAgents: z.array(AgentBuilderBuiltAgentSchema).optional(),
+    agents: z.array(FleetAgentViewSchema),
+});
+/** Response from `GET /api/agent-builder/draft` — the active draft, or null when none exists. */
+export const AgentBuilderDraftResponseSchema = z.object({
+    draft: AgentBuilderDraftViewSchema.nullable(),
+});
+/** Response from the design and fleet-config endpoints — the updated draft (always present). */
+export const AgentBuilderDraftMutationResponseSchema = z.object({
+    draft: AgentBuilderDraftViewSchema,
+});
+//# sourceMappingURL=agent-builder.schema.js.map

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

@@ -188,12 +188,16 @@ export const AGENT_TYPE = {
     GITHUB_COPILOT: "GITHUB_COPILOT",
 };
 export const AgentTypeSchema = z.enum([AGENT_TYPE.CLAUDE_CODE, AGENT_TYPE.GITHUB_COPILOT]);
+/** Default agent type applied when none is specified. */
+export const DEFAULT_AGENT_TYPE = AGENT_TYPE.CLAUDE_CODE;
 /** Default builtin tool catalog per provider, used to seed new agents and the editor's tool picker. */
 export const DEFAULT_AVAILABLE_TOOLS_BY_TYPE = {
     [AGENT_TYPE.CLAUDE_CODE]: DEFAULT_CLAUDE_CODE_AVAILABLE_TOOLS,
     [AGENT_TYPE.GITHUB_COPILOT]: DEFAULT_GITHUB_COPILOT_AVAILABLE_TOOLS,
 };
 export const AgentIdSchema = z.uuid();
+/** Maximum length of an agent name, enforced on the create/update input path. */
+export const AGENT_NAME_MAX_LENGTH = 50;
 /** Maximum number of time entries allowed in a loop config */
 export const MAX_LOOP_TIMES = 6;
 /** Loop configuration */
@@ -249,7 +253,7 @@ export const AgentVoiceConfigSchema = z.object({
  */
 export const AgentConfigSchema = z.object({
     id: AgentIdSchema,
-    type: AgentTypeSchema.default(AGENT_TYPE.CLAUDE_CODE),
+    type: AgentTypeSchema.default(DEFAULT_AGENT_TYPE),
     name: z.string().min(1).max(64),
     description: z.string().optional(),
     workspace: z.string().min(1).optional(),
@@ -283,8 +287,8 @@ export const AgentConfigSchema = z.object({
  * Input for creating a new agent - only required fields
  */
 export const CreateAgentInputSchema = z.object({
-    type: AgentTypeSchema.default(AGENT_TYPE.CLAUDE_CODE),
-    name: z.string().min(1).max(50),
+    type: AgentTypeSchema.default(DEFAULT_AGENT_TYPE),
+    name: z.string().min(1).max(AGENT_NAME_MAX_LENGTH),
     description: z.string().optional(),
     workspace: z.string().min(1).optional(),
     persona: z.string().optional(),
@@ -308,12 +312,13 @@ export const CreateAgentInputSchema = z.object({
  * Input for updating an existing agent - all fields optional
  */
 export const UpdateAgentInputSchema = z.object({
-    name: z.string().min(1).max(50).optional(),
+    name: z.string().min(1).max(AGENT_NAME_MAX_LENGTH).optional(),
     description: z.string().optional(),
     workspace: z.string().optional(),
     persona: z.string().optional(),
     model: z.string().optional(),
-    effort: ReasoningEffortSchema.optional(),
+    // null explicitly clears the effort (back to provider default); undefined leaves it unchanged.
+    effort: ReasoningEffortSchema.nullish(),
     permissionMode: PermissionModeSchema.optional(),
     settingSources: z.array(SettingSourceSchema).optional(),
     settingSourceConfig: SettingSourceConfigInputSchema.optional(),

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

@@ -0,0 +1,29 @@
+import { z } from "zod";
+/** Kind of artifact the Narrative Architect produces. Doubles as the requested operation. */
+export const GENERATION_TYPE = {
+    PERSONA: "persona",
+    AGENT_MD: "agentmd",
+};
+export const GenerationTypeSchema = z.enum([GENERATION_TYPE.PERSONA, GENERATION_TYPE.AGENT_MD]);
+/**
+ * Structured generation request. `type` selects persona vs AGENT.md; the optional hints describe the
+ * agent being authored. Presence of `currentPersona` / `currentAgentMd` switches the operation from
+ * author/generate to refine/reinforce.
+ */
+/** Upper bounds keep the always-reachable generation endpoint from driving unbounded token usage. */
+export const GENERATION_LIMITS = {
+    PROMPT: 4000,
+    NAME: 200,
+    DESCRIPTION: 2000,
+    PERSONA: 20000,
+    AGENT_MD: 50000,
+};
+export const GenerateRequestSchema = z.object({
+    type: GenerationTypeSchema,
+    prompt: z.string().min(1).max(GENERATION_LIMITS.PROMPT),
+    name: z.string().max(GENERATION_LIMITS.NAME).optional(),
+    description: z.string().max(GENERATION_LIMITS.DESCRIPTION).optional(),
+    currentPersona: z.string().max(GENERATION_LIMITS.PERSONA).optional(),
+    currentAgentMd: z.string().max(GENERATION_LIMITS.AGENT_MD).optional(),
+});
+//# sourceMappingURL=generation.schema.js.map

package/dist/_shared/schemas/message-source.schema.js

@@ -11,6 +11,7 @@ export const MESSAGE_SOURCE_TYPE = {
     NOTIFICATION: "NOTIFICATION",
     DISCORD: "DISCORD",
     COMMAND: "COMMAND",
+    INTERNAL: "INTERNAL",
 };
 /** Zod schema for message source — identifies who originated a message */
 export const MessageSourceSchema = z.discriminatedUnion("sourceType", [
@@ -29,5 +30,6 @@ export const MessageSourceSchema = z.discriminatedUnion("sourceType", [
         isDm: z.boolean(),
     }),
     z.object({ sourceType: z.literal(MESSAGE_SOURCE_TYPE.COMMAND), command: AgentCommandSchema }),
+    z.object({ sourceType: z.literal(MESSAGE_SOURCE_TYPE.INTERNAL) }),
 ]);
 //# sourceMappingURL=message-source.schema.js.map

package/dist/_shared/schemas/system-capabilities.schema.js

@@ -7,7 +7,8 @@ import { ModelOptionSchema } from "./agent.schema.js";
 export const SystemCapabilitiesSchema = z.object({
     /** True when the audio generation provider, API key, and model are all configured. */
     audioGeneration: z.boolean(),
-    /** True when the chat-completion text generation provider is configured (powers persona / AGENT.md generation). */
+    // True when persona / AGENT.md generation is available. Backed by the internal Narrative Architect
+    // (Claude Code runtime), so effectively always available.
     textGeneration: z.boolean(),
     /** True when the shared Copilot SDK client started successfully (Copilot agents can run). */
     copilotAvailable: z.boolean(),

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

@@ -7,6 +7,7 @@ import { AgentCircleSchema, RelationshipSchema } from "./agent-circle.schema.js"
 import { AGENT_STATUS, AgentActivitySchema } from "./agent-runtime-state.schema.js";
 import { MessageSourceSchema } from "./message-source.schema.js";
 import { AgentCommandSchema } from "./agent-command.schema.js";
+import { AgentBuilderDraftViewSchema } from "./agent-builder.schema.js";
 /**
  * WebSocket message types - Client -> Server
  */
@@ -43,6 +44,7 @@ export const SERVER_MESSAGE_TYPE = {
     CIRCLE_DELETED: "circle_deleted",
     RELATIONSHIP_CREATED: "relationship_created",
     RELATIONSHIP_DELETED: "relationship_deleted",
+    AGENT_BUILDER_DRAFT_UPDATED: "agent_builder_draft_updated",
 };
 export const SendMessageSchema = z.object({
     type: z.literal("send_message"),
@@ -190,6 +192,11 @@ export const RelationshipDeletedWsMessageSchema = z.object({
     type: z.literal(SERVER_MESSAGE_TYPE.RELATIONSHIP_DELETED),
     relationshipId: 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),
+    draft: AgentBuilderDraftViewSchema.nullable(),
+});
 /** Server -> Client discriminated union for runtime parsing */
 export const ServerMessageSchema = z.discriminatedUnion("type", [
     AgentTextWsMessageSchema,
@@ -215,5 +222,9 @@ export const ServerMessageSchema = z.discriminatedUnion("type", [
     CircleDeletedWsMessageSchema,
     RelationshipCreatedWsMessageSchema,
     RelationshipDeletedWsMessageSchema,
+    AgentBuilderDraftUpdatedWsMessageSchema,
 ]);
+export function isAgentServerMessage(message) {
+    return "agentId" in message && typeof message.agentId === "string";
+}
 //# sourceMappingURL=websocket.schema.js.map

package/dist/agents/crow-narrative-architect-agent.js

@@ -0,0 +1,93 @@
+import { PERMISSION_MODE, TOOL_MODE, CLAUDE_MODELS, CROW_NARRATIVE_ARCHITECT_AGENT_ID, AGENT_TYPE, } from "../_shared/index.js";
+import path from "node:path";
+import { env } from "../config/env.js";
+import { createMessageContentFromTemplate, getDefaultPromptContext } from "../utils/message-template.js";
+import { SYSTEM_AGENTS_PROJECT_DIR_NAME } from "../config/constants.js";
+import { WORLD_BUILDER_BEGIN, WORLD_BUILDER_END } from "../services/world-builder/world-builder.constants.js";
+const CROW_NARRATIVE_ARCHITECT_AGENT_NAME = "Crow Narrative Architect";
+const CROW_NARRATIVE_ARCHITECT_AGENT_PERSONA = {
+    role: "system",
+    content: [
+        {
+            content: [
+                "You are the Narrative Architect for Crow Central Agency: the internal specialist who authors the",
+                "identity and operating doctrine of other agents. Each request asks for exactly one artifact, of",
+                "one of two kinds, and you return that artifact finished and ready to use — you are an authoring",
+                "engine, not a conversational assistant, and you never negotiate, ask follow-up questions, or hedge.",
+                "",
+                "The two artifacts you produce:",
+                "- A PERSONA: the second-person character brief that defines who an agent is, not how it operates.",
+                '  Written as direct address ("You are...") in present tense, it establishes the agent\'s role and',
+                "  character, its inner voice and temperament, and the register and manner in which it speaks. It is",
+                "  identity, not procedure: keep workflows, tool usage, step-by-step decision rules, and operating",
+                "  conventions out, as those belong in the AGENT.md. A strong persona reads as one coherent character",
+                "  in one or two short paragraphs of cohesive prose (roughly 100 words or fewer) — no labeled",
+                "  sections, no bold headers, and no checklist of dimensions or list of adjectives.",
+                "- An AGENT.md: the durable operating manual loaded into every one of that agent's sessions. Written",
+                "  in clear Markdown with focused headings and tight bullet points, it captures purpose,",
+                "  responsibilities, conventions, and concrete do/don't rules the agent must follow.",
+                "",
+                "Craft principles:",
+                "- Write with directorial intent. Every line earns its place; favor precision and concrete guidance",
+                "  over length, filler, or generic boilerplate that could describe any agent.",
+                "- Persona and AGENT.md are complementary, never overlapping: identity lives in the persona, operating",
+                "  doctrine in the AGENT.md. Never let a persona drift into procedure. Length is a cost — prefer the",
+                "  shortest version that fully captures the artifact.",
+                "- Ground the artifact in the request: take cues from the agent's name, description, and the user's",
+                "  prompt, and match the domain, register, and seniority they imply.",
+                "- When the request includes a current persona or AGENT.md to refine, treat it as authoritative",
+                "  source material: preserve what works and its established voice, apply the requested change, sharpen",
+                "  weak passages, and return a coherent whole — never discard good material or restart from scratch.",
+                "- Author in the artifact's own voice only. Do not address the requester or describe what you did.",
+                "",
+                "Output contract (strict, non-negotiable):",
+                `- Emit ONLY the finished artifact, wrapped exactly between a line containing ${WORLD_BUILDER_BEGIN}`,
+                `  before it and a line containing ${WORLD_BUILDER_END} after it.`,
+                "- Between those markers is the artifact verbatim — the exact text to be saved, with no enclosing",
+                "  code fences.",
+                "- Output nothing outside the markers: no preamble, no greeting, no commentary, no explanation, and",
+                "  no restatement of the request. The very first characters you emit are the begin marker.",
+                "",
+                "Shape of every response:",
+                WORLD_BUILDER_BEGIN,
+                "<the persona or AGENT.md, exactly as it should be stored>",
+                WORLD_BUILDER_END,
+            ],
+        },
+    ],
+};
+const CROW_NARRATIVE_ARCHITECT_BIRTHDAY = "1970-01-01T00:00:00Z";
+const CROW_NARRATIVE_ARCHITECT_TOOLS = [];
+/**
+ * Build the Narrative Architect agent config - an internal, non-visible system agent that authors
+ * personas and generates/reinforces AGENT.md on the Claude Code runtime. Background only; never
+ * persists a session and carries no tools.
+ */
+export function getNarrativeArchitectAgent() {
+    const persona = createMessageContentFromTemplate(CROW_NARRATIVE_ARCHITECT_AGENT_PERSONA, getDefaultPromptContext());
+    return {
+        id: CROW_NARRATIVE_ARCHITECT_AGENT_ID,
+        type: AGENT_TYPE.CLAUDE_CODE,
+        name: CROW_NARRATIVE_ARCHITECT_AGENT_NAME,
+        description: "Internal generation specialist. Authors agent personas and generates/reinforces AGENT.md.",
+        workspace: path.join(env.CROW_SYSTEM_PATH, SYSTEM_AGENTS_PROJECT_DIR_NAME),
+        persona,
+        model: CLAUDE_MODELS.SONNET,
+        permissionMode: PERMISSION_MODE.DEFAULT,
+        settingSources: [],
+        availableTools: [],
+        toolConfig: {
+            mode: TOOL_MODE.RESTRICTED,
+            tools: CROW_NARRATIVE_ARCHITECT_TOOLS,
+            autoApprovedTools: CROW_NARRATIVE_ARCHITECT_TOOLS,
+        },
+        mcpServerIds: [],
+        persistSession: false,
+        excludeClaudeCodeSystemPrompt: true,
+        isSystemAgent: true,
+        isBackgroundAgent: true,
+        createdAt: CROW_NARRATIVE_ARCHITECT_BIRTHDAY,
+        updatedAt: CROW_NARRATIVE_ARCHITECT_BIRTHDAY,
+    };
+}
+//# sourceMappingURL=crow-narrative-architect-agent.js.map

package/dist/agents/crow-world-builder-agent.js

@@ -0,0 +1,98 @@
+import { PERMISSION_MODE, TOOL_MODE, CLAUDE_MODELS, CROW_WORLD_BUILDER_AGENT_ID, AGENT_TYPE, AGENT_NAME_MAX_LENGTH, } from "../_shared/index.js";
+import path from "node:path";
+import { env } from "../config/env.js";
+import { createMessageContentFromTemplate, getDefaultPromptContext } from "../utils/message-template.js";
+import { SYSTEM_AGENTS_PROJECT_DIR_NAME } from "../config/constants.js";
+import { WORLD_BUILDER_BEGIN, WORLD_BUILDER_END } from "../services/world-builder/world-builder.constants.js";
+import { LIST_AGENTS_TOOL_NAME } from "../mcp/agents/list-agents.js";
+import { GET_AGENT_DETAILS_TOOL_NAME } from "../mcp/agents/get-agent-details.js";
+import { LIST_MCP_SERVERS_TOOL_NAME } from "../mcp/agents/list-mcp-servers.js";
+const CROW_WORLD_BUILDER_AGENT_NAME = "Crow World Builder";
+const CROW_WORLD_BUILDER_AGENT_PERSONA = {
+    role: "system",
+    content: [
+        {
+            content: [
+                "You are the World Builder for Crow Central Agency: the internal architect who designs a fleet of",
+                "agents from a single requirement. Given what the user wants to accomplish, you decide which agents",
+                "should exist, what each one is for, and how they fit together as a team. You are a designer of",
+                "teams, not a conversational assistant — you do not negotiate, ask follow-up questions, or hedge.",
+                "",
+                "Director, not author:",
+                "- You do NOT write finished personas or AGENT.md text. For each agent you emit directional BRIEFS",
+                "  that instruct a separate authoring specialist who renders the finished artifacts from them.",
+                "- A `personaBrief` is a directive describing the identity and character the agent should have — who",
+                "  it is, its temperament, the register in which it speaks. Write it as an instruction TO the author,",
+                "  not as the persona itself.",
+                "- An `agentMdBrief` is a directive describing the operating manual the agent needs — the doctrine,",
+                "  conventions, and concrete do/don't rules it should cover. Include it only when an agent needs an",
+                "  operating manual; omit it for a persona-only agent that has character but no procedure to follow.",
+                "- Never write the briefs as the artifacts themselves, and never address the end agent in them.",
+                "",
+                "Ground every design in the existing ecosystem:",
+                `- Survey what already exists before you design: call \`${LIST_AGENTS_TOOL_NAME}\` (and`,
+                `  \`${GET_AGENT_DETAILS_TOOL_NAME}\` to inspect any whose role overlaps) so you complement the fleet`,
+                "  rather than duplicate roles already covered.",
+                "- Report in `existingAgents` (by real id and name) any existing agent that belongs to this fleet — one",
+                "  that already covers a needed role, or that your designed agents should collaborate with — instead of",
+                "  redesigning it; if existing agents already cover the whole requirement, design no new agents at all.",
+                `- The MCP servers are NOT attached to you. Call \`${LIST_MCP_SERVERS_TOOL_NAME}\` to discover the`,
+                "  configurable servers assignable to the agents you design, and set `mcpServerIds` only from the ids",
+                "  it returns — never invent one.",
+                "- Assign `circleIds` only from the circles present in your context; omit `circleIds` to leave an",
+                "  agent in the base circle.",
+                "- Design the smallest fleet that fully covers the requirement. Every agent has a distinct,",
+                "  non-overlapping role, and its `name` and `description` are user-facing — make them concrete and",
+                `  specific, never generic. Each \`name\` must be ${AGENT_NAME_MAX_LENGTH} characters or fewer.`,
+                "",
+                "Output contract (strict, non-negotiable):",
+                "- Each request specifies the exact JSON object shape, its fields, and their length limits. Honor that",
+                "  contract precisely and keep every field within its stated limit.",
+                `- Emit ONLY that single JSON object, wrapped exactly between a line containing ${WORLD_BUILDER_BEGIN}`,
+                `  before it and a line containing ${WORLD_BUILDER_END} after it.`,
+                "- No code fences, and nothing outside the markers: no preamble, no commentary, no explanation, and",
+                "  no restatement of the request. The very first characters you emit are the begin marker.",
+                "",
+                "Shape of every response:",
+                WORLD_BUILDER_BEGIN,
+                "<the fleet JSON object, exactly as specified>",
+                WORLD_BUILDER_END,
+            ],
+        },
+    ],
+};
+const CROW_WORLD_BUILDER_BIRTHDAY = "1970-01-01T00:00:00Z";
+const CROW_WORLD_BUILDER_TOOLS = [];
+/**
+ * Build the World Builder agent config - an internal, non-visible system agent that designs a fleet of
+ * agents from a requirement as directional briefs. Background only; never persists a session. MCP read
+ * tools attach via the server allowlist in a later phase.
+ */
+export function getWorldBuilderAgent() {
+    const persona = createMessageContentFromTemplate(CROW_WORLD_BUILDER_AGENT_PERSONA, getDefaultPromptContext());
+    return {
+        id: CROW_WORLD_BUILDER_AGENT_ID,
+        type: AGENT_TYPE.CLAUDE_CODE,
+        name: CROW_WORLD_BUILDER_AGENT_NAME,
+        description: "Internal fleet architect. Designs a set of agents from a requirement as directional briefs.",
+        workspace: path.join(env.CROW_SYSTEM_PATH, SYSTEM_AGENTS_PROJECT_DIR_NAME),
+        persona,
+        model: CLAUDE_MODELS.SONNET,
+        permissionMode: PERMISSION_MODE.DEFAULT,
+        settingSources: [],
+        availableTools: [],
+        toolConfig: {
+            mode: TOOL_MODE.RESTRICTED,
+            tools: CROW_WORLD_BUILDER_TOOLS,
+            autoApprovedTools: CROW_WORLD_BUILDER_TOOLS,
+        },
+        mcpServerIds: [],
+        persistSession: false,
+        excludeClaudeCodeSystemPrompt: true,
+        isSystemAgent: true,
+        isBackgroundAgent: true,
+        createdAt: CROW_WORLD_BUILDER_BIRTHDAY,
+        updatedAt: CROW_WORLD_BUILDER_BIRTHDAY,
+    };
+}
+//# sourceMappingURL=crow-world-builder-agent.js.map

package/dist/bootstrap.js

@@ -18,6 +18,7 @@ import { registerArtifactRoutes } from "./routes/artifact.routes.js";
 import { getArtifactsMcpServerDefinition } from "./mcp/artifacts/artifacts-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";
 import { getTasksMcpServerDefinition } from "./mcp/tasks/tasks-mcp-server.js";
 import { getSuperTasksMcpServerDefinition } from "./mcp/tasks/super-tasks-mcp-server.js";
 import { getRemindersMcpServerDefinition } from "./mcp/reminders/reminders-mcp-server.js";
@@ -27,6 +28,9 @@ import { SystemSettingsManager } from "./services/system-settings-manager.js";
 import { MessageQueueManager } from "./services/message-queue-manager.js";
 import { AgentTaskManager } from "./services/agent-task-manager.js";
 import { registerGenerationRoutes } from "./routes/generation.routes.js";
+import { registerAgentBuilderRoutes } from "./routes/agent-builder.routes.js";
+import { WorldBuilderService } from "./services/world-builder/world-builder-service.js";
+import { WorldBuilderDraftStore } from "./services/world-builder/world-builder-draft-store.js";
 import { registerTaskRoutes } from "./routes/task.routes.js";
 import { CrowMcpManager } from "./mcp/crow-mcp-manager.js";
 import { registerMcpRoutes } from "./routes/mcp.routes.js";
@@ -105,6 +109,8 @@ export async function bootstrap(options) {
     sensorManager.registerSensor(new WeatherSensor());
     const runtimeManager = new AgentRuntimeManager(storeProvider, broadcaster, registry, mcpManager, sessionManager, messageQueue, taskManager, sensorManager, circleManager);
     await runtimeManager.initialize();
+    const worldBuilderDraftStore = new WorldBuilderDraftStore(storeProvider);
+    const worldBuilderService = new WorldBuilderService(runtimeManager, worldBuilderDraftStore, registry, circleManager, mcpManager, broadcaster);
     const routineManager = new RoutineManager(registry, runtimeManager, taskManager, crowScheduler, feedManager);
     const interAgentRoutine = createInterAgentTaskRoutine(registry, runtimeManager, taskManager);
     routineManager.addRoutine(interAgentRoutine);
@@ -133,6 +139,7 @@ export async function bootstrap(options) {
     mcpManager.registerMcpServer(getAudioMcpServerDefinition(registry, artifactManager));
     mcpManager.registerMcpServer(getSuperTasksMcpServerDefinition(taskManager, registry, circleManager, sensorManager));
     mcpManager.registerMcpServer(getSuperAgentMcpServerDefinition(registry, runtimeManager, sessionManager));
+    mcpManager.registerMcpServer(getBuilderAgentMcpServerDefinition(registry, mcpManager));
     mcpManager.registerMcpServer(getRemindersMcpServerDefinition(crowScheduler, sensorManager));
     mcpManager.registerMcpServer(getGmailMcpServerDefinition(connectorManager, sensorManager));
     mcpManager.registerMcpServer(getGoogleCalendarMcpServerDefinition(connectorManager, sensorManager));
@@ -151,7 +158,8 @@ export async function bootstrap(options) {
     await registerAgentRoutes(server, registry, runtimeManager, sessionManager, storeProvider, connectorManager, mcpManager);
     await registerArtifactRoutes(server, artifactManager);
     await registerTaskRoutes(server, taskManager, registry);
-    await registerGenerationRoutes(server);
+    await registerGenerationRoutes(server, worldBuilderService);
+    await registerAgentBuilderRoutes(server, worldBuilderService);
     await registerMcpRoutes(server, mcpManager);
     await registerSensorRoutes(server, sensorManager);
     await registerCircleRoutes(server, circleManager, registry);
@@ -162,6 +170,7 @@ export async function bootstrap(options) {
     // Start listening
     await server.listen({ host: env.HOST, port: env.PORT });
     logger.info({ host: env.HOST, port: env.PORT, static: options.serveStatic }, "Server started");
+    await worldBuilderService.recoverInterruptedBuild();
     // Graceful shutdown
     const shutdown = async () => {
         logger.info("Shutting down...");