@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/agent/tools2/tools/ls.js

@@ -0,0 +1,141 @@
+import path from "node:path";
+import { z } from "zod";
+import { mapVirtualSystemSkillsPathToPhysical } from "../../../skills/system/tool-paths.js";
+import { createToolFactory, PermissionLevel, ToolCategory } from "../types.js";
+/**
+ * Format file size into human-readable format (like ls -lh).
+ *
+ * @param bytes - File size in bytes
+ * @returns Human-readable size string (e.g., "1.5K", "32M")
+ */
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}K`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}G`;
+}
+/**
+ * Format date into ls -l style format.
+ *
+ * @param date - Date to format
+ * @returns Formatted date string (e.g., "Jan 15 14:30")
+ */
+function formatDate(date) {
+    const months = [
+        "Jan",
+        "Feb",
+        "Mar",
+        "Apr",
+        "May",
+        "Jun",
+        "Jul",
+        "Aug",
+        "Sep",
+        "Oct",
+        "Nov",
+        "Dec",
+    ];
+    const month = months[date.getMonth()];
+    const day = date.getDate().toString().padStart(2, " ");
+    const hours = date.getHours().toString().padStart(2, "0");
+    const minutes = date.getMinutes().toString().padStart(2, "0");
+    return `${month} ${day} ${hours}:${minutes}`;
+}
+/**
+ * Format file metadata into ls -lh style output line.
+ *
+ * @param meta - File metadata object
+ * @returns Formatted line (e.g., "-rw-r--r--  1 user  staff  1.5K Jan 15 14:30 file.ts")
+ */
+function formatMetadataLine(meta) {
+    const type = meta.isDirectory ? "d" : "-";
+    const perms = "rw-r--r--";
+    const size = formatSize(meta.size);
+    const date = formatDate(meta.mtime);
+    const name = path.basename(meta.path);
+    return `${type}${perms}  1 user  staff  ${size.padStart(6)} ${date} ${name}`;
+}
+/**
+ * ls tool - List directory contents with metadata.
+ *
+ * Lists files and directories in a specified path, showing file sizes,
+ * modification times, and whether each entry is a file or directory.
+ * Uses AppShell for virtual file system support (APIs appear as .ts files).
+ */
+export const lsToolFactory = createToolFactory("ls", (services) => ({
+    description: `
+List directory contents with metadata (file sizes, modification times, file/directory types).
+
+Use this tool when:
+- Browsing a specific directory to see what files and folders exist
+- Understanding directory structure
+- Need file metadata (sizes, timestamps) to decide which files to read
+- Initial exploration of an unfamiliar codebase
+- Finding recently modified files in a directory
+
+Returns formatted output similar to ls -lh. Call multiple times on subdirectories if you need to explore deeper.
+`,
+    category: ToolCategory.FILE,
+    defaultPermission: PermissionLevel.ALLOW,
+    inputSchema: z.object({
+        path: z
+            .string()
+            .optional()
+            .describe("Directory to list (defaults to current directory)"),
+        includeHidden: z
+            .boolean()
+            .optional()
+            .describe("Include hidden files (starting with .)"),
+    }),
+    readOnly: true,
+    execute: async ({ path: dirPath = ".", includeHidden = false }) => {
+        const appRoot = services.appShell.appRootDirPath;
+        // Resolve requested path against app root
+        const resolvedPath = path.resolve(appRoot, dirPath);
+        // Security: Prevent directory traversal outside app root
+        if (!resolvedPath.startsWith(appRoot)) {
+            throw new Error(`Access denied: path '${dirPath}' is outside the application directory`);
+        }
+        // Build glob pattern for this directory
+        const relativeDirPath = path.relative(appRoot, resolvedPath);
+        const physicalRelativeDirPath = mapVirtualSystemSkillsPathToPhysical(relativeDirPath);
+        const pattern = physicalRelativeDirPath
+            ? `${physicalRelativeDirPath}/*`
+            : "*";
+        // Get files with metadata from AppShell
+        const fileEntries = await services.appShell.listFiles([pattern], {
+            includeMetadata: true,
+            includeDirs: true,
+            dot: includeHidden,
+        });
+        // Filter file entries to only include direct children of the target directory
+        const directChildren = fileEntries.filter((entry) => {
+            const entryDir = path.dirname(entry.path);
+            return (entryDir === relativeDirPath || (entryDir === "." && !relativeDirPath));
+        });
+        // Combine and sort alphabetically by name
+        const allEntries = directChildren.sort((a, b) => path.basename(a.path).localeCompare(path.basename(b.path)));
+        // Format output
+        if (allEntries.length === 0) {
+            return { output: "" };
+        }
+        const lines = allEntries.map(formatMetadataLine);
+        const totalSize = allEntries.reduce((sum, e) => sum + e.size, 0);
+        const output = `total ${formatSize(totalSize)}\n${lines.join("\n")}`;
+        return { output };
+    },
+    getSummary: (_input, output) => {
+        // Count non-empty lines excluding the "total" line
+        const lines = output.output
+            .split("\n")
+            .filter((l) => l.trim() && !l.startsWith("total"));
+        const count = lines.length;
+        return {
+            output: `${count} item${count === 1 ? "" : "s"}`,
+        };
+    },
+}));
+//# sourceMappingURL=ls.js.map

