@agentxm/extension-lifecycle 0.28.11 → 0.28.13

package/dist/src/subagents/operations/enable.d.ts

@@ -7,11 +7,13 @@
  */
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
-import { CodingAgentRepository } from "@agentxm/extension-workspace";
-import { LifecycleFailureAdapter } from "../../failure-adapter.js";
+import { CodingAgentRepository } from "@agentxm/workspace-projection";
+import { NativeWriteAuthority } from "@agentxm/agent-integration";
+import { StepFailureConversion } from "../../step-failure-conversion.js";
 import type { OperationHandler } from "@agentxm/workspace-operations";
 import type { Operation } from "@agentxm/workspace-operations";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { WorkspaceTransactionScope } from "@agentxm/workspace-transactions";
 /**
  * Enable a previously disabled subagent (re-render files and update state).
  *
@@ -26,5 +28,5 @@ export type EnableSubagentOperation = Operation<"enable-subagent", {
  * Resolves accepted canonical content, renders to configured agents, and then
  * updates the desired settings entry.
  */
-export declare const enableSubagent: OperationHandler<EnableSubagentOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | CodingAgentRepository | LifecycleFailureAdapter>;
+export declare const enableSubagent: OperationHandler<EnableSubagentOperation, FileSystem.FileSystem | Path.Path | WorkspaceMutations | WorkspaceTransactionScope | CodingAgentRepository | NativeWriteAuthority | StepFailureConversion>;
 //# sourceMappingURL=enable.d.ts.map

package/dist/src/subagents/operations/enable.js

@@ -10,13 +10,16 @@ import * as Path from "effect/Path";
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
-import { CodingAgentRepository, subagentContentFilename, subagentContentPath, warnOnOrphanOverrides, managedSubagentFile, } from "@agentxm/extension-workspace";
+import { subagentContentFilename, subagentContentPath } from "@agentxm/workspace-state";
+import { CodingAgentRepository, managedSubagentRenderInput, managedSubagentFile, } from "@agentxm/workspace-projection";
+import { NativeWriteAuthority, warnOnOrphanOverrides } from "@agentxm/agent-integration";
 import { ExtensionLifecycleFailed } from "../../errors.js";
-import { LifecycleFailureAdapter, withAdaptedStepFailures } from "../../failure-adapter.js";
+import { StepFailureConversion, withAdaptedStepFailures } from "../../step-failure-conversion.js";
 import { WorkspaceMutations } from "@agentxm/workspace-state";
+import { WorkspaceTransactionScope, runWorkspaceTransaction, } from "@agentxm/workspace-transactions";
 import { RenderedFilesMapSchema } from "@agentxm/workspace-state";
 import { makeWorkspaceRelativePath } from "@agentxm/extension-model/unstable/path-types";
-import { parseSubagentMd } from "@agentxm/registry-protocol/unstable/content/subagent-content";
+import { parseSubagentMd } from "@agentxm/extension-content";
 import { subagentLifecycleArtifact } from "./artifact.js";
 import { usableAcceptedCanonical } from "@agentxm/workspace-state";
 /**
@@ -93,20 +96,22 @@ export const enableSubagent = (op) => Effect.gen(function* () {
     const configuredAgents = yield* agentRepo.getConfiguredAgents();
     yield* warnOnOrphanOverrides(`Subagent "${op.args.subagentName}"`, agentOverrides, configuredAgents.map((a) => a.id));
     const renderedFilesMap = {};
-    yield* ws.runTransaction({
+    yield* runWorkspaceTransaction({
         transition: Effect.gen(function* () {
             yield* Effect.forEach(configuredAgents, (agent) => agent
                 .addSubagent({
                 workspaceRoot: baseDir,
                 scope: ws.scope,
-                managedFile,
-                input: {
-                    agentId: agent.id,
-                    name: op.args.subagentName,
-                    body: parsed.body,
-                    frontmatter: renderFrontmatter,
-                    agentOverrides: agentOverrides?.[agent.id],
-                },
+                input: managedSubagentRenderInput({
+                    managedFile,
+                    input: {
+                        agentId: agent.id,
+                        name: op.args.subagentName,
+                        body: parsed.body,
+                        frontmatter: renderFrontmatter,
+                        agentOverrides: agentOverrides?.[agent.id],
+                    },
+                }),
                 force: false,
             })
                 .pipe(Effect.flatMap((outcome) => {

package/dist/src/subagents/uninstall/plan.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Uninstalling subagents.
+ *
+ * The removal reports what it withdrew from the settlement the operation
+ * returns, so a package retained because an installed pack still requires it
+ * is reported as retained rather than as removed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import { SubagentManager } from "@agentxm/extension-materialization";
+import type { Plan } from "@agentxm/workspace-operations";
+import type { ExtensionLifecycleFailed } from "../../errors.js";
+import { type InstallStepRequirements } from "../../install/vocabulary.js";
+import type { SubagentUninstallIntent } from "../../uninstall/vocabulary.js";
+/** Expand the selector against installed subagents; a glob may match nothing. */
+export declare const parseSubagentUninstallRequest: (selector: string) => Effect.Effect<SubagentUninstallIntent, ExtensionLifecycleFailed, InstallStepRequirements>;
+/** The closures a settled subagent removal becomes. */
+export declare const planSubagentUninstall: (intent: SubagentUninstallIntent) => Effect.Effect<Plan<InstallStepRequirements>, ExtensionLifecycleFailed, InstallStepRequirements | SubagentManager>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/src/subagents/uninstall/plan.js

