crow-central-agency 0.25.13 → 0.25.14

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

@@ -43,6 +43,7 @@ export const ArtifactMetadataSchema = z.object({
     entityId: z.string(),
     entityType: EntityTypeSchema,
     size: z.number(),
+    tags: z.array(z.string()).optional(),
     createdTimestamp: z.number(),
     updatedTimestamp: z.number(),
     createdBy: AgentTaskSourceSchema,

package/dist/bootstrap.js

@@ -147,6 +147,7 @@ export async function bootstrap(options) {
         isConfigurable: googleContactsMcpDefinition.isConfigurable,
         displayName: googleContactsMcpDefinition.displayName,
     });
+    await runtimeManager.startRecovery();
     // Start scheduler
     crowScheduler.start();
     // Create Fastify server

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

@@ -18,6 +18,7 @@ export const APP_ERROR_CODES = {
     INVALID_STATE_TRANSITION: "invalid_state_transition",
     PATH_TRAVERSAL: "path_traversal",
     INVALID_FILENAME: "invalid_filename",
+    CONFLICT: "conflict",
     MCP_CONFIG_NOT_FOUND: "mcp_config_not_found",
     MCP_ERROR: "mcp_error",
     SDK_ERROR: "sdk_error",

package/dist/mcp/artifacts/artifacts-mcp-server-utils.js

@@ -2,8 +2,50 @@ import path from "node:path";
 import { ARTIFACT_CONTENT_TYPE, ARTIFACT_TYPE } from "../../_shared/index.js";
 import { formatLocalDateTime } from "../../utils/date-utils.js";
 import { processTextContent, textToolResult } from "../tool-utils.js";
+import { last } from "es-toolkit";
 export const ARTIFACT_TYPE_VALUES = Object.values(ARTIFACT_TYPE);
 export const ARTIFACT_CONTENT_TYPE_VALUES = Object.values(ARTIFACT_CONTENT_TYPE);
+export const EDIT_ARTIFACT_MODE = {
+    INSERT: "insert",
+    REPLACE: "replace",
+};
+export const EDIT_ARTIFACT_MODE_VALUES = Object.values(EDIT_ARTIFACT_MODE);
+/**
+ * Apply an insert/replace line edit. Lines are 1-based; endLine is inclusive (used for replace only).
+ * Throws when line numbers are out of range or endLine is missing/invalid for replace.
+ */
+export function applyLineEdit(existingContent, content, mode, startLine, endLine) {
+    const existingLines = existingContent.split("\n");
+    const totalLines = existingLines.length;
+    if (startLine < 1) {
+        throw new Error("startLine must be a positive integer starting from 1.");
+    }
+    // allow adding a line after last line
+    if (startLine > totalLines + 1) {
+        throw new Error(`Starting line (${startLine}) exceeds the total number of lines (${totalLines}).`);
+    }
+    if (mode === EDIT_ARTIFACT_MODE.REPLACE) {
+        if (endLine === undefined) {
+            throw new Error("endLine is required for 'replace' mode.");
+        }
+        if (endLine > totalLines) {
+            throw new Error(`Ending line (${endLine}) exceeds the total number of lines (${totalLines}).`);
+        }
+        if (endLine < startLine) {
+            throw new Error(`Ending line (${endLine}) must be greater than or equal to starting line (${startLine}).`);
+        }
+    }
+    const preContent = existingLines.slice(0, startLine - 1);
+    const effectiveEnd = mode === EDIT_ARTIFACT_MODE.REPLACE && endLine !== undefined ? endLine : startLine - 1;
+    const postContent = existingLines.slice(effectiveEnd);
+    const newContent = content.split("\n");
+    const lastLine = last(newContent);
+    if (lastLine !== undefined && !lastLine) {
+        newContent.splice(-1, 1);
+    }
+    const updatedContent = preContent.concat(newContent).concat(postContent).join("\n");
+    return updatedContent;
+}
 /** Image extensions that Claude can process natively via base64 */
 const SUPPORTED_IMAGE_MIME = {
     ".jpg": "image/jpeg",
@@ -18,8 +60,11 @@ const PDF_MIME = "application/pdf";
 export function buildReadArtifactResult(content, metadata, userTimezone, lineOptions) {
     const header = [
         `--- METADATA ---`,
-        `[Type: ${metadata.type} | Content: ${metadata.contentType} | Modified: ${formatLocalDateTime(new Date(metadata.updatedTimestamp), userTimezone)}]`,
+        `[Type: ${metadata.type} | Content: ${metadata.contentType} | Modified: ${formatLocalDateTime(new Date(metadata.updatedTimestamp), userTimezone)} | Version: ${metadata.updatedTimestamp}]`,
     ];
+    if (metadata.tags?.length) {
+        header.push(`[Tags: ${metadata.tags.join(", ")}]`);
+    }
     if (typeof content === "string" || metadata.contentType === ARTIFACT_CONTENT_TYPE.TEXT) {
         const rawText = typeof content === "string" ? content : content.toString("utf-8");
         const processed = processTextContent(rawText, lineOptions);
@@ -55,4 +100,28 @@ export function buildReadArtifactResult(content, metadata, userTimezone, lineOpt
         `[Binary artifact: ${metadata.contentType} content (${metadata.size} bytes). This binary format is not supported for interpretation.]`,
     ]);
 }
+/** Build the MCP text result for a find-content search. Dedupes by line; honors an optional limit on lines. */
+export function buildFindContentResult(filename, query, result, limit) {
+    if (!result.found) {
+        return textToolResult([`No matches found for "${query}" in ${filename}.`]);
+    }
+    const seenLines = new Set();
+    const shownLines = [];
+    for (const match of result.matches) {
+        if (seenLines.has(match.lineNumber)) {
+            continue;
+        }
+        seenLines.add(match.lineNumber);
+        if (limit === undefined || shownLines.length < limit) {
+            shownLines.push(`[L${match.lineNumber}] ${match.lineContent}`);
+        }
+    }
+    const truncated = limit !== undefined && seenLines.size > limit;
+    const lines = [
+        `Found ${seenLines.size} matching line(s) for "${query}" in ${filename}${truncated ? ` (showing first ${limit})` : ""}:`,
+        "Lines are prefixed with [LNNN] markers. These markers are NOT part of the line content.",
+        ...shownLines,
+    ];
+    return textToolResult(lines);
+}
 //# sourceMappingURL=artifacts-mcp-server-utils.js.map

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

@@ -1,28 +1,39 @@
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { getWriteArtifactToolConfig } from "./write-artifact.js";
+import { getEditArtifactToolConfig } from "./edit-artifact.js";
 import { getReadArtifactToolConfig } from "./read-artifact.js";
 import { getListArtifactsToolConfig } from "./list-artifacts.js";
 import { getDeleteArtifactToolConfig } from "./delete-artifact.js";
+import { getFindContentInArtifactToolConfig } from "./find-content-in-artifact.js";
 import { getWriteCircleArtifactToolConfig } from "./write-circle-artifact.js";
+import { getEditCircleArtifactToolConfig } from "./edit-circle-artifact.js";
 import { getReadCircleArtifactToolConfig } from "./read-circle-artifact.js";
 import { getListCircleArtifactsToolConfig } from "./list-circle-artifacts.js";
 import { getDeleteCircleArtifactToolConfig } from "./delete-circle-artifact.js";
+import { getFindContentInCircleArtifactToolConfig } from "./find-content-in-circle-artifact.js";
 export const ARTIFACTS_MCP_SERVER_NAME = "crow-artifacts";
 export function createArtifactsMcpServer(agentId, artifactManager, registry, circleManager, sensorManager) {
     const writeArtifact = getWriteArtifactToolConfig(agentId, artifactManager, sensorManager);
+    const editArtifact = getEditArtifactToolConfig(agentId, artifactManager, sensorManager);
     const readArtifact = getReadArtifactToolConfig(agentId, artifactManager, registry, circleManager, sensorManager);
     const listArtifacts = getListArtifactsToolConfig(agentId, artifactManager, registry, circleManager, sensorManager);
     const deleteArtifact = getDeleteArtifactToolConfig(agentId, artifactManager);
+    const findContentInArtifact = getFindContentInArtifactToolConfig(agentId, artifactManager);
     const writeCircleArtifact = getWriteCircleArtifactToolConfig(agentId, artifactManager, sensorManager);
+    const editCircleArtifact = getEditCircleArtifactToolConfig(agentId, artifactManager, sensorManager);
     const readCircleArtifact = getReadCircleArtifactToolConfig(agentId, artifactManager, sensorManager);
     const listCircleArtifacts = getListCircleArtifactsToolConfig(agentId, artifactManager, sensorManager);
     const deleteCircleArtifact = getDeleteCircleArtifactToolConfig(agentId, artifactManager);
+    const findContentInCircleArtifact = getFindContentInCircleArtifactToolConfig(agentId, artifactManager);
     return createSdkMcpServer({
         name: ARTIFACTS_MCP_SERVER_NAME,
         tools: [
             tool(writeArtifact.name, writeArtifact.description, writeArtifact.inputSchema, writeArtifact.handler, {
                 annotations: writeArtifact.annotations,
             }),
+            tool(editArtifact.name, editArtifact.description, editArtifact.inputSchema, editArtifact.handler, {
+                annotations: editArtifact.annotations,
+            }),
             tool(readArtifact.name, readArtifact.description, readArtifact.inputSchema, readArtifact.handler, {
                 annotations: readArtifact.annotations,
             }),
@@ -32,10 +43,13 @@ export function createArtifactsMcpServer(agentId, artifactManager, registry, cir
             tool(deleteArtifact.name, deleteArtifact.description, deleteArtifact.inputSchema, deleteArtifact.handler, {
                 annotations: deleteArtifact.annotations,
             }),
+            tool(findContentInArtifact.name, findContentInArtifact.description, findContentInArtifact.inputSchema, findContentInArtifact.handler, { annotations: findContentInArtifact.annotations }),
             tool(writeCircleArtifact.name, writeCircleArtifact.description, writeCircleArtifact.inputSchema, writeCircleArtifact.handler, { annotations: writeCircleArtifact.annotations }),
+            tool(editCircleArtifact.name, editCircleArtifact.description, editCircleArtifact.inputSchema, editCircleArtifact.handler, { annotations: editCircleArtifact.annotations }),
             tool(readCircleArtifact.name, readCircleArtifact.description, readCircleArtifact.inputSchema, readCircleArtifact.handler, { annotations: readCircleArtifact.annotations }),
             tool(listCircleArtifacts.name, listCircleArtifacts.description, listCircleArtifacts.inputSchema, listCircleArtifacts.handler, { annotations: listCircleArtifacts.annotations }),
             tool(deleteCircleArtifact.name, deleteCircleArtifact.description, deleteCircleArtifact.inputSchema, deleteCircleArtifact.handler, { annotations: deleteCircleArtifact.annotations }),
+            tool(findContentInCircleArtifact.name, findContentInCircleArtifact.description, findContentInCircleArtifact.inputSchema, findContentInCircleArtifact.handler, { annotations: findContentInCircleArtifact.annotations }),
         ],
     });
 }

package/dist/mcp/artifacts/delete-circle-artifact.js

@@ -9,7 +9,7 @@ export function getDeleteCircleArtifactToolConfig(agentId, artifactManager) {
     };
     const handler = async ({ circle_id, filename }) => {
         if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
-            return textToolResult(["Error: you are not a direct member of this circle"], true);
+            return textToolResult(["You are not a direct member of this circle."], true);
         }
         try {
             const metadata = await artifactManager.getCircleArtifactMetadata(circle_id, filename);

package/dist/mcp/artifacts/edit-artifact.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { ARTIFACT_CONTENT_TYPE } from "../../_shared/index.js";
+import { getErrorToolResult, textToolResult } from "../tool-utils.js";
+import { formatLocalDateTime } from "../../utils/date-utils.js";
+import { applyLineEdit, EDIT_ARTIFACT_MODE, EDIT_ARTIFACT_MODE_VALUES } from "./artifacts-mcp-server-utils.js";
+export const EDIT_ARTIFACT_TOOL_NAME = "edit_artifact";
+export function getEditArtifactToolConfig(agentId, artifactManager, sensorManager) {
+    const inputSchema = {
+        filename: z.string().describe("Name of an existing TEXT artifact to edit."),
+        mode: z
+            .enum(EDIT_ARTIFACT_MODE_VALUES)
+            .describe("Edit mode. 'insert': insert new lines before startLine. 'replace': replace lines startLine..endLine inclusive. Both require a TEXT artifact."),
+        content: z.string().describe("The new text to insert or use as replacement."),
+        startLine: z
+            .number()
+            .min(1)
+            .describe("1-based line number. For 'insert', new lines are placed before this line. For 'replace', this is the first line replaced."),
+        endLine: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("1-based inclusive last line to replace. Required for 'replace' mode. Ignored for 'insert'."),
+        version: z
+            .number()
+            .describe("The Version value from your most recent read of this artifact (the [Version: ...] token)."),
+        addTags: z.array(z.string()).optional().describe("Optional tags to add to the artifact."),
+        removeTags: z.array(z.string()).optional().describe("Optional tags to remove from the artifact."),
+    };
+    const handler = async ({ filename: rawFilename, content, mode, startLine, endLine, version, addTags, removeTags, }) => {
+        const filename = rawFilename.trim();
+        try {
+            if (mode === EDIT_ARTIFACT_MODE.REPLACE && endLine === undefined) {
+                throw new Error("endLine is required for 'replace' mode.");
+            }
+            const { content: existingContent, metadata } = await artifactManager.readArtifact(agentId, filename);
+            if (metadata.contentType !== ARTIFACT_CONTENT_TYPE.TEXT || typeof existingContent !== "string") {
+                throw new Error(`edit_artifact only supports TEXT artifacts (${metadata.filename} is ${metadata.contentType}). Use write_artifact to replace the file.`);
+            }
+            const nextContent = applyLineEdit(existingContent, content, mode, startLine, endLine);
+            const updated = await artifactManager.updateArtifact(agentId, filename, {
+                content: nextContent,
+                addTags,
+                removeTags,
+                expectedUpdatedTimestamp: version,
+            });
+            const userTimezone = await sensorManager.getUserTimezone();
+            const editNote = mode === EDIT_ARTIFACT_MODE.REPLACE
+                ? `replaced lines ${startLine}-${endLine}`
+                : `inserted at line ${startLine}`;
+            return textToolResult([
+                `Artifact edited: ${updated.filename} (${editNote}, size: ${updated.size} bytes, modified: ${formatLocalDateTime(new Date(updated.updatedTimestamp), userTimezone)}). Re-read the artifact before the next edit; line numbers and Version are now stale.`,
+            ]);
+        }
+        catch (error) {
+            return getErrorToolResult(error, "Failed to edit artifact.");
+        }
+    };
+    const config = {
+        name: EDIT_ARTIFACT_TOOL_NAME,
+        description: "Surgically modify a TEXT artifact you own by inserting or replacing a range of lines. Use write_artifact to replace the full file or to write non-TEXT content.",
+        inputSchema,
+        handler,
+    };
+    return config;
+}
+//# sourceMappingURL=edit-artifact.js.map

package/dist/mcp/artifacts/edit-circle-artifact.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { ARTIFACT_CONTENT_TYPE } from "../../_shared/index.js";
+import { getErrorToolResult, textToolResult } from "../tool-utils.js";
+import { formatLocalDateTime } from "../../utils/date-utils.js";
+import { applyLineEdit, EDIT_ARTIFACT_MODE, EDIT_ARTIFACT_MODE_VALUES } from "./artifacts-mcp-server-utils.js";
+export const EDIT_CIRCLE_ARTIFACT_TOOL_NAME = "edit_circle_artifact";
+export function getEditCircleArtifactToolConfig(agentId, artifactManager, sensorManager) {
+    const inputSchema = {
+        circle_id: z.string().describe("The circle ID that owns the artifact."),
+        filename: z.string().describe("Name of an existing TEXT circle artifact to edit."),
+        mode: z
+            .enum(EDIT_ARTIFACT_MODE_VALUES)
+            .describe("Edit mode. 'insert': insert new lines before startLine. 'replace': replace lines startLine..endLine inclusive. Both require a TEXT artifact."),
+        content: z.string().describe("The new text to insert or use as replacement."),
+        startLine: z
+            .number()
+            .min(1)
+            .describe("1-based line number. For 'insert', new lines are placed before this line. For 'replace', this is the first line replaced."),
+        endLine: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("1-based inclusive last line to replace. Required for 'replace' mode. Ignored for 'insert'."),
+        version: z
+            .number()
+            .describe("The Version value from your most recent read of this artifact (the [Version: ...] token)."),
+        addTags: z.array(z.string()).optional().describe("Optional tags to add to the artifact."),
+        removeTags: z.array(z.string()).optional().describe("Optional tags to remove from the artifact."),
+    };
+    const handler = async ({ circle_id, filename: rawFilename, content, mode, startLine, endLine, version, addTags, removeTags, }) => {
+        if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
+            return textToolResult(["You are not a direct member of this circle."], true);
+        }
+        const filename = rawFilename.trim();
+        try {
+            if (mode === EDIT_ARTIFACT_MODE.REPLACE && endLine === undefined) {
+                throw new Error("endLine is required for 'replace' mode.");
+            }
+            const { content: existingContent, metadata } = await artifactManager.readCircleArtifact(circle_id, filename);
+            if (metadata.contentType !== ARTIFACT_CONTENT_TYPE.TEXT || typeof existingContent !== "string") {
+                throw new Error(`edit_circle_artifact only supports TEXT artifacts (${metadata.filename} is ${metadata.contentType}). Use write_circle_artifact to replace the file.`);
+            }
+            const nextContent = applyLineEdit(existingContent, content, mode, startLine, endLine);
+            const updated = await artifactManager.updateCircleArtifact(circle_id, filename, {
+                content: nextContent,
+                addTags,
+                removeTags,
+                expectedUpdatedTimestamp: version,
+            });
+            const userTimezone = await sensorManager.getUserTimezone();
+            const editNote = mode === EDIT_ARTIFACT_MODE.REPLACE
+                ? `replaced lines ${startLine}-${endLine}`
+                : `inserted at line ${startLine}`;
+            return textToolResult([
+                `Circle artifact edited: ${updated.filename} (circle: ${circle_id}, ${editNote}, size: ${updated.size} bytes, modified: ${formatLocalDateTime(new Date(updated.updatedTimestamp), userTimezone)}). Re-read the artifact before the next edit; line numbers and Version are now stale.`,
+            ]);
+        }
+        catch (error) {
+            return getErrorToolResult(error, "Failed to edit circle artifact.");
+        }
+    };
+    const config = {
+        name: EDIT_CIRCLE_ARTIFACT_TOOL_NAME,
+        description: "Surgically modify a TEXT circle artifact by inserting or replacing a range of lines. Only direct members of the circle can edit. Use write_circle_artifact to replace the full file or to write non-TEXT content.",
+        inputSchema,
+        handler,
+    };
+    return config;
+}
+//# sourceMappingURL=edit-circle-artifact.js.map

package/dist/mcp/artifacts/find-content-in-artifact.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { getErrorToolResult, textToolResult } from "../tool-utils.js";
+import { buildFindContentResult } from "./artifacts-mcp-server-utils.js";
+export const FIND_CONTENT_IN_ARTIFACT_TOOL_NAME = "find_content_in_artifact";
+export function getFindContentInArtifactToolConfig(agentId, artifactManager) {
+    const inputSchema = {
+        filename: z.string().describe("Name of an existing TEXT artifact to search."),
+        query: z.string().min(1).describe("Substring to search for. Case-insensitive."),
+        startLine: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("Optional. 1-based line number to start searching from. Defaults to 1."),
+        limit: z.number().min(1).optional().describe("Optional. Maximum number of matches to return."),
+    };
+    const handler = async ({ filename: rawFilename, query, startLine, limit }) => {
+        const filename = rawFilename.trim();
+        try {
+            if (!query) {
+                return textToolResult(["Search query must not be empty."], true);
+            }
+            const result = await artifactManager.findArtifactContent(agentId, filename, query, startLine);
+            return buildFindContentResult(filename, query, result, limit);
+        }
+        catch (error) {
+            return getErrorToolResult(error, "Failed to search artifact content.");
+        }
+    };
+    const config = {
+        name: FIND_CONTENT_IN_ARTIFACT_TOOL_NAME,
+        description: "Search a TEXT artifact you own for a substring and return matching lines with their 1-based line numbers. Case-insensitive. Use startLine to skip ahead and limit to cap the number of matches.",
+        inputSchema,
+        handler,
+    };
+    return config;
+}
+//# sourceMappingURL=find-content-in-artifact.js.map

package/dist/mcp/artifacts/find-content-in-circle-artifact.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { getErrorToolResult, textToolResult } from "../tool-utils.js";
+import { buildFindContentResult } from "./artifacts-mcp-server-utils.js";
+export const FIND_CONTENT_IN_CIRCLE_ARTIFACT_TOOL_NAME = "find_content_in_circle_artifact";
+export function getFindContentInCircleArtifactToolConfig(agentId, artifactManager) {
+    const inputSchema = {
+        circle_id: z.string().describe("The circle ID that owns the artifact."),
+        filename: z.string().describe("Name of an existing TEXT circle artifact to search."),
+        query: z.string().min(1).describe("Substring to search for. Case-insensitive."),
+        startLine: z
+            .number()
+            .min(1)
+            .optional()
+            .describe("Optional. 1-based line number to start searching from. Defaults to 1."),
+        limit: z.number().min(1).optional().describe("Optional. Maximum number of matches to return."),
+    };
+    const handler = async ({ circle_id, filename: rawFilename, query, startLine, limit, }) => {
+        if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
+            return textToolResult(["You are not a direct member of this circle."], true);
+        }
+        const filename = rawFilename.trim();
+        try {
+            if (!query) {
+                return textToolResult(["Search query must not be empty."], true);
+            }
+            const result = await artifactManager.findCircleArtifactContent(circle_id, filename, query, startLine);
+            return buildFindContentResult(filename, query, result, limit);
+        }
+        catch (error) {
+            return getErrorToolResult(error, "Failed to search circle artifact content.");
+        }
+    };
+    const config = {
+        name: FIND_CONTENT_IN_CIRCLE_ARTIFACT_TOOL_NAME,
+        description: "Search a TEXT circle artifact for a substring and return matching lines with their 1-based line numbers. Only direct members of the circle can search. Case-insensitive. Use startLine to skip ahead and limit to cap the number of matches.",
+        inputSchema,
+        handler,
+    };
+    return config;
+}
+//# sourceMappingURL=find-content-in-circle-artifact.js.map

package/dist/mcp/artifacts/list-artifacts.js

@@ -11,29 +11,40 @@ export function getListArtifactsToolConfig(agentId, artifactManager, registry, c
             .enum(ARTIFACT_TYPE_VALUES)
             .optional()
             .describe(`Filter by artifact type. Values: ${ARTIFACT_TYPE_VALUES.join(", ")}`),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Filter by tags. Only artifacts that have every specified tag are returned."),
         limit: z.number().optional().describe("Number of artifacts to return per page."),
         skip: z.number().optional().describe("Number of artifacts to skip for pagination."),
     };
-    const handler = async ({ agent_id, type, limit, skip }) => {
+    const handler = async ({ agent_id, type, tags, limit, skip }) => {
         const targetId = agent_id ?? agentId;
         if (agent_id) {
             try {
                 registry.getAgent(agent_id);
             }
             catch {
-                return textToolResult(["Error: agent not found"], true);
+                return textToolResult(["Target agent not found."], true);
             }
             if (!circleManager.isAgentVisible(agentId, targetId)) {
-                return textToolResult(["Error: agent not visible to you"], true);
+                return textToolResult(["Target agent is not visible to you."], true);
             }
         }
         try {
             const [artifacts, userTimezone] = await Promise.all([
-                artifactManager.listArtifacts(targetId, { type }),
+                artifactManager.listArtifacts(targetId, { type, tags }),
                 sensorManager.getUserTimezone(),
             ]);
             if (artifacts.length === 0) {
-                const suffix = type ? ` with type ${type}` : "";
+                const filterParts = [];
+                if (type) {
+                    filterParts.push(`type ${type}`);
+                }
+                if (tags?.length) {
+                    filterParts.push(`tags [${tags.join(", ")}]`);
+                }
+                const suffix = filterParts.length ? ` matching ${filterParts.join(" and ")}` : "";
                 return textToolResult([`No artifacts found for agent ${targetId}${suffix}.`]);
             }
             const pagination = applyPagination(artifacts, limit || DEFAULT_ARTIFACTS_LIMIT, skip);

package/dist/mcp/artifacts/list-circle-artifacts.js

@@ -11,20 +11,31 @@ export function getListCircleArtifactsToolConfig(agentId, artifactManager, senso
             .enum(ARTIFACT_TYPE_VALUES)
             .optional()
             .describe(`Filter by artifact type. Values: ${ARTIFACT_TYPE_VALUES.join(", ")}`),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Filter by tags. Only artifacts that have every specified tag are returned."),
         limit: z.number().optional().describe("Number of artifacts to return per page."),
         skip: z.number().optional().describe("Number of artifacts to skip for pagination."),
     };
-    const handler = async ({ circle_id, type, limit, skip }) => {
+    const handler = async ({ circle_id, type, tags, limit, skip }) => {
         if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
-            return textToolResult(["Error: you are not a direct member of this circle"], true);
+            return textToolResult(["You are not a direct member of this circle."], true);
         }
         try {
             const [artifacts, userTimezone] = await Promise.all([
-                artifactManager.listCircleArtifacts(circle_id, { type }),
+                artifactManager.listCircleArtifacts(circle_id, { type, tags }),
                 sensorManager.getUserTimezone(),
             ]);
             if (artifacts.length === 0) {
-                const suffix = type ? ` with type ${type}` : "";
+                const filterParts = [];
+                if (type) {
+                    filterParts.push(`type ${type}`);
+                }
+                if (tags?.length) {
+                    filterParts.push(`tags [${tags.join(", ")}]`);
+                }
+                const suffix = filterParts.length ? ` matching ${filterParts.join(" and ")}` : "";
                 return textToolResult([`No artifacts found for circle ${circle_id}${suffix}.`]);
             }
             const pagination = applyPagination(artifacts, limit || DEFAULT_CIRCLE_ARTIFACTS_LIMIT, skip);

package/dist/mcp/artifacts/read-artifact.js

@@ -23,15 +23,14 @@ export function getReadArtifactToolConfig(agentId, artifactManager, registry, ci
             registry.getAgent(agent_id);
         }
         catch {
-            return textToolResult(["Error: agent not found"], true);
+            return textToolResult(["Target agent not found."], true);
         }
         if (!circleManager.isAgentVisible(agentId, agent_id)) {
-            return textToolResult(["Error: agent not visible to you"], true);
+            return textToolResult(["Target agent is not visible to you."], true);
         }
         try {
-            const [content, metadata, userTimezone] = await Promise.all([
+            const [{ content, metadata }, userTimezone] = await Promise.all([
                 artifactManager.readArtifact(agent_id, filename, { useAdapter: true }),
-                artifactManager.getArtifactMetadata(agent_id, filename),
                 sensorManager.getUserTimezone(),
             ]);
             return buildReadArtifactResult(content, metadata, userTimezone, { showLineNumber, startLine, limit });

package/dist/mcp/artifacts/read-circle-artifact.js

@@ -20,12 +20,11 @@ export function getReadCircleArtifactToolConfig(agentId, artifactManager, sensor
     };
     const handler = async ({ circle_id, filename, showLineNumber, startLine, limit, }) => {
         if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
-            return textToolResult(["Error: you are not a direct member of this circle"], true);
+            return textToolResult(["You are not a direct member of this circle."], true);
         }
         try {
-            const [content, metadata, userTimezone] = await Promise.all([
+            const [{ content, metadata }, userTimezone] = await Promise.all([
                 artifactManager.readCircleArtifact(circle_id, filename, { useAdapter: true }),
-                artifactManager.getCircleArtifactMetadata(circle_id, filename),
                 sensorManager.getUserTimezone(),
             ]);
             return buildReadArtifactResult(content, metadata, userTimezone, { showLineNumber, startLine, limit });

package/dist/mcp/artifacts/write-artifact.js

@@ -6,7 +6,7 @@ import { ARTIFACT_CONTENT_TYPE_VALUES, ARTIFACT_TYPE_VALUES } from "./artifacts-
 export const WRITE_ARTIFACT_TOOL_NAME = "write_artifact";
 export function getWriteArtifactToolConfig(agentId, artifactManager, sensorManager) {
     const inputSchema = {
-        filename: z.string().describe("Name of the file to create or overwrite, e.g. 'report.md' or 'data.json'"),
+        filename: z.string().describe("Name of the file to write, e.g. 'report.md' or 'data.json'."),
         content: z
             .string()
             .describe("The content to write. For TEXT content type, provide the raw text. For binary content types (IMAGE, AUDIO, BINARY), provide base64-encoded data."),
@@ -17,9 +17,13 @@ export function getWriteArtifactToolConfig(agentId, artifactManager, sensorManag
         content_type: z
             .enum(ARTIFACT_CONTENT_TYPE_VALUES)
             .optional()
-            .describe(`Content type annotation. Values: ${ARTIFACT_CONTENT_TYPE_VALUES.join(", ")}. Defaults to ${ARTIFACT_CONTENT_TYPE.TEXT}`),
+            .describe(`Content type annotation. Values: ${ARTIFACT_CONTENT_TYPE_VALUES.join(", ")}. Defaults to ${ARTIFACT_CONTENT_TYPE.TEXT}.`),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Tags to attach to the artifact. Fully replaces existing tags; omit to leave the artifact untagged."),
     };
-    const handler = async ({ filename: rawFilename, content, type, content_type }) => {
+    const handler = async ({ filename: rawFilename, content, type, content_type, tags, }) => {
         const filename = rawFilename.trim();
         try {
             const isBinary = content_type && content_type !== ARTIFACT_CONTENT_TYPE.TEXT;
@@ -27,6 +31,7 @@ export function getWriteArtifactToolConfig(agentId, artifactManager, sensorManag
             const metadata = await artifactManager.writeArtifact(agentId, filename, artifactContent, {
                 type,
                 contentType: content_type,
+                tags,
                 createdBy: { sourceType: AGENT_TASK_SOURCE_TYPE.AGENT, agentId },
             });
             const userTimezone = await sensorManager.getUserTimezone();
@@ -43,7 +48,7 @@ export function getWriteArtifactToolConfig(agentId, artifactManager, sensorManag
     };
     const config = {
         name: WRITE_ARTIFACT_TOOL_NAME,
-        description: "Save a file to your own artifacts folder. Other agents can read your artifacts to collaborate. You can only write to your own folder.",
+        description: "Save a file to your own artifacts folder, creating it or replacing the existing file at that name. Other agents can read your artifacts to collaborate. Use edit_artifact for surgical line-level changes to a TEXT artifact.",
         inputSchema,
         handler,
     };

package/dist/mcp/artifacts/write-circle-artifact.js

@@ -6,8 +6,8 @@ import { ARTIFACT_CONTENT_TYPE_VALUES, ARTIFACT_TYPE_VALUES } from "./artifacts-
 export const WRITE_CIRCLE_ARTIFACT_TOOL_NAME = "write_circle_artifact";
 export function getWriteCircleArtifactToolConfig(agentId, artifactManager, sensorManager) {
     const inputSchema = {
-        circle_id: z.string().describe("The circle ID to write the artifact to"),
-        filename: z.string().describe("Name of the file to create or overwrite"),
+        circle_id: z.string().describe("The circle ID to write the artifact to."),
+        filename: z.string().describe("Name of the file to write."),
         content: z
             .string()
             .describe("The content to write. For TEXT content type, provide the raw text. For binary content types (IMAGE, AUDIO, BINARY), provide base64-encoded data."),
@@ -18,11 +18,15 @@ export function getWriteCircleArtifactToolConfig(agentId, artifactManager, senso
         content_type: z
             .enum(ARTIFACT_CONTENT_TYPE_VALUES)
             .optional()
-            .describe(`Content type annotation. Values: ${ARTIFACT_CONTENT_TYPE_VALUES.join(", ")}. Defaults to ${ARTIFACT_CONTENT_TYPE.TEXT}`),
+            .describe(`Content type annotation. Values: ${ARTIFACT_CONTENT_TYPE_VALUES.join(", ")}. Defaults to ${ARTIFACT_CONTENT_TYPE.TEXT}.`),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Tags to attach to the artifact. Fully replaces existing tags; omit to leave the artifact untagged."),
     };
-    const handler = async ({ circle_id, filename: rawFilename, content, type, content_type, }) => {
+    const handler = async ({ circle_id, filename: rawFilename, content, type, content_type, tags, }) => {
         if (!artifactManager.isDirectCircleMember(circle_id, agentId)) {
-            return textToolResult(["Error: you are not a direct member of this circle"], true);
+            return textToolResult(["You are not a direct member of this circle."], true);
         }
         const filename = rawFilename.trim();
         try {
@@ -31,6 +35,7 @@ export function getWriteCircleArtifactToolConfig(agentId, artifactManager, senso
             const metadata = await artifactManager.writeCircleArtifact(circle_id, filename, artifactContent, {
                 type,
                 contentType: content_type,
+                tags,
                 createdBy: { sourceType: AGENT_TASK_SOURCE_TYPE.AGENT, agentId },
             });
             const userTimezone = await sensorManager.getUserTimezone();
@@ -47,7 +52,7 @@ export function getWriteCircleArtifactToolConfig(agentId, artifactManager, senso
     };
     const config = {
         name: WRITE_CIRCLE_ARTIFACT_TOOL_NAME,
-        description: "Save a file to a circle's shared artifacts folder. Only direct members of the circle can read and write circle artifacts.",
+        description: "Save a file to a circle's shared artifacts folder, creating it or replacing the existing file at that name. Only direct members of the circle can read and write circle artifacts. Use edit_circle_artifact for surgical line-level changes to a TEXT artifact.",
         inputSchema,
         handler,
     };

package/dist/mcp/tool-utils.js

@@ -76,7 +76,7 @@ export function processTextContent(text, options) {
     const clampedEnd = Math.min(options.limit !== undefined ? start + options.limit : totalLines, totalLines);
     const sliced = allLines.slice(start, clampedEnd);
     if (options.showLineNumber) {
-        headerParts.push("Lines are prefixed with [LNNN] markers. These markers are NOT part of the note content.");
+        headerParts.push("Lines are prefixed with [LNNN] markers. These markers are NOT part of the line content.");
     }
     const hasRange = options.startLine !== undefined || options.limit !== undefined;
     headerParts.push(`--- CONTENT${hasRange ? ` (lines ${start + 1} - ${clampedEnd})` : ""} ---`);