@xfey/tutti 0.1.113 → 0.1.114

package/dist/server-shell/cli/relay-registration.js

@@ -39,6 +39,7 @@ export async function registerHostWithRelay(options) {
             integration_source_ingestion_v1: true,
             integration_development_bot_v1: true,
             integration_clarification_v1: true,
+            feishu_supporting_reads_v1: true,
             integration_external_references_v1: true,
             integration_attachment_ingestion_v1: true,
             integration_managed_reference_ingestion_v1: true,

package/dist/server-shell/http/routes/agent-context-skills-routes.js

@@ -1,5 +1,5 @@
 import { redactText } from "@tutti/shared/utils";
-import { listUserSkills, readUserSkill, SkillServiceError, } from "../../../skills/index.js";
+import { listUserSkills, readUserSkill, SkillServiceError } from "../../../skills/index.js";
 import { authorizeAgentContextRequest } from "./agent-context-auth.js";
 import { AgentContextBadRequestError } from "./agent-context-errors.js";
 import { boundedLimit, pageByOffset, queryString, truncateText } from "./agent-context-query.js";
@@ -23,6 +23,7 @@ function handleSkillReadError(error, skillName) {
         case "validation_failed":
             return skillUnavailable({ skillName, reason: "invalid" });
         case "filesystem_error":
+        case "read_limit_exceeded":
             return skillUnavailable({ skillName, reason: "unavailable" });
         case "invalid_zip":
             return skillUnavailable({ skillName, reason: "invalid" });

package/dist/server-shell/http/routes/project-api/openapi-skills-routes.d.ts

@@ -17,6 +17,17 @@ export declare const HOST_PROJECT_SKILLS_OPENAPI_ROUTES: ({
                 }>>;
             }>;
         };
+        413: {
+            description: string;
+            schema: import("@sinclair/typebox").TObject<{
+                error: import("@sinclair/typebox").TObject<{
+                    code: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"bad_request">, import("@sinclair/typebox").TLiteral<"unauthorized">, import("@sinclair/typebox").TLiteral<"forbidden">, import("@sinclair/typebox").TLiteral<"not_found">, import("@sinclair/typebox").TLiteral<"conflict">, import("@sinclair/typebox").TLiteral<"validation_failed">, import("@sinclair/typebox").TLiteral<"provider_not_configured">, import("@sinclair/typebox").TLiteral<"provider_auth_invalid">, import("@sinclair/typebox").TLiteral<"provider_quota_or_billing_required">, import("@sinclair/typebox").TLiteral<"provider_rate_limited">, import("@sinclair/typebox").TLiteral<"provider_model_unavailable">, import("@sinclair/typebox").TLiteral<"provider_network_error">, import("@sinclair/typebox").TLiteral<"relay_session_invalid">, import("@sinclair/typebox").TLiteral<"project_membership_required">, import("@sinclair/typebox").TLiteral<"command_replay_mismatch">, import("@sinclair/typebox").TLiteral<"repo_snapshot_unavailable">, import("@sinclair/typebox").TLiteral<"host_unavailable">, import("@sinclair/typebox").TLiteral<"skill_read_limit_exceeded">, import("@sinclair/typebox").TLiteral<"internal_error">]>;
+                    message: import("@sinclair/typebox").TString;
+                    retryable: import("@sinclair/typebox").TBoolean;
+                    details: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+                }>;
+            }>;
+        };
     };
     parameters?: never;
     requestBody?: never;
@@ -41,6 +52,17 @@ export declare const HOST_PROJECT_SKILLS_OPENAPI_ROUTES: ({
                 }>;
             }>;
         };