@@ -0,0 +1,142 @@
+/**
+ * Uninstalling subagents.
+ *
+ * The removal reports what it withdrew from the settlement the operation
+ * returns, so a package retained because an installed pack still requires it
+ * is reported as retained rather than as removed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { NO_MATERIALIZATION_OBSERVATION, SubagentManager, buildUninstallOperation, } from "@agentxm/extension-materialization";
+import { parseExtensionFqnParts } from "@agentxm/extension-model/unstable/extensions";
+import { WorkspaceMutations, acquiredExtensionDisplayPathFromLockEntry, } from "@agentxm/workspace-state";
+import { expandGlob } from "../../glob.js";
+import { lifecycleStepFailure } from "../../step-failure.js";
+import { installRefused } from "../../install/vocabulary.js";
+import { makeWorkspaceRetentionPolicy } from "../../uninstall/retention-policy.js";
+import { workspaceCanonicalPath, workspaceCanonicalRoot, workspaceLockfilePath, workspaceSettingsPath, } from "../../workspace-paths.js";
+const resolvedVersion = (entry) => entry !== undefined && entry.type === "registry" ? entry.resolvedVersion : undefined;
+const subagentSourceTarget = (args) => args.lockEntry === undefined
+    ? { path: workspaceCanonicalPath(args.scope, args.name), change: args.change }
+    : {
+        path: acquiredExtensionDisplayPathFromLockEntry(workspaceCanonicalRoot(args.scope), args.lockEntry, "subagents", args.lockEntry.workspaceName),
+        change: args.change,
+    };
+const subagentArtifact = (args) => {
+    const targetChange = args.change === "removed" ? "removed" : "unchanged";
+    const targets = [
+        { path: workspaceLockfilePath(args.scope), change: args.lockfileChange },
+        { path: workspaceSettingsPath(args.scope), change: "updated" },
+        subagentSourceTarget({
+            name: args.name,
+            lockEntry: args.lockEntry,
+            change: targetChange,
+            scope: args.scope,
+        }),
+        ...args.materializedTargets.map((target) => ({ ...target, change: targetChange })),
+    ];
+    const firstTarget = targets[0];
+    const version = resolvedVersion(args.lockEntry);
+    return {
+        path: firstTarget?.path ?? args.name,
+        scope: args.scope,
+        ...(args.agents.length > 0 ? { agents: args.agents } : {}),
+        ...(version !== undefined ? { version } : {}),
+        change: args.change,
+        fileCount: targets.length,
+        ...(targets.length > 0 ? { targets } : {}),
+    };
+};
+/** Expand the selector against installed subagents; a glob may match nothing. */
+export const parseSubagentUninstallRequest = Effect.fn("UninstallExtensions.parseSubagentRequest")(function* (selector) {
+    const ws = yield* WorkspaceMutations;
+    const rows = yield* ws.records.rows("subagent").pipe(Effect.mapError((cause) => installRefused({
+        category: "internal",
+        detail: "Installed subagents could not be read",
+        cause,
+    })));
+    const installedNames = [...new Set(rows.map((row) => row.name))];
+    const matched = expandGlob(selector, installedNames);
+    if (selector.includes("*") && matched.length === 0) {
+        return { targets: [] };
+    }
+    const names = matched.length > 0
+        ? matched
+        : (() => {
+            const parsed = parseExtensionFqnParts(selector);
+            const resolvedName = parsed?.type === "subagent" ? parsed.name : selector;
+            return installedNames.includes(resolvedName) ? [resolvedName] : [];
+        })();
+    return {
+        targets: names.map((name) => ({ type: "subagent", name })),
+    };
+});
+/** The closures a settled subagent removal becomes. */
+export const planSubagentUninstall = Effect.fn("UninstallExtensions.planSubagents")(function* (intent) {
+    const ws = yield* WorkspaceMutations;
+    const subagentManager = yield* SubagentManager;
+    const retentionPolicy = makeWorkspaceRetentionPolicy(ws);
+    // The accepted resolution names the package the removal retires, and the
+    // removal deletes it, so it is read before the step runs.
+    const steps = yield* Effect.forEach(intent.targets, (target) => Effect.gen(function* () {
+        const lockEntry = Option.getOrUndefined(yield* ws
+            .getLockedSubagent(target.name)
+            .pipe(Effect.catch(() => Effect.succeed(Option.none()))));
+        return buildUninstallOperation(subagentManager, retentionPolicy, {
+            target,
+            toStepFailure: lifecycleStepFailure,
+            buildArtifact: ({ settlement, unmaterialization }) => {
+                if (settlement.declaration === "absent") {
+                    return Effect.succeed(subagentArtifact({
+                        name: target.name,
+                        lockEntry,
+                        materializedTargets: [],
+                        agents: [],
+                        change: "unchanged",
+                        lockfileChange: "unchanged",
+                        scope: ws.scope,
+                    }));
+                }
+                if (settlement.canonical === "retained-by-pack") {
+                    // The declaration was withdrawn, so this changed the workspace
+                    // even though the package and its projections stay.
+                    return Effect.succeed(subagentArtifact({
+                        name: target.name,
+                        lockEntry,
+                        materializedTargets: [],
+                        agents: [],
+                        change: "updated",
+                        lockfileChange: "unchanged",
+                        scope: ws.scope,
+                    }));
+                }
+                const observation = Option.match(unmaterialization, {
+                    onNone: () => NO_MATERIALIZATION_OBSERVATION,
+                    onSome: (facts) => facts.observation,
+                });
+                return Effect.succeed(subagentArtifact({
+                    name: target.name,
+                    lockEntry,
+                    materializedTargets: observation.targets,
+                    agents: observation.agents,
+                    change: "removed",
+                    lockfileChange: "updated",
+                    scope: ws.scope,
+                }));
+            },
+        });
+    }));
+    return {
+        _tag: "Plan",
+        name: intent.targets.length === 0
+            ? "Uninstall subagents"
+            : intent.targets.length === 1
+                ? "Uninstall subagent"
+                : `Uninstall ${intent.targets.length} subagents`,
+        description: Option.none(),
+        jobs: [{ concurrency: 1, steps }],
+    };
+});
+//# sourceMappingURL=plan.js.map