package/dist/ai-service/agent/tools2/tools/ls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ls.js","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/ls.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/agent/tools2/tools/read.d.ts

@@ -0,0 +1,12 @@
+import type { AppShell } from "../../../app-interface/shell.js";
+/**
+ * Read tool - Reads files from the filesystem with optional offset/limit.
+ */
+export declare const readToolFactory: import("../types.js").ToolFactory<{
+    appShell: AppShell;
+}, import("../types.js").Tool<{
+    file_path: string;
+    limit?: number | undefined;
+    offset?: number | undefined;
+}, string>>;
+//# sourceMappingURL=read.d.ts.map

package/dist/ai-service/agent/tools2/tools/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/read.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAQhE;;GAEG;AACH,eAAO,MAAM,eAAe;cAEH,QAAQ;;;;;WAyDhC,CAAC"}

package/dist/ai-service/agent/tools2/tools/read.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { createToolFactory, PermissionLevel, ToolCategory, ToolExecutionError, } from "../types.js";
+/**
+ * Read tool - Reads files from the filesystem with optional offset/limit.
+ */
+export const readToolFactory = createToolFactory("read", (services) => ({
+    description: `
+Reads a file from the local filesystem. You can access any file directly by using this tool. Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
+`,
+    category: ToolCategory.FILE,
+    defaultPermission: PermissionLevel.ALLOW,
+    inputSchema: z.object({
+        file_path: z.string().describe("Relative path to file"),
+        offset: z
+            .number()
+            .optional()
+            .describe("Line number to start reading from"),
+        limit: z.number().optional().describe("Number of lines to read"),
+    }),
+    execute: async ({ file_path, offset, limit }) => {
+        try {
+            const content = await services.appShell.readFile(file_path, {
+                offset,
+                limit,
+            });
+            // Format with line numbers (cat -n style)
+            const lines = content.split("\n");
+            const lineNumberStart = offset ?? 1;
+            const formattedLines = lines.map((line, index) => {
+                const lineNumber = lineNumberStart + index;
+                return `${lineNumber.toString().padStart(6)}\t${line}`;
+            });
+            return formattedLines.join("\n");
+        }
+        catch (error) {
+            if (!(error instanceof Error)) {
+                throw new Error("Failed to read file: Unknown error");
+            }
+            throw new ToolExecutionError(`Failed to read file: ${error.message}`, {
+                toolName: "",
+                input: {},
+                context: {},
+                severity: "warn",
+            });
+        }
+    },
+    getSummary: (input, output) => {
+        // Full file read
+        if (input.offset === undefined && input.limit === undefined) {
+            return { output: "full read" };
+        }
+        const lineCount = typeof output === "string" ? output.split("\n").length : 0;
+        const startLine = input.offset ?? 1;
+        const endLine = startLine + lineCount - 1;
+        return {
+            output: `lines ${startLine}-${endLine}`,
+        };
+    },
+}));
+//# sourceMappingURL=read.js.map