+        413: {
+            description: string;
+            schema: import("@sinclair/typebox").TObject<{
+                error: import("@sinclair/typebox").TObject<{
+                    code: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"bad_request">, import("@sinclair/typebox").TLiteral<"unauthorized">, import("@sinclair/typebox").TLiteral<"forbidden">, import("@sinclair/typebox").TLiteral<"not_found">, import("@sinclair/typebox").TLiteral<"conflict">, import("@sinclair/typebox").TLiteral<"validation_failed">, import("@sinclair/typebox").TLiteral<"provider_not_configured">, import("@sinclair/typebox").TLiteral<"provider_auth_invalid">, import("@sinclair/typebox").TLiteral<"provider_quota_or_billing_required">, import("@sinclair/typebox").TLiteral<"provider_rate_limited">, import("@sinclair/typebox").TLiteral<"provider_model_unavailable">, import("@sinclair/typebox").TLiteral<"provider_network_error">, import("@sinclair/typebox").TLiteral<"relay_session_invalid">, import("@sinclair/typebox").TLiteral<"project_membership_required">, import("@sinclair/typebox").TLiteral<"command_replay_mismatch">, import("@sinclair/typebox").TLiteral<"repo_snapshot_unavailable">, import("@sinclair/typebox").TLiteral<"host_unavailable">, import("@sinclair/typebox").TLiteral<"skill_read_limit_exceeded">, import("@sinclair/typebox").TLiteral<"internal_error">]>;
+                    message: import("@sinclair/typebox").TString;
+                    retryable: import("@sinclair/typebox").TBoolean;
+                    details: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+                }>;
+            }>;
+        };
     };
     requestBody?: never;
 } | {
@@ -54,6 +76,7 @@ export declare const HOST_PROJECT_SKILLS_OPENAPI_ROUTES: ({
             description: string;
             schema: import("@sinclair/typebox").TSchema;
         };
+        413?: never;
     };
     parameters?: never;
 })[];

package/dist/server-shell/http/routes/project-api/openapi-skills-routes.js

@@ -1,4 +1,4 @@
-import { DeleteSkillBodySchema, DeleteSkillResponseSchema, GetSkillResponseSchema, GetSkillsResponseSchema, ImportSkillZipBodySchema, ImportSkillZipResponseSchema, } from "@tutti/shared/schemas/api";
+import { ApiErrorResponseSchema, DeleteSkillBodySchema, DeleteSkillResponseSchema, GetSkillResponseSchema, GetSkillsResponseSchema, ImportSkillZipBodySchema, ImportSkillZipResponseSchema, } from "@tutti/shared/schemas/api";
 import { HOST_PROJECT_API_BASE_PATH } from "./constants.js";
 import { SkillNamePathParameter } from "./openapi-path-parameters.js";
 export const HOST_PROJECT_SKILLS_OPENAPI_ROUTES = [
@@ -9,6 +9,10 @@ export const HOST_PROJECT_SKILLS_OPENAPI_ROUTES = [
         tags: ["skills"],
         responses: {
             200: { description: "User skills projection.", schema: GetSkillsResponseSchema },
+            413: {
+                description: "Feishu preview list budget exceeded; no partial list.",
+                schema: ApiErrorResponseSchema,
+            },
         },
     },
     {
@@ -19,6 +23,10 @@ export const HOST_PROJECT_SKILLS_OPENAPI_ROUTES = [
         parameters: [SkillNamePathParameter],
         responses: {
             200: { description: "User skill detail projection.", schema: GetSkillResponseSchema },
+            413: {
+                description: "Skill read budget exceeded; no truncated skill.",
+                schema: ApiErrorResponseSchema,
+            },
         },
     },
     {

package/dist/server-shell/http/routes/project-api/openapi.d.ts

@@ -885,6 +885,17 @@ export declare const HOST_PROJECT_OPENAPI_ROUTES: ({
                 }>>;
             }>;
         };
+        413: {
+            description: string;
+            schema: import("@sinclair/typebox").TObject<{
+                error: import("@sinclair/typebox").TObject<{
+                    code: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"bad_request">, import("@sinclair/typebox").TLiteral<"unauthorized">, import("@sinclair/typebox").TLiteral<"forbidden">, import("@sinclair/typebox").TLiteral<"not_found">, import("@sinclair/typebox").TLiteral<"conflict">, import("@sinclair/typebox").TLiteral<"validation_failed">, import("@sinclair/typebox").TLiteral<"provider_not_configured">, import("@sinclair/typebox").TLiteral<"provider_auth_invalid">, import("@sinclair/typebox").TLiteral<"provider_quota_or_billing_required">, import("@sinclair/typebox").TLiteral<"provider_rate_limited">, import("@sinclair/typebox").TLiteral<"provider_model_unavailable">, import("@sinclair/typebox").TLiteral<"provider_network_error">, import("@sinclair/typebox").TLiteral<"relay_session_invalid">, import("@sinclair/typebox").TLiteral<"project_membership_required">, import("@sinclair/typebox").TLiteral<"command_replay_mismatch">, import("@sinclair/typebox").TLiteral<"repo_snapshot_unavailable">, import("@sinclair/typebox").TLiteral<"host_unavailable">, import("@sinclair/typebox").TLiteral<"skill_read_limit_exceeded">, import("@sinclair/typebox").TLiteral<"internal_error">]>;
+                    message: import("@sinclair/typebox").TString;
+                    retryable: import("@sinclair/typebox").TBoolean;
+                    details: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+                }>;
+            }>;
+        };
     };
     parameters?: never;
     requestBody?: never;
