@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/core/schema.d.ts

@@ -0,0 +1,139 @@
+import * as z from 'zod/v4';
+export declare const IsoDateTime: z.ZodISODateTime;
+export declare const Sha256Hex: z.ZodString;
+export declare const NonNegInt: z.ZodInt;
+export declare const PositiveInt: z.ZodInt;
+declare const FILE_TYPES: readonly ["file", "directory", "symlink", "other"];
+export type FileType = (typeof FILE_TYPES)[number];
+export declare const FileType: z.ZodEnum<{
+    file: "file";
+    directory: "directory";
+    symlink: "symlink";
+    other: "other";
+}>;
+declare const FILE_KINDS: readonly ["text", "binary", "image", "audio", "pdf"];
+export type FileKind = (typeof FILE_KINDS)[number];
+export declare const FileKind: z.ZodEnum<{
+    binary: "binary";
+    text: "text";
+    image: "image";
+    audio: "audio";
+    pdf: "pdf";
+}>;
+export declare const SHELL_METACHAR_RE: RegExp;
+export declare const isBlank: (val: string) => boolean;
+export declare const OptionalPath: z.ZodOptional<z.ZodString>;
+export declare const RequiredPath: z.ZodString;
+export declare const SafeGlobPattern: z.ZodString;
+export declare const FileInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+        symlink: "symlink";
+        other: "other";
+    }>;
+    size: z.ZodInt;
+    tokenEstimate: z.ZodOptional<z.ZodInt>;
+    created: z.ZodISODateTime;
+    modified: z.ZodISODateTime;
+    accessed: z.ZodISODateTime;
+    permissions: z.ZodString;
+    isHidden: z.ZodBoolean;
+    mimeType: z.ZodOptional<z.ZodString>;
+    symlinkTarget: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const OperationSummarySchema: z.ZodObject<{
+    total: z.ZodInt;
+    succeeded: z.ZodInt;
+    failed: z.ZodInt;
+}, z.core.$strict>;
+export declare const PerFileErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** One entry of a tool's `failures[]`: the path that failed and why. */
+export declare const PathFailureSchema: z.ZodObject<{
+    path: z.ZodString;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * One entry of a source→destination tool's `failures[]`. The verb and noun stay
+ * per-op so the `.describe()` text reads correctly for each caller.
+ */
+export declare function pairFailureSchema(verb: 'copied' | 'moved', noun: 'copy' | 'move'): z.ZodObject<{
+    source: z.ZodString;
+    destination: z.ZodString;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Wire shape of a `pairFailureSchema` entry — the runtime twin of the schema. */
+export type PairFailureItem = z.infer<ReturnType<typeof pairFailureSchema>>;
+interface ReadRangeDescriptions {
+    head: string;
+    tail: string;
+    startLine: string;
+    endLine: string;
+}
+export declare function createReadRangeFields(descs: ReadRangeDescriptions): {
+    head: z.ZodOptional<z.ZodInt32>;
+    tail: z.ZodOptional<z.ZodInt32>;
+    startLine: z.ZodOptional<z.ZodInt32>;
+    endLine: z.ZodOptional<z.ZodInt32>;
+};
+export declare function validateReadRange(value: {
+    head?: number | undefined;
+    tail?: number | undefined;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+}, ctx: z.RefinementCtx): void;
+export declare function defaultFalseBoolean(description: string): z.ZodDefault<z.ZodBoolean>;
+export declare const includeHiddenField: () => z.ZodDefault<z.ZodBoolean>;
+export declare const includeIgnoredField: () => z.ZodDefault<z.ZodBoolean>;
+export declare const maxDepthField: () => z.ZodOptional<z.ZodNumber>;
+export type SingleOrBatchShape<TExtra extends z.ZodRawShape> = TExtra & {
+    path: z.ZodOptional<typeof RequiredPath>;
+    paths: z.ZodOptional<z.ZodArray<typeof RequiredPath>>;
+};
+export declare function singleOrBatchPathsInput<TExtra extends z.ZodRawShape>(opts: {
+    extra: TExtra;
+    maxBatch?: number;
+}): z.ZodObject<SingleOrBatchShape<TExtra>>;
+/**
+ * Extract the filesystem paths from a {@link singleOrBatchPathsInput} shape
+ * (`{ path?, paths?, files?[{path}] }`) for the executor's access-grant
+ * pre-check. Exactly one of the three is set (enforced by the schema's
+ * superRefine), so they are checked in priority order.
+ */
+export declare function singleOrBatchAccessPaths(args: {
+    path?: string | undefined;
+    paths?: string[] | undefined;
+    files?: readonly {
+        path: string;
+    }[] | undefined;
+}): string[];
+export declare const ContinuationSchema: z.ZodObject<{
+    tool: z.ZodString;
+    args: z.ZodObject<{
+        path: z.ZodString;
+        startLine: z.ZodInt;
+        endLine: z.ZodInt;
+    }, z.core.$strict>;
+    hint: z.ZodString;
+}, z.core.$strict>;
+export declare const CursorSchema: z.ZodOptional<z.ZodString>;
+export declare const NextCursorSchema: z.ZodOptional<z.ZodString>;
+export {};
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAY5B,eAAO,MAAM,WAAW,kBAMtB,CAAC;AAIH,eAAO,MAAM,SAAS,aAG2D,CAAC;AAElF,eAAO,MAAM,SAAS,UAEoB,CAAC;AAE3C,eAAO,MAAM,WAAW,UAEe,CAAC;AAExC,QAAA,MAAM,UAAU,oDAAc,CAAC;AAC/B,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,eAAO,MAAM,QAAQ;;;;;EAAqB,CAAC;AAE3C,QAAA,MAAM,UAAU,sDAAa,CAAC;AAC9B,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,eAAO,MAAM,QAAQ;;;;;;EAAqB,CAAC;AAI3C,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAE7C,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAAkC,CAAC;AA6CzE,eAAO,MAAM,YAAY,4BAAsB,CAAC;AAChD,eAAO,MAAM,YAAY,aAAW,CAAC;AAErC,eAAO,MAAM,eAAe,aA0CmC,CAAC;AAKhE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;kBAazB,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;;kBAIjC,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;kBAK7B,CAAC;AAEH,wEAAwE;AACxE,eAAO,MAAM,iBAAiB;;;;;;;;kBAG5B,CAAC;AAEH;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM;;;;;;;;;mBAMhF;AAED,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC,CAAC;AAI5E,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,qBAAqB;;;;;EA2BjE;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE;IACL,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B,EACD,GAAG,EAAE,CAAC,CAAC,aAAa,GACnB,IAAI,CA0DN;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAEnF;AAED,eAAO,MAAM,kBAAkB,QAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CACA,CAAC;AAChE,eAAO,MAAM,mBAAmB,QAAO,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CACS,CAAC;AAC1E,eAAO,MAAM,aAAa,QAAO,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAM+B,CAAC;AAI1F,MAAM,MAAM,kBAAkB,CAAC,MAAM,SAAS,CAAC,CAAC,WAAW,IAAI,MAAM,GAAG;IACtE,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;IACzC,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;CACvD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,MAAM,SAAS,CAAC,CAAC,WAAW,EAAE,IAAI,EAAE;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CA4C1C;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7B,KAAK,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;CACjD,GAAG,MAAM,EAAE,CAKX;AAQD,eAAO,MAAM,kBAAkB;;;;;;;;kBAM7B,CAAC;AAQH,eAAO,MAAM,YAAY,4BAKtB,CAAC;AAEJ,eAAO,MAAM,gBAAgB,4BAEgD,CAAC"}

package/dist/core/schema.js

@@ -0,0 +1,345 @@
+import * as z from 'zod/v4';
+import { isSafeGlobSyntax } from './glob.js';
+import { MIME_KINDS } from './mime.js';
+import { ENTRY_TYPES } from './primitives.js';
+import { MAX_SEARCH_DEPTH } from './util.js';
+// Runtime: full ISO-8601 UTC; emits the standard `date-time` format on the wire
+// (no AJV warning — it is a known format, unlike sha256_hex / base64url).
+// No `id` on this or any other shared schema below: an `id` hoists the schema
+// into `$defs` and leaves a `$ref` at every use site, which is exactly the wire
+// weight `toDraft202012` (tools/define.ts) publishes without.
+export const IsoDateTime = z.iso.datetime().meta({
+    description: 'ISO 8601 UTC date-time string (e.g. 2024-01-15T12:00:00.000Z)',
+    // `format: "date-time"` already pins the value; zod's ~330-char calendar
+    // regex is pure wire weight. Runtime validation still runs it — this
+    // suppresses the emitted keyword only.
+    pattern: undefined,
+});
+// pattern (not z.hash('sha256')) so no `format: "sha256_hex"` keyword is emitted;
+// the SDK's AJV validator warns on that unknown format at every server start.
+export const Sha256Hex = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/)
+    .meta({ description: 'SHA-256 digest as a 64-character lowercase hex string' });
+export const NonNegInt = z
+    .int({ message: 'Must be integer' })
+    .nonnegative({ message: 'Must be ≥ 0' });
+export const PositiveInt = z
+    .int({ message: 'Must be integer' })
+    .positive({ message: 'Must be > 0' });
+const FILE_TYPES = ENTRY_TYPES;
+export const FileType = z.enum(FILE_TYPES);
+const FILE_KINDS = MIME_KINDS;
+export const FileKind = z.enum(FILE_KINDS);
+const MAX_PATH_LENGTH = 4096;
+export const SHELL_METACHAR_RE = /[\n\r;|`]/;
+export const isBlank = (val) => val.trim().length === 0;
+const PathBase = z
+    .string()
+    .min(1, { message: 'Path required' })
+    .max(MAX_PATH_LENGTH, { message: `Path too long (max ${MAX_PATH_LENGTH} chars)` })
+    .superRefine((val, ctx) => {
+    if (val.length === 0) {
+        return;
+    }
+    if (val.trim().length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Path cannot be empty or whitespace-only',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+    if (val.includes('\0')) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Path cannot contain null bytes',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+    if (val.includes('..')) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Directory traversal sequences ("..") are forbidden',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+    if (SHELL_METACHAR_RE.test(val)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Path contains prohibited characters (newlines or shell metacharacters)',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+})
+    .describe('File or directory path inside an allowed workspace root.');
+export const OptionalPath = PathBase.optional();
+export const RequiredPath = PathBase;
+export const SafeGlobPattern = z
+    .string()
+    .min(1, { message: 'Pattern required' })
+    .max(1000, { message: 'Max 1000 chars' })
+    .superRefine((val, ctx) => {
+    if (val.length === 0) {
+        return;
+    }
+    if (val.trim().length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Pattern cannot be empty or whitespace-only',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+    if (val.includes('\0')) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Pattern cannot contain null bytes',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+    if (!isSafeGlobSyntax(val)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Invalid glob or unsafe path (absolute/.. forbidden)',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+    if (SHELL_METACHAR_RE.test(val)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Pattern contains prohibited characters (newlines or shell metacharacters)',
+            fatal: true,
+        });
+        return z.NEVER;
+    }
+})
+    .describe('Relative glob pattern under the search root (e.g. "**/*.ts", "src/**/*.js").')
+    .meta({ examples: ['**/*.ts', 'src/**/*.js', '*.{ts,tsx}'] });
+// Only the fields whose key does not already say what they hold carry a
+// description. A `.describe('Name')` on `name` costs every client tokens to
+// learn nothing.
+export const FileInfoSchema = z.strictObject({
+    name: z.string(),
+    path: z.string(),
+    type: FileType,
+    size: NonNegInt,
+    tokenEstimate: NonNegInt.optional().describe('Rough token estimate; use to pre-screen read cost'),
+    created: IsoDateTime,
+    modified: IsoDateTime,
+    accessed: IsoDateTime,
+    permissions: z.string(),
+    isHidden: z.boolean(),
+    mimeType: z.string().optional(),
+    symlinkTarget: z.string().optional().describe('Target (symlink)'),
+});
+export const OperationSummarySchema = z.strictObject({
+    total: NonNegInt,
+    succeeded: NonNegInt,
+    failed: NonNegInt,
+});
+export const PerFileErrorSchema = z.strictObject({
+    code: z.string(),
+    message: z.string(),
+    path: z.string().optional(),
+    suggestion: z.string().optional(),
+});
+/** One entry of a tool's `failures[]`: the path that failed and why. */
+export const PathFailureSchema = z.strictObject({
+    path: z.string(),
+    error: PerFileErrorSchema,
+});
+/**
+ * One entry of a source→destination tool's `failures[]`. The verb and noun stay
+ * per-op so the `.describe()` text reads correctly for each caller.
+ */
+export function pairFailureSchema(verb, noun) {
+    return z.strictObject({
+        source: z.string().describe(`Source path that could not be ${verb}`),
+        destination: z.string().describe(`Intended destination path for the failed ${noun}`),
+        error: PerFileErrorSchema,
+    });
+}
+export function createReadRangeFields(descs) {
+    return {
+        head: z
+            .int32()
+            .min(1, { message: 'Min: 1' })
+            .max(100000, { message: 'Max: 100,000' })
+            .optional()
+            .describe(descs.head),
+        tail: z
+            .int32()
+            .min(1, { message: 'Min: 1' })
+            .max(100000, { message: 'Max: 100,000' })
+            .optional()
+            .describe(descs.tail),
+        startLine: z
+            .int32()
+            .min(1, { message: 'Min: 1' })
+            .max(100000, { message: 'Max: 100,000' })
+            .optional()
+            .describe(descs.startLine),
+        endLine: z
+            .int32()
+            .min(1, { message: 'Min: 1' })
+            .max(100000, { message: 'Max: 100,000' })
+            .optional()
+            .describe(descs.endLine),
+    };
+}
+export function validateReadRange(value, ctx) {
+    const hasHead = value.head !== undefined;
+    const hasTail = value.tail !== undefined;
+    const hasStart = value.startLine !== undefined;
+    const hasEnd = value.endLine !== undefined;
+    if (hasHead && (hasStart || hasEnd)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['head'],
+            message: "Cannot use 'head' with 'startLine'/'endLine'",
+            params: {
+                rule: 'head_no_line_range',
+                conflictsWith: ['startLine', 'endLine'],
+                suggestion: "Use either 'head' alone or 'startLine'/'endLine' together.",
+            },
+            input: value,
+        });
+    }
+    if (hasTail && (hasHead || hasStart || hasEnd)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['tail'],
+            message: "Cannot use 'tail' with 'head'/'startLine'/'endLine'",
+            params: {
+                rule: 'tail_exclusive',
+                conflictsWith: ['head', 'startLine', 'endLine'],
+                suggestion: "Use 'tail' alone or use 'startLine'/'endLine' without 'tail'.",
+            },
+            input: value,
+        });
+    }
+    if (hasEnd && !hasStart) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['endLine'],
+            message: "'endLine' requires 'startLine' to be set",
+            params: {
+                rule: 'endLine_requires_startLine',
+                suggestion: "Provide both 'startLine' and 'endLine' together.",
+            },
+            input: value,
+        });
+    }
+    const effectiveStart = value.startLine ?? 1;
+    if (value.endLine !== undefined && value.endLine < effectiveStart) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['endLine'],
+            message: "'endLine' must be >= 'startLine'",
+            params: {
+                rule: 'endLine_gte_startLine',
+                conflictsWith: ['startLine'],
+                suggestion: 'Set endLine to a value greater than or equal to startLine.',
+            },
+            input: value,
+        });
+    }
+}
+export function defaultFalseBoolean(description) {
+    return z.boolean().default(false).describe(description);
+}
+export const includeHiddenField = () => defaultFalseBoolean('Include hidden items (starting with .)');
+export const includeIgnoredField = () => defaultFalseBoolean('Include ignored items (node_modules, .git, etc).');
+export const maxDepthField = () => z
+    .uint32()
+    .min(0)
+    .max(MAX_SEARCH_DEPTH)
+    .optional()
+    .describe('Max directory depth to scan; 0 = base directory only, omit for unlimited');
+const DEFAULT_MAX_BATCH = 1000;
+export function singleOrBatchPathsInput(opts) {
+    const maxBatch = opts.maxBatch ?? DEFAULT_MAX_BATCH;
+    const shape = {
+        ...opts.extra,
+        path: RequiredPath.optional().describe('Single file path; mutually exclusive with paths'),
+        paths: z
+            .array(RequiredPath)
+            .min(1)
+            .max(maxBatch)
+            .optional()
+            .describe(`Array of file paths for batch mode (max ${String(maxBatch)}); mutually exclusive with path`),
+    };
+    const base = z.strictObject(shape).superRefine((value, ctx) => {
+        const hasPath = value['path'] !== undefined;
+        const hasPaths = value['paths'] !== undefined;
+        if (!hasPath && !hasPaths) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['path'],
+                message: "Either 'path' or 'paths' must be provided",
+                input: value,
+            });
+            return;
+        }
+        if (hasPath && hasPaths) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['paths'],
+                message: "Cannot use both 'path' and 'paths'",
+                input: value,
+            });
+        }
+    });
+    // Mirror the superRefine above on the wire: exactly one input mode. `{}` and
+    // `path`+`paths` both fail this oneOf, matching the runtime rule.
+    return base.meta({
+        oneOf: [{ required: ['path'] }, { required: ['paths'] }],
+    });
+}
+/**
+ * Extract the filesystem paths from a {@link singleOrBatchPathsInput} shape
+ * (`{ path?, paths?, files?[{path}] }`) for the executor's access-grant
+ * pre-check. Exactly one of the three is set (enforced by the schema's
+ * superRefine), so they are checked in priority order.
+ */
+export function singleOrBatchAccessPaths(args) {
+    if (args.path)
+        return [args.path];
+    if (args.paths)
+        return [...args.paths];
+    if (args.files)
+        return args.files.map((f) => f.path);
+    return [];
+}
+// `args` is the exact argument object the one producer (read's
+// buildReadContinuation) emits, not a free-form record: a bare
+// `z.record(z.string(), z.unknown())` renders as `additionalProperties: {}`,
+// which carries no validation keyword and constrains nothing — the Inspector's
+// portability check flags it, and a client cannot tell what to pass. Widen this
+// (to a union) only when a second tool starts emitting continuations.
+export const ContinuationSchema = z.strictObject({
+    tool: z.string().describe('Tool name to call for the next chunk'),
+    args: z
+        .strictObject({ path: z.string(), startLine: PositiveInt, endLine: PositiveInt })
+        .describe('Ready-to-use arguments for the next call; pass verbatim'),
+    hint: z.string().describe('One-sentence description of the data still remaining to be read'),
+});
+// ponytail: charset regex, not z.base64url() — the SDK's AJV warns on the
+// unknown `base64url` format; the server's own decode (cursor.ts) is the real
+// validation, so loosening the client-facing schema to the alphabet is safe.
+const base64urlCursor = z.string().regex(/^[A-Za-z0-9_-]+$/);
+// Ships once per paginated tool — wording is budgeted (TOOL-SURFACE-002).
+export const CursorSchema = base64urlCursor
+    .optional()
+    .describe('Opaque pagination cursor; pass unchanged for the next page. Pages slice one snapshot ' +
+    'taken on the first call; it expires after ~60s — re-request without a cursor if rejected.');
+export const NextCursorSchema = base64urlCursor
+    .optional()
+    .describe('Cursor for the next page; omitted when this is the final page.');
+//# sourceMappingURL=schema.js.map

package/dist/core/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,gFAAgF;AAChF,0EAA0E;AAC1E,8EAA8E;AAC9E,gFAAgF;AAChF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC;IAC/C,WAAW,EAAE,+DAA+D;IAC5E,yEAAyE;IACzE,qEAAqE;IACrE,uCAAuC;IACvC,OAAO,EAAE,SAAS;CACnB,CAAC,CAAC;AAEH,kFAAkF;AAClF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC;KACvB,MAAM,EAAE;KACR,KAAK,CAAC,gBAAgB,CAAC;KACvB,IAAI,CAAC,EAAE,WAAW,EAAE,uDAAuD,EAAE,CAAC,CAAC;AAElF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC;KACvB,GAAG,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;KACnC,WAAW,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;AAE3C,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC;KACzB,GAAG,CAAC,EAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;KACnC,QAAQ,CAAC,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;AAExC,MAAM,UAAU,GAAG,WAAW,CAAC;AAE/B,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAE3C,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAE3C,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAE7C,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAW,EAAW,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC;AAEzE,MAAM,QAAQ,GAAG,CAAC;KACf,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;KACpC,GAAG,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,sBAAsB,eAAe,SAAS,EAAE,CAAC;KACjF,WAAW,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACxB,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,yCAAyC;YAClD,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,gCAAgC;YACzC,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,oDAAoD;YAC7D,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,wEAAwE;YACjF,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;AACH,CAAC,CAAC;KACD,QAAQ,CAAC,0DAA0D,CAAC,CAAC;AAExE,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;AAChD,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC;AAErC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;KACvC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;KACxC,WAAW,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACxB,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,4CAA4C;YACrD,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,mCAAmC;YAC5C,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,qDAAqD;YAC9D,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,2EAA2E;YACpF,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QACH,OAAO,CAAC,CAAC,KAAK,CAAC;IACjB,CAAC;AACH,CAAC,CAAC;KACD,QAAQ,CAAC,8EAA8E,CAAC;KACxF,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;AAEhE,wEAAwE;AACxE,4EAA4E;AAC5E,iBAAiB;AACjB,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,YAAY,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,SAAS;IACf,aAAa,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;IACjG,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,WAAW;IACrB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;CAClE,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,YAAY,CAAC;IACnD,KAAK,EAAE,SAAS;IAChB,SAAS,EAAE,SAAS;IACpB,MAAM,EAAE,SAAS;CAClB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC9C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,kBAAkB;CAC1B,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAwB,EAAE,IAAqB;IAC/E,OAAO,CAAC,CAAC,YAAY,CAAC;QACpB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,IAAI,EAAE,CAAC;QACpE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,IAAI,EAAE,CAAC;QACpF,KAAK,EAAE,kBAAkB;KAC1B,CAAC,CAAC;AACL,CAAC;AAcD,MAAM,UAAU,qBAAqB,CAAC,KAA4B;IAChE,OAAO;QACL,IAAI,EAAE,CAAC;aACJ,KAAK,EAAE;aACP,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;aAC7B,GAAG,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;aACxC,QAAQ,EAAE;aACV,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,EAAE,CAAC;aACJ,KAAK,EAAE;aACP,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;aAC7B,GAAG,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;aACxC,QAAQ,EAAE;aACV,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QACvB,SAAS,EAAE,CAAC;aACT,KAAK,EAAE;aACP,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;aAC7B,GAAG,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;aACxC,QAAQ,EAAE;aACV,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;QAC5B,OAAO,EAAE,CAAC;aACP,KAAK,EAAE;aACP,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;aAC7B,GAAG,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;aACxC,QAAQ,EAAE;aACV,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAKC,EACD,GAAoB;IAEpB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;IACzC,MAAM,QAAQ,GAAG,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC;IAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC;IAE3C,IAAI,OAAO,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,EAAE,CAAC;QACpC,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,8CAA8C;YACvD,MAAM,EAAE;gBACN,IAAI,EAAE,oBAAoB;gBAC1B,aAAa,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC;gBACvC,UAAU,EAAE,4DAA4D;aACzE;YACD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,OAAO,IAAI,QAAQ,IAAI,MAAM,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,MAAM,CAAC;YACd,OAAO,EAAE,qDAAqD;YAC9D,MAAM,EAAE;gBACN,IAAI,EAAE,gBAAgB;gBACtB,aAAa,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC;gBAC/C,UAAU,EAAE,+DAA+D;aAC5E;YACD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,IAAI,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACxB,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,OAAO,EAAE,0CAA0C;YACnD,MAAM,EAAE;gBACN,IAAI,EAAE,4BAA4B;gBAClC,UAAU,EAAE,kDAAkD;aAC/D;YACD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,MAAM,cAAc,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,GAAG,cAAc,EAAE,CAAC;QAClE,GAAG,CAAC,QAAQ,CAAC;YACX,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,SAAS,CAAC;YACjB,OAAO,EAAE,kCAAkC;YAC3C,MAAM,EAAE;gBACN,IAAI,EAAE,uBAAuB;gBAC7B,aAAa,EAAE,CAAC,WAAW,CAAC;gBAC5B,UAAU,EAAE,4DAA4D;aACzE;YACD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAA+B,EAAE,CACjE,mBAAmB,CAAC,wCAAwC,CAAC,CAAC;AAChE,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAA+B,EAAE,CAClE,mBAAmB,CAAC,kDAAkD,CAAC,CAAC;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAG,GAA+B,EAAE,CAC5D,CAAC;KACE,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,gBAAgB,CAAC;KACrB,QAAQ,EAAE;KACV,QAAQ,CAAC,0EAA0E,CAAC,CAAC;AAE1F,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAO/B,MAAM,UAAU,uBAAuB,CAA+B,IAGrE;IACC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IAEpD,MAAM,KAAK,GAAkB;QAC3B,GAAG,IAAI,CAAC,KAAK;QACb,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;QACzF,KAAK,EAAE,CAAC;aACL,KAAK,CAAC,YAAY,CAAC;aACnB,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,QAAQ,CAAC;aACb,QAAQ,EAAE;aACV,QAAQ,CACP,2CAA2C,MAAM,CAAC,QAAQ,CAAC,iCAAiC,CAC7F;KACJ,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QAC5D,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,SAAS,CAAC;QAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC;QAE9C,IAAI,CAAC,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC1B,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,MAAM,CAAC;gBACd,OAAO,EAAE,2CAA2C;gBACpD,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,OAAO,IAAI,QAAQ,EAAE,CAAC;YACxB,GAAG,CAAC,QAAQ,CAAC;gBACX,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,OAAO,CAAC;gBACf,OAAO,EAAE,oCAAoC;gBAC7C,KAAK,EAAE,KAAK;aACb,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,kEAAkE;IAClE,OAAO,IAAI,CAAC,IAAI,CAAC;QACf,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC;KACzD,CAA4C,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAIxC;IACC,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACrD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,+DAA+D;AAC/D,+DAA+D;AAC/D,6EAA6E;AAC7E,+EAA+E;AAC/E,gFAAgF;AAChF,sEAAsE;AACtE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;IACjE,IAAI,EAAE,CAAC;SACJ,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;SAChF,QAAQ,CAAC,yDAAyD,CAAC;IACtE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iEAAiE,CAAC;CAC7F,CAAC,CAAC;AAEH,0EAA0E;AAC1E,8EAA8E;AAC9E,6EAA6E;AAC7E,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;AAE7D,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe;KACxC,QAAQ,EAAE;KACV,QAAQ,CACP,uFAAuF;IACrF,2FAA2F,CAC9F,CAAC;AAEJ,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe;KAC5C,QAAQ,EAAE;KACV,QAAQ,CAAC,gEAAgE,CAAC,CAAC","sourcesContent":["import * as z from 'zod/v4';\n\nimport { isSafeGlobSyntax } from './glob.js';\nimport { MIME_KINDS } from './mime.js';\nimport { ENTRY_TYPES } from './primitives.js';\nimport { MAX_SEARCH_DEPTH } from './util.js';\n\n// Runtime: full ISO-8601 UTC; emits the standard `date-time` format on the wire\n// (no AJV warning — it is a known format, unlike sha256_hex / base64url).\n// No `id` on this or any other shared schema below: an `id` hoists the schema\n// into `$defs` and leaves a `$ref` at every use site, which is exactly the wire\n// weight `toDraft202012` (tools/define.ts) publishes without.\nexport const IsoDateTime = z.iso.datetime().meta({\n  description: 'ISO 8601 UTC date-time string (e.g. 2024-01-15T12:00:00.000Z)',\n  // `format: \"date-time\"` already pins the value; zod's ~330-char calendar\n  // regex is pure wire weight. Runtime validation still runs it — this\n  // suppresses the emitted keyword only.\n  pattern: undefined,\n});\n\n// pattern (not z.hash('sha256')) so no `format: \"sha256_hex\"` keyword is emitted;\n// the SDK's AJV validator warns on that unknown format at every server start.\nexport const Sha256Hex = z\n  .string()\n  .regex(/^[0-9a-f]{64}$/)\n  .meta({ description: 'SHA-256 digest as a 64-character lowercase hex string' });\n\nexport const NonNegInt = z\n  .int({ message: 'Must be integer' })\n  .nonnegative({ message: 'Must be ≥ 0' });\n\nexport const PositiveInt = z\n  .int({ message: 'Must be integer' })\n  .positive({ message: 'Must be > 0' });\n\nconst FILE_TYPES = ENTRY_TYPES;\nexport type FileType = (typeof FILE_TYPES)[number];\nexport const FileType = z.enum(FILE_TYPES);\n\nconst FILE_KINDS = MIME_KINDS;\nexport type FileKind = (typeof FILE_KINDS)[number];\nexport const FileKind = z.enum(FILE_KINDS);\n\nconst MAX_PATH_LENGTH = 4096;\n\nexport const SHELL_METACHAR_RE = /[\\n\\r;|`]/;\n\nexport const isBlank = (val: string): boolean => val.trim().length === 0;\n\nconst PathBase = z\n  .string()\n  .min(1, { message: 'Path required' })\n  .max(MAX_PATH_LENGTH, { message: `Path too long (max ${MAX_PATH_LENGTH} chars)` })\n  .superRefine((val, ctx) => {\n    if (val.length === 0) {\n      return;\n    }\n    if (val.trim().length === 0) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Path cannot be empty or whitespace-only',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n    if (val.includes('\\0')) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Path cannot contain null bytes',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n    if (val.includes('..')) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Directory traversal sequences (\"..\") are forbidden',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n    if (SHELL_METACHAR_RE.test(val)) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Path contains prohibited characters (newlines or shell metacharacters)',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n  })\n  .describe('File or directory path inside an allowed workspace root.');\n\nexport const OptionalPath = PathBase.optional();\nexport const RequiredPath = PathBase;\n\nexport const SafeGlobPattern = z\n  .string()\n  .min(1, { message: 'Pattern required' })\n  .max(1000, { message: 'Max 1000 chars' })\n  .superRefine((val, ctx) => {\n    if (val.length === 0) {\n      return;\n    }\n    if (val.trim().length === 0) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Pattern cannot be empty or whitespace-only',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n    if (val.includes('\\0')) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Pattern cannot contain null bytes',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n    if (!isSafeGlobSyntax(val)) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Invalid glob or unsafe path (absolute/.. forbidden)',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n    if (SHELL_METACHAR_RE.test(val)) {\n      ctx.addIssue({\n        code: 'custom',\n        message: 'Pattern contains prohibited characters (newlines or shell metacharacters)',\n        fatal: true,\n      });\n      return z.NEVER;\n    }\n  })\n  .describe('Relative glob pattern under the search root (e.g. \"**/*.ts\", \"src/**/*.js\").')\n  .meta({ examples: ['**/*.ts', 'src/**/*.js', '*.{ts,tsx}'] });\n\n// Only the fields whose key does not already say what they hold carry a\n// description. A `.describe('Name')` on `name` costs every client tokens to\n// learn nothing.\nexport const FileInfoSchema = z.strictObject({\n  name: z.string(),\n  path: z.string(),\n  type: FileType,\n  size: NonNegInt,\n  tokenEstimate: NonNegInt.optional().describe('Rough token estimate; use to pre-screen read cost'),\n  created: IsoDateTime,\n  modified: IsoDateTime,\n  accessed: IsoDateTime,\n  permissions: z.string(),\n  isHidden: z.boolean(),\n  mimeType: z.string().optional(),\n  symlinkTarget: z.string().optional().describe('Target (symlink)'),\n});\n\nexport const OperationSummarySchema = z.strictObject({\n  total: NonNegInt,\n  succeeded: NonNegInt,\n  failed: NonNegInt,\n});\n\nexport const PerFileErrorSchema = z.strictObject({\n  code: z.string(),\n  message: z.string(),\n  path: z.string().optional(),\n  suggestion: z.string().optional(),\n});\n\n/** One entry of a tool's `failures[]`: the path that failed and why. */\nexport const PathFailureSchema = z.strictObject({\n  path: z.string(),\n  error: PerFileErrorSchema,\n});\n\n/**\n * One entry of a source→destination tool's `failures[]`. The verb and noun stay\n * per-op so the `.describe()` text reads correctly for each caller.\n */\nexport function pairFailureSchema(verb: 'copied' | 'moved', noun: 'copy' | 'move') {\n  return z.strictObject({\n    source: z.string().describe(`Source path that could not be ${verb}`),\n    destination: z.string().describe(`Intended destination path for the failed ${noun}`),\n    error: PerFileErrorSchema,\n  });\n}\n\n/** Wire shape of a `pairFailureSchema` entry — the runtime twin of the schema. */\nexport type PairFailureItem = z.infer<ReturnType<typeof pairFailureSchema>>;\n\n// TODO(future): Wrap createReadRangeFields output in a typed Zod object with built-in\n// cross-validation. Safe for now — the only caller (read.ts) calls validateReadRange in its own superRefine.\ninterface ReadRangeDescriptions {\n  head: string;\n  tail: string;\n  startLine: string;\n  endLine: string;\n}\n\nexport function createReadRangeFields(descs: ReadRangeDescriptions) {\n  return {\n    head: z\n      .int32()\n      .min(1, { message: 'Min: 1' })\n      .max(100000, { message: 'Max: 100,000' })\n      .optional()\n      .describe(descs.head),\n    tail: z\n      .int32()\n      .min(1, { message: 'Min: 1' })\n      .max(100000, { message: 'Max: 100,000' })\n      .optional()\n      .describe(descs.tail),\n    startLine: z\n      .int32()\n      .min(1, { message: 'Min: 1' })\n      .max(100000, { message: 'Max: 100,000' })\n      .optional()\n      .describe(descs.startLine),\n    endLine: z\n      .int32()\n      .min(1, { message: 'Min: 1' })\n      .max(100000, { message: 'Max: 100,000' })\n      .optional()\n      .describe(descs.endLine),\n  };\n}\n\nexport function validateReadRange(\n  value: {\n    head?: number | undefined;\n    tail?: number | undefined;\n    startLine?: number | undefined;\n    endLine?: number | undefined;\n  },\n  ctx: z.RefinementCtx,\n): void {\n  const hasHead = value.head !== undefined;\n  const hasTail = value.tail !== undefined;\n  const hasStart = value.startLine !== undefined;\n  const hasEnd = value.endLine !== undefined;\n\n  if (hasHead && (hasStart || hasEnd)) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['head'],\n      message: \"Cannot use 'head' with 'startLine'/'endLine'\",\n      params: {\n        rule: 'head_no_line_range',\n        conflictsWith: ['startLine', 'endLine'],\n        suggestion: \"Use either 'head' alone or 'startLine'/'endLine' together.\",\n      },\n      input: value,\n    });\n  }\n  if (hasTail && (hasHead || hasStart || hasEnd)) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['tail'],\n      message: \"Cannot use 'tail' with 'head'/'startLine'/'endLine'\",\n      params: {\n        rule: 'tail_exclusive',\n        conflictsWith: ['head', 'startLine', 'endLine'],\n        suggestion: \"Use 'tail' alone or use 'startLine'/'endLine' without 'tail'.\",\n      },\n      input: value,\n    });\n  }\n  if (hasEnd && !hasStart) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['endLine'],\n      message: \"'endLine' requires 'startLine' to be set\",\n      params: {\n        rule: 'endLine_requires_startLine',\n        suggestion: \"Provide both 'startLine' and 'endLine' together.\",\n      },\n      input: value,\n    });\n  }\n  const effectiveStart = value.startLine ?? 1;\n  if (value.endLine !== undefined && value.endLine < effectiveStart) {\n    ctx.addIssue({\n      code: 'custom',\n      path: ['endLine'],\n      message: \"'endLine' must be >= 'startLine'\",\n      params: {\n        rule: 'endLine_gte_startLine',\n        conflictsWith: ['startLine'],\n        suggestion: 'Set endLine to a value greater than or equal to startLine.',\n      },\n      input: value,\n    });\n  }\n}\n\nexport function defaultFalseBoolean(description: string): z.ZodDefault<z.ZodBoolean> {\n  return z.boolean().default(false).describe(description);\n}\n\nexport const includeHiddenField = (): z.ZodDefault<z.ZodBoolean> =>\n  defaultFalseBoolean('Include hidden items (starting with .)');\nexport const includeIgnoredField = (): z.ZodDefault<z.ZodBoolean> =>\n  defaultFalseBoolean('Include ignored items (node_modules, .git, etc).');\nexport const maxDepthField = (): z.ZodOptional<z.ZodNumber> =>\n  z\n    .uint32()\n    .min(0)\n    .max(MAX_SEARCH_DEPTH)\n    .optional()\n    .describe('Max directory depth to scan; 0 = base directory only, omit for unlimited');\n\nconst DEFAULT_MAX_BATCH = 1000;\n\nexport type SingleOrBatchShape<TExtra extends z.ZodRawShape> = TExtra & {\n  path: z.ZodOptional<typeof RequiredPath>;\n  paths: z.ZodOptional<z.ZodArray<typeof RequiredPath>>;\n};\n\nexport function singleOrBatchPathsInput<TExtra extends z.ZodRawShape>(opts: {\n  extra: TExtra;\n  maxBatch?: number;\n}): z.ZodObject<SingleOrBatchShape<TExtra>> {\n  const maxBatch = opts.maxBatch ?? DEFAULT_MAX_BATCH;\n\n  const shape: z.ZodRawShape = {\n    ...opts.extra,\n    path: RequiredPath.optional().describe('Single file path; mutually exclusive with paths'),\n    paths: z\n      .array(RequiredPath)\n      .min(1)\n      .max(maxBatch)\n      .optional()\n      .describe(\n        `Array of file paths for batch mode (max ${String(maxBatch)}); mutually exclusive with path`,\n      ),\n  };\n\n  const base = z.strictObject(shape).superRefine((value, ctx) => {\n    const hasPath = value['path'] !== undefined;\n    const hasPaths = value['paths'] !== undefined;\n\n    if (!hasPath && !hasPaths) {\n      ctx.addIssue({\n        code: 'custom',\n        path: ['path'],\n        message: \"Either 'path' or 'paths' must be provided\",\n        input: value,\n      });\n      return;\n    }\n    if (hasPath && hasPaths) {\n      ctx.addIssue({\n        code: 'custom',\n        path: ['paths'],\n        message: \"Cannot use both 'path' and 'paths'\",\n        input: value,\n      });\n    }\n  });\n\n  // Mirror the superRefine above on the wire: exactly one input mode. `{}` and\n  // `path`+`paths` both fail this oneOf, matching the runtime rule.\n  return base.meta({\n    oneOf: [{ required: ['path'] }, { required: ['paths'] }],\n  }) as z.ZodObject<SingleOrBatchShape<TExtra>>;\n}\n\n/**\n * Extract the filesystem paths from a {@link singleOrBatchPathsInput} shape\n * (`{ path?, paths?, files?[{path}] }`) for the executor's access-grant\n * pre-check. Exactly one of the three is set (enforced by the schema's\n * superRefine), so they are checked in priority order.\n */\nexport function singleOrBatchAccessPaths(args: {\n  path?: string | undefined;\n  paths?: string[] | undefined;\n  files?: readonly { path: string }[] | undefined;\n}): string[] {\n  if (args.path) return [args.path];\n  if (args.paths) return [...args.paths];\n  if (args.files) return args.files.map((f) => f.path);\n  return [];\n}\n\n// `args` is the exact argument object the one producer (read's\n// buildReadContinuation) emits, not a free-form record: a bare\n// `z.record(z.string(), z.unknown())` renders as `additionalProperties: {}`,\n// which carries no validation keyword and constrains nothing — the Inspector's\n// portability check flags it, and a client cannot tell what to pass. Widen this\n// (to a union) only when a second tool starts emitting continuations.\nexport const ContinuationSchema = z.strictObject({\n  tool: z.string().describe('Tool name to call for the next chunk'),\n  args: z\n    .strictObject({ path: z.string(), startLine: PositiveInt, endLine: PositiveInt })\n    .describe('Ready-to-use arguments for the next call; pass verbatim'),\n  hint: z.string().describe('One-sentence description of the data still remaining to be read'),\n});\n\n// ponytail: charset regex, not z.base64url() — the SDK's AJV warns on the\n// unknown `base64url` format; the server's own decode (cursor.ts) is the real\n// validation, so loosening the client-facing schema to the alphabet is safe.\nconst base64urlCursor = z.string().regex(/^[A-Za-z0-9_-]+$/);\n\n// Ships once per paginated tool — wording is budgeted (TOOL-SURFACE-002).\nexport const CursorSchema = base64urlCursor\n  .optional()\n  .describe(\n    'Opaque pagination cursor; pass unchanged for the next page. Pages slice one snapshot ' +\n      'taken on the first call; it expires after ~60s — re-request without a cursor if rejected.',\n  );\n\nexport const NextCursorSchema = base64urlCursor\n  .optional()\n  .describe('Cursor for the next page; omitted when this is the final page.');\n"]}

