@steerable/agent-shell 0.6.15

package/LICENSE

@@ -0,0 +1,91 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form.
+
+"Work" shall mean the work of authorship made available under the
+License.
+
+"Derivative Works" shall mean any work based on the Work.
+
+"Contribution" shall mean any work of authorship intentionally
+submitted to Licensor for inclusion in the Work.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor.
+
+2. Grant of Copyright License.
+Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable copyright license to reproduce, prepare
+Derivative Works of, publicly display, publicly perform, sublicense,
+and distribute the Work and such Derivative Works in Source or Object
+form.
+
+3. Grant of Patent License.
+Subject to the terms and conditions of this License, each Contributor
+hereby grants to You a perpetual, worldwide, non-exclusive, no-charge,
+royalty-free, irrevocable patent license to make, have made, use,
+offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution.
+You may reproduce and distribute copies of the Work or Derivative
+Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative
+Works a copy of this License; and
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+(c) You must retain, in the Source form of any Derivative Works that
+You distribute, all copyright, patent, trademark, and attribution
+notices from the Source form of the Work; and
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained within
+such NOTICE file.
+
+5. Submission of Contributions.
+Unless You explicitly state otherwise, any Contribution intentionally
+submitted for inclusion in the Work shall be under the terms and
+conditions of this License.
+
+6. Trademarks.
+This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor.
+
+7. Disclaimer of Warranty.
+Unless required by applicable law or agreed to in writing, Licensor
+provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS
+OF ANY KIND.
+
+8. Limitation of Liability.
+In no event and under no legal theory shall any Contributor be liable
+to You for damages arising as a result of this License or out of the
+use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability.
+While redistributing the Work or Derivative Works thereof, You may
+choose to offer, and charge a fee for, acceptance of support, warranty,
+indemnity, or other liability obligations.

package/contracts/tool-contract.json

