@agentxm/extension-model 0.38.0 → 0.39.0

package/dist/src/unstable/hooks/manifest-schema.js

@@ -1,112 +1,296 @@
-/**
- * Hook manifest schema definition.
- *
- * @experimental This API is unstable and may change without notice.
- */
+/** Native Hook package contract. @experimental */
+import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-import { CanonicalHookEventIdSchema, CanonicalHookToolIdSchema, HookBlockOutcomeSchema, HookModifyOperationSchema, } from "../agent-capabilities/schema.js";
-import { CommonManifestBaseFields, ExtensionNameSchema, NonPackManifestFields, } from "../extensions/common.js";
+import { HookBlockOutcomeSchema, HookModifyOperationSchema } from "../agent-capabilities/schema.js";
+import { CommonManifestBaseFields, ConfigurableAgentIdSchema, ExtensionNameSchema, NonPackManifestFields, } from "../extensions/common.js";
+import { VersionRangeSchema } from "../version-constraints/version-constraints.js";
 export const HOOK_MANIFEST_FILENAME = "hook.json";
 export const HOOK_EXTENSION_DIR = "hooks";
 export const HOOK_MANIFEST_SCHEMA_URL = "https://axm.sh/schemas/hook.schema.json";
 export const HookRuntimeSchema = Schema.Literals(["bash", "node", "python"]).annotate({
     identifier: "HookRuntime",
-    title: "Hook Runtime",
-    description: "Interpreter family used to execute the materialized hook entrypoint.",
+    description: "Interpreter family used to execute this native command handler.",
 });
-export const HookEventSchema = CanonicalHookEventIdSchema.annotate({
-    identifier: "HookEvent",
-    title: "Hook Event",
-    description: "Canonical AXM hook event this extension binds to.",
-});
-export const HookMatchSchema = Schema.Struct({
-    tools: Schema.optional(Schema.NonEmptyArray(CanonicalHookToolIdSchema).pipe(Schema.check(Schema.isUnique()))),
-}).annotate({
-    identifier: "HookMatch",
-    title: "Hook Match",
-    description: "Portable hook matcher expressed over AXM canonical tool IDs.",
+const HookIdSchema = Schema.NonEmptyString.check(Schema.isPattern(/^[a-z][a-z0-9-]*$/), Schema.isMaxLength(80));
+const ConfigurationKeySchema = Schema.NonEmptyString.check(Schema.isPattern(/^[a-zA-Z][a-zA-Z0-9_]*$/), Schema.isMaxLength(64));
+const EnvironmentKeySchema = Schema.NonEmptyString.check(Schema.isPattern(/^[a-zA-Z_][a-zA-Z0-9_]*$/));
+export const HookPackagePathSchema = Schema.NonEmptyString.check(Schema.isPattern(
+// eslint-disable-next-line no-control-regex -- Package paths must reject control characters, including NUL.
+/^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))(?!.*\/\/)(?!.*[\\:\u0000-\u001f])[^/]+(?:\/[^/]+)*$/)).annotate({
+    identifier: "HookPackagePath",
+    description: "A safe, package-relative POSIX file path. Absolute paths and traversal are forbidden.",
 });