package/dist/core/search.d.ts

@@ -0,0 +1,100 @@
+import { RE2 } from '@adguard/re2-wasm';
+import type { StoppedReason } from './concurrency.js';
+import type { PathGuard } from './path.js';
+interface SearchResult {
+    file: string;
+    line: number;
+    content: string;
+    matchCount?: number;
+}
+export type Regex = RE2;
+export interface RegexCompileOptions {
+    caseSensitive?: boolean;
+}
+/**
+ * Compile a pattern on RE2 rather than on V8's irregexp.
+ *
+ * Patterns arrive from the MCP client, so a backtracking engine would let one
+ * request pin the event loop with no way out: an abort signal cannot preempt a
+ * synchronous `exec`, and on stdio that wedges the whole server. RE2 matches in
+ * time linear in the input and cannot backtrack at all, so the hazard is gone
+ * rather than bounded.
+ *
+ * RE2 rejects the constructs the tool schema documents as unsupported —
+ * lookahead, lookbehind, backreferences — with its own {@link SyntaxError},
+ * which the tool layer turns into a normal tool error. It always matches in
+ * Unicode mode and requires the `u` flag to say so.
+ *
+ * Every compiled pattern owns memory in re2-wasm's fixed 16 MB heap, which
+ * `ALLOW_MEMORY_GROWTH` is off for. re2-wasm never frees it and a
+ * FinalizationRegistry does not keep up (V8 sees no pressure from the wasm
+ * heap), so exhaustion is an emscripten `abort()` that kills regex search for
+ * the rest of the process. Every caller MUST pass the result to
+ * {@link freeRegex} when it is done with it.
+ */
+export declare function compileRegex(pattern: string, options?: RegexCompileOptions): Regex;
+/**
+ * Release a compiled pattern's wasm memory. re2-wasm exposes no disposal of its
+ * own, so this reaches the embind handle it holds privately; a version that
+ * renames the field degrades to the pre-existing leak rather than throwing.
+ * Idempotent — a second call on an already-freed handle is swallowed. Using a
+ * {@link Regex} after freeing it is undefined behaviour in the wasm heap, so
+ * free only in a `finally` that owns the compile.
+ */
+export declare function freeRegex(regex: Regex | undefined): void;
+export interface SearchContentOptions {
+    caseSensitive?: boolean;
+    isRegex?: boolean;
+    maxResults?: number;
+    filePattern?: string;
+    excludePatterns?: string[];
+    respectGitignore?: boolean;
+    includeHidden?: boolean;
+    maxDepth?: number;
+    maxFileSize?: number;
+    signal?: AbortSignal;
+}
+export interface SearchContentOutcome {
+    basePath: string;
+    matches: SearchResult[];
+    summary: {
+        /**
+         * Matching *lines*, one per entry in `matches` — not pattern occurrences.
+         * A line with three occurrences counts once here and reports 3 in its own
+         * `SearchResult.matchCount`.
+         */
+        matchingLines: number;
+        filesScanned: number;
+        filesMatched: number;
+        truncated: boolean;
+        /** Files the guard rejected or that could not be stat'd. */
+        skippedInaccessible: number;
+        /** Files skipped unread because they exceed maxFileSize. */
+        skippedTooLarge: number;
+        stoppedReason?: StoppedReason;
+    };
+}
+/** Owns the compiled pattern's lifetime; the scan itself is `scanContent`. */
+export declare function searchContent(directory: string, pattern: string, options: SearchContentOptions, pathGuard: PathGuard): Promise<SearchContentOutcome>;
+export declare function searchFiles(directory: string, pattern: string, excludePatterns: string[], options: {
+    maxResults?: number;
+    includeHidden?: boolean;
+    sortBy?: 'name' | 'path';
+    respectGitignore?: boolean;
+    maxDepth?: number;
+    signal?: AbortSignal;
+}, pathGuard: PathGuard): Promise<{
+    basePath: string;
+    results: {
+        path: string;
+    }[];
+    summary: {
+        matched: number;
+        filesScanned: number;
+        truncated: boolean;
+        skippedInaccessible: number;
+        stoppedReason?: StoppedReason;
+    };
+}>;
+export {};
+//# sourceMappingURL=search.d.ts.map

package/dist/core/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAGxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAI3C,UAAU,YAAY;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC;AACxB,MAAM,WAAW,mBAAmB;IAClC,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAKD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,KAAK,CAWtF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CAOxD;AAkBD,MAAM,WAAW,oBAAoB;IACnC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,EAAE;QACP;;;;WAIG;QACH,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,4DAA4D;QAC5D,mBAAmB,EAAE,MAAM,CAAC;QAC5B,4DAA4D;QAC5D,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B,CAAC;CACH;AAED,8EAA8E;AAC9E,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AA6HD,wBAAsB,WAAW,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,EAAE,EACzB,OAAO,EAAE;IACP,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,EACD,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC;IACT,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5B,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,CAAC,EAAE,aAAa,CAAC;KAC/B,CAAC;CACH,CAAC,CAiDD"}