package/dist/ai-service/agent/tools2/tools/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAC9C,MAAM,EACN,CAAC,QAAgC,EAAE,EAAE,CAAC,CAAC;IACrC,WAAW,EAAE;;CAEhB;IACG,QAAQ,EAAE,YAAY,CAAC,IAAI;IAC3B,iBAAiB,EAAE,eAAe,CAAC,KAAK;IACxC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC;QACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACvD,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,mCAAmC,CAAC;QAChD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yBAAyB,CAAC;KACjE,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE;QAC9C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE;gBAC1D,MAAM;gBACN,KAAK;aACN,CAAC,CAAC;YAEH,0CAA0C;YAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,CAAC;YACpC,MAAM,cAAc,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;gBAC/C,MAAM,UAAU,GAAG,eAAe,GAAG,KAAK,CAAC;gBAC3C,OAAO,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACzD,CAAC,CAAC,CAAC;YAEH,OAAO,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;gBAC9B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,IAAI,kBAAkB,CAAC,wBAAwB,KAAK,CAAC,OAAO,EAAE,EAAE;gBACpE,QAAQ,EAAE,EAAE;gBACZ,KAAK,EAAE,EAAE;gBACT,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,MAAM;aACjB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAC5B,iBAAiB;QACjB,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACjC,CAAC;QAED,MAAM,SAAS,GACb,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QACpC,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC;QAC1C,OAAO;YACL,MAAM,EAAE,SAAS,SAAS,IAAI,OAAO,EAAE;SACxC,CAAC;IACJ,CAAC;CACF,CAAC,CACH,CAAC"}

package/dist/ai-service/agent/tools2/tools/remember-knowledge.d.ts

@@ -0,0 +1,31 @@
+import type { RememberKnowledgeCandidate } from "@superblocksteam/library-shared/types";
+import type { Clark, ClarkStateHandlerParams } from "../../../state-machine/clark-fsm.js";
+/**
+ * The rememberKnowledge tool is a *signal* tool — it does not persist anything itself.
+ *
+ * When Clark calls it, it:
+ * 1. Sets `clark.context.rememberKnowledgeCandidatesForTurn` with the candidates
+ * 2. Triggers the approval flow for those candidates
+ *
+ * The actual persistence is handled in the llm-generating handler after the user confirms.
+ *
+ * This tool should be available from normal chat flow whenever Clark detects
+ * the user wants to remember something.
+ */
+export declare const rememberKnowledgeToolFactory: import("../types.js").ToolFactory<{
+    clark: Clark;
+    services: ClarkStateHandlerParams;
+}, import("../types.js").Tool<{
+    candidates: RememberKnowledgeCandidate[];
+}, {
+    success: boolean;
+    message: string;
+    candidates?: undefined;
+    recentlySavedMatches?: undefined;
+} | {
+    success: boolean;
+    message: string;
+    candidates: RememberKnowledgeCandidate[];
+    recentlySavedMatches: string[];
+}>>;
+//# sourceMappingURL=remember-knowledge.d.ts.map

package/dist/ai-service/agent/tools2/tools/remember-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember-knowledge.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/remember-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AAMxF,OAAO,KAAK,EACV,KAAK,EACL,uBAAuB,EACxB,MAAM,qCAAqC,CAAC;AAwC7C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B;WAElB,KAAK;cAAY,uBAAuB;;gBAiC3C,0BAA0B,EAAE;;;;;;;;;;;GAmE/C,CAAC"}

package/dist/ai-service/agent/tools2/tools/remember-knowledge.js

