@jini-ai/agentic 0.4.3 → 0.4.4

package/dist/core/handle.d.ts

@@ -40,6 +40,19 @@ export type AgentHandleProps = {
 export declare function agentHandle({ handle }: {
     handle: string;
 }, options?: AgentHandleOptions): AgentHandleProps;
+/**
+ * Derives a bounded handle segment from an opaque id without rewriting that id.
+ * Short valid ids keep their spelling; other ids use a stable 64-bit FNV-1a fingerprint
+ * of their UTF-16 code units. The `h-<16 hex digits>` namespace is reserved for fingerprints.
+ * Unlike list collision suffixes, this segment does not depend on filtering or row order.
+ * This is display identity, not a cryptographic or authorization primitive.
+ * @param required - The original id; arbitrary characters, empty and long strings are accepted.
+ * @returns A valid segment of at most 40 characters; callers reserve space for their fixed prefix.
+ * @complexity O(n) time in id characters, O(1) auxiliary space. No effects or errors.
+ */
+export declare function agentHandleSegment({ value }: {
+    value: string;
+}, _optional?: Record<string, never>): string;
 /**
  * The handle for one sub-element published under `base` — `<base>-<action>`.
  *

package/dist/core/handle.js

@@ -38,6 +38,25 @@ export function agentHandle({ handle }, options = {}) {
         props[AGENT_PAGE_ATTRIBUTE] = options.page;
     return props;
 }
+/**
+ * Derives a bounded handle segment from an opaque id without rewriting that id.
+ * Short valid ids keep their spelling; other ids use a stable 64-bit FNV-1a fingerprint
+ * of their UTF-16 code units. The `h-<16 hex digits>` namespace is reserved for fingerprints.
+ * Unlike list collision suffixes, this segment does not depend on filtering or row order.
+ * This is display identity, not a cryptographic or authorization primitive.
+ * @param required - The original id; arbitrary characters, empty and long strings are accepted.
+ * @returns A valid segment of at most 40 characters; callers reserve space for their fixed prefix.
+ * @complexity O(n) time in id characters, O(1) auxiliary space. No effects or errors.
+ */
+export function agentHandleSegment({ value }, _optional = {}) {
+    if (value.length <= 40 && isValidElementHandle({ handle: value }) && !/^h-[0-9a-f]{16}$/.test(value))
+        return value;
+    let hash = 0xcbf29ce484222325n;
+    for (let index = 0; index < value.length; index += 1) {
+        hash = BigInt.asUintN(64, (hash ^ BigInt(value.charCodeAt(index))) * 0x100000001b3n);
+    }
+    return `h-${hash.toString(16).padStart(16, '0')}`;
+}
 /**
  * The handle for one sub-element published under `base` — `<base>-<action>`.
  *

package/dist/core/index.d.ts

@@ -21,7 +21,7 @@ export type { PageDriver, FindElementsFilter, PageSummary } from './page-driver.
 export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, type FindElementsResult, type PageElementResult, type PageActivitySnapshot, type PageWriteObservation, } from './page-executor.js';
 export { PAGE_CAPABILITIES } from './page-capabilities.js';
 export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_PRIVATE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, type AgentElementRole, type AgentElementDescriptor, type AgentElementRawState, type AgentElementState, } from './element-handles.js';
-export { agentHandle, agentSubHandle, agentHandleProps, type AgentHandleOptions, type AgentHandleProps, type AgentHandlePropsOptions, } from './handle.js';
+export { agentHandle, agentHandleSegment, agentSubHandle, agentHandleProps, type AgentHandleOptions, type AgentHandleProps, type AgentHandlePropsOptions, } from './handle.js';
 export { buildAgentListHandles } from './list-handles.js';
 export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, type FieldDescriptor, type FieldRefusal, type FieldReadRefusal, type NormalizedLabel, } from './guards.js';
 /**
@@ -48,4 +48,5 @@ export { createGenUiEncoder, type GenUiEncodeContext, type GenUiEncoder, type Ge
 export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcNotification, type JsonRpcResponse, type JsonRpcError, } from './mcp-ui-apps.js';
 export { defaultAgenticMessages } from "./messages.js";
 export { createAnnotatedActionsScript } from './annotated-actions-script.js';
+export * from './site-guide/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -20,7 +20,7 @@ export { findCapability, findCapabilityInputError, availableCapabilities, } from
 export { executePageCapability, projectElementState, DEFAULT_HIGHLIGHT_MS, MAX_HIGHLIGHT_MS, MAX_STATEFUL_ELEMENTS, } from './page-executor.js';
 export { PAGE_CAPABILITIES } from './page-capabilities.js';
 export { AGENT_ELEMENT_ATTRIBUTE, AGENT_ROLE_ATTRIBUTE, AGENT_LABEL_ATTRIBUTE, AGENT_PAGE_ATTRIBUTE, AGENT_PRIVATE_ATTRIBUTE, AGENT_ELEMENT_ROLES, isValidElementHandle, resolveHandleSelector, } from './element-handles.js';
-export { agentHandle, agentSubHandle, agentHandleProps, } from './handle.js';
+export { agentHandle, agentHandleSegment, agentSubHandle, agentHandleProps, } from './handle.js';
 export { buildAgentListHandles } from './list-handles.js';
 export { findFieldFillRefusal, findFieldReadRefusal, describeFieldRefusal, describeFieldReadRefusal, normalizeAgentLabel, MAX_AGENT_LABEL_LENGTH, } from './guards.js';
 /**
@@ -47,4 +47,5 @@ export { createGenUiEncoder, } from './gen-ui/index.js';
 export { MCP_UI_VIEW_METHODS, MCP_UI_HOST_NOTIFICATIONS, MCP_UI_VIEW_NOTIFICATIONS, MCP_UI_HOST_REQUESTS, MCP_UI_SANDBOX_NOTE, JINI_PAGE_ACTION_METHOD, JSON_RPC_ERROR_CODES, isJsonRpcMessage, isJsonRpcRequest, createJsonRpcRequest, createJsonRpcNotification, createJsonRpcResult, createJsonRpcError, createPageActionRequest, } from './mcp-ui-apps.js';
 export { defaultAgenticMessages } from "./messages.js";
 export { createAnnotatedActionsScript } from './annotated-actions-script.js';
+export * from './site-guide/index.js';
 //# sourceMappingURL=index.js.map

package/dist/core/site-guide/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './topic-schema.js';
+export * from './site-guide.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/site-guide/index.js

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './topic-schema.js';
+export * from './site-guide.js';
+//# sourceMappingURL=index.js.map

package/dist/core/site-guide/site-guide.d.ts

@@ -0,0 +1,18 @@
+import type { SiteGuide, SiteGuidePorts } from './types.js';
+export declare class SiteGuideInputError extends Error {
+    constructor({ message }: {
+        readonly message: string;
+    }, _options?: Record<string, never>);
+}
+/** Build a neutral read-only guide over host ports. No product state or plugin loader is ambient.
+ * Authorization and contributions are read fresh for each request. Errors from enrichment/facts
+ * yield explicit unavailable status without copying arbitrary error messages into model context.
+ * @param ports - Facts, authorization, optional enrichment, and host minimal capability cards.
+ * @returns One overview/explain service. Invalid input and hidden topics throw SiteGuideInputError.
+ * @complexity O(t + p) per request, topics plus distinct permissions; one bulk facts read.
+ * @example createSiteGuide({ facts, authorize, builtInTopics: cards }).run({ caller, operation: 'overview' });
+ */
+export declare function createSiteGuide(ports: SiteGuidePorts, options?: {
+    readonly readTimeoutMs?: number;
+}): SiteGuide;
+//# sourceMappingURL=site-guide.d.ts.map

package/dist/core/site-guide/site-guide.js

@@ -0,0 +1,144 @@
+const MINIMAL_TOPICS = [{
+        id: 'site', title: 'How this site works', summary: 'Learn the available building blocks before planning or building.',
+        explanation: 'Read the live facts, then consult the host topics and their tools. Missing or forbidden facts are unknown, not disabled capabilities.',
+        permissions: [], pointers: [], workflows: [],
+    }];
+export class SiteGuideInputError extends Error {
+    constructor({ message }, _options = {}) { super(message); this.name = 'SiteGuideInputError'; }
+}
+/** Bound an injected read so an unavailable extension cannot hang learning. Always clear timers.
+ * @complexity O(1) beyond the supplied read; rejection text is kept internal to the shell.
+ */
+async function boundedRead(read, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([Promise.resolve().then(read), new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error('site guide read timed out')), timeoutMs);
+            })]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** Compose by topic id. Core cards keep their owner; plugins add distinct, permission-gated topics.
+ * @complexity O(t) in bounded built-in and contributed topic counts, O(t) lookup space.
+ */
+function combineTopics(builtIns, contributions) {
+    const topics = new Map(builtIns.map(topic => [topic.id, { topic, source: 'core' }]));
+    const byId = new Map();
+    for (const contribution of contributions) {
+        for (const topic of contribution.topics) {
+            const candidates = byId.get(topic.id) ?? [];
+            candidates.push({ topic, pluginId: contribution.pluginId });
+            byId.set(topic.id, candidates);
+        }
+    }
+    let conflicts = false;
+    for (const [id, candidates] of byId) {
+        // A contribution cannot replace a host's prose, pointers, workflows or security gates.
+        if (topics.has(id) || candidates.length !== 1) {
+            conflicts = true;
+            continue;
+        }
+        const candidate = candidates[0];
+        topics.set(id, { topic: candidate.topic, source: candidate.pluginId });
+    }
+    return { topics: [...topics.values()], conflicts };
+}
+/** Build a neutral read-only guide over host ports. No product state or plugin loader is ambient.
+ * Authorization and contributions are read fresh for each request. Errors from enrichment/facts
+ * yield explicit unavailable status without copying arbitrary error messages into model context.
+ * @param ports - Facts, authorization, optional enrichment, and host minimal capability cards.
+ * @returns One overview/explain service. Invalid input and hidden topics throw SiteGuideInputError.
+ * @complexity O(t + p) per request, topics plus distinct permissions; one bulk facts read.
+ * @example createSiteGuide({ facts, authorize, builtInTopics: cards }).run({ caller, operation: 'overview' });
+ */
+export function createSiteGuide(ports, options = {}) {
+    const timeoutMs = options.readTimeoutMs ?? 5_000;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new SiteGuideInputError({ message: 'readTimeoutMs must be a positive finite number' });
+    const builtIns = ports.builtInTopics ?? MINIMAL_TOPICS;
+    if (builtIns.length > 256 || new Set(builtIns.map(topic => topic.id)).size !== builtIns.length)
+        throw new SiteGuideInputError({ message: 'Built-in topics must have unique ids and contain at most 256 cards' });
+    return { async run(input, _options = {}) {
+            if (input.operation !== 'overview' && input.operation !== 'explain')
+                throw new SiteGuideInputError({ message: 'operation must be overview or explain' });
+            if (input.operation === 'overview' && input.topic !== undefined)
+                throw new SiteGuideInputError({ message: 'topic is only accepted with operation explain' });
+            if (input.operation === 'explain' && (typeof input.topic !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(input.topic))) {
+                throw new SiteGuideInputError({ message: 'explain requires a topic id from overview' });
+            }
+            let contributions = [];
+            let enrichment = 'ok';
+            if (ports.loadContributions) {
+                try {
+                    const loaded = await boundedRead(() => ports.loadContributions({ caller: input.caller }), timeoutMs);
+                    if (loaded.items.reduce((count, item) => count + item.topics.length, 0) > 256)
+                        throw new SiteGuideInputError({ message: 'Too many contributed topics' });
+                    contributions = loaded.items;
+                    if (loaded.refusals.length)
+                        enrichment = 'partial';
+                }
+                catch {
+                    enrichment = 'unavailable';
+                }
+            }
+            const combined = combineTopics(builtIns, contributions);
+            if (combined.conflicts)
+                enrichment = 'partial';
+            const decisions = new Map();
+            const allowed = (permission) => {
+                let decision = decisions.get(permission);
+                if (!decision) {
+                    // Failed authorization is denial, never an excuse to expose a card or run its read.
+                    decision = boundedRead(() => ports.authorize({ caller: input.caller, permission }), timeoutMs).catch(() => false);
+                    decisions.set(permission, decision);
+                }
+                return decision;
+            };
+            const permitted = async (permissions) => (await Promise.all(permissions.map(allowed))).every(Boolean);
+            const views = [];
+            for (const entry of combined.topics) {
+                if (input.operation === 'explain' && entry.topic.id !== input.topic)
+                    continue;
+                if (!await permitted(entry.topic.permissions))
+                    continue;
+                const view = { id: entry.topic.id, title: entry.topic.title, summary: entry.topic.summary, source: entry.source };
+                if (input.operation === 'explain') {
+                    const pointers = [];
+                    for (const { permissions, ...pointer } of entry.topic.pointers)
+                        if (await permitted(permissions))
+                            pointers.push(pointer);
+                    const workflows = [];
+                    for (const { permissions, ...workflow } of entry.topic.workflows)
+                        if (await permitted(permissions))
+                            workflows.push(workflow);
+                    views.push({ ...view, explanation: entry.topic.explanation, pointers, workflows });
+                }
+                else
+                    views.push(view);
+            }
+            if (input.operation === 'explain' && views.length === 0)
+                throw new SiteGuideInputError({ message: 'Topic unavailable. Call site_guide with operation overview for topics you may read.' });
+            let facts = {};
+            const topicIds = views.map(view => view.id);
+            // Overview is discovery only; read fresh domain facts when a visible topic is explained.
+            if (input.operation === 'explain') {
+                try {
+                    const read = await boundedRead(() => ports.facts.read({ caller: input.caller, topics: topicIds }), timeoutMs);
+                    // A facts adapter returning an unrelated section cannot disclose it through this tool.
+                    facts = Object.fromEntries(topicIds.map(id => [id, read[id] ?? { status: 'unavailable' }]));
+                }
+                catch {
+                    facts = Object.fromEntries(topicIds.map(id => [id, { status: 'unavailable' }]));
+                }
+            }
+            const callerPermissions = [];
+            for (const [permission, decision] of decisions)
+                if (await decision)
+                    callerPermissions.push(permission);
+            return { operation: input.operation, topics: views, facts, callerPermissions, enrichment };
+        } };
+}
+//# sourceMappingURL=site-guide.js.map