-export const HookDecisionRequirementSchema = Schema.Union([
-    Schema.Struct({ kind: Schema.Literal("observe") }),
+/** Symbolic references are preserved, never resolved against the author's environment. */
+export const HookEnvironmentReferenceSchema = Schema.Struct({ env: EnvironmentKeySchema });
+export const HookValueSchema = Schema.Union([
+    Schema.String,
+    Schema.Struct({ config: ConfigurationKeySchema }),
+    HookEnvironmentReferenceSchema,
+]).annotate({ identifier: "HookValue" });
+export const HookConfigurationValueSchema = Schema.Union([
+    Schema.String,
+    Schema.Finite,
+    Schema.Boolean,
+    HookEnvironmentReferenceSchema,
+]);
+export const HookConfigurationValuesSchema = Schema.Record(ConfigurationKeySchema, HookConfigurationValueSchema);
+const ConfigurationFields = {
+    description: Schema.optional(Schema.NonEmptyString),
+    required: Schema.optional(Schema.Boolean),
+};
+export const HookConfigurationFieldSchema = Schema.Union([
     Schema.Struct({
-        kind: Schema.Literal("block"),
-        outcomes: Schema.optional(Schema.NonEmptyArray(HookBlockOutcomeSchema).pipe(Schema.check(Schema.isUnique()))),
+        ...ConfigurationFields,
+        type: Schema.Literal("string"),
+        default: Schema.optional(Schema.String),
+        secret: Schema.optional(Schema.Boolean),
+        allowEmpty: Schema.optional(Schema.Boolean),
+        minLength: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+        maxLength: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
     }),
     Schema.Struct({
-        kind: Schema.Literal("modify"),
-        operations: Schema.optional(Schema.NonEmptyArray(HookModifyOperationSchema).pipe(Schema.check(Schema.isUnique()))),
+        ...ConfigurationFields,
+        type: Schema.Literal("number"),
+        default: Schema.optional(Schema.Finite),
+        minimum: Schema.optional(Schema.Finite),
+        maximum: Schema.optional(Schema.Finite),
     }),
-]).annotate({
-    identifier: "HookDecisionRequirement",
-    title: "Hook Decision Requirement",
-    description: "Decision capability a hook binding requires from the target agent event.",
-});
-export const HookBindingTargetSchema = Schema.Struct({
-    matcherRaw: Schema.optional(Schema.NonEmptyString),
+    Schema.Struct({
+        ...ConfigurationFields,
+        type: Schema.Literal("boolean"),
+        default: Schema.optional(Schema.Boolean),
+    }),
+    Schema.Struct({
+        ...ConfigurationFields,
+        type: Schema.Literal("enum"),
+        values: Schema.NonEmptyArray(Schema.NonEmptyString).check(Schema.isUnique()),
+        default: Schema.optional(Schema.NonEmptyString),
+    }),
+]).annotate({ identifier: "HookConfigurationField" });
+export const HookBindingRequirementsSchema = Schema.Struct({
+    outcomes: Schema.optional(Schema.NonEmptyArray(HookBlockOutcomeSchema).check(Schema.isUnique())),
+    operations: Schema.optional(Schema.NonEmptyArray(HookModifyOperationSchema).check(Schema.isUnique())),
 }).annotate({
-    identifier: "HookBindingTarget",
-    title: "Hook Binding Target",
-    description: "Target-agent-specific hook binding escape hatches.",
+    identifier: "HookBindingRequirements",
+    description: "Every declared outcome and operation must be supported by this native event. Omit for observation only.",
+});
+export const HookCommandHandlerSchema = Schema.Struct({
+    type: Schema.Literal("command"),
+    name: Schema.optional(Schema.NonEmptyString),
+    runtime: HookRuntimeSchema,
+    entrypoint: HookPackagePathSchema,
+    args: Schema.optional(Schema.Array(HookValueSchema)),
+    env: Schema.optional(Schema.Record(EnvironmentKeySchema, HookValueSchema)),
+    timeoutMs: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+}).annotate({ identifier: "HookCommandHandler" });
+export const HookEventSchema = Schema.NonEmptyString.check(Schema.isPattern(/^[a-zA-Z][a-zA-Z0-9_.:-]*$/)).annotate({
+    identifier: "HookEvent",
+    description: "Exact event name in the implementation's native host protocol.",
 });
-export const CanonicalHookBindingSchema = Schema.Struct({
-    on: HookEventSchema,
-    match: Schema.optional(HookMatchSchema),
-    matcherRaw: Schema.optional(Schema.NonEmptyString),
-    targets: Schema.optional(Schema.Record(Schema.String, HookBindingTargetSchema)),
+export const HookBindingSchema = Schema.Struct({
+    id: HookIdSchema,
+    event: HookEventSchema,
+    matcher: Schema.optional(Schema.NonEmptyString),
+    handler: HookCommandHandlerSchema,
+    requires: Schema.optional(HookBindingRequirementsSchema),
+}).annotate({ identifier: "HookBinding" });
+export const HookImplementationSchema = Schema.Struct({
+    id: HookIdSchema,
+    protocol: ConfigurableAgentIdSchema,
     requires: Schema.optional(Schema.Struct({
-        decision: HookDecisionRequirementSchema,
+        hostVersion: Schema.optional(VersionRangeSchema),
+        profiles: Schema.optional(Schema.NonEmptyArray(Schema.NonEmptyString).check(Schema.isUnique())),
+        platforms: Schema.optional(Schema.NonEmptyArray(Schema.Literals(["darwin", "linux", "win32"])).check(Schema.isUnique())),
+        scopes: Schema.optional(Schema.NonEmptyArray(Schema.Literals(["project", "user"])).check(Schema.isUnique())),
     })),
+    bindings: Schema.NonEmptyArray(HookBindingSchema),
+}).annotate({ identifier: "HookImplementation" });
+export const HookFixtureSchema = Schema.Struct({
+    id: HookIdSchema,
+    implementation: HookIdSchema,
+    binding: HookIdSchema,
+    input: HookPackagePathSchema,
+    expect: Schema.Struct({
+        exitCode: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 255 })),
+        stdout: Schema.optional(HookPackagePathSchema),
+        stderr: Schema.optional(HookPackagePathSchema),
+    }),
 }).annotate({
-    identifier: "CanonicalHookBinding",
-    title: "Canonical Hook Binding",
-    description: "Universal hook event binding expressed in AXM canonical vocabulary.",
-});
-export const HookBindingSchema = CanonicalHookBindingSchema.annotate({
-    identifier: "HookBinding",
-    title: "Hook Binding",
-    description: "Universal hook event binding with portable canonical matching and raw native escape hatches.",
-});
-export const HookCapabilitiesSchema = Schema.Struct({
-    network: Schema.optional(Schema.Boolean),
-    filesystemWrite: Schema.optional(Schema.Boolean),
-    exec: Schema.optional(Schema.Array(Schema.NonEmptyString)),
-    env: Schema.optional(Schema.Array(Schema.NonEmptyString)),
-}).annotate({
-    identifier: "HookCapabilities",
-    title: "Hook Capabilities",
-    description: "Advisory author-declared hook capability surface. v1 does not enforce it.",
+    identifier: "HookFixture",
+    description: "Native stdin and expected output files used only by explicitly requested fixture execution.",
 });
-/**
- * Schema for hook manifest files (hook.json).
- *
- * Hooks distribute an executable body plus agent event bindings. Install
- * materializes the body under agent_extensions and registers native agent hook
- * settings that invoke the materialized entrypoint.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export const HookManifestSchema = Schema.Struct({
+const HookManifestStruct = Schema.Struct({
     $schema: Schema.optional(Schema.String),
     ...CommonManifestBaseFields,
-    ...NonPackManifestFields,
+    enhances: NonPackManifestFields.enhances,
+    requires: NonPackManifestFields.requires,
+    recommendedPacks: NonPackManifestFields.recommendedPacks,
+    standalone: NonPackManifestFields.standalone,
     type: Schema.Literal("hook"),
-    name: ExtensionNameSchema.pipe(Schema.annotateKey({ messageMissingKey: "hook name is required" }), Schema.annotate({
-        description: "Short name for this hook within its owner namespace. Combined with owner, forms the FQN @owner/hooks/<name>.",
-    })),
-    title: Schema.optional(Schema.NonEmptyString.annotate({
-        description: "Optional display title for this hook.",
-    })),
-    runtime: HookRuntimeSchema.pipe(Schema.annotateKey({ messageMissingKey: "runtime is required" })),
-    entrypoint: Schema.NonEmptyString.pipe(Schema.annotateKey({ messageMissingKey: "entrypoint is required" }), Schema.annotate({
-        description: "Hook body entrypoint path, relative to the hook manifest directory.",
-        examples: ["src/hook.sh", "src/hook.js", "src/hook.py"],
-    })),
-    bindings: Schema.Array(HookBindingSchema).pipe(Schema.annotateKey({ messageMissingKey: "bindings are required" })),
-    timeoutMs: Schema.optional(Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0)))),
-    capabilities: Schema.optional(HookCapabilitiesSchema),
-}).annotate({
+    name: ExtensionNameSchema,
+    title: Schema.optional(Schema.NonEmptyString),
+    implementations: Schema.NonEmptyArray(HookImplementationSchema),
+    configuration: Schema.optional(Schema.Record(ConfigurationKeySchema, HookConfigurationFieldSchema)),
+    assets: Schema.optional(Schema.Array(HookPackagePathSchema).check(Schema.isUnique())),
+    fixtures: Schema.optional(Schema.Array(HookFixtureSchema)),
+});
+const configurationValueProblem = (field, value) => {
+    if (field.type === "string" && field.secret === true) {
+        return typeof value === "object"
+            ? undefined
+            : "Secret configuration requires a symbolic environment reference.";
+    }
+    if (typeof value === "object")
+        return "Environment references are only accepted by secret string configuration.";
+    switch (field.type) {
+        case "string":
+            if (typeof value !== "string")
+                return "Expected a string.";
+            if (value.length === 0 && field.allowEmpty !== true)
+                return "An empty string is not allowed.";
+            if (field.minLength !== undefined && value.length < field.minLength)
+                return "String is shorter than minLength.";
+            if (field.maxLength !== undefined && value.length > field.maxLength)
+                return "String is longer than maxLength.";
+            return undefined;
+        case "boolean":
+            return typeof value === "boolean" ? undefined : "Expected a boolean.";
+        case "number":
+            if (typeof value !== "number" || !Number.isFinite(value))
+                return "Expected a finite number.";
+            if (field.minimum !== undefined && value < field.minimum)
+                return "Number is below minimum.";
+            if (field.maximum !== undefined && value > field.maximum)
+                return "Number exceeds maximum.";
+            return undefined;
+        case "enum":
+            return typeof value === "string" && field.values.includes(value)
+                ? undefined
+                : "Expected a declared enum value.";
+    }
+};
+export const HookManifestSchema = HookManifestStruct.check(Schema.makeFilter((manifest) => {
+    const issues = [];
+    const implementationIds = new Set();
+    for (const [index, implementation] of manifest.implementations.entries()) {
+        if (implementationIds.has(implementation.id))
+            issues.push({
+                path: ["implementations", index, "id"],
+                issue: "Implementation IDs must be unique.",
+            });
+        implementationIds.add(implementation.id);
+        const bindingIds = new Set();
+        for (const [bindingIndex, binding] of implementation.bindings.entries()) {
+            if (bindingIds.has(binding.id))
+                issues.push({
+                    path: ["implementations", index, "bindings", bindingIndex, "id"],
+                    issue: "Binding IDs must be unique within an implementation.",
+                });
+            bindingIds.add(binding.id);
+            for (const value of [
+                ...(binding.handler.args ?? []),
+                ...Object.values(binding.handler.env ?? {}),
+            ]) {
+                if (typeof value === "object" &&
+                    "config" in value &&
+                    !Object.hasOwn(manifest.configuration ?? {}, value.config)) {
+                    issues.push({
+                        path: ["implementations", index, "bindings", bindingIndex, "handler"],
+                        issue: `Unknown configuration reference: ${value.config}.`,
+                    });
+                }
+            }
+        }
+    }
+    for (const [key, field] of Object.entries(manifest.configuration ?? {})) {
+        if (field.default !== undefined) {
+            const problem = configurationValueProblem(field, field.default);
+            if (problem !== undefined)
+                issues.push({ path: ["configuration", key, "default"], issue: problem });
+        }
+        if (field.type === "string" &&
+            field.minLength !== undefined &&
+            field.maxLength !== undefined &&
+            field.minLength > field.maxLength)
+            issues.push({
+                path: ["configuration", key],
+                issue: "minLength must not exceed maxLength.",
+            });
+        if (field.type === "number" &&
+            field.minimum !== undefined &&
+            field.maximum !== undefined &&
+            field.minimum > field.maximum)
+            issues.push({ path: ["configuration", key], issue: "minimum must not exceed maximum." });
+    }
+    const fixtureIds = new Set();
+    for (const [index, fixture] of (manifest.fixtures ?? []).entries()) {
+        if (fixtureIds.has(fixture.id))
+            issues.push({ path: ["fixtures", index, "id"], issue: "Fixture IDs must be unique." });
+        fixtureIds.add(fixture.id);
+        const implementation = manifest.implementations.find((entry) => entry.id === fixture.implementation);
+        if (implementation === undefined ||
+            !implementation.bindings.some((entry) => entry.id === fixture.binding))
+            issues.push({
+                path: ["fixtures", index],
+                issue: "Fixture must reference an existing implementation and binding.",
+            });
+    }
+    return issues;
+})).annotate({
     identifier: "HookManifest",
     title: "Hook Manifest",
-    description: "Hook manifest for managed agent hooks. The executable body lives under src/ and is invoked from native agent settings.",
+    description: "A package of explicit native Hook implementations, shared assets, typed consumer configuration, and optional native protocol fixtures. AXM installs native settings; it does not translate payloads or execute hook bodies during lifecycle operations.",
 });
+/** Files required to install and activate any declared implementation. */
+export const requiredHookRuntimeFiles = (manifest) => [
+    ...new Set([
+        ...(manifest.assets ?? []),
+        ...manifest.implementations.flatMap((implementation) => implementation.bindings.map((binding) => binding.handler.entrypoint)),
+    ]),
+];
+/** Source-authoring closure; fixtures may be omitted from a distributed package. */
+export const referencedHookPackageFiles = (manifest) => [
+    ...new Set([
+        ...requiredHookRuntimeFiles(manifest),
+        ...(manifest.fixtures ?? []).flatMap((fixture) => [
+            fixture.input,
+            ...(fixture.expect.stdout === undefined ? [] : [fixture.expect.stdout]),
+            ...(fixture.expect.stderr === undefined ? [] : [fixture.expect.stderr]),
+        ]),
+    ]),
+];
+/** Explicit consumer values override author defaults; no source objects are mutated. */
+export const resolveHookConfiguration = (manifest, values = {}) => {
+    const fields = manifest.configuration ?? {};
+    const issues = [];
+    const resolved = {};
+    for (const key of Object.keys(values))
+        if (!Object.hasOwn(fields, key))
+            issues.push({ key, code: "unknown", message: "Unknown hook configuration key." });
+    for (const [key, field] of Object.entries(fields)) {
+        const input = Object.hasOwn(values, key) ? values[key] : field.default;
+        if (input === undefined) {
+            if (field.required === true)
+                issues.push({ key, code: "missing", message: "Required hook configuration is missing." });
+            continue;
+        }
+        const decoded = Schema.decodeUnknownResult(HookConfigurationValueSchema)(input, {
+            onExcessProperty: "error",
+        });
+        if (Result.isFailure(decoded)) {
+            issues.push({
+                key,
+                code: "invalid",
+                message: "Expected a scalar value or symbolic environment reference.",
+            });
+            continue;
+        }
+        const problem = configurationValueProblem(field, decoded.success);
+        if (problem !== undefined)
+            issues.push({ key, code: "invalid", message: problem });
+        else
+            resolved[key] = decoded.success;
+    }
+    return issues.length > 0 ? Result.fail(issues) : Result.succeed(resolved);
+};
 //# sourceMappingURL=manifest-schema.js.map

package/dist/src/unstable/hooks/resolution.d.ts

@@ -0,0 +1,24 @@
+import type { ConfigurableAgentId } from "../agent-capabilities/identity.js";
+import type { WorkspaceScope } from "../workspace-scope.js";
+import type { HookManifest, HookImplementation } from "./manifest-schema.js";
+export interface HookImplementationContext {
+    readonly scope: WorkspaceScope;
+    readonly platform?: string;
+    readonly hostVersion?: string;
+    readonly profile?: string;
+    readonly availableRuntimes?: ReadonlyArray<"bash" | "node" | "python">;
+}
+export type HookImplementationResolution = {
+    readonly status: "selected" | "conditional";
+    readonly implementation: HookImplementation;
+    readonly conditions: ReadonlyArray<string>;
+} | {
+    readonly status: "unsupported";
+    readonly reasons: ReadonlyArray<string>;
+} | {
+    readonly status: "ambiguous";
+    readonly implementationIds: ReadonlyArray<string>;
+};
+/** Select declared implementations without treating unknown host facts as verified support. */
+export declare const resolveHookImplementation: (manifest: HookManifest, agentId: ConfigurableAgentId, context: HookImplementationContext) => HookImplementationResolution;
+//# sourceMappingURL=resolution.d.ts.map

package/dist/src/unstable/hooks/resolution.js

@@ -0,0 +1,99 @@
+/** Exact native Hook realization selection, shared by projection and discovery. @experimental */
+import * as semver from "semver";
+import { installable } from "../agent-capabilities/derive.js";
+import { agentById } from "../agent-capabilities/lookup.js";
+/** Select declared implementations without treating unknown host facts as verified support. */
+export const resolveHookImplementation = (manifest, agentId, context) => {
+    // Native command serialization currently uses POSIX shell quoting and expansion.
+    if (context.platform !== undefined &&
+        context.platform !== "linux" &&
+        context.platform !== "darwin")
+        return {
+            status: "unsupported",
+            reasons: [
+                `Native Hook command serialization is unavailable on ${context.platform}; supported platforms are linux and darwin.`,
+            ],
+        };
+    const agent = agentById(agentId);
+    const hook = agent.capabilities.hook;
+    const writer = hook.axm.writer;
+    if (writer === null ||
+        !("locations" in hook.native) ||
+        !hook.native.locations.some((location) => location.scope === context.scope && writer.locationIds.includes(location.id)))
+        return {
+            status: "unsupported",
+            reasons: [`No native Hook writer supports ${agentId} at ${context.scope} scope.`],
+        };
+    const candidates = [];
+    const reasons = [];
+    for (const implementation of manifest.implementations) {
+        if (implementation.protocol !== agentId)
+            continue;
+        const failures = implementation.bindings
+            .map((binding) => installable(agent, binding))
+            .filter((verdict) => !verdict.installable);
+        if (failures.length > 0) {
+            reasons.push(...failures.map((failure) => `${implementation.id}: ${failure.reason}`));
+            continue;
+        }
+        const required = implementation.requires;
+        if (required?.scopes !== undefined && !required.scopes.includes(context.scope)) {
+            reasons.push(`${implementation.id} does not support ${context.scope} scope.`);
+            continue;
+        }
+        const conditions = context.platform === undefined
+            ? ["Platform must support the native POSIX command serializer (linux or darwin)."]
+            : [];
+        let excluded = false;
+        const runtimes = [
+            ...new Set(implementation.bindings.map((binding) => binding.handler.runtime)),
+        ];
+        if (context.availableRuntimes === undefined)
+            conditions.push(`Native host environment must provide: ${runtimes.map((runtime) => (runtime === "python" ? "python3" : runtime)).join(", ")}; availability is unverified.`);
+        else if (runtimes.some((runtime) => !context.availableRuntimes?.includes(runtime))) {
+            reasons.push(`${implementation.id} requires unavailable runtimes: ${runtimes.filter((runtime) => !context.availableRuntimes?.includes(runtime)).join(", ")}.`);
+            excluded = true;
+        }
+        if (required?.platforms !== undefined) {
+            if (context.platform === undefined)
+                conditions.push(`Platform must be one of: ${required.platforms.join(", ")}.`);
+            else if (!required.platforms.some((platform) => platform === context.platform)) {
+                reasons.push(`${implementation.id} does not support ${context.platform}.`);
+                excluded = true;
+            }
+        }
+        if (required?.profiles !== undefined) {
+            if (context.profile === undefined)
+                conditions.push(`Host profile must be one of: ${required.profiles.join(", ")}.`);
+            else if (!required.profiles.includes(context.profile)) {
+                reasons.push(`${implementation.id} does not support profile ${context.profile}.`);
+                excluded = true;
+            }
+        }
+        if (required?.hostVersion !== undefined) {
+            if (context.hostVersion === undefined)
+                conditions.push(`Host version must satisfy ${required.hostVersion}.`);
+            else if (!semver.satisfies(context.hostVersion, required.hostVersion)) {
+                reasons.push(`${implementation.id} requires host version ${required.hostVersion}.`);
+                excluded = true;
+            }
+        }
+        if (!excluded)
+            candidates.push({ implementation, conditions });
+    }
+    if (candidates.length > 1)
+        return {
+            status: "ambiguous",
+            implementationIds: candidates.map(({ implementation }) => implementation.id),
+        };
+    const candidate = candidates[0];
+    if (candidate === undefined)
+        return {
+            status: "unsupported",
+            reasons: reasons.length > 0
+                ? reasons
+                : [`No implementation declares the ${agentId} native protocol.`],
+        };
+    return { status: candidate.conditions.length === 0 ? "selected" : "conditional", ...candidate };
+};
+//# sourceMappingURL=resolution.js.map

package/dist/src/unstable/sources/http-artifact.d.ts

@@ -0,0 +1,24 @@
+import * as Schema from "effect/Schema";
+/** Digest of the exact downloaded artifact bytes, independent of the unpacked tree. */
+export declare const ArtifactDigestSchema: Schema.brand<Schema.String, "ArtifactDigest">;
+export type ArtifactDigest = typeof ArtifactDigestSchema.Type;
+/** A relative file in a downloaded package, never a filesystem escape. */
+export declare const ArtifactPathSchema: Schema.NonEmptyString;
+export declare const ArtifactUrlSchema: Schema.URLFromString;
+/** Accepted download inputs; replay verifies each exact artifact without re-reading discovery. */
+export declare const HttpArtifactSnapshotSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly format: Schema.Literals<readonly ["skill-md", "zip", "tar", "tar.gz"]>;
+    readonly url: Schema.URLFromString;
+    readonly digest: Schema.brand<Schema.String, "ArtifactDigest">;
+}>, Schema.Struct<{
+    readonly format: Schema.Literal<"files">;
+    readonly files: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly url: Schema.URLFromString;
+        readonly digest: Schema.brand<Schema.String, "ArtifactDigest">;
+    }>>;
+}>]>;
+export type HttpArtifactSnapshot = typeof HttpArtifactSnapshotSchema.Type;
+/** Recognizable public artifact and discovery locations, leaving clone URLs to Git. */
+export declare const httpSourceKind: (url: URL) => "skill-md" | "archive" | "index" | undefined;
+//# sourceMappingURL=http-artifact.d.ts.map