@@ -0,0 +1,326 @@
+{
+  "edit": {
+    "atomic": true,
+    "errorCodes": [
+      "empty_old",
+      "no_edits",
+      "ambiguous",
+      "not_found",
+      "overlap"
+    ],
+    "matchLevels": [
+      "exact",
+      "trim",
+      "unicode"
+    ],
+    "newField": "newText",
+    "oldField": "oldText",
+    "overlap": "reject"
+  },
+  "toolSearch": {
+    "bm25": {
+      "b": 0.75,
+      "k1": 1.2,
+      "nameWeight": 2
+    },
+    "defaultMaxResults": 8,
+    "inventory": [
+      {
+        "description": "Create a new issue in a GitHub repository",
+        "name": "mcp__github__create_issue"
+      },
+      {
+        "description": "Search issues and pull requests in a repository",
+        "name": "mcp__github__search_issues"
+      },
+      {
+        "description": "List repositories for the authenticated user",
+        "name": "mcp__github__list_repos"
+      },
+      {
+        "description": "Post a message to a Slack channel",
+        "name": "mcp__slack__post_message"
+      },
+      {
+        "description": "Search messages across Slack channels",
+        "name": "mcp__slack__search_messages"
+      },
+      {
+        "description": "Create an issue in a Linear workspace",
+        "name": "mcp__linear__create_issue"
+      },
+      {
+        "description": "Read a file from the local workspace",
+        "name": "local_read_file"
+      },
+      {
+        "description": "A tool whose entire name is one query term",
+        "name": "issue"
+      }
+    ],
+    "maxResultsCeiling": 20,
+    "scoreTolerance": 1e-12,
+    "scoreVectors": [
+      {
+        "query": "github",
+        "ranked": [
+          {
+            "name": "mcp__github__create_issue",
+            "score": 1.443104830718
+          },
+          {
+            "name": "mcp__github__list_repos",
+            "score": 1.30187499838
+          },
+          {
+            "name": "mcp__github__search_issues",
+            "score": 1.251896326088
+          }
+        ]
+      },
+      {
+        "query": "create issue",
+        "ranked": [
+          {
+            "name": "mcp__linear__create_issue",
+            "score": 3.451237117528
+          },
+          {
+            "name": "mcp__github__create_issue",
+            "score": 3.400327657896
+          },
+          {
+            "name": "issue",
+            "score": 1.384801863508
+          }
+        ]
+      },
+      {
+        "query": "message",
+        "ranked": [
+          {
+            "name": "mcp__slack__post_message",
+            "score": 2.778736145041
+          }
+        ]
+      },
+      {
+        "query": "search",
+        "ranked": [
+          {
+            "name": "mcp__slack__search_messages",
+            "score": 2.047846649401
+          },
+          {
+            "name": "mcp__github__search_issues",
+            "score": 1.957222827178
+          }
+        ]
+      },
+      {
+        "query": "issue repository",
+        "ranked": [
+          {
+            "name": "mcp__github__create_issue",
+            "score": 2.658061541828
+          },
+          {
+            "name": "mcp__linear__create_issue",
+            "score": 1.464710891814
+          },
+          {
+            "name": "issue",
+            "score": 1.384801863508
+          },
+          {
+            "name": "mcp__github__search_issues",
+            "score": 1.21495671111
+          }
+        ]
+      },
+      {
+        "query": "issue",
+        "ranked": [
+          {
+            "name": "mcp__linear__create_issue",
+            "score": 1.464710891814
+          },
+          {
+            "name": "mcp__github__create_issue",
+            "score": 1.443104830718
+          },
+          {
+            "name": "issue",
+            "score": 1.384801863508
+          }
+        ]
+      },
+      {
+        "query": "create",
+        "ranked": [
+          {
+            "name": "mcp__linear__create_issue",
+            "score": 1.986526225713
+          },
+          {
+            "name": "mcp__github__create_issue",
+            "score": 1.957222827178
+          }
+        ]
+      },
+      {
+        "query": "slack channel",
+        "ranked": [
+          {
+            "name": "mcp__slack__post_message",
+            "score": 3.734001329872
+          },
+          {
+            "name": "mcp__slack__search_messages",
+            "score": 2.047846649401
+          }
+        ]
+      },
+      {
+        "query": "linear workspace search",
+        "ranked": [
+          {
+            "name": "mcp__linear__create_issue",
+            "score": 4.028010974315
+          },
+          {
+            "name": "mcp__slack__search_messages",
+            "score": 2.047846649401
+          },
+          {
+            "name": "mcp__github__search_issues",
+            "score": 1.957222827178
+          },
+          {
+            "name": "local_read_file",
+            "score": 1.324075484332
+          }
+        ]
+      },
+      {
+        "query": "mcp",
+        "ranked": [
+          {
+            "name": "mcp__slack__search_messages",
+            "score": 0.4577086775
+          },
+          {
+            "name": "mcp__github__list_repos",
+            "score": 0.448572269188
+          },
+          {
+            "name": "mcp__linear__create_issue",
+            "score": 0.439793469682
+          },
+          {
+            "name": "mcp__slack__post_message",
+            "score": 0.439793469682
+          },
+          {
+            "name": "mcp__github__create_issue",
+            "score": 0.431351686207
+          },
+          {
+            "name": "mcp__github__search_issues",
+            "score": 0.431351686207
+          }
+        ]
+      },
+      {
+        "query": "kubernetes helm rollout",
+        "ranked": []
+      },
+      {
+        "query": "zzz",
+        "ranked": []
+      }
+    ],
+    "tieBreak": "score descending, then name ascending"
+  },
+  "tools": {
+    "bash": {
+      "desktopName": "local_exec_shell",
+      "requiredInput": [
+        "command"
+      ],
+      "requiredResult": [
+        "exitCode",
+        "stdout",
+        "stderr"
+      ]
+    },
+    "edit_file": {
+      "desktopName": "local_edit_file",
+      "optionalInput": [
+        "expectedVersion"
+      ],
+      "requiredInput": [
+        "path",
+        "edits"
+      ],
+      "requiredResult": [
+        "version",
+        "diff",
+        "applied",
+        "matches"
+      ]
+    },
+    "read_file": {
+      "desktopName": "local_read_file",
+      "requiredInput": [
+        "path"
+      ],
+      "requiredResult": [
+        "content",
+        "version"
+      ]
+    },
+    "write_file": {
+      "desktopName": "local_write_file",
+      "optionalInput": [
+        "expectedVersion"
+      ],
+      "requiredInput": [
+        "path",
+        "content"
+      ],
+      "requiredResult": [
+        "version"
+      ]
+    }
+  },
+  "version": 2,
+  "versionAlgorithm": "sha256-utf8-hex",
+  "versionToken": {
+    "inputField": "expectedVersion",
+    "onConflict": "reject",
+    "resultField": "version"
+  },
+  "versionVectors": [
+    {
+      "input": "",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "input": "hello world",
+      "sha256": "b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9"
+    },
+    {
+      "input": "中文测试",
+      "sha256": "e350545d18735c5dd2dec50dcb971f3eb4cdda24b95a79bdb6b553f6a01ceb87"
+    },
+    {
+      "input": "line1\nline2\n",
+      "sha256": "2751a3a2f303ad21752038085e2b8c5f98ecff61a2e4ebbd43506a941725be80"
+    },
+    {
+      "input": "The quick brown fox jumps over the lazy dog 中文 123",
+      "sha256": "58117d7814c853d4309001a610af6de66b4b2e73dadff71ab5514ea674218644"
+    }
+  ]
+}