package/dist/core/site-guide/topic-schema.d.ts

@@ -0,0 +1,16 @@
+import type { GuideTopic } from './types.js';
+/** Parse bounded data-only enrichment. Invalid fields and duplicate ids refuse the whole file.
+ * @returns Validated topics or a fixed, data-free diagnostic; never quotes plugin bytes.
+ * @complexity O(n) characters, capped at 256 KiB of UTF-8, plus bounded shape traversal.
+ * @example parseGuideTopics({ raw: '{"version":1,"topics":[]}' });
+ */
+export declare function parseGuideTopics({ raw }: {
+    readonly raw: string;
+}, _options?: Record<string, never>): {
+    readonly ok: true;
+    readonly descriptors: readonly GuideTopic[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+//# sourceMappingURL=topic-schema.d.ts.map

package/dist/core/site-guide/topic-schema.js

@@ -0,0 +1,68 @@
+/** Native shape guards keep the core barrel usable without the optional A2UI/Zod peer. */
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function text(value, maximum = 8_000) {
+    return typeof value === 'string' && value.length > 0 && value.length <= maximum;
+}
+function keys(value, permitted) {
+    return Object.keys(value).every(key => permitted.includes(key));
+}
+function list(value, maximum, guard) {
+    return Array.isArray(value) && value.length <= maximum && value.every(guard);
+}
+function permission(value) { return text(value, 128); }
+function permissions(value) { return list(value, 32, permission); }
+function step(value) { return text(value); }
+/** Accept document/admin/HTTPS pointers, never script URLs or arbitrary local files. */
+function href(value) {
+    return text(value, 512) && (value.startsWith('/admin/') || value.startsWith('development/') || value.startsWith('https://'));
+}
+function pointer(value) {
+    if (!record(value) || !keys(value, ['label', 'tool', 'href', 'permissions']))
+        return false;
+    if (!text(value.label) || !permissions(value.permissions))
+        return false;
+    if (value.tool !== undefined && !text(value.tool, 128))
+        return false;
+    if (value.href !== undefined && !href(value.href))
+        return false;
+    return value.tool !== undefined || value.href !== undefined;
+}
+function workflow(value) {
+    if (!record(value) || !keys(value, ['title', 'steps', 'permissions']))
+        return false;
+    return text(value.title) && permissions(value.permissions) && list(value.steps, 16, step) && value.steps.length > 0;
+}
+function topic(value) {
+    if (!record(value) || !keys(value, ['id', 'title', 'summary', 'explanation', 'permissions', 'pointers', 'workflows']))
+        return false;
+    if (!text(value.id, 64) || !/^[a-z][a-z0-9-]*$/.test(value.id))
+        return false;
+    return text(value.title, 128) && text(value.summary, 1_000) && text(value.explanation) && permissions(value.permissions)
+        && list(value.pointers, 24, pointer) && list(value.workflows, 16, workflow);
+}
+/** Parse bounded data-only enrichment. Invalid fields and duplicate ids refuse the whole file.
+ * @returns Validated topics or a fixed, data-free diagnostic; never quotes plugin bytes.
+ * @complexity O(n) characters, capped at 256 KiB of UTF-8, plus bounded shape traversal.
+ * @example parseGuideTopics({ raw: '{"version":1,"topics":[]}' });
+ */
+export function parseGuideTopics({ raw }, _options = {}) {
+    if (raw.length > 262_144 || new TextEncoder().encode(raw).byteLength > 262_144)
+        return { ok: false, reason: 'site-guide manifest exceeds 256 KiB' };
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'site-guide manifest must be valid JSON' };
+    }
+    if (!record(value) || !keys(value, ['version', 'topics']) || value.version !== 1 || !list(value.topics, 64, topic)) {
+        return { ok: false, reason: 'site-guide manifest does not match version 1 topic schema' };
+    }
+    const ids = new Set(value.topics.map(item => item.id));
+    if (ids.size !== value.topics.length)
+        return { ok: false, reason: 'site-guide manifest contains duplicate topic ids' };
+    return { ok: true, descriptors: value.topics };
+}
+//# sourceMappingURL=topic-schema.js.map