package/dist/src/unstable/sources/http-artifact.js

@@ -0,0 +1,46 @@
+import * as Schema from "effect/Schema";
+/** Digest of the exact downloaded artifact bytes, independent of the unpacked tree. */
+export const ArtifactDigestSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((value) => /^sha256:[0-9a-f]{64}$/u.test(value)
+    ? undefined
+    : "Expected SHA-256 artifact digest in sha256:<hex> form")), Schema.brand("ArtifactDigest"));
+/** A relative file in a downloaded package, never a filesystem escape. */
+export const ArtifactPathSchema = Schema.NonEmptyString.pipe(Schema.check(Schema.makeFilter((value) => value.includes("\\") ||
+    value.includes("\0") ||
+    value.startsWith("/") ||
+    /^[A-Za-z]:/u.test(value) ||
+    value.split("/").some((part) => part === ".." || part === "." || part.length === 0)
+    ? "Expected a contained artifact file path"
+    : undefined)));
+export const ArtifactUrlSchema = Schema.URLFromString.pipe(Schema.check(Schema.makeFilter((url) => url.protocol === "https:" && url.username === "" && url.password === ""
+    ? undefined
+    : "Expected a credential-free HTTPS artifact URL")));
+/** Accepted download inputs; replay verifies each exact artifact without re-reading discovery. */
+export const HttpArtifactSnapshotSchema = Schema.Union([
+    Schema.Struct({
+        format: Schema.Literals(["skill-md", "zip", "tar", "tar.gz"]),
+        url: ArtifactUrlSchema,
+        digest: ArtifactDigestSchema,
+    }),
+    Schema.Struct({
+        format: Schema.Literal("files"),
+        files: Schema.Array(Schema.Struct({
+            path: ArtifactPathSchema,
+            url: ArtifactUrlSchema,
+            digest: ArtifactDigestSchema,
+        })).pipe(Schema.check(Schema.isMinLength(1))),
+    }),
+]);
+/** Recognizable public artifact and discovery locations, leaving clone URLs to Git. */
+export const httpSourceKind = (url) => {
+    if (url.protocol !== "https:")
+        return undefined;
+    if (url.pathname.endsWith("/SKILL.md"))
+        return "skill-md";
+    if (/\.(zip|tar|tar\.gz|tgz)$/iu.test(url.pathname))
+        return "archive";
+    if (url.pathname === "/" ||
+        /^\/\.well-known\/(agent-skills|skills)(?:\/index\.json|\/?)$/u.test(url.pathname))
+        return "index";
+    return undefined;
+};
+//# sourceMappingURL=http-artifact.js.map

