@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/builtin/memory.d.ts

@@ -13,6 +13,12 @@
  *
  * Delete is SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
  * by MemoryManager, so accidental deletions are recoverable by hand.
+ *
+ * Three locations are exposed:
+ *   - "global"   Cross-project memory under CODE_SHELL_HOME.
+ *   - "project"  Memory scoped to ctx.cwd (the backward-compatible default).
+ *   - "profile"  Portable memory owned by the active digital-human profile;
+ *                available only when ToolContext.profileMemoryDir is present.
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";

package/dist/tool-system/builtin/memory.js

@@ -13,6 +13,12 @@
  *
  * Delete is SOFT — files are moved to <baseDir>/memory-trash/<ISO>/<scope>/
  * by MemoryManager, so accidental deletions are recoverable by hand.
+ *
+ * Three locations are exposed:
+ *   - "global"   Cross-project memory under CODE_SHELL_HOME.
+ *   - "project"  Memory scoped to ctx.cwd (the backward-compatible default).
+ *   - "profile"  Portable memory owned by the active digital-human profile;
+ *                available only when ToolContext.profileMemoryDir is present.
  */
 import { MemoryManager } from "../../session/memory.js";
 const VALID_SCOPES = ["user", "dream"];
@@ -26,10 +32,11 @@ function parseScope(raw) {
     }
     return raw;
 }