package/dist/core/site-guide/types.d.ts

@@ -0,0 +1,83 @@
+/** Read-only learning contracts. Hosts supply facts; plugins supply prose, never read effects. */
+export interface GuideCaller {
+    readonly principalId: string;
+}
+export interface GuidePointer {
+    readonly label: string;
+    readonly tool?: string | undefined;
+    readonly href?: string | undefined;
+    readonly permissions: readonly string[];
+}
+export interface GuideWorkflow {
+    readonly title: string;
+    readonly steps: readonly string[];
+    readonly permissions: readonly string[];
+}
+export interface GuideTopic {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly explanation: string;
+    readonly permissions: readonly string[];
+    readonly pointers: readonly GuidePointer[];
+    readonly workflows: readonly GuideWorkflow[];
+}
+export interface GuideContribution {
+    readonly pluginId: string;
+    readonly topics: readonly GuideTopic[];
+}
+export interface GuideContributionResult {
+    readonly items: readonly GuideContribution[];
+    /** Host-local diagnostics; never expose arbitrary loader messages to the model. */
+    readonly refusals: readonly string[];
+}
+export type GuideFact = {
+    readonly status: 'ok';
+    readonly data: unknown;
+    readonly truncated?: boolean;
+} | {
+    readonly status: 'forbidden' | 'unavailable';
+};
+/** Only a permission-scoped, explicitly projected DTO may leave the host adapter. */
+export interface SiteFactsPort {
+    read(input: {
+        readonly caller: GuideCaller;
+        readonly topics: readonly string[];
+    }, options?: Record<string, never>): Promise<Readonly<Record<string, GuideFact>>>;
+}
+export interface SiteGuidePorts {
+    readonly facts: SiteFactsPort;
+    readonly authorize: (input: {
+        readonly caller: GuideCaller;
+        readonly permission: string;
+    }, options?: Record<string, never>) => Promise<boolean>;
+    readonly loadContributions?: (input: {
+        readonly caller: GuideCaller;
+    }, options?: Record<string, never>) => Promise<GuideContributionResult>;
+    readonly builtInTopics?: readonly GuideTopic[];
+}
+export interface GuideTopicView {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly explanation?: string;
+    readonly pointers?: readonly Omit<GuidePointer, 'permissions'>[];
+    readonly workflows?: readonly Omit<GuideWorkflow, 'permissions'>[];
+    readonly source: string;
+}
+export interface GuideResult {
+    readonly operation: 'overview' | 'explain';
+    readonly topics: readonly GuideTopicView[];
+    readonly facts: Readonly<Record<string, GuideFact>>;
+    /** Granted permissions consulted for this result, rather than an inventory of the caller's roles. */
+    readonly callerPermissions: readonly string[];
+    readonly enrichment: 'ok' | 'unavailable' | 'partial';
+}
+export interface SiteGuide {
+    run(input: {
+        readonly caller: GuideCaller;
+        readonly operation: 'overview' | 'explain';
+        readonly topic?: string;
+    }, options?: Record<string, never>): Promise<GuideResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/site-guide/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/skills/install/archive.js

@@ -37,6 +37,7 @@ export async function readSkillArchive({ base64, archiveReader }, _optional = {}
         finally {
             reader.close({});
         }
+        /** Converts malformed archive parser failures into a client-actionable validation refusal. */
     }
     catch (error) {
         if (error instanceof SkillInputError)

package/dist/skills/install/index.d.ts

@@ -8,4 +8,5 @@ export * from "./layout.js";
 export * from "./live-registration.js";
 export * from "./fetch-adapter.js";
 export * from "./node-filesystem.js";
+export * from "./yauzl-archive-reader.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/skills/install/index.js

@@ -8,4 +8,5 @@ export * from "./layout.js";
 export * from "./live-registration.js";
 export * from "./fetch-adapter.js";
 export * from "./node-filesystem.js";
+export * from "./yauzl-archive-reader.js";
 //# sourceMappingURL=index.js.map

package/dist/skills/install/install-service.d.ts

@@ -1,4 +1,4 @@
-import { type SkillUploadFile } from "./validation.js";
+import { validateSkillFiles, type SkillUploadFile } from "./validation.js";
 import { type GitHubSkillSource } from "./github.js";
 import type { SkillInstallDeps } from "./ports.js";
 export interface ManagedSkill {
@@ -17,7 +17,26 @@ export type SkillInstallInput = {
 } | {
     readonly archiveBase64: string;
 });
+/** A fetched and fully validated skill package, not yet written. Holding the validated bytes (not
+ * the source) means commitSkillInstall writes exactly what was validated, with no second fetch. */
+export interface PreparedSkillInstall {
+    readonly toolId: string;
+    readonly name: string;
+    readonly description: string;
+    readonly source: ManagedSkill["source"];
+    readonly files: ReturnType<typeof validateSkillFiles>["files"];
+}
+/** Fetch/decode and validate before asking for mutation approval. No filesystem writes. */
+export declare function prepareSkillInstall(required: {
+    input: SkillInstallInput;
+    deps: Pick<SkillInstallDeps, "fetch" | "archiveReader" | "yamlReader" | "toolId">;
+}, _optional?: {}): Promise<PreparedSkillInstall>;
 export interface SkillInstaller {
+    prepareSkillInstall(required: SkillInstallInput): Promise<PreparedSkillInstall>;
+    commitSkillInstall(required: {
+        workspaceId: string;
+        prepared: PreparedSkillInstall;
+    }): Promise<ManagedSkill>;
     installSkill(required: SkillInstallInput): Promise<ManagedSkill>;
     listManagedSkills(required: {
         workspaceId: string;

package/dist/skills/install/install-service.js

@@ -3,6 +3,20 @@ import { SkillInputError, validateSkillFiles } from "./validation.js";
 import { readSkillArchive } from "./archive.js";
 import { fetchGitHubSkill } from "./github.js";
 import { readSkillState } from "./state.js";
+/** Fetch/decode and validate before asking for mutation approval. No filesystem writes. */
+export async function prepareSkillInstall(required, _optional = {}) {
+    const { input, deps } = required;
+    let upload;
+    let source = "uploaded";
+    if ("githubUrl" in input)
+        ({ files: upload, source } = await fetchGitHubSkill({ githubUrl: input.githubUrl, fetch: deps.fetch }));
+    else if ("archiveBase64" in input)
+        upload = await readSkillArchive({ base64: input.archiveBase64, archiveReader: deps.archiveReader });
+    else
+        upload = input.files;
+    const validated = validateSkillFiles({ files: upload, yamlReader: deps.yamlReader });
+    return { ...validated, toolId: deps.toolId({ name: validated.name }), source };
+}
 /** Validate before writes; publish via rename, with instance-local queues keyed by resolved root.
  * Cross-process exclusivity remains the host filesystem/layout adapter's responsibility.
  */
@@ -16,6 +30,7 @@ export function createSkillInstaller(deps, optional = {}) {
             throw new SkillInputError({ message: "Invalid skill state file name." });
         return layout;
     };
+    /** Serializes mutations in this server without leaving persistent locks after a crash. */
     async function locked(workspaceId, work) {
         const key = layoutFor(workspaceId).workspaceRoot;
         const result = (queues.get(key) ?? Promise.resolve()).catch(() => { }).then(work);
@@ -47,19 +62,15 @@ export function createSkillInstaller(deps, optional = {}) {
         return directory;
     }
     const changed = async (workspaceId, toolId) => { await optional.onChanged?.({ workspaceId, toolId }); };
-    return {
+    const installer = {
         listManagedSkills,
+        prepareSkillInstall: input => prepareSkillInstall({ input, deps }),
         async installSkill(input) {
-            let upload;
-            let source = "uploaded";
-            if ("githubUrl" in input)
-                ({ files: upload, source } = await fetchGitHubSkill({ githubUrl: input.githubUrl, fetch: deps.fetch }));
-            else if ("archiveBase64" in input)
-                upload = await readSkillArchive({ base64: input.archiveBase64, archiveReader: deps.archiveReader });
-            else
-                upload = input.files;
-            const validated = validateSkillFiles({ files: upload, yamlReader: deps.yamlReader });
-            const toolId = deps.toolId({ name: validated.name });
+            return installer.commitSkillInstall({ workspaceId: input.workspaceId, prepared: await prepareSkillInstall({ input, deps }) });
+        },
+        async commitSkillInstall(input) {
+            const validated = input.prepared;
+            const { toolId, source } = validated;
             const layout = layoutFor(input.workspaceId);
             return locked(input.workspaceId, async () => {
                 if ((await listManagedSkills(input)).some(skill => skill.toolId === toolId))
@@ -112,6 +123,7 @@ export function createSkillInstaller(deps, optional = {}) {
             });
         },
     };
+    return installer;
 }
 function containedDirectory(root, directory) {
     if (!directory || directory === "." || directory === ".." || /[/\\\x00]/.test(directory))

package/dist/skills/install/layout.d.ts

@@ -1,4 +1,12 @@
 import type { SkillLayoutPort } from './ports.js';
+/**
+ * Deliberately does NOT import anything from `src/features/agent-plugins/` — Agent Skills and Agent
+ * Plugins are different things with their own directories (owner decision, above), and this file's
+ * small id-segment guard is duplicated rather than shared, for the same reason
+ * `capability-projection.ts`/`capability-source.ts` already duplicate their own `humanize` helper
+ * between themselves: a private guard belonging to one small module, not a promise to keep two
+ * independent features' internals in sync.
+ */
 /** Every storage location is host-owned; this adapter has no product or cwd defaults.
  * Layout resolves the same required root/stagingRoot/workspaceDirectory/stateFileName
  * contract used by the installer. No site, environment or cwd defaults are allowed: separate

package/dist/skills/install/layout.js

@@ -1,4 +1,26 @@
 import path from 'node:path';
+/**
+ * One safe, indivisible path segment: lowercase alphanumerics in `-`/`.`-separated runs, with no
+ * leading, trailing, or doubled separator. Mirrors `agent-plugins/layout.ts`'s own
+ * `SAFE_ID_SEGMENT_PATTERN` — duplicated rather than imported (see this file's header) — and accepts
+ * this instance's real workspace id (`workspace-local`, per `<site>/uploads/ws/workspace-local/`) as
+ * well as every UUID.
+ */
+const SAFE_ID_SEGMENT_PATTERN = /^[a-z0-9]+(?:[-.][a-z0-9]+)*$/;
+/** Bounds the segment so a caller cannot drive a pathological path length. */
+const MAX_ID_SEGMENT_LENGTH = 64;
+// The segment grammar above moved from Tovu features/skills/layout.ts; the sibling path in its
+// historical rationale refers to Tovu features/agent-plugins/layout.ts.
+/**
+ * Deliberately does NOT import anything from `src/features/agent-plugins/` — Agent Skills and Agent
+ * Plugins are different things with their own directories (owner decision, above), and this file's
+ * small id-segment guard is duplicated rather than shared, for the same reason
+ * `capability-projection.ts`/`capability-source.ts` already duplicate their own `humanize` helper
+ * between themselves: a private guard belonging to one small module, not a promise to keep two
+ * independent features' internals in sync.
+ */
+// This paragraph records the original Tovu module boundary; the private segment guard now
+// belongs to this Jini layout owner, and the host keeps only the site-directory adapter.
 /** Every storage location is host-owned; this adapter has no product or cwd defaults.
  * Layout resolves the same required root/stagingRoot/workspaceDirectory/stateFileName
  * contract used by the installer. No site, environment or cwd defaults are allowed: separate
@@ -13,8 +35,11 @@ export function createSkillLayout(required, _optional = {}) {
     if (!stateFileName || /[/\\\x00]/.test(stateFileName) || ['.', '..', 'SKILL.md', 'README.md', 'LICENSE', 'references', 'scripts', 'assets'].includes(stateFileName))
         throw new Error('Invalid skill state file name.');
     return Object.freeze({ resolve({ workspaceId }) {
+            // Normalize BEFORE validating, not after — see `agent-plugins/layout.ts`'s own comment at the
+            // identical line: the pattern is deliberately lowercase-only, and the normalized value is the
+            // one that actually becomes the path segment, so it is the only value worth asserting about.
             const normalized = workspaceId.toLowerCase();
-            if (normalized.length > 64 || !/^[a-z0-9]+(?:[-.][a-z0-9]+)*$/.test(normalized))
+            if (normalized.length > MAX_ID_SEGMENT_LENGTH || !SAFE_ID_SEGMENT_PATTERN.test(normalized))
                 throw new Error(`resolve: '${workspaceId}' is not a valid workspace id`);
             return { workspaceRoot: path.join(root, workspaceDirectory, normalized), stagingRoot: path.resolve(stagingRoot), stateFileName };
         } });

package/dist/skills/install/live-registration.js

@@ -8,6 +8,7 @@ export function createLiveSkillRegistration(required, _optional = {}) {
     registry.has = input => slots.has(input.id) ? active.has(input.id) : has(input);
     let fingerprint = '';
     return ({ tools }) => {
+        // Discovery changes invalidate the search snapshot; handlers always use current guidance.
         const nextFingerprint = JSON.stringify(tools.map(t => t.descriptor));
         const next = new Map(tools.map(t => [t.descriptor.id, t]));
         if (next.size !== tools.length)

package/dist/skills/install/validation.d.ts

@@ -1,11 +1,15 @@
 import type { YamlReaderPort } from "./ports.js";
 export type SkillYamlPort = YamlReaderPort;
 export declare class SkillInputError extends Error {
-    constructor({ message }: {
+    constructor(required: {
         message: string;
     }, optional?: {
         cause?: unknown;
     });
+    /** Published host adapters may still use the native Error call shape during migration. */
+    constructor(message: string, optional?: {
+        cause?: unknown;
+    });
 }
 export interface SkillUploadFile {
     readonly path: string;

package/dist/skills/install/validation.js

@@ -1,8 +1,8 @@
 /** Bounded skill-bundle validation; scripts are stored as data and never executed. */
 import path from "node:path";
 export class SkillInputError extends Error {
-    constructor({ message }, optional = {}) {
-        super(message, optional);
+    constructor(required, optional = {}) {
+        super(typeof required === "string" ? required : required.message, optional);
     }
 }
 export const MAX_SKILL_BYTES = 8 * 1024 * 1024;