package/dist/attachments.d.ts

@@ -0,0 +1,41 @@
+export declare const ATTACHMENTS_DIR_NAME = "attachments";
+/** 单个附件上限（base64 解码前字节数）；多文件总和还受 HTTP body 上限约束。 */
+export declare const ATTACHMENT_MAX_BYTES: number;
+export interface AttachmentInput {
+    /** Electron：源文件绝对路径。 */
+    path?: string;
+    /** 原始文件名（用于落盘命名）。 */
+    name?: string;
+    /** BS/browser：base64 编码的文件字节。 */
+    data?: string;
+}
+export interface StoredAttachment {
+    /** 落盘后的文件名（可能与原名不同，同名会加 -N 后缀）。 */
+    name: string;
+    /** 落盘后的绝对路径。失败时为空串。 */
+    path: string;
+    /** 文件字节数。失败时为 0。 */
+    size: number;
+    /** 单个文件失败原因（成功时缺省）。 */
+    error?: string;
+}
+export declare function isValidChatAttachmentsKey(chatId: string): boolean;
+/**
+ * 当前会话的附件目录（会确保目录存在）。chatId 非法时仍然返回路径但由
+ * 调用方在写入前用 {@link isValidChatAttachmentsKey} 校验。
+ */
+export declare function getChatAttachmentsDir(chatId: string): string;
+/** 去掉路径分隔符与控制字符，只保留安全的文件名。 */
+export declare function sanitizeName(name: string): string;
+/** 同名文件加 -1 / -2 后缀，避免覆盖已有附件。 */
+export declare function uniqueFileName(dir: string, name: string): string;
+/**
+ * 把一批附件落进会话附件目录。按输入顺序返回逐文件结果（成功或失败都
+ * 不会中断整批），调用方据此决定哪些文件可用。
+ *
+ * 每个文件二选一提供来源：`path`（服务端直接拷贝）或 `data`（base64 字节，
+ * 服务端解码落盘）。两者都缺时记 error；两者都有时优先 `data`。
+ */
+export declare function saveAttachmentFiles(chatId: string, files: AttachmentInput[]): Promise<{
+    files: StoredAttachment[];
+}>;

package/dist/attachments.js