package/dist/src/test-packages.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Minimal valid local extension packages, one per type an install can acquire
+ * from a directory.
+ *
+ * Each writes the manifest and the canonical content the product itself
+ * requires — nothing simulated — under `<root>/vendor/<name>`, and returns the
+ * package root so a specification can hand it to an install as a source.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+/** What a local package fixture is called and how it identifies itself. */
+export interface LocalPackageFixture {
+    readonly name: string;
+    readonly description?: string;
+    readonly version?: string;
+    readonly owner?: string;
+}
+/** A local skill package: `skill.json` plus `src/SKILL.md`. */
+export declare const writeLocalSkillPackage: (root: string, fixture: LocalPackageFixture) => string;
+/**
+ * A bare Agent Skill directory: one root `SKILL.md` carrying the frontmatter
+ * the Agent Skill format requires, with no `skill.json` and no `src/`. It is
+ * the other entry-document layout a Skill source can arrive in.
+ */
+export declare const writeAgentSkillDirectory: (root: string, fixture: LocalPackageFixture) => string;
+/** A local subagent package: `subagent.json` plus `src/<name>.md`. */
+export declare const writeLocalSubagentPackage: (root: string, fixture: LocalPackageFixture) => string;
+/** A local rule package: `rule.json` plus `src/RULE.md`. */
+export declare const writeLocalRulePackage: (root: string, fixture: LocalPackageFixture) => string;
+/** A local hooks package: `hook.json` plus `src/hook.sh`. */
+export declare const writeLocalHookPackage: (root: string, fixture: LocalPackageFixture) => string;
+/** A local Open Knowledge Format bundle: `knowledge.json` plus `src/index.md`. */
+export declare const writeLocalKnowledgePackage: (root: string, fixture: LocalPackageFixture) => string;
+//# sourceMappingURL=test-packages.d.ts.map