package/dist/src/unstable/sources/printer.js

@@ -21,6 +21,12 @@ const printLocalSource = (source) => {
  */
 export const printSourceParams = (source) => {
     switch (source.type) {
+        case "http": {
+            const url = new URL(source.url.href);
+            if (source.entry !== undefined)
+                url.hash = `skill=${encodeURIComponent(source.entry)}`;
+            return url.href;
+        }
         case "local":
             return printLocalSource(source);
         case "git": {
@@ -28,7 +34,14 @@ export const printSourceParams = (source) => {
                 onSome: printForgeCoordinate,
                 onNone: () => {
                     const url = new URL(source.url.href);
-                    url.hash = Option.getOrElse(source.ref, () => "");
+                    if (Option.isSome(source.subPath)) {
+                        const selector = new URLSearchParams({ path: source.subPath.value });
+                        if (Option.isSome(source.ref))
+                            selector.set("ref", source.ref.value);
+                        url.hash = `axm:${selector.toString()}`;
+                    }
+                    else
+                        url.hash = Option.getOrElse(source.ref, () => "");
                     return url.href;
                 },
             });

package/dist/src/unstable/sources/source-host-provider.d.ts

@@ -142,6 +142,9 @@ export interface NamedRegistryCandidate {
 export interface ExtensionFiles {
     /** Absolute path to directory containing extension files. */
     readonly directory: string;
+    /** Complete package context for a selected component. */
+    readonly packageDirectory?: string;
+    readonly componentPath?: string;
 }
 /**
  * Source host provider that unifies how all source types are accessed.