@agentxm/extension-authoring 0.28.12 → 0.28.13

package/dist/src/create/scaffolds/subagent.js

@@ -0,0 +1,47 @@
+/**
+ * The starter content a new subagent is created with.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { decodeExtensionNameSync } from "@agentxm/extension-model/unstable/extensions";
+import { MANIFEST_FILENAME, MANIFEST_SCHEMA_URL, } from "@agentxm/extension-model/unstable/subagents/manifest-schema";
+import { decodeVersionSync } from "@agentxm/extension-model/unstable/version-constraints";
+import { manifestText, stageFileAt } from "./scaffold.js";
+const INITIAL_VERSION = decodeVersionSync("0.0.1");
+const subagentBody = (name) => [
+    "---",
+    `name: ${name}`,
+    "---",
+    "",
+    "Describe what this subagent does and when to delegate work to it.\n",
+].join("\n");
+export const subagentScaffold = (args) => {
+    const body = `src/${args.name}.md`;
+    const manifest = {
+        $schema: MANIFEST_SCHEMA_URL,
+        owner: args.owner,
+        type: "subagent",
+        name: decodeExtensionNameSync(args.name),
+        version: INITIAL_VERSION,
+    };
+    return {
+        subject: "Subagent",
+        version: INITIAL_VERSION,
+        contentFiles: [MANIFEST_FILENAME, body],
+        entryFile: body,
+        populate: (stagingPath) => Effect.gen(function* () {
+            const path = yield* Path.Path;
+            yield* stageFileAt({
+                path: path.join(stagingPath, MANIFEST_FILENAME),
+                contents: manifestText(manifest),
+            });
+            yield* stageFileAt({
+                path: path.join(stagingPath, "src", `${args.name}.md`),
+                contents: subagentBody(args.name),
+            });
+        }),
+    };
+};
+//# sourceMappingURL=subagent.js.map

package/dist/src/create-preflight.d.ts

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
-import { CreateDestinationExists, CreateDestinationInspectionFailed, CreateNameConfigured } from "@agentxm/extension-workspace";
+import { CreateDestinationInspectionFailed, CreateNameConfigured } from "./authored-package-errors.js";
+import { CreateDestinationExists } from "@agentxm/extension-materialization";
 export interface CreateOnlyPreflightArgs {
     readonly subject: string;
     readonly name: string;
@@ -8,5 +9,5 @@ export interface CreateOnlyPreflightArgs {
     readonly destinations: ReadonlyArray<string>;
 }
 /** Refuse every declared identity/path collision before a create operation mutates the workspace. */
-export declare const preflightCreateOnly: (args: CreateOnlyPreflightArgs) => Effect.Effect<undefined, CreateNameConfigured | CreateDestinationExists | CreateDestinationInspectionFailed, FileSystem.FileSystem>;
+export declare const preflightCreateOnly: (args: CreateOnlyPreflightArgs) => Effect.Effect<undefined, CreateNameConfigured | CreateDestinationInspectionFailed | CreateDestinationExists, FileSystem.FileSystem>;
 //# sourceMappingURL=create-preflight.d.ts.map

package/dist/src/create-preflight.js