package/dist/src/test-packages.js

@@ -0,0 +1,111 @@
+/**
+ * Minimal valid local extension packages, one per type an install can acquire
+ * from a directory.
+ *
+ * Each writes the manifest and the canonical content the product itself
+ * requires — nothing simulated — under `<root>/vendor/<name>`, and returns the
+ * package root so a specification can hand it to an install as a source.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as fs from "node:fs";
+import * as nodePath from "node:path";
+const writePackageFile = (packageRoot, relative, contents) => {
+    const file = nodePath.join(packageRoot, relative);
+    fs.mkdirSync(nodePath.dirname(file), { recursive: true });
+    fs.writeFileSync(file, contents);
+};
+const preparePackageRoot = (root, fixture, manifestFilename, manifest) => {
+    const packageRoot = nodePath.join(root, "vendor", fixture.name);
+    fs.mkdirSync(nodePath.join(packageRoot, "src"), { recursive: true });
+    writePackageFile(packageRoot, manifestFilename, `${JSON.stringify(manifest, null, 2)}\n`);
+    return packageRoot;
+};
+/** A local skill package: `skill.json` plus `src/SKILL.md`. */
+export const writeLocalSkillPackage = (root, fixture) => {
+    const description = fixture.description ?? `The ${fixture.name} skill.`;
+    const packageRoot = preparePackageRoot(root, fixture, "skill.json", {
+        $schema: "https://axm.sh/schemas/skill.schema.json",
+        owner: fixture.owner ?? "@acme",
+        type: "skill",
+        name: fixture.name,
+        version: fixture.version ?? "1.0.0",
+        description,
+    });
+    writePackageFile(packageRoot, "src/SKILL.md", `---\nname: "${fixture.name}"\ndescription: "${description}"\n---\n\n# ${fixture.name}\n\n${description}\n`);
+    return packageRoot;
+};
+/**
+ * A bare Agent Skill directory: one root `SKILL.md` carrying the frontmatter
+ * the Agent Skill format requires, with no `skill.json` and no `src/`. It is
+ * the other entry-document layout a Skill source can arrive in.
+ */
+export const writeAgentSkillDirectory = (root, fixture) => {
+    const description = fixture.description ?? `The ${fixture.name} skill.`;
+    const packageRoot = nodePath.join(root, "vendor", fixture.name);
+    fs.mkdirSync(packageRoot, { recursive: true });
+    writePackageFile(packageRoot, "SKILL.md", `---\nname: "${fixture.name}"\ndescription: "${description}"\n---\n\n# ${fixture.name}\n\n${description}\n`);
+    return packageRoot;
+};
+/** A local subagent package: `subagent.json` plus `src/<name>.md`. */
+export const writeLocalSubagentPackage = (root, fixture) => {
+    const description = fixture.description ?? `The ${fixture.name} subagent.`;
+    const packageRoot = preparePackageRoot(root, fixture, "subagent.json", {
+        $schema: "https://axm.sh/schemas/subagent.schema.json",
+        owner: fixture.owner ?? "@acme",
+        type: "subagent",
+        name: fixture.name,
+        version: fixture.version ?? "1.0.0",
+        description,
+    });
+    writePackageFile(packageRoot, `src/${fixture.name}.md`, `---\nname: ${fixture.name}\ndescription: ${description}\n---\n\n# ${fixture.name}\n`);
+    return packageRoot;
+};
+/** A local rule package: `rule.json` plus `src/RULE.md`. */
+export const writeLocalRulePackage = (root, fixture) => {
+    const description = fixture.description ?? `The ${fixture.name} rule.`;
+    const packageRoot = preparePackageRoot(root, fixture, "rule.json", {
+        $schema: "https://axm.sh/schemas/rule.schema.json",
+        owner: fixture.owner ?? "@acme",
+        type: "rule",
+        name: fixture.name,
+        version: fixture.version ?? "1.0.0",
+        description,
+    });
+    writePackageFile(packageRoot, "src/RULE.md", `Guidance for ${fixture.name}: ${description}\n`);
+    return packageRoot;
+};
+/** A local hooks package: `hook.json` plus `src/hook.sh`. */
+export const writeLocalHookPackage = (root, fixture) => {
+    const description = fixture.description ?? `The ${fixture.name} hook.`;
+    const packageRoot = preparePackageRoot(root, fixture, "hook.json", {
+        $schema: "https://axm.sh/schemas/hook.schema.json",
+        owner: fixture.owner ?? "@acme",
+        type: "hook",
+        name: fixture.name,
+        version: fixture.version ?? "1.0.0",
+        description,
+        runtime: "bash",
+        entrypoint: "src/hook.sh",
+        bindings: [{ on: "tool.pre", match: { tools: ["file.write"] } }],
+    });
+    writePackageFile(packageRoot, "src/hook.sh", `#!/usr/bin/env bash\necho "${fixture.name}"\n`);
+    return packageRoot;
+};
+/** A local Open Knowledge Format bundle: `knowledge.json` plus `src/index.md`. */
+export const writeLocalKnowledgePackage = (root, fixture) => {
+    const description = fixture.description ?? `The ${fixture.name} knowledge bundle.`;
+    const packageRoot = preparePackageRoot(root, fixture, "knowledge.json", {
+        $schema: "https://axm.sh/schemas/knowledge.schema.json",
+        owner: fixture.owner ?? "@acme",
+        type: "knowledge",
+        name: fixture.name,
+        version: fixture.version ?? "1.0.0",
+        description,
+        format: { name: "okf", version: "0.2" },
+        bundleRoot: "src",
+    });
+    writePackageFile(packageRoot, "src/index.md", `---\nokf_version: "0.2"\ndescription: "${description}"\n---\n\n# ${fixture.name}\n`);
+    return packageRoot;
+};
+//# sourceMappingURL=test-packages.js.map