@@ -0,0 +1,147 @@
+/**
+ * 会话附件空间：把用户在输入框上传的文件持久化到会话对应的空间内。
+ *
+ * 每个会话一个独立目录：`<userDataDir>/attachments/<chatId>/`。持久化的
+ * 好处与场景包的每会话工作区（<pack>-projects/<chatId>）一致：
+ *   - 文件不再依赖「原始路径」——用户拖进来的临时下载文件、截图被移动 /
+ *     删除后，会话里的引用仍然有效；
+ *   - 后续轮次 agent 可以通过 `local_read_file`（以及图像附件的多模态
+ *     `metadata.images`）稳定读回这份文件；
+ *   - 目录按 chatId 隔离，删除会话时（未来的清理逻辑）可以整体回收。
+ *
+ * 与 `image-attachment.ts` 的分工：本模块只负责「把文件放进去」；图片怎么
+ * 解码成模型可见的 base64 仍由 `image-attachment.ts` 处理。二者路径都在
+ * 主进程 / BS 服务端。
+ *
+ * 写入支持两种来源（Electron 与 BS 模式各用其一）：
+ *   - `path`：Electron 拖拽 / `<input type="file">` 的 File 对象带真实路径，
+ *     服务端直接 copyFile；
+ *   - `data`：浏览器（BS 模式）里 File 没有路径，renderer 读成 base64 传上
+ *     来，服务端解码后落盘。
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { copyFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getUserDataDir } from './runtime.js';
+export const ATTACHMENTS_DIR_NAME = 'attachments';
+/** 单个附件上限（base64 解码前字节数）；多文件总和还受 HTTP body 上限约束。 */
+export const ATTACHMENT_MAX_BYTES = 25 * 1024 * 1024;
+/** chatId 由 storage 用 randomUUID 生成；这里只做白名单防御。 */
+const SAFE_CHAT_ID = /^[0-9a-zA-Z_-]{1,64}$/;
+export function isValidChatAttachmentsKey(chatId) {
+    return SAFE_CHAT_ID.test(chatId);
+}
+/**
+ * 当前会话的附件目录（会确保目录存在）。chatId 非法时仍然返回路径但由
+ * 调用方在写入前用 {@link isValidChatAttachmentsKey} 校验。
+ */
+export function getChatAttachmentsDir(chatId) {
+    const dir = path.join(getUserDataDir(), ATTACHMENTS_DIR_NAME, chatId);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** 去掉路径分隔符与控制字符，只保留安全的文件名。 */
+export function sanitizeName(name) {
+    const raw = String(name ?? '').replace(/\\/g, '/');
+    const base = raw.split('/').pop() ?? '';
+    const cleaned = base
+        // 控制字符与 Windows/跨平台保留字符统一替换为下划线。
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\u0000-\u001f<>:"|?*]/g, '_')
+        .trim();
+    return cleaned || 'file';
+}
+/** 同名文件加 -1 / -2 后缀，避免覆盖已有附件。 */
+export function uniqueFileName(dir, name) {
+    if (!existsSync(path.join(dir, name)))
+        return name;
+    const ext = path.extname(name);
+    const base = path.basename(name, ext);
+    for (let i = 1; i < 100_000; i += 1) {
+        const candidate = `${base}-${i}${ext}`;
+        if (!existsSync(path.join(dir, candidate)))
+            return candidate;
+    }
+    return `${base}-${Date.now()}${ext}`;
+}
+/** base64 → Buffer；空串返回 null（表示「没有数据来源」）。 */
+function decodeData(data) {
+    const text = data.trim();
+    if (!text)
+        return null;
+    return Buffer.from(text, 'base64');
+}
+/**
+ * 把一批附件落进会话附件目录。按输入顺序返回逐文件结果（成功或失败都
+ * 不会中断整批），调用方据此决定哪些文件可用。
+ *
+ * 每个文件二选一提供来源：`path`（服务端直接拷贝）或 `data`（base64 字节，
+ * 服务端解码落盘）。两者都缺时记 error；两者都有时优先 `data`。
+ */
+export async function saveAttachmentFiles(chatId, files) {
+    const out = [];
+    if (!isValidChatAttachmentsKey(chatId)) {
+        for (const file of files) {
+            const name = sanitizeName(file.name || path.basename(file.path || ''));
+            out.push({ name, path: '', size: 0, error: `invalid chatId: ${chatId}` });
+        }
+        return { files: out };
+    }
+    const dir = getChatAttachmentsDir(chatId);
+    for (const file of files) {
+        const sourcePath = typeof file.path === 'string' ? file.path.trim() : '';
+        const name = sanitizeName(file.name || path.basename(sourcePath || ''));
+        const data = typeof file.data === 'string' ? file.data : '';
+        try {
+            if (data.trim()) {
+                const bytes = decodeData(data);
+                const size = bytes.length;
+                if (size > ATTACHMENT_MAX_BYTES) {
+                    out.push({
+                        name,
+                        path: '',
+                        size: 0,
+                        error: `file too large (${size} bytes), max=${ATTACHMENT_MAX_BYTES}`,
+                    });
+                    continue;
+                }
+                const storedName = uniqueFileName(dir, name);
+                const destPath = path.join(dir, storedName);
+                await writeFile(destPath, bytes);
+                out.push({ name: storedName, path: destPath, size });
+                continue;
+            }
+            if (sourcePath) {
+                const sourceStat = await stat(sourcePath);
+                if (!sourceStat.isFile()) {
+                    out.push({ name, path: '', size: 0, error: 'source is not a regular file' });
+                    continue;
+                }
+                if (sourceStat.size > ATTACHMENT_MAX_BYTES) {
+                    out.push({
+                        name,
+                        path: '',
+                        size: 0,
+                        error: `file too large (${sourceStat.size} bytes), max=${ATTACHMENT_MAX_BYTES}`,
+                    });
+                    continue;
+                }
+                const storedName = uniqueFileName(dir, name);
+                const destPath = path.join(dir, storedName);
+                await copyFile(sourcePath, destPath);
+                out.push({ name: storedName, path: destPath, size: sourceStat.size });
+                continue;
+            }
+            out.push({ name, path: '', size: 0, error: 'no content (missing path and data)' });
+        }
+        catch (err) {
+            out.push({
+                name,
+                path: '',
+                size: 0,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { files: out };
+}

package/dist/brand.d.ts

@@ -0,0 +1,24 @@
+import type { ScenarioId } from './scenario/pack.js';
+/** 开放字符串（0.3g）：'generic' | 各场景产品 flavor | 未来产品 id。 */
+export type AppFlavor = ScenarioId;
+/** shell 默认智能体；场景产品里仍可选，但不一定作为首页默认。 */
+export declare const LOCAL_ASSISTANT_AGENT_ID = "local-assistant";
+/** 内置「智能助手」：种子时 `loadAllSkills` 开启（无视触发条件全量加载技能）。 */
+export declare const ALL_ROUND_ASSISTANT_AGENT_ID = "all-round-assistant";
+export interface Brand {
+    flavor: AppFlavor;
+    /** UI 显示名：窗口标题、通知标题等 */
+    displayName: string;
+    /** LLM 身份自称（系统提示词里用） */
+    agentName: string;
+    /** 一句话定位（fallback prompt 用） */
+    tagline: string;
+    /** 新对话 / 首页未选手动专家时绑定的内置智能体 id */
+    defaultAgentId: string;
+}
+/**
+ * 注入产品品牌（产品组装根在第一个 import 时调用）。重复注入抛错
+ * （组装期笔误，fail fast）。注入后作废缓存，后续 getBrand() 重算。
+ */
+export declare function setProductBrand(brand: Omit<Brand, 'flavor'>): void;
+export declare function getBrand(): Brand;