@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
-import { CreateDestinationExists, CreateDestinationInspectionFailed, CreateNameConfigured, } from "@agentxm/extension-workspace";
+import { CreateDestinationInspectionFailed, CreateNameConfigured, } from "./authored-package-errors.js";
+import { CreateDestinationExists } from "@agentxm/extension-materialization";
 /** Refuse every declared identity/path collision before a create operation mutates the workspace. */
 export const preflightCreateOnly = Effect.fn("Extensions.preflightCreateOnly")(function* (args) {
     if (args.configured) {

package/dist/src/errors.d.ts

@@ -7,7 +7,7 @@
  */
 import * as Schema from "effect/Schema";
 declare const AuthoringFailed_base: Schema.Class<AuthoringFailed, Schema.TaggedStruct<"AuthoringFailed", {
-    readonly category: Schema.Literals<readonly ["conflict", "internal", "not_found", "validation"]>;
+    readonly category: Schema.Literals<readonly ["conflict", "internal", "not_found", "usage", "validation"]>;
     readonly detail: Schema.String;
     readonly recover: Schema.optional<Schema.String>;
     readonly suggestions: Schema.optional<Schema.$Array<Schema.Struct<{

package/dist/src/errors.js

@@ -18,7 +18,7 @@ const CarriedSuggestedActionSchema = Schema.Struct({
  * `suggestions`, and `cause` carry over verbatim.
  */
 export class AuthoringFailed extends Schema.TaggedError()("AuthoringFailed", {
-    category: Schema.Literals(["conflict", "internal", "not_found", "validation"]),
+    category: Schema.Literals(["conflict", "internal", "not_found", "usage", "validation"]),
     detail: Schema.String,
     recover: Schema.optional(Schema.String),
     suggestions: Schema.optional(Schema.Array(CarriedSuggestedActionSchema)),

package/dist/src/fork/fork-extension.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Forking a managed AXM package into workspace authorship.
+ *
+ * A fork reads one package out of a source the person named, rewrites its
+ * identity to the target the workspace will author, and publishes it as a new
+ * canonical package. The source is never touched, and the fork starts at its
+ * own initial version rather than inheriting the original's.
+ *
+ * `prepare` settles every decision and stages the rewritten package into a
+ * scoped temporary directory: which package the source resolves to, whether
+ * the target identity is one this workspace may author, whether the
+ * destination is free, and what activation the fork carries. Nothing under
+ * the workspace is written. `previewOrApply` resolves the frozen candidate, so
+ * a preview and an apply describe one decision — and the staged content is
+ * re-hashed before publication, so content that changed between the two
+ * refuses rather than lands.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type * as Scope from "effect/Scope";
+import { ExtensionManagers, McpSecretStore, type ManagerRequirements, type RecipeRequirements } from "@agentxm/extension-materialization";
+import { type ExtensionType, type FqnInvalidError, type Handle } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHostProviders, WorkspaceCatalog, type SourceResolutionFailure } from "@agentxm/extension-sources";
+import { type CandidateFingerprintFailed, type ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import type { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, type ConfiguredAgentOutcomesProvider, type LockfileValidationError, type PackageContentHashFailed, type WorkspaceLockfileReadFailure, type WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import { AuthoringFailed } from "../errors.js";
+import type { AuthoredPackageError } from "../authored-package-errors.js";
+import type { FrontmatterParseFailure } from "@agentxm/extension-content";
+import { AuthoringScopeUnsupported, type AuthoringOwnerMismatch, type AuthoringOwnerRequired } from "../create/errors.js";
+export interface ForkExtensionRequest {
+    /** Registry, workspace, local, or Git AXM package source, as typed. */
+    readonly source: string;
+    /** Owner-qualified identity the fork will carry. */
+    readonly target: string;
+    /** Source package identity, when the source holds more than one package. */
+    readonly from: Option.Option<string>;
+    /** Materialize the fork immediately instead of leaving it declared and inert. */
+    readonly enable: boolean;
+    /**
+     * Whether the invoking surface can prompt for a connection input an MCP
+     * server's manifest requires.
+     */
+    readonly nonInteractive: boolean;
+}
+/** What every step in a fork may require when it runs. */
+export type ForkExtensionRequirements = ManagerRequirements | RecipeRequirements | WorkspaceMutations | CodingAgentRepository | McpSecretStore;
+/** A settled fork: every decision is made and nothing under the workspace is written. */
+export interface ForkExtensionCandidate {
+    readonly type: ExtensionType;
+    /** Owner-qualified identity of the fork. */
+    readonly fqn: string;
+    readonly owner: Handle;
+    readonly name: string;
+    /** Owner-qualified identity of the package the fork was taken from. */
+    readonly sourceFqn: string;
+    /** Where the source package was found, in operator-facing terms. */
+    readonly origin: string;
+    /** Workspace-relative directory the fork will occupy. */
+    readonly authoredPath: string;
+    /** Workspace-relative settings file the declaration is written to. */
+    readonly settingsPath: string;
+    /** Whether the fork is materialized once it is declared. */
+    readonly enabled: boolean;
+    readonly execution: ExecutionCandidate<ForkExtensionRequirements>;
+}
+/** Every failure settling a fork can surface before anything is written. */
+export type ForkExtensionFailure = AuthoringFailed | AuthoredPackageError | FrontmatterParseFailure | AuthoringOwnerRequired | AuthoringOwnerMismatch | AuthoringScopeUnsupported | SourceResolutionFailure | PackageContentHashFailed | LockfileValidationError | WorkspaceLockfileReadFailure | WorkspaceSettingsReadFailure | CandidateFingerprintFailed | FqnInvalidError;
+/** Everything settling a fork reads before it freezes a candidate. */
+export type PrepareForkExtensionRequirements = FileSystem.FileSystem | Path.Path | Scope.Scope | HttpClient.HttpClient | WorkspaceMutations | ExtensionManagers | SourceHostProviders | WorkspaceCatalog | ConfiguredAgentOutcomesProvider;
+/** The plan a fork resolves; it names the operation everywhere the fork is reported. */
+export declare const forkExtensionPlanName = "Fork AXM extension package";
+/** Settle a fork and stage its content without writing anything to the workspace. */
+export declare const prepareForkExtension: (request: ForkExtensionRequest) => Effect.Effect<ForkExtensionCandidate, ForkExtensionFailure, PrepareForkExtensionRequirements>;
+/** Preview or apply a settled fork, resolving to one operation outcome. */
+export declare const previewOrApplyForkExtension: (candidate: ForkExtensionCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | ForkExtensionRequirements>;
+/** The fork use case: settle a request, then preview or apply it. */
+export declare const ForkExtension: {
+    readonly prepare: (request: ForkExtensionRequest) => Effect.Effect<ForkExtensionCandidate, ForkExtensionFailure, PrepareForkExtensionRequirements>;
+    readonly previewOrApply: (candidate: ForkExtensionCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | ForkExtensionRequirements>;
+};
+//# sourceMappingURL=fork-extension.d.ts.map

package/dist/src/fork/fork-extension.js

@@ -0,0 +1,253 @@
+/**
+ * Forking a managed AXM package into workspace authorship.
+ *
+ * A fork reads one package out of a source the person named, rewrites its
+ * identity to the target the workspace will author, and publishes it as a new
+ * canonical package. The source is never touched, and the fork starts at its
+ * own initial version rather than inheriting the original's.
+ *
+ * `prepare` settles every decision and stages the rewritten package into a
+ * scoped temporary directory: which package the source resolves to, whether
+ * the target identity is one this workspace may author, whether the
+ * destination is free, and what activation the fork carries. Nothing under
+ * the workspace is written. `previewOrApply` resolves the frozen candidate, so
+ * a preview and an apply describe one decision — and the staged content is
+ * re-hashed before publication, so content that changed between the two
+ * refuses rather than lands.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import { ExtensionManagers, McpSecretStore, buildAuthoredExtensionStep, copyExtensionDirectory, createCanonicalDirectory, materializeAuthoredMcpServer, recoverCanonicalDirectory, } from "@agentxm/extension-materialization";
+import { extensionTypeFromPlural, extensionTypeToPlural, formatFqn, parseFqn, parseSourceQualifiedRegistrySourcePatternParts, } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHostProviders, WorkspaceCatalog, findExtensionPackagesFromSource, inspectExtensionPackage, resolveSource, } from "@agentxm/extension-sources";
+import { operationPresentation, prepareExecutionCandidate, resolveExecutionCandidate, } from "@agentxm/workspace-operations";
+import { WorkspaceMutations, computePackageContentHash, } from "@agentxm/workspace-state";
+import { authoredDeclaration } from "../authored-declaration.js";
+import { preflightCreateOnly } from "../create-preflight.js";
+import { AuthoringFailed } from "../errors.js";
+import { authoringStepFailure } from "../step-failure.js";
+import { requireAuthoredOwner, settingsRelativePath } from "../create/authoring-owner.js";
+import { AuthoringScopeUnsupported, } from "../create/errors.js";
+import { forkExtensionPackage } from "../fork-package.js";
+/** The version a fork starts at, regardless of what the source published. */
+const INITIAL_FORK_VERSION = "0.1.0";
+// -----------------------------------------------------------------------------
+// Source selection
+// -----------------------------------------------------------------------------
+const exactFilter = (fqn) => ({
+    names: [fqn.name],
+    owner: Option.some(fqn.owner),
+    type: fqn.type,
+});
+/**
+ * Which packages in the named source the fork will consider.
+ *
+ * An explicit `--from` identity is decisive. Otherwise a source that already
+ * names an owner, type, and name in its own syntax narrows to that package,
+ * and anything else considers every package the source holds — which is what
+ * makes "the source contains more than one" an answerable ambiguity rather
+ * than a silent first-match.
+ */
+const filterForSource = (source, from) => {
+    if (Option.isSome(from)) {
+        return Effect.fromResult(parseFqn(from.value)).pipe(Effect.map(exactFilter));
+    }
+    const registry = parseSourceQualifiedRegistrySourcePatternParts(source);
+    if (registry?.type !== undefined && registry.name !== undefined) {
+        return Effect.succeed({
+            names: [registry.name],
+            owner: Option.some(registry.owner),
+            type: extensionTypeFromPlural[registry.type],
+        });
+    }
+    return Effect.succeed({ names: [], owner: Option.none(), type: "*" });
+};
+const selectPackage = (packages) => {
+    const candidate = packages[0];
+    if (candidate === undefined) {
+        return Effect.fail(new AuthoringFailed({
+            category: "not_found",
+            detail: "No managed AXM extension package was found; use skills import or subagents import for supported unmanaged/native content",
+        }));
+    }
+    if (packages.length > 1) {
+        return Effect.fail(new AuthoringFailed({
+            category: "validation",
+            detail: "The source contains multiple AXM packages; select one with --from <FQN>",
+        }));
+    }
+    return Effect.succeed(candidate);
+};
+/**
+ * Build the fork's publication step with the requirements this use case keeps
+ * in `R`, so the workspace facade and the credential store stay requirements
+ * rather than captured values.
+ */
+const forkStep = (manager, args) => buildAuthoredExtensionStep(manager, args);
+/** The plan a fork resolves; it names the operation everywhere the fork is reported. */
+export const forkExtensionPlanName = "Fork AXM extension package";
+// -----------------------------------------------------------------------------
+// prepare
+// -----------------------------------------------------------------------------
+/** Settle a fork and stage its content without writing anything to the workspace. */
+export const prepareForkExtension = Effect.fn("ForkExtension.prepare")(function* (request) {
+    const ws = yield* WorkspaceMutations;
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const managers = yield* ExtensionManagers;
+    const providers = yield* SourceHostProviders;
+    const target = yield* Effect.fromResult(parseFqn(request.target));
+    yield* requireAuthoredOwner(target.owner, { subject: "package", command: "fork" });
+    if (ws.layout.scope !== "project") {
+        return yield* new AuthoringScopeUnsupported({ subject: "fork", scope: ws.layout.scope });
+    }
+    const source = yield* resolveSource(request.source);
+    const filter = yield* filterForSource(request.source, request.from);
+    const packages = source.type === "workspace"
+        ? [
+            {
+                ...(yield* inspectExtensionPackage(path.join(ws.layout.authoredRoot(source.extensionType), source.name))),
+                origin: providers.origin(source),
+            },
+        ].filter((candidate) => filter.type !== "*" && filter.type !== candidate.identity.type
+            ? false
+            : filter.names.length > 0 && !filter.names.includes(candidate.identity.name)
+                ? false
+                : Option.isNone(filter.owner) || filter.owner.value === candidate.identity.owner)
+        : yield* findExtensionPackagesFromSource(source, filter);
+    const selected = yield* selectPackage(packages);
+    const name = target.name;
+    const targetDir = path.join(ws.layout.authoredRoot(target.type), name);
+    const authoredPath = path.relative(ws.baseDir, targetDir);
+    const settingsPath = settingsRelativePath(path, ws);
+    const fqn = formatFqn(target);
+    // Refuse an occupied destination here, so a preview refuses it too; the
+    // closure repeats the check under the transaction lock in case the
+    // destination is claimed between preview and apply.
+    const createOnly = preflightCreateOnly({
+        subject: "Fork target",
+        name,
+        configured: false,
+        destinations: [targetDir],
+    });
+    yield* createOnly;
+    const stagingRoot = yield* fs.makeTempDirectoryScoped({ prefix: "axm-fork-" }).pipe(Effect.mapError((cause) => new AuthoringFailed({
+        category: "internal",
+        detail: "Fork staging directory could not be created",
+        cause,
+    })));
+    const stagedPackage = path.join(stagingRoot, "package");
+    yield* forkExtensionPackage({
+        sourceDir: selected.directory,
+        targetDir: stagedPackage,
+        sourceIdentity: selected.identity,
+        target,
+    });
+    const stagedHash = yield* computePackageContentHash(stagedPackage);
+    const declaration = authoredDeclaration(ws, target.type, name);
+    const current = yield* declaration.read;
+    const enabled = request.enable || Option.getOrElse(current.enabled, () => false);
+    const artifact = {
+        path: authoredPath,
+        scope: ws.scope,
+        version: INITIAL_FORK_VERSION,
+        change: "created",
+        targets: [
+            { path: authoredPath, change: "created" },
+            { path: settingsPath, change: "created" },
+        ],
+    };
+    const sourceFqn = `${selected.identity.owner}/${extensionTypeToPlural[selected.identity.type]}/${selected.identity.name}`;
+    const common = {
+        toStepFailure: authoringStepFailure,
+        location: targetDir,
+        versionRange: Option.none(),
+        label: `Fork ${sourceFqn} -> ${fqn}`,
+        message: `Forked ${fqn}`,
+        enabled,
+        allowConfiguredSourceTransition: true,
+        markAuthored: declaration.declare({ enabled: true, env: current.env }),
+        finalizeAuthored: declaration.declare({ enabled, env: current.env }),
+        plannedArtifact: artifact,
+        buildArtifact: () => Effect.succeed(artifact),
+        preflight: Effect.gen(function* () {
+            yield* recoverCanonicalDirectory({ baseDir: ws.baseDir, canonicalPath: targetDir });
+            yield* createOnly;
+        }),
+        scaffold: createCanonicalDirectory({
+            baseDir: ws.baseDir,
+            canonicalPath: targetDir,
+            subject: "Fork target",
+            populate: (publicationPath) => copyExtensionDirectory(stagedPackage, publicationPath).pipe(Effect.mapError((cause) => new AuthoringFailed({
+                category: "internal",
+                detail: `Prepared fork could not be staged for ${authoredPath}`,
+                cause,
+            }))),
+            validate: (publicationPath) => computePackageContentHash(publicationPath).pipe(Effect.flatMap((currentHash) => currentHash === stagedHash
+                ? Effect.void
+                : new AuthoringFailed({
+                    category: "conflict",
+                    detail: "Prepared fork content changed before it could be applied",
+                }))),
+        }).pipe(Effect.asVoid),
+    };
+    const step = (() => {
+        switch (target.type) {
+            case "skill":
+                return forkStep(managers.skill, { ...common, target: { type: "skill", name } });
+            case "subagent":
+                return forkStep(managers.subagent, { ...common, target: { type: "subagent", name } });
+            case "rule":
+                return forkStep(managers.rule, { ...common, target: { type: "rule", name } });
+            case "hook":
+                return forkStep(managers.hook, { ...common, target: { type: "hook", name } });
+            case "knowledge":
+                return forkStep(managers.knowledge, { ...common, target: { type: "knowledge", name } });
+            case "pack":
+                return forkStep(managers.pack, {
+                    ...common,
+                    target: { type: "pack", owner: target.owner, name },
+                });
+            case "mcp-server":
+                return forkStep(managers["mcp-server"], {
+                    ...common,
+                    target: { type: "mcp-server", name },
+                    materializeInstall: (ref) => materializeAuthoredMcpServer({ ref, nonInteractive: request.nonInteractive }),
+                });
+        }
+    })();
+    const plan = {
+        _tag: "Plan",
+        name: forkExtensionPlanName,
+        description: Option.some(`Create ${fqn} from ${selected.origin}; the source remains unchanged and the fork starts ${enabled ? "enabled" : "disabled"}`),
+        presentation: operationPresentation({ imperative: "fork", past: "Forked", gerund: "Forking" }, target.type),
+        jobs: [{ concurrency: 1, steps: [step] }],
+    };
+    return {
+        type: target.type,
+        fqn,
+        owner: target.owner,
+        name,
+        sourceFqn,
+        origin: selected.origin,
+        authoredPath,
+        settingsPath,
+        enabled,
+        execution: yield* prepareExecutionCandidate(plan),
+    };
+});
+// -----------------------------------------------------------------------------
+// previewOrApply
+// -----------------------------------------------------------------------------
+/** Preview or apply a settled fork, resolving to one operation outcome. */
+export const previewOrApplyForkExtension = (candidate, execution) => resolveExecutionCandidate(candidate.execution, execution);
+/** The fork use case: settle a request, then preview or apply it. */
+export const ForkExtension = {
+    prepare: prepareForkExtension,
+    previewOrApply: previewOrApplyForkExtension,
+};
+//# sourceMappingURL=fork-extension.js.map

package/dist/src/fork-package.d.ts

@@ -1,8 +1,8 @@
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
-import { ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid } from "@agentxm/extension-workspace";
-import { type FrontmatterParseFailure } from "@agentxm/registry-protocol/unstable/content/frontmatter";
+import { ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid } from "./authored-package-errors.js";
+import { type FrontmatterParseFailure } from "@agentxm/extension-content";
 import type { ExtensionFqnParts, ExtensionName, ExtensionType } from "@agentxm/extension-model/unstable/extensions/common";
 import type { Handle } from "@agentxm/extension-model/unstable/extensions/handle";
 export interface ForkExtensionPackageArgs {

package/dist/src/fork-package.js

@@ -4,10 +4,10 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import YAML from "yaml";
-import { ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid, } from "@agentxm/extension-workspace";
-import { ManifestIdentitySchema, manifestFilenameForType, manifestSchemaForType, } from "@agentxm/registry-protocol/unstable/publish/manifest-policy";
-import { copyExtensionDirectory } from "@agentxm/extension-workspace";
-import { parseFrontmatterEffect, } from "@agentxm/registry-protocol/unstable/content/frontmatter";
+import { ForkPackageConflict, ForkPackageFailed, ForkPackageInvalid, } from "./authored-package-errors.js";
+import { ManifestIdentitySchema, manifestFilenameForType, manifestSchemaForType, } from "@agentxm/extension-content";
+import { copyExtensionDirectory } from "@agentxm/extension-materialization";
+import { parseFrontmatterEffect } from "@agentxm/extension-content";
 const INITIAL_FORK_VERSION = "0.1.0";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const readJson = (filePath) => Effect.gen(function* () {

package/dist/src/import/import-native-extension.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Importing native, unmanaged content as an authored AXM package.
+ *
+ * Three routes share one decision: a native skill directory or file, a native
+ * subagent document, and a native MCP connection declared in an agent's own
+ * config all become a workspace-authored package that carries the identity the
+ * person asked for, not the identity the native content happened to have. The
+ * native source is never modified — except for an MCP connection, whose native
+ * declaration is retired only after the managed package validates, because
+ * leaving both would give one connection two owners.
+ *
+ * `prepare` settles the identity, the destination, and the activation, and
+ * stages the converted package into a scoped temporary directory; nothing
+ * under the workspace is written. `previewOrApply` resolves that candidate.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import type * as Scope from "effect/Scope";
+import { ExtensionManagers, McpSecretStore, type ManagerRequirements, type NativeMcpEntryRef, type RecipeRequirements } from "@agentxm/extension-materialization";
+import { type FqnInvalidError, type Handle } from "@agentxm/extension-model/unstable/extensions";
+import { SourceHostProviders, WorkspaceCatalog, type SourceResolutionFailure } from "@agentxm/extension-sources";
+import { type CandidateFingerprintFailed, type ExecutionCandidate, type PlanExecution } from "@agentxm/workspace-operations";
+import type { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { WorkspaceMutations, type ConfiguredAgentOutcomesProvider, type LockfileValidationError, type PackageContentHashFailed, type WorkspaceLockfileReadFailure, type WorkspaceSettingsReadFailure } from "@agentxm/workspace-state";
+import type { AuthoredPackageError } from "../authored-package-errors.js";
+import { AuthoringFailed } from "../errors.js";
+import { AuthoringScopeUnsupported, type AuthoringOwnerMismatch, type AuthoringOwnerRequired } from "../create/errors.js";
+import type { FrontmatterParseFailure } from "@agentxm/extension-content";
+/** The extension types native content can be imported as. */
+export type NativeImportType = "skill" | "subagent" | "mcp-server";
+interface ImportRequestBase {
+    /** Owner-qualified identity the imported package will carry. */
+    readonly target: string;
+    /** Materialize the import immediately instead of leaving it declared and inert. */
+    readonly enable: boolean;
+}
+export interface ImportNativeSkillRequest extends ImportRequestBase {
+    readonly type: "skill";
+    /** Local or Git native source, as the person typed it. */
+    readonly source: string;
+}
+export interface ImportNativeSubagentRequest extends ImportRequestBase {
+    readonly type: "subagent";
+    readonly source: string;
+}
+/** One native MCP connection the workspace discovered, in package terms. */
+export interface NativeMcpCandidate {
+    /** The native connection key. */
+    readonly name: string;
+    /**
+     * The remote form the connection has, or none when it is a local command
+     * that no package manifest can represent losslessly.
+     */
+    readonly remote: Option.Option<{
+        readonly url: string;
+        readonly headers: Readonly<Record<string, string>>;
+    }>;
+    /** Connection inputs the declaration carries. */
+    readonly env: Readonly<Record<string, string>>;
+    /** Every native declaration of this connection, across agent config files. */
+    readonly entries: ReadonlyArray<NativeMcpEntryRef>;
+}
+/** What the workspace discovered about its unmanaged native MCP connections. */
+export interface NativeMcpDiscovery {
+    readonly candidates: ReadonlyArray<NativeMcpCandidate>;
+    /** Connection keys whose native declarations disagree across agents. */
+    readonly conflicts: ReadonlyArray<string>;
+}
+export interface ImportNativeMcpServerRequest extends ImportRequestBase {
+    readonly type: "mcp-server";
+    readonly discovery: NativeMcpDiscovery;
+    /**
+     * Whether the invoking surface can prompt for a connection input the
+     * converted manifest requires.
+     */
+    readonly nonInteractive: boolean;
+}
+/** What a person asked to import. */
+export type ImportNativeExtensionRequest = ImportNativeSkillRequest | ImportNativeSubagentRequest | ImportNativeMcpServerRequest;
+/** What every step in a native import may require when it runs. */
+export type ImportNativeExtensionRequirements = ManagerRequirements | RecipeRequirements | WorkspaceMutations | CodingAgentRepository | McpSecretStore;
+/** A settled import: every decision is made and nothing under the workspace is written. */
+export interface ImportNativeExtensionCandidate {
+    readonly type: NativeImportType;
+    readonly fqn: string;
+    readonly owner: Handle;
+    readonly name: string;
+    /** Where the native content came from, in operator-facing terms. */
+    readonly origin: string;
+    /** Workspace-relative directory the package will occupy. */
+    readonly authoredPath: string;
+    /** Workspace-relative settings file the declaration is written to. */
+    readonly settingsPath: string;
+    /** Whether the import is materialized once it is declared. */
+    readonly enabled: boolean;
+    readonly execution: ExecutionCandidate<ImportNativeExtensionRequirements>;
+}
+/** Every failure settling a native import can surface before anything is written. */
+export type ImportNativeExtensionFailure = AuthoringFailed | AuthoredPackageError | FrontmatterParseFailure | AuthoringOwnerRequired | AuthoringOwnerMismatch | AuthoringScopeUnsupported | SourceResolutionFailure | PackageContentHashFailed | LockfileValidationError | WorkspaceLockfileReadFailure | WorkspaceSettingsReadFailure | CandidateFingerprintFailed | FqnInvalidError;
+/** Everything settling a native import reads before it freezes a candidate. */
+export type PrepareImportNativeExtensionRequirements = FileSystem.FileSystem | Path.Path | Scope.Scope | HttpClient.HttpClient | WorkspaceMutations | ExtensionManagers | SourceHostProviders | WorkspaceCatalog | ConfiguredAgentOutcomesProvider;
+/** The plan a native import resolves. */
+export declare const importNativeExtensionPlanName: (type: NativeImportType) => string;
+/** Settle a native import and stage its converted content, writing nothing. */
+export declare const prepareImportNativeExtension: (request: ImportNativeExtensionRequest) => Effect.Effect<ImportNativeExtensionCandidate, ImportNativeExtensionFailure, PrepareImportNativeExtensionRequirements>;
+/** Preview or apply a settled native import, resolving to one operation outcome. */
+export declare const previewOrApplyImportNativeExtension: (candidate: ImportNativeExtensionCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | ImportNativeExtensionRequirements>;
+/** The native-import use case: settle a request, then preview or apply it. */
+export declare const ImportNativeExtension: {
+    readonly prepare: (request: ImportNativeExtensionRequest) => Effect.Effect<ImportNativeExtensionCandidate, ImportNativeExtensionFailure, PrepareImportNativeExtensionRequirements>;
+    readonly previewOrApply: (candidate: ImportNativeExtensionCandidate, execution: PlanExecution) => Effect.Effect<import("@agentxm/workspace-operations").OperationResolution<never>, WorkspaceSettingsReadFailure | import("@agentxm/workspace-operations").ApprovalRecoveryMissing | import("@agentxm/workspace-operations").PlanInteractionFailed | import("@agentxm/workspace-transactions").WorkspaceTransitionAcquireFailure, ConfiguredAgentOutcomesProvider | import("@agentxm/workspace-operations").OperationJournal | import("@agentxm/workspace-operations").ResolvePlanInteraction | import("@agentxm/workspace-transactions").FootprintRecorder | ImportNativeExtensionRequirements>;
+};
+export {};
+//# sourceMappingURL=import-native-extension.d.ts.map