-/** Location: "global" → cross-project store (no projectDir); "project"
- *  (default, back-compat) → this repo's store. Anything else → "project". */
+/** Location defaults to project for backward compatibility. */
 function parseLocation(raw) {
-    return raw === "global" ? "global" : "project";
+    if (raw === "global" || raw === "profile")
+        return raw;
+    return "project";
 }
 function parseOrigin(raw) {
     return typeof raw === "string" && VALID_ORIGINS.includes(raw)
@@ -37,6 +44,12 @@ function parseOrigin(raw) {
         : undefined;
 }
 function mmFor(ctx, scope, location = "project") {
+    if (location === "profile") {
+        if (!ctx?.profileMemoryDir) {
+            throw new Error('profile memory is unavailable for this run; activate a digital human with portableMemory enabled before using location "profile"');
+        }
+        return new MemoryManager({ baseDir: ctx.profileMemoryDir, scope });
+    }
     // location=global → omit projectDir so the manager points at the global store.
     return new MemoryManager({
         projectDir: location === "global" ? undefined : ctx?.cwd,
@@ -45,15 +58,16 @@ function mmFor(ctx, scope, location = "project") {
 }
 const LOCATION_SCHEMA = {
     type: "string",
-    enum: ["global", "project"],
-    description: 'Which store: "global" (applies across all projects) or "project" (this repo only). Defaults to "project".',
+    enum: ["global", "project", "profile"],
+    description: 'Which store: "global" (applies across all projects), "project" (this repo only), or "profile" (travels with the active digital human; requires portableMemory). Defaults to "project".',
 };
 // ─── MemoryList ────────────────────────────────────────────────────────────
 export const memoryListToolDef = {
     name: "MemoryList",
     description: "List persistent memory entries from one scope. " +
-        "Returns each entry's id, origin, counts, name, type, and short description (not the full content — use MemoryRead for that). " +
+        "Returns each entry's exact scope/location locator, id, origin, counts, name, type, and short description (not the full content — use MemoryRead for that). " +
         "Use this before MemorySave/MemoryDelete to find the exact name to target. " +
+        "Copy the returned scope and location exactly when calling MemoryRead; never guess them from the entry name or type. " +
         'Scopes: "user" (entries the user owns; you need permission to modify) or "dream" (auto-consolidation workspace; you may freely modify).',
     inputSchema: {
         type: "object",
@@ -74,12 +88,14 @@ export async function memoryListTool(args, ctx) {
         return scope;
     }
     try {
-        const mm = mmFor(ctx, scope, parseLocation(args.location));
+        const location = parseLocation(args.location);
+        const mm = mmFor(ctx, scope, location);
         const entries = mm.loadAll();
-        if (entries.length === 0)
-            return `(no memories in scope "${scope}")`;
+        if (entries.length === 0) {
+            return `(no memories at scope="${scope}" location="${location}")`;
+        }
         return entries
-            .map((e) => `- [${e.type}] ${e.name} ` +
+            .map((e) => `- [scope="${scope}" location="${location}" type="${e.type}"] ${e.name} ` +
             `(id:${e.id ?? "(none)"}, origin:${e.origin ?? "manual"}, use:${e.useCount ?? 0}, updates:${e.updateCount ?? 0}) — ` +
             e.description)
             .join("\n");
@@ -92,14 +108,15 @@ export async function memoryListTool(args, ctx) {
 export const memoryReadToolDef = {
     name: "MemoryRead",
     description: "Read the full content of a single memory entry by name. " +
-        "Use MemoryList first to find the exact name.",
+        "Use the exact scope and location printed on the injected memory index or returned by MemoryList; never infer or guess either value. " +
+        "If a read reports that the memory is missing, do not repeat the identical call. Use MemoryList once to refresh that exact store, or continue without the memory.",
     inputSchema: {
         type: "object",
         properties: {
             scope: {
                 type: "string",
                 enum: ["user", "dream"],
-                description: "Which scope to read from",
+                description: "Exact scope printed on the injected memory index or returned by MemoryList",
             },
             location: LOCATION_SCHEMA,
             name: {
@@ -123,8 +140,10 @@ export async function memoryReadTool(args, ctx) {
         const mm = mmFor(ctx, scope, location);
         const entries = mm.loadAll();
         const entry = entries.find((e) => e.name === name || e.fileName === name);
-        if (!entry)
-            return `Error: no memory named "${name}" in scope "${scope}"`;
+        if (!entry) {
+            return (`Error: no memory named "${name}" at scope="${scope}" location="${location}". ` +
+                "Do not repeat this identical MemoryRead call. Use MemoryList once to refresh this exact store, or continue without the memory.");
+        }
         // Recall signal (用户拍板 C + 可见性): reading a memory bumps its usage so
         // the recall-TTL sweep keeps frequently-read memories alive, and emits a
         // stream event so the UI can show the user this memory was actually used.
@@ -148,6 +167,8 @@ export async function memoryReadTool(args, ctx) {
         }
         return (`name: ${entry.name}\n` +
             `id: ${entry.id ?? ""}\n` +
+            `scope: ${scope}\n` +
+            `location: ${location}\n` +
             `description: ${entry.description}\n` +
             `type: ${entry.type}\n` +
             `origin: ${entry.origin ?? "manual"}\n` +
@@ -170,7 +191,7 @@ export const memorySaveToolDef = {
         "feedback (how to approach work), " +
         "project (non-obvious facts about ongoing work), " +
         "reference (pointers to external resources). " +
-        "Pick `location`: global (a lesson/preference true in ANY project) vs project (this repo only). " +
+        "Pick `location`: global (a lesson/preference true in ANY project), project (this repo only), or profile (knowledge that should travel with the active digital human). " +
         "If a memory in the injected index is now stale or wrong, update it by id or MemoryDelete it — keep the store correct rather than letting contradictions pile up. " +
         "The `description` is a one-line summary shown in the index; the `content` is the full body.",
     inputSchema: {

package/dist/tool-system/builtin/panel.d.ts

@@ -0,0 +1,9 @@
+import type { ContentBlock, ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const panelToolDef: ToolDefinition;
+type PanelToolImageResult = {
+    contentBlocks: ContentBlock[];
+    result: string;
+};
+export declare function panelTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | PanelToolImageResult>;
+export {};

package/dist/tool-system/builtin/panel.js

@@ -0,0 +1,314 @@
+import { validateToolInputSchemaStrict } from "../validation.js";
+export const panelToolDef = {
+    name: "Panel",
+    description: "Discover, open, and use panels in the interactive host. Use action='list' to discover " +
+        "stable panel ids, action='tools' to inspect a Panel App's structured Agent tools, and " +
+        "action='invoke' to call one. Invoking a tool opens its panel automatically.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["list", "open", "tools", "invoke"],
+                description: "List panels, open one, list its tools, or invoke one of its tools.",
+            },
+            panel_id: {
+                type: "string",
+                description: "Stable id returned by action='list'. Required except for action='list'.",
+            },
+            tool_name: {
+                type: "string",
+                description: "Declared tool name returned by action='tools'. Required for action='invoke'.",
+            },
+            arguments: {
+                type: "object",
+                description: "JSON object passed to the Panel App tool handler.",
+                additionalProperties: true,
+            },
+        },
+        required: ["action"],
+    },
+};
+const NO_PANEL_HOST = "Error: panel hosting is not available in this session. This tool requires an interactive Desktop host.";
+const INVALID_PANEL_IMAGE = "Error: Panel App returned an invalid image result";
+const MAX_PANEL_IMAGE_DIMENSION = 16_384;
+const MAX_PANEL_IMAGE_PIXELS = 24_000_000;
+const MAX_PANEL_JSON_RESULT_BYTES = 512 * 1024;
+function plainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function boundedPanelJson(value) {
+    try {
+        const encoded = JSON.stringify(value, null, 2);
+        return Buffer.byteLength(encoded, "utf8") <= MAX_PANEL_JSON_RESULT_BYTES ? encoded : null;
+    }
+    catch {
+        return null;
+    }
+}
+function safePanelToolDescriptors(value) {
+    if (!Array.isArray(value) || value.length > 16)
+        return null;
+    const tools = [];
+    for (const candidate of value) {
+        if (!plainObject(candidate) ||
+            typeof candidate.name !== "string" ||
+            !/^[a-z][a-z0-9_]{0,63}$/.test(candidate.name) ||
+            typeof candidate.description !== "string" ||
+            candidate.description.length < 1 ||
+            candidate.description.length > 500 ||
+            !plainObject(candidate.inputSchema) ||
+            candidate.inputSchema.type !== "object" ||
+            validateToolInputSchemaStrict(candidate.inputSchema) !== null ||
+            typeof candidate.readOnly !== "boolean") {
+            return null;
+        }
+        tools.push({
+            name: candidate.name,
+            description: candidate.description,
+            inputSchema: candidate.inputSchema,
+            readOnly: candidate.readOnly,
+        });
+    }
+    if (new Set(tools.map((tool) => tool.name)).size !== tools.length)
+        return null;
+    return tools;
+}
+function validImageDimensions(width, height) {
+    return (Number.isSafeInteger(width) &&
+        Number.isSafeInteger(height) &&
+        width > 0 &&
+        height > 0 &&
+        width <= MAX_PANEL_IMAGE_DIMENSION &&
+        height <= MAX_PANEL_IMAGE_DIMENSION &&
+        width * height <= MAX_PANEL_IMAGE_PIXELS);
+}
+function jpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        return null;
+    let offset = 2;
+    while (offset + 3 < bytes.length) {
+        while (offset < bytes.length && bytes[offset] === 0xff)
+            offset += 1;
+        if (offset >= bytes.length)
+            return null;
+        const marker = bytes[offset];
+        offset += 1;
+        if (marker === 0xd8 || marker === 0x01)
+            continue;
+        if (marker === 0xd9 || marker === 0xda)
+            return null;
+        if (offset + 2 > bytes.length)
+            return null;
+        const length = bytes.readUInt16BE(offset);
+        if (length < 2 || offset + length > bytes.length)
+            return null;
+        const startOfFrame = (marker >= 0xc0 && marker <= 0xc3) ||
+            (marker >= 0xc5 && marker <= 0xc7) ||
+            (marker >= 0xc9 && marker <= 0xcb) ||
+            (marker >= 0xcd && marker <= 0xcf);
+        if (startOfFrame) {
+            if (length < 7)
+                return null;
+            return {
+                height: bytes.readUInt16BE(offset + 3),
+                width: bytes.readUInt16BE(offset + 5),
+            };
+        }
+        offset += length;
+    }
+    return null;
+}
+function webpDimensions(bytes) {
+    if (bytes.length < 20 ||
+        bytes.subarray(0, 4).toString("ascii") !== "RIFF" ||
+        bytes.subarray(8, 12).toString("ascii") !== "WEBP") {
+        return null;
+    }
+    const format = bytes.subarray(12, 16).toString("ascii");
+    if (format === "VP8X") {
+        if (bytes.length < 30)
+            return null;
+        return {
+            width: 1 + bytes.readUIntLE(24, 3),
+            height: 1 + bytes.readUIntLE(27, 3),
+        };
+    }
+    if (format === "VP8 ") {
+        if (bytes.length < 30 || bytes[23] !== 0x9d || bytes[24] !== 0x01 || bytes[25] !== 0x2a) {
+            return null;
+        }
+        return {
+            width: bytes.readUInt16LE(26) & 0x3fff,
+            height: bytes.readUInt16LE(28) & 0x3fff,
+        };
+    }
+    if (format === "VP8L") {
+        if (bytes.length < 25 || bytes[20] !== 0x2f)
+            return null;
+        return {
+            width: 1 + bytes[21] + ((bytes[22] & 0x3f) << 8),
+            height: 1 + (bytes[22] >> 6) + (bytes[23] << 2) + ((bytes[24] & 0x0f) << 10),
+        };
+    }
+    return null;
+}
+function imageDimensions(mediaType, data) {
+    let bytes;
+    try {
+        bytes = Buffer.from(data, "base64");
+    }
+    catch {
+        return null;
+    }
+    if (mediaType === "image/png") {
+        if (bytes.length < 24 ||
+            !bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) ||
+            bytes.readUInt32BE(8) !== 13 ||
+            bytes.subarray(12, 16).toString("ascii") !== "IHDR") {
+            return null;
+        }
+        return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+    }
+    if (mediaType === "image/jpeg") {
+        return jpegDimensions(bytes);
+    }
+    if (mediaType === "image/webp") {
+        return webpDimensions(bytes);
+    }
+    if (mediaType === "image/gif") {
+        const signature = bytes.subarray(0, 6).toString("ascii");
+        if (bytes.length < 10 || (signature !== "GIF87a" && signature !== "GIF89a"))
+            return null;
+        return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+    }
+    return null;
+}
+function imageResult(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const candidate = value;
+    if (candidate.kind !== "image")
+        return null;
+    const mediaType = candidate.mediaType;
+    const data = candidate.data;
+    if (typeof mediaType !== "string" ||
+        !["image/png", "image/jpeg", "image/webp", "image/gif"].includes(mediaType) ||
+        typeof data !== "string" ||
+        data.length === 0 ||
+        data.length > 350_000 ||
+        data.length % 4 !== 0 ||
+        !/^[a-z0-9+/]+={0,2}$/iu.test(data)) {
+        return INVALID_PANEL_IMAGE;
+    }
+    const dimensions = imageDimensions(mediaType, data);
+    if (!dimensions ||
+        !validImageDimensions(dimensions.width, dimensions.height) ||
+        (candidate.width !== undefined && candidate.width !== dimensions.width) ||
+        (candidate.height !== undefined && candidate.height !== dimensions.height)) {
+        return INVALID_PANEL_IMAGE;
+    }
+    const metadata = { mediaType, ...dimensions };
+    for (const key of [
+        "nodeId",
+        "pageId",
+        "pageName",
+        "path",
+        "revision",
+        "stateRevision",
+        "summary",
+    ]) {
+        const value = candidate[key];
+        if (typeof value === "string" && value.length <= 2_000)
+            metadata[key] = value;
+    }
+    return {
+        contentBlocks: [
+            {
+                type: "image",
+                source: {
+                    type: "base64",
+                    media_type: mediaType,
+                    data,
+                },
+            },
+        ],
+        result: JSON.stringify(metadata, null, 2),
+    };
+}
+export async function panelTool(args, ctx) {
+    const bridge = ctx?.panels;
+    if (!bridge)
+        return NO_PANEL_HOST;
+    const action = args.action;
+    if (action === "list") {
+        const listed = await bridge.list();
+        // A failed discovery must not be reported as an empty host: "(no panels
+        // available)" reads as fact and makes the model stop trying.
+        if (listed.failed)
+            return `Error: ${listed.failed}`;
+        const panels = listed.items;
+        if (panels.length === 0)
+            return "(no panels available)";
+        return panels.map((panel) => `${panel.id}\t${panel.title}\t${panel.source}`).join("\n");
+    }
+    if (action === "open") {
+        const panelId = typeof args.panel_id === "string" ? args.panel_id.trim() : "";
+        if (!panelId)
+            return "Error: panel_id is required for action='open'";
+        const result = await bridge.open(panelId);
+        return result.ok
+            ? `Opened panel ${result.panelId}`
+            : `Error: ${result.detail ?? `could not open panel ${panelId}`}`;
+    }
+    if (action === "tools") {
+        const panelId = typeof args.panel_id === "string" ? args.panel_id.trim() : "";
+        if (!panelId)
+            return "Error: panel_id is required for action='tools'";
+        if (!bridge.tools)
+            return "Error: this panel host does not expose Agent tools";
+        const queried = await bridge.tools(panelId);
+        // Same hazard as list: "has no Agent tools" is a factual claim, so a Stop or
+        // a timeout must not be laundered into it.
+        if (queried.failed)
+            return `Error: ${queried.failed}`;
+        const tools = safePanelToolDescriptors(queried.items);
+        if (!tools)
+            return "Error: panel host returned malformed Agent tool descriptors";
+        if (tools.length === 0)
+            return `(panel ${panelId} has no Agent tools)`;
+        return (boundedPanelJson({ panelId, tools }) ??
+            "Error: panel host returned oversized Agent tool descriptors");
+    }
+    if (action === "invoke") {
+        const panelId = typeof args.panel_id === "string" ? args.panel_id.trim() : "";
+        const toolName = typeof args.tool_name === "string" ? args.tool_name.trim() : "";
+        if (!panelId)
+            return "Error: panel_id is required for action='invoke'";
+        if (!toolName)
+            return "Error: tool_name is required for action='invoke'";
+        if (!bridge.invoke)
+            return "Error: this panel host cannot invoke Agent tools";
+        if (args.arguments !== undefined &&
+            (!args.arguments || typeof args.arguments !== "object" || Array.isArray(args.arguments))) {
+            return "Error: arguments must be a JSON object for action='invoke'";
+        }
+        const toolArgs = args.arguments ?? {};
+        const result = await bridge.invoke(panelId, toolName, toolArgs);
+        if (!result.ok) {
+            return `Error: ${result.detail ?? `could not invoke ${toolName} in ${panelId}`}`;
+        }
+        const image = imageResult(result.result);
+        if (image)
+            return image;
+        return (boundedPanelJson({
+            panelId: result.panelId,
+            toolName: result.toolName,
+            result: result.result ?? null,
+        }) ?? "Error: Panel App returned an oversized or non-JSON result");
+    }
+    return `Error: unknown panel action '${String(action)}'`;
+}

package/dist/tool-system/builtin/read.js

@@ -125,7 +125,11 @@ function detectBinary(filePath, sample) {
     if (sample.includes(0))
         return { kind: "binary" };
     try {
-        new TextDecoder("utf-8", { fatal: true }).decode(sample);
+        // `stream: true` tolerates a multi-byte UTF-8 char truncated by the sample
+        // boundary (e.g. a CJK char split at byte 8192). Without it, a valid UTF-8
+        // text file gets misdetected as binary whenever the sample cut lands mid-char.
+        // A genuinely invalid byte in the MIDDLE of the sample still throws.
+        new TextDecoder("utf-8", { fatal: true }).decode(sample, { stream: true });
     }
     catch {
         return { kind: "binary" };

package/dist/tool-system/builtin/send-message-to-session.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext, ToolVisibilityContext } from "../context.js";
+export declare const SEND_MESSAGE_TO_SESSION_TOOL_NAME = "SendMessageToSession";
+export declare const sendMessageToSessionToolDef: ToolDefinition;
+export declare function rewriteSendMessageToSessionToolDefinition(def: ToolDefinition, ctx: ToolVisibilityContext): ToolDefinition;
+export declare function sendMessageToSessionTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/send-message-to-session.js

@@ -0,0 +1,67 @@
+export const SEND_MESSAGE_TO_SESSION_TOOL_NAME = "SendMessageToSession";
+export const sendMessageToSessionToolDef = {
+    name: SEND_MESSAGE_TO_SESSION_TOOL_NAME,
+    description: "Send a message to another host-authorized Session in the current project. " +
+        "Use this exactly like a person sending a message in that Session: the message becomes the target Session's next user turn and queues or starts its work. " +
+        "When you have later additions, call this tool again with another message. The call creates no persistent relationship or automatic subscription.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            target_session_id: {
+                type: "string",
+                description: "One target Session id from the host-authorized closed list.",
+            },
+            message: {
+                type: "string",
+                minLength: 1,
+                maxLength: 48_000,
+                description: "The complete message to send as the target Session's user turn: task, relevant context, constraints, and artifact paths.",
+            },
+        },
+        required: ["target_session_id", "message"],
+    },
+};
+export function rewriteSendMessageToSessionToolDefinition(def, ctx) {
+    const targets = ctx.sessionMessageTargets ?? [];
+    return {
+        ...def,
+        description: `${def.description}\n\nAvailable target Sessions:\n${targets
+            .map((target) => formatTarget(target))
+            .join("\n")}`,
+        inputSchema: {
+            ...def.inputSchema,
+            properties: {
+                ...(def.inputSchema.properties ?? {}),
+                target_session_id: {
+                    type: "string",
+                    enum: targets.map((target) => target.sessionId),
+                    description: "Select exactly one host-authorized target Session listed below.",
+                },
+            },
+        },
+    };
+}
+export async function sendMessageToSessionTool(args, ctx) {
+    const service = ctx?.sessionMessages;
+    if (!service)
+        return "Error: cross-Session messaging is not available in this run.";
+    const targetSessionId = typeof args.target_session_id === "string" ? args.target_session_id.trim() : "";
+    const message = typeof args.message === "string" ? args.message : "";
+    if (!targetSessionId)
+        return "Error: target_session_id is required.";
+    if (!message.trim())
+        return "Error: message is required.";
+    if (message.length > 48_000)
+        return "Error: message exceeds 48000 characters.";
+    try {
+        const target = await service.send({ targetSessionId, message });
+        return `Message sent to "${target.title}" (${target.sessionId}); its Session has queued the turn.`;
+    }
+    catch (error) {
+        return `Error: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+function formatTarget(target) {
+    const profile = target.workspaceProfile ? `; digital human: ${target.workspaceProfile}` : "";
+    return `- ${target.sessionId}: ${target.title}${profile}`;
+}

package/dist/tool-system/builtin/sources.d.ts

@@ -0,0 +1,8 @@
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+/** Registering the same adapter objects is safe to repeat across test/host imports. */
+export declare function registerBuiltinSourceAdapters(): void;
+export declare const listSourcesToolDef: ToolDefinition;
+export declare function listSourcesTool(_args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare const readSourceToolDef: ToolDefinition;
+export declare function readSourceTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;