@@ -909,6 +920,17 @@ export declare const HOST_PROJECT_OPENAPI_ROUTES: ({
                 }>;
             }>;
         };
+        413: {
+            description: string;
+            schema: import("@sinclair/typebox").TObject<{
+                error: import("@sinclair/typebox").TObject<{
+                    code: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"bad_request">, import("@sinclair/typebox").TLiteral<"unauthorized">, import("@sinclair/typebox").TLiteral<"forbidden">, import("@sinclair/typebox").TLiteral<"not_found">, import("@sinclair/typebox").TLiteral<"conflict">, import("@sinclair/typebox").TLiteral<"validation_failed">, import("@sinclair/typebox").TLiteral<"provider_not_configured">, import("@sinclair/typebox").TLiteral<"provider_auth_invalid">, import("@sinclair/typebox").TLiteral<"provider_quota_or_billing_required">, import("@sinclair/typebox").TLiteral<"provider_rate_limited">, import("@sinclair/typebox").TLiteral<"provider_model_unavailable">, import("@sinclair/typebox").TLiteral<"provider_network_error">, import("@sinclair/typebox").TLiteral<"relay_session_invalid">, import("@sinclair/typebox").TLiteral<"project_membership_required">, import("@sinclair/typebox").TLiteral<"command_replay_mismatch">, import("@sinclair/typebox").TLiteral<"repo_snapshot_unavailable">, import("@sinclair/typebox").TLiteral<"host_unavailable">, import("@sinclair/typebox").TLiteral<"skill_read_limit_exceeded">, import("@sinclair/typebox").TLiteral<"internal_error">]>;
+                    message: import("@sinclair/typebox").TString;
+                    retryable: import("@sinclair/typebox").TBoolean;
+                    details: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+                }>;
+            }>;
+        };
     };
     requestBody?: never;
 } | {

package/dist/server-shell/http/routes/project-api/project-timeline-projection.js

@@ -1,3 +1,5 @@
+import { clarificationAnswerRole } from "@tutti/shared/utils";
+import { readSubmittedClarificationMessages } from "../../../../collaboration-state/index.js";
 import { readProviderUsageBreakdownForAnchors, readProviderUsageModelSummariesForAnchors, readProviderUsageProjection, readProviderUsageSourceSummariesForAnchors, } from "../../../../provider-usage/index.js";
 import { runGitRaw } from "../../../../workspace-ops/git.js";
 const TIMELINE_LIMIT = 50;
@@ -178,34 +180,24 @@ function clarificationChatLink(messageId) {
         message_id: messageId,
     };
 }