@@ -0,0 +1,118 @@
+import z from "zod";
+import { recordKnowledgeDuplicateHint, recordKnowledgeSuggestion, } from "../../../knowledge/knowledge-metrics.js";
+import { createToolFactory, PermissionLevel, ToolCategory } from "../types.js";
+const rememberKnowledgeCandidateSchema = z.object({
+    name: z
+        .string()
+        .describe('A short, unique, human-readable name for this knowledge entry (e.g. "No Emojis in UI")'),
+    description: z
+        .string()
+        .describe("A one-sentence summary that acts as a retrieval trigger for when this knowledge entry should be applied"),
+    content: z
+        .string()
+        .describe("The full content of the knowledge entry — a clear, actionable rule or preference"),
+    targetFactName: z
+        .string()
+        .optional()
+        .describe("For action=update or action=delete: the name of an existing knowledge entry to modify"),
+    action: z
+        .enum(["create", "update", "delete"])
+        .optional()
+        .default("create")
+        .describe("Whether to create a new knowledge entry, update an existing one, or delete one"),
+    reason: z
+        .string()
+        .optional()
+        .describe("Optional explanation of why this knowledge entry is being remembered"),
+});
+/**
+ * The rememberKnowledge tool is a *signal* tool — it does not persist anything itself.
+ *
+ * When Clark calls it, it:
+ * 1. Sets `clark.context.rememberKnowledgeCandidatesForTurn` with the candidates
+ * 2. Triggers the approval flow for those candidates
+ *
+ * The actual persistence is handled in the llm-generating handler after the user confirms.
+ *
+ * This tool should be available from normal chat flow whenever Clark detects
+ * the user wants to remember something.
+ */
+export const rememberKnowledgeToolFactory = createToolFactory("rememberKnowledge", ({ clark }) => {
+    return {
+        category: ToolCategory.MEMORY,
+        readOnly: true,
+        defaultPermission: PermissionLevel.ALLOW,
+        description: `Use this tool when the user wants you to remember, save, or keep track of a preference, rule, or instruction specific to this application.
+
+Call this tool when the user:
+- Explicitly says "/remember" or "remember this"
+- Says things like "always use X", "make sure you never Y", "I want you to know that Z"
+- Indicates a persistent preference or rule they want applied to this app going forward
+
+You should draft one or more knowledge-entry candidates based on what the user wants to remember.
+Each candidate should have:
+- A short, unique name
+- A clear one-sentence description that works as a retrieval trigger: include what the knowledge entry governs and the kinds of user requests/phrases that should activate it
+- The full rule/preference as content — **use Markdown** to structure the content: use headings, bullet lists, bold, and code blocks where appropriate so the knowledge entry is easy to read and follow
+
+After calling this tool, continue with the rest of the user's request. The knowledge entry is NOT saved yet — it will be shown to the user for approval. Do not tell the user that it's saved or remembered; say you've drafted it for their review.
+Do NOT call this tool for one-off instructions that only apply to the current task.
+
+Read existing knowledge before drafting new entries, and avoid duplicates unless you intend to update.`,
+        inputSchema: z.object({
+            candidates: z
+                .array(rememberKnowledgeCandidateSchema)
+                .min(1)
+                .describe("One or more knowledge entries to remember. Typically just one per call."),
+        }),
+        execute: async ({ candidates, }) => {
+            // Validate: reject placeholder content
+            const PLACEHOLDER_PATTERNS = [
+                /^update this knowledge/i,
+                /^placeholder/i,
+                /\[(?:insert|fill|replace|your|add|placeholder|todo|knowledge|content|description|name)\b.*\]/i,
+                /^TODO/i,
+            ];
+            const validCandidates = candidates.filter((c) => {
+                const isPlaceholder = PLACEHOLDER_PATTERNS.some((p) => p.test(c.content) || p.test(c.name));
+                return (!isPlaceholder &&
+                    c.content.trim().length > 0 &&
+                    c.name.trim().length > 0);
+            });
+            if (validCandidates.length === 0) {
+                return {
+                    success: false,
+                    message: "No valid knowledge-entry candidates provided. Please provide specific, non-placeholder content.",
+                };
+            }
+            const normalizedCandidates = validCandidates;
+            // Store candidates in Clark context for approval message handling
+            clark.updateContext((ctx) => ({
+                ...ctx,
+                rememberKnowledgeCandidatesForTurn: normalizedCandidates,
+                explicitRememberKnowledgeIntentForTurn: true,
+            }));
+            const recentOutcomes = clark.context.recentKnowledgeSaveOutcomes ?? [];
+            const recentNames = new Set(recentOutcomes
+                .filter((outcome) => outcome.status !== "failed")
+                .map((outcome) => outcome.factName.trim().toLowerCase()));
+            const recentlySavedMatches = normalizedCandidates
+                .filter((candidate) => recentNames.has(candidate.name.trim().toLowerCase()))
+                .map((candidate) => candidate.name);
+            recordKnowledgeSuggestion({
+                candidateCount: normalizedCandidates.length,
+                source: "remember_knowledge",
+            });
+            if (recentlySavedMatches.length > 0) {
+                recordKnowledgeDuplicateHint();
+            }
+            return {
+                success: true,
+                message: `Drafted ${normalizedCandidates.length} knowledge entr${normalizedCandidates.length === 1 ? "y" : "ies"} for user approval. Not saved yet — continue with the user's request.`,
+                candidates: normalizedCandidates,
+                recentlySavedMatches,
+            };
+        },
+    };
+});
+//# sourceMappingURL=remember-knowledge.js.map