package/dist/src/test-registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A file-backed Registry a specification can publish into.
+ *
+ * Writes the real Registry directory layout — a per-extension index plus
+ * version archives with genuine integrity hashes — that the production
+ * source-resolution layer reads over `file://`. Publication instants predate
+ * the deterministic test clock by more than the default minimum release age,
+ * so every written version is immediately eligible; rewriting an extension
+ * with a longer version list models a later publication.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface RegistrySkillVersion {
+    readonly version: string;
+    /** Body text of the skill document, so versions are observably distinct. */
+    readonly body: string;
+    /**
+     * Publication instant. Defaults to one that predates the minimum release
+     * age; pass a recent instant to model a release the age policy still holds.
+     */
+    readonly published?: string;
+}
+export interface RegistrySubagentVersion {
+    readonly version: string;
+    /** Body text of the subagent document, so versions are observably distinct. */
+    readonly body: string;
+    readonly published?: string;
+}
+export interface RegistryMcpVersion {
+    readonly version: string;
+    /** Additional package files included in the version archive. */
+    readonly files?: Readonly<Record<string, string>>;
+    /** Declared environment input, for credential-lifecycle evidence. */
+    readonly secretInput?: string;
+}
+export interface RegistryPackVersion {
+    readonly version: string;
+    readonly files?: Readonly<Record<string, string>>;
+    /** Member constraints keyed by fully qualified name, as the manifest records them. */
+    readonly dependencies: Readonly<Record<string, string>>;
+    readonly published?: string;
+}
+export interface RegistryKnowledgeVersion {
+    readonly version: string;
+    /** Body text of the bundle's root index, so versions are observably distinct. */
+    readonly body: string;
+    readonly published?: string;
+}
+export interface RegistryRuleVersion {
+    readonly version: string;
+    readonly body: string;
+    readonly published?: string;
+}
+export interface RegistryHookVersion {
+    readonly version: string;
+    readonly published?: string;
+}
+export interface LifecycleRegistry {
+    /** Absolute Registry root directory. */
+    readonly root: string;
+    /** The settings `sources` entry that points at this Registry. */
+    readonly source: {
+        readonly name: string;
+        readonly type: "registry";
+        readonly location: string;
+    };
+    readonly writeSkill: (name: string, versions: ReadonlyArray<RegistrySkillVersion>) => void;
+    readonly writeSubagent: (name: string, versions: ReadonlyArray<RegistrySubagentVersion>) => void;
+    readonly writeRule: (name: string, versions: ReadonlyArray<RegistryRuleVersion>) => void;
+    readonly writeHook: (name: string, versions: ReadonlyArray<RegistryHookVersion>) => void;
+    readonly writeMcp: (name: string, versions: ReadonlyArray<RegistryMcpVersion>) => void;
+    readonly writePack: (name: string, versions: ReadonlyArray<RegistryPackVersion>) => void;
+    readonly writeKnowledge: (name: string, versions: ReadonlyArray<RegistryKnowledgeVersion>) => void;
+    readonly cleanup: () => void;
+}
+/** Publish into a throwaway `file://` Registry. */
+export declare const makeLifecycleRegistry: () => LifecycleRegistry;
+//# sourceMappingURL=test-registry.d.ts.map