-function readClarificationAnswerSnippets(db, submittedRefsJson) {
-    const submittedRefs = parseJsonStringArray(submittedRefsJson);
-    if (submittedRefs.length === 0) {
-        return { answer_count: 0, answers: [] };
-    }
-    const readMessage = db.prepare(`
-      SELECT
-        id AS message_id,
-        author_kind,
-        author_display_name,
-        body,
-        created_at
-      FROM messages
-      WHERE id = ?
-        AND message_kind = 'user_text'
-        AND author_kind = 'human'
-      LIMIT 1
-    `);
-    const answers = submittedRefs.flatMap((messageId) => {
-        const row = readMessage.get(messageId);
-        return row === undefined ? [] : [row];
+function readClarificationAnswerSnippets(db, roundId) {
+    const answers = readSubmittedClarificationMessages(db, roundId).filter((message) => clarificationAnswerRole(message) !== null);
+    const visibleAnswers = answers.slice(0, TRACE_SOURCE_SNIPPET_LIMIT).map((answer) => {
+        let author = authorLabel({
+            author_kind: answer.author.kind,
+            author_display_name: answer.author.display_name ?? null,
+        });
+        if (clarificationAnswerRole(answer) === "operator") {
+            const displayName = answer.author.display_name?.trim();
+            author = displayName ? `${displayName} (operator)` : "Development operator";
+        }
+        return {
+            message_id: answer.id,
+            author,
+            body: truncateSnippetBody(answer.body),
+            created_at: answer.created_at,
+        };
     });
-    const visibleAnswers = answers.slice(0, TRACE_SOURCE_SNIPPET_LIMIT).map((answer) => ({
-        message_id: answer.message_id,
-        author: authorLabel(answer),
-        body: truncateSnippetBody(answer.body),
-        created_at: answer.created_at,
-    }));
     return {
         answer_count: answers.length,
         answers: visibleAnswers,
@@ -213,7 +205,7 @@ function readClarificationAnswerSnippets(db, submittedRefsJson) {
 }
 function clarificationTraceFromRow(db, row) {
     const payload = parseJsonObject(row.request_payload_json);
-    const answers = readClarificationAnswerSnippets(db, row.submitted_message_refs_json);
+    const answers = readClarificationAnswerSnippets(db, row.round_id);
     const visibleAnswers = answers.answers;
     const title = stringValue(payload, "title");
     const summary = stringValue(payload, "summary");
@@ -247,7 +239,6 @@ function readLatestTaskCompileClarificationTrace(db, workflowRef) {
           clarification_rounds.status AS round_status,
           clarification_rounds.request_payload_json,
           clarification_rounds.card_message_id,
-          clarification_rounds.submitted_message_refs_json,
           clarification_rounds.submitted_at,
           clarification_rounds.updated_at
         FROM clarification_rounds
@@ -273,7 +264,6 @@ function readLatestClarificationTraceByThread(db, threadId) {
           clarification_rounds.status AS round_status,
           clarification_rounds.request_payload_json,
           clarification_rounds.card_message_id,
-          clarification_rounds.submitted_message_refs_json,
           clarification_rounds.submitted_at,
           clarification_rounds.updated_at
         FROM clarification_threads
@@ -302,7 +292,6 @@ function readLatestResolvedTaskClarificationTrace(db, taskId, throughCreatedAt)
           clarification_rounds.status AS round_status,
           clarification_rounds.request_payload_json,
           clarification_rounds.card_message_id,
-          clarification_rounds.submitted_message_refs_json,
           clarification_rounds.submitted_at,
           clarification_rounds.updated_at
         FROM clarification_rounds
@@ -533,7 +522,10 @@ function readPromotedCommitChanges(workspaceRoot, commitOid) {
     if (result.status !== 0) {
         return undefined;
     }
-    const fields = result.stdout.toString("utf8").split("\0").filter((field) => field !== "");
+    const fields = result.stdout
+        .toString("utf8")
+        .split("\0")
+        .filter((field) => field !== "");
     const changes = [];
     for (let index = 0; index < fields.length;) {
         const status = fields[index];
@@ -843,7 +835,9 @@ export function readProjectTimelineProjection(input) {
     ].sort(compareTimelineItemsByTimeDesc);
     return {
         generated_at: now().toISOString(),
-        usage_overview: input.db === undefined ? emptyUsageOverview() : readProviderUsageProjection(input.db, { now }),
+        usage_overview: input.db === undefined
+            ? emptyUsageOverview()
+            : readProviderUsageProjection(input.db, { now }),
         items: items.slice(0, TIMELINE_LIMIT),
     };
 }

package/dist/server-shell/http/routes/project-api/skills-helpers.js

@@ -1,5 +1,12 @@
 import { getProjectUserSkillsRoot, SkillServiceError } from "../../../../skills/index.js";
 import { HostProjectBadRequestError, HostProjectNotFoundError, HostProjectStoreUnavailableError, HostProjectValidationError, } from "./errors.js";
+class HostSkillReadLimitError extends Error {
+    statusCode = 413;
+    code = "skill_read_limit_exceeded";
+    constructor() {
+        super("Skill read exceeds the supported limit");
+    }
+}
 export function skillsChangedInvalidates() {
     return [{ kind: "skills" }, { kind: "read_state" }, { kind: "bootstrap" }];
 }
@@ -24,6 +31,8 @@ function toHostProjectSkillError(error) {
             return new HostProjectValidationError(error.message);
         case "filesystem_error":
             return new HostProjectStoreUnavailableError();
+        case "read_limit_exceeded":
+            return new HostSkillReadLimitError();
     }
 }
 export async function withAsyncSkillServiceErrorMapping(fn) {

package/dist/server-shell/http/routes/project-api/skills-routes.js

@@ -14,9 +14,11 @@ export function registerSkillRoutes(app, { options, workspaceEvents, }) {
             },
         },
     }, (request) => {
-        requireHostProjectSession(request, options);
+        const session = requireHostProjectSession(request, options);
         return withSkillServiceErrorMapping(() => ({
-            items: listUserSkills(requireProjectUserSkillsRoot(options)),
+            items: listUserSkills(requireProjectUserSkillsRoot(options), {
+                mode: session.client_session.transport === "feishu_platform_session" ? "preview" : "full",
+            }),
         }));
     });
     app.get(`${HOST_PROJECT_API_BASE_PATH}/skills/:skillName`, {
@@ -26,9 +28,11 @@ export function registerSkillRoutes(app, { options, workspaceEvents, }) {
             },
         },
     }, (request) => {
-        requireHostProjectSession(request, options);
+        const session = requireHostProjectSession(request, options);
         return withSkillServiceErrorMapping(() => ({
-            skill: readUserSkill(requireProjectUserSkillsRoot(options), request.params.skillName),
+            skill: readUserSkill(requireProjectUserSkillsRoot(options), request.params.skillName, {
+                mode: session.client_session.transport === "feishu_platform_session" ? "preview" : "full",
+            }),
         }));
     });
     app.post(`${HOST_PROJECT_API_BASE_PATH}/skills/import`, {

package/dist/server-shell/http/validation.js

@@ -17,6 +17,7 @@ const API_ERROR_CODES = new Set([
     "command_replay_mismatch",
     "repo_snapshot_unavailable",
     "host_unavailable",
+    "skill_read_limit_exceeded",
     "internal_error",
 ]);
 function isApiErrorCode(value) {

package/dist/skills/constants.d.ts

@@ -5,4 +5,9 @@ export declare const MAX_SKILL_TOTAL_UNCOMPRESSED_BYTES: number;
 export declare const MAX_SKILL_FILE_BYTES: number;
 export declare const MAX_SKILL_FILE_COUNT = 1000;
 export declare const MAX_SKILL_DIRECTORY_DEPTH = 24;
+export declare const MAX_SKILL_PREVIEW_BYTES: number;
+export declare const MAX_SKILL_PREVIEW_METADATA_BYTES: number;
+export declare const MAX_SKILL_PREVIEW_SCAN_ENTRIES = 512;
+export declare const MAX_SKILL_PREVIEW_ITEMS = 256;
+export declare const MAX_SKILL_PREVIEW_LIST_BYTES: number;
 //# sourceMappingURL=constants.d.ts.map

package/dist/skills/constants.js

@@ -6,4 +6,10 @@ export const MAX_SKILL_TOTAL_UNCOMPRESSED_BYTES = 200 * 1024 * 1024;
 export const MAX_SKILL_FILE_BYTES = 50 * 1024 * 1024;
 export const MAX_SKILL_FILE_COUNT = 1_000;
 export const MAX_SKILL_DIRECTORY_DEPTH = 24;
+// Browser preview budgets are independent of the full skill used by the runtime.
+export const MAX_SKILL_PREVIEW_BYTES = 200 * 1024;
+export const MAX_SKILL_PREVIEW_METADATA_BYTES = 32 * 1024;
+export const MAX_SKILL_PREVIEW_SCAN_ENTRIES = 512;
+export const MAX_SKILL_PREVIEW_ITEMS = 256;
+export const MAX_SKILL_PREVIEW_LIST_BYTES = 512 * 1024;
 //# sourceMappingURL=constants.js.map

package/dist/skills/errors.d.ts

@@ -1,4 +1,4 @@
-export type SkillServiceErrorCode = "invalid_skill_name" | "skill_not_found" | "invalid_zip" | "validation_failed" | "filesystem_error";
+export type SkillServiceErrorCode = "invalid_skill_name" | "skill_not_found" | "invalid_zip" | "validation_failed" | "read_limit_exceeded" | "filesystem_error";
 export declare class SkillServiceError extends Error {
     readonly code: SkillServiceErrorCode;
     constructor(code: SkillServiceErrorCode, message: string);

package/dist/skills/file-reader.d.ts

@@ -0,0 +1,14 @@
+export declare function skillReadLimitExceeded(): never;
+/** Read from one checked descriptor; never follow a SKILL.md symlink or block on a FIFO. */
+export declare function readSkillFile(input: {
+    root: string;
+    name: string;
+    maxBytes: number;
+    metadataOnly?: boolean;
+}): {
+    markdown: string;
+    updatedAt: string;
+};
+/** Bound enumeration before collecting names; a limit never returns a partial list. */
+export declare function listSkillDirectories(root: string, maxEntries?: number): string[];
+//# sourceMappingURL=file-reader.d.ts.map

package/dist/skills/file-reader.js

@@ -0,0 +1,123 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync, realpathSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { SKILL_MD_FILE_NAME } from "./constants.js";
+import { SkillServiceError } from "./errors.js";
+import { decodeSkillMarkdown, isValidSkillName } from "./metadata.js";
+function unsafePath() {
+    throw new SkillServiceError("validation_failed", "Skill path is not a regular project skill");
+}
+export function skillReadLimitExceeded() {
+    throw new SkillServiceError("read_limit_exceeded", "Skill read exceeds the supported limit");
+}
+function mapReadError(error) {
+    if (error instanceof SkillServiceError)
+        throw error;
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+        throw new SkillServiceError("skill_not_found", "Skill does not exist");
+    }
+    throw new SkillServiceError("filesystem_error", "Skill could not be read");
+}
+function realDirectory(path) {
+    if (!lstatSync(path).isDirectory())
+        unsafePath();
+    return realpathSync(path);
+}
+function resolveSkillFile(root, name) {
+    const realRoot = realDirectory(resolve(root));
+    const directory = join(realRoot, name);
+    if (realDirectory(directory) !== directory)
+        unsafePath();
+    const file = join(directory, SKILL_MD_FILE_NAME);
+    if (!lstatSync(file).isFile() || realpathSync(file) !== file)
+        unsafePath();
+    return file;
+}
+function sameFile(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs &&
+        left.ctimeMs === right.ctimeMs);
+}
+/** Read from one checked descriptor; never follow a SKILL.md symlink or block on a FIFO. */
+export function readSkillFile(input) {
+    if (!isValidSkillName(input.name)) {
+        throw new SkillServiceError("invalid_skill_name", "Skill name is invalid");
+    }
+    let fd;
+    try {
+        const file = resolveSkillFile(input.root, input.name);
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const before = fstatSync(fd);
+        if (!before.isFile() || !sameFile(before, lstatSync(file)))
+            unsafePath();
+        if (!input.metadataOnly && before.size > input.maxBytes)
+            skillReadLimitExceeded();
+        const buffer = Buffer.alloc(Math.min(before.size, input.maxBytes) + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = readSync(fd, buffer, length, buffer.length - length, length);
+            if (read === 0)
+                break;
+            length += read;
+        }
+        if (!sameFile(before, fstatSync(fd)) ||
+            resolveSkillFile(input.root, input.name) !== file ||
+            !sameFile(before, lstatSync(file))) {
+            throw new SkillServiceError("filesystem_error", "Skill changed while being read");
+        }
+        const bytes = buffer.subarray(0, length);
+        const text = decodeSkillMarkdown(bytes, input.metadataOnly === true && before.size > length);
+        if (input.metadataOnly) {
+            // Frontmatter syntax stays owned by metadata.ts. Only its bounded prefix is decoded.
+            const prefix = text.replace(/\r\n/gu, "\n");
+            const end = prefix.startsWith("---\n") ? prefix.indexOf("\n---", 4) : -1;
+            if (end !== -1) {
+                const metadata = prefix.slice(0, end + 4);
+                if (Buffer.byteLength(metadata) > input.maxBytes)
+                    skillReadLimitExceeded();
+                return { markdown: metadata, updatedAt: before.mtime.toISOString() };
+            }
+        }
+        if (length > input.maxBytes)
+            skillReadLimitExceeded();
+        return { markdown: text, updatedAt: before.mtime.toISOString() };
+    }
+    catch (error) {
+        return mapReadError(error);
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Bound enumeration before collecting names; a limit never returns a partial list. */
+export function listSkillDirectories(root, maxEntries = Infinity) {
+    try {
+        const realRoot = realDirectory(resolve(root));
+        const directory = opendirSync(realRoot);
+        const names = [];
+        let count = 0;
+        try {
+            for (let entry = directory.readSync(); entry !== null; entry = directory.readSync()) {
+                if (++count > maxEntries)
+                    skillReadLimitExceeded();
+                if (entry.isDirectory() && isValidSkillName(entry.name))
+                    names.push(entry.name);
+            }
+        }
+        finally {
+            directory.closeSync();
+        }
+        if (realDirectory(resolve(root)) !== realRoot)
+            unsafePath();
+        return names.sort();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return mapReadError(error);
+    }
+}
+//# sourceMappingURL=file-reader.js.map

package/dist/skills/index.d.ts

@@ -26,9 +26,12 @@ export type UserSkillImportResult = {
     disposition: UserSkillImportDisposition;
     skill: SkillDetailProjection;
 };
+export type UserSkillReadOptions = {
+    mode?: "full" | "preview";
+};
 export declare function getProjectUserSkillsRoot(tuttiHome: string, projectId: ProjectId): string;
-export declare function listUserSkills(userSkillsRoot: string): SkillProjection[];
-export declare function readUserSkill(userSkillsRoot: string, skillName: string): SkillDetailProjection;
+export declare function listUserSkills(userSkillsRoot: string, options?: UserSkillReadOptions): SkillProjection[];
+export declare function readUserSkill(userSkillsRoot: string, skillName: string, options?: UserSkillReadOptions): SkillDetailProjection;
 export declare function importUserSkillZip(options: {
     userSkillsRoot: string;
     zipBuffer: Buffer;

package/dist/skills/index.js

@@ -1,9 +1,10 @@
-import { existsSync, mkdtempSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { SKILL_MD_FILE_NAME, USER_SKILLS_DIRECTORY_NAME } from "./constants.js";
+import { MAX_SKILL_FILE_BYTES, MAX_SKILL_PREVIEW_BYTES, MAX_SKILL_PREVIEW_METADATA_BYTES, MAX_SKILL_PREVIEW_SCAN_ENTRIES, MAX_SKILL_PREVIEW_ITEMS, MAX_SKILL_PREVIEW_LIST_BYTES, USER_SKILLS_DIRECTORY_NAME, } from "./constants.js";
 import { SkillServiceError } from "./errors.js";
-import { isValidSkillName, parseSkillMarkdown, } from "./metadata.js";
+import { listSkillDirectories, readSkillFile, skillReadLimitExceeded } from "./file-reader.js";
+import { isValidSkillName, parseSkillMarkdown } from "./metadata.js";
 import { prepareUserSkillZipImport, writeCandidateFiles, } from "./zip-import.js";
 export { MAX_SKILL_DIRECTORY_DEPTH, MAX_SKILL_FILE_BYTES, MAX_SKILL_FILE_COUNT, MAX_SKILL_TOTAL_UNCOMPRESSED_BYTES, MAX_SKILL_ZIP_BYTES, SKILL_MD_FILE_NAME, USER_SKILLS_DIRECTORY_NAME, } from "./constants.js";
 export { SkillServiceError } from "./errors.js";
@@ -30,17 +31,6 @@ function skillDirectory(userSkillsRoot, skillName) {
     ensureInside(userSkillsRoot, directory);
     return directory;
 }
-function readSkillMarkdown(filePath) {
-    let skillMd;
-    try {
-        skillMd = readFileSync(filePath, "utf8");
-    }
-    catch {
-        throw new SkillServiceError("skill_not_found", "Skill does not exist");
-    }
-    const metadata = parseSkillMarkdown(skillMd);
-    return { ...metadata, skill_md: skillMd };
-}
 function toSkillProjection(options) {
     return {
         name: options.metadata.name,
@@ -53,53 +43,58 @@ function toSkillProjection(options) {
         ...(options.updatedAt === undefined ? {} : { updated_at: options.updatedAt }),
     };
 }
-function readSkillProjection(directory) {
-    const skillMdPath = join(directory, SKILL_MD_FILE_NAME);
-    const parsed = readSkillMarkdown(skillMdPath);
-    const stat = statSync(skillMdPath);
+function readSkillProjection(root, name, preview) {
+    const file = readSkillFile({
+        root,
+        name,
+        maxBytes: preview ? MAX_SKILL_PREVIEW_METADATA_BYTES : MAX_SKILL_FILE_BYTES,
+        metadataOnly: preview,
+    });
     return toSkillProjection({
-        metadata: parsed,
-        updatedAt: stat.mtime.toISOString(),
+        metadata: parseSkillMarkdown(file.markdown),
+        updatedAt: file.updatedAt,
     });
 }
-export function listUserSkills(userSkillsRoot) {
-    if (!existsSync(userSkillsRoot)) {
-        return [];
-    }
+export function listUserSkills(userSkillsRoot, options = {}) {
+    const preview = options.mode === "preview";
     const items = [];
-    for (const entry of readdirSync(userSkillsRoot, { withFileTypes: true })) {
-        if (!entry.isDirectory() || !isValidSkillName(entry.name)) {
-            continue;
-        }
+    let responseBytes = Buffer.byteLength('{"items":[]}');
+    for (const name of listSkillDirectories(userSkillsRoot, preview ? MAX_SKILL_PREVIEW_SCAN_ENTRIES : undefined)) {
         try {
-            const projection = readSkillProjection(join(userSkillsRoot, entry.name));
-            if (projection.name === entry.name) {
+            const projection = readSkillProjection(userSkillsRoot, name, preview);
+            if (projection.name === name) {
+                responseBytes += Buffer.byteLength(JSON.stringify(projection)) + 1;
+                if (preview &&
+                    (items.length >= MAX_SKILL_PREVIEW_ITEMS || responseBytes > MAX_SKILL_PREVIEW_LIST_BYTES)) {
+                    skillReadLimitExceeded();
+                }
                 items.push(projection);
             }
         }
-        catch {
+        catch (error) {
+            if (preview && error instanceof SkillServiceError && error.code === "read_limit_exceeded")
+                throw error;
             // Keep the management surface available even if a stale local directory is malformed.
         }
     }
     return items.sort((left, right) => left.name.localeCompare(right.name));
 }
-export function readUserSkill(userSkillsRoot, skillName) {
-    const directory = skillDirectory(userSkillsRoot, skillName);
-    const skillMdPath = join(directory, SKILL_MD_FILE_NAME);
-    if (!existsSync(skillMdPath)) {
-        throw new SkillServiceError("skill_not_found", "Skill does not exist");
-    }
-    const parsed = readSkillMarkdown(skillMdPath);
+export function readUserSkill(userSkillsRoot, skillName, options = {}) {
+    const file = readSkillFile({
+        root: userSkillsRoot,
+        name: skillName,
+        maxBytes: options.mode === "preview" ? MAX_SKILL_PREVIEW_BYTES : MAX_SKILL_FILE_BYTES,
+    });
+    const parsed = parseSkillMarkdown(file.markdown);
     if (parsed.name !== skillName) {
         throw new SkillServiceError("validation_failed", "Skill metadata is invalid");
     }
-    const stat = statSync(skillMdPath);
     return {
         ...toSkillProjection({
             metadata: parsed,
-            updatedAt: stat.mtime.toISOString(),
+            updatedAt: file.updatedAt,
         }),
-        skill_md: parsed.skill_md,
+        skill_md: file.markdown,
     };
 }
 export async function importUserSkillZip(options) {

package/dist/skills/metadata.d.ts

@@ -4,5 +4,7 @@ export type ParsedSkillMarkdown = {
     short_description?: string;
 };
 export declare function isValidSkillName(value: string): boolean;
+/** Keep import preflight and runtime reads consistent; partial applies only to bounded prefixes. */
+export declare function decodeSkillMarkdown(bytes: Uint8Array, partial?: boolean): string;
 export declare function parseSkillMarkdown(skillMd: string): ParsedSkillMarkdown;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/skills/metadata.js

@@ -1,7 +1,16 @@
 import { SkillServiceError } from "./errors.js";
 const SKILL_NAME_PATTERN = /^[a-z0-9_-]+$/u;
 export function isValidSkillName(value) {
-    return SKILL_NAME_PATTERN.test(value);
+    return value.length <= 96 && SKILL_NAME_PATTERN.test(value);
+}
+/** Keep import preflight and runtime reads consistent; partial applies only to bounded prefixes. */
+export function decodeSkillMarkdown(bytes, partial = false) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes, { stream: partial });
+    }
+    catch {
+        throw new SkillServiceError("validation_failed", "Skill text is not valid UTF-8");
+    }
 }
 export function parseSkillMarkdown(skillMd) {
     const frontmatter = extractFrontmatter(skillMd);