package/dist/ai-service/agent/tools2/tools/remember-knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember-knowledge.js","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/remember-knowledge.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/agent/tools2/tools/spawn-coding-subagents.d.ts

@@ -0,0 +1,50 @@
+import { type HeapMonitor } from "../../../chat/transcript-budget.js";
+import type { Clark, ClarkStateHandlerParams } from "../../../state-machine/clark-fsm.js";
+import { type CodingSubagentResult } from "../../subagents/coding/run-coding-subagent.js";
+export declare function buildSpawnCodingSubagentsDescription(v2ToV3MigrationInProgress: boolean): string;
+export declare function buildSpawnCodingSubagentsApiNamesFieldDescription(v2ToV3MigrationInProgress: boolean): string;
+/**
+ * spawnCodingSubagents — main-agent-only tool that spawns a batch of
+ * coding sub-agents in parallel and waits for all of them to finish.
+ *
+ * Two callers exist today:
+ * - v2 → v3 migrations, where `restructure.ts` seeds
+ *   `.superblocks/ai/checklist.json` upfront before Clark ever runs.
+ * - third-party app migrations (Replit / Lovable / v0 / Next.js), where
+ *   no upfront seeding occurs — Clark seeds the checklist itself via
+ *   `build_manageChecklist` once it has read the source.
+ *
+ * Both callers need the on-disk checklist as the shared coordination
+ * surface for sub-agents (the in-memory `clark.context.checklist` is
+ * not safe to mutate from concurrent sub-agents). Whenever this tool
+ * is invoked without an existing checklist file, we lazily promote the
+ * current in-memory checklist (if any) onto disk so the sub-agents and
+ * the main agent see the same items going forward.
+ *
+ * Availability is gated on the caller being in a migration-shaped
+ * context: either an active checklist already exists, or the org has
+ * the third-party-import feature enabled (the only flag that signals
+ * "this Clark session may be doing an external app migration"). Outside
+ * those cases the tool errors so we don't accidentally spawn sub-agents
+ * during regular feature work.
+ */
+export declare const spawnCodingSubagentsToolFactory: import("../types.js").ToolFactory<{
+    clark: Clark;
+    services: ClarkStateHandlerParams;
+    v2ToV3MigrationInProgress: boolean;
+    heapMonitor?: HeapMonitor;
+}, import("../types.js").Tool<{
+    subagents: {
+        id: string;
+        instructions: string;
+        apiNames?: string[] | undefined;
+    }[];
+    maxStepsPerSubagent?: number | undefined;
+}, {
+    completed: number;
+    errored: number;
+    maxSteps: number;
+    success: boolean;
+    subagents: CodingSubagentResult[];
+}>>;
+//# sourceMappingURL=spawn-coding-subagents.d.ts.map

package/dist/ai-service/agent/tools2/tools/spawn-coding-subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-coding-subagents.d.ts","sourceRoot":"","sources":["../../../../../src/ai-service/agent/tools2/tools/spawn-coding-subagents.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EACV,KAAK,EACL,uBAAuB,EACxB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,+CAA+C,CAAC;AAkBvD,wBAAgB,oCAAoC,CAClD,yBAAyB,EAAE,OAAO,GACjC,MAAM,CAiDR;AAED,wBAAgB,iDAAiD,CAC/D,yBAAyB,EAAE,OAAO,GACjC,MAAM,CAKR;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,+BAA+B;WAQjC,KAAK;cACF,uBAAuB;+BACN,OAAO;kBACpB,WAAW;;;;;;;;;eAoOhB,MAAM;aACR,MAAM;cACL,MAAM;;;GALjB,CAAC"}