@agentxm/workspace-state 0.28.11 → 0.28.13

package/package.json

@@ -4,8 +4,11 @@
     "url": "https://github.com/agentxm/axm/issues"
   },
   "dependencies": {
-    "@agentxm/extension-model": "^0.28.11",
-    "@agentxm/registry-protocol": "^0.28.11",
+    "@agentxm/agent-integration": "^0.28.13",
+    "@agentxm/extension-content": "^0.28.13",
+    "@agentxm/extension-model": "^0.28.13",
+    "@agentxm/registry-protocol": "^0.28.13",
+    "@agentxm/workspace-transactions": "^0.28.13",
     "effect": "4.0.0-rc.112",
     "jsonc-parser": "^3.3.1",
     "semver": "^7.8.5",
@@ -13,6 +16,7 @@
   },
   "description": "AXM workspace state kernel: settings, lockfile, read model, and desired-state vocabulary for the axm CLI. Unstable and unsupported — use the axm.sh CLI.",
   "devDependencies": {
+    "@agentxm/specification-metadata": "^0.28.13",
     "@effect/platform-node": "4.0.0-rc.112",
     "@effect/vitest": "4.0.0-rc.112",
     "@types/semver": "^7.7.1",
@@ -29,6 +33,11 @@
       "default": "./dist/src/index.js",
       "types": "./dist/src/index.d.ts"
     },
+    "./live": {
+      "axm-source": "./src/live.ts",
+      "default": "./dist/src/live.js",
+      "types": "./dist/src/live.d.ts"
+    },
     "./testing": {
       "axm-source": "./src/testing.ts",
       "default": "./dist/src/testing.js",
@@ -49,11 +58,11 @@
     "access": "public"
   },
   "repository": {
-    "directory": "packages/workspace-state",
+    "directory": "packages/core/workspace-state",
     "type": "git",
     "url": "https://github.com/agentxm/axm.git"
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.28.11"
-}
+  "version": "0.28.13"
+}

package/dist/src/utils/atomic-write.d.ts

@@ -1,67 +0,0 @@
-/**
- * Shared atomic single-file replacement: write a uniquely named temp file in
- * the target's directory, then rename it over the target.
- *
- * The temp file lives next to the target so the rename stays on one
- * filesystem (and therefore atomic), and is removed on any failure or
- * interruption. Temp names follow `<target>.tmp.<unique>`; sweepers that
- * clean stale temps (e.g. the lockfile writer) rely on that prefix.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import type * as FileSystem from "effect/FileSystem";
-import * as Path from "effect/Path";
-import type { PlatformError } from "effect/PlatformError";
-/**
- * Step at which an atomic write failed. `check-target` and `read-target` can
- * only occur with `skipIfUnchanged: "fail-on-read-error"`.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export type AtomicWriteStep = "check-target" | "read-target" | "write-temp" | "rename";
-/**
- * Failure passed to `mapError` so each call site keeps its own error shape.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export interface AtomicWriteFailure {
-    readonly step: AtomicWriteStep;
-    readonly targetPath: string;
-    readonly tempPath: string;
-    readonly cause: PlatformError;
-}
-/**
- * Content-equality short-circuit mode: `fail-on-read-error` surfaces
- * check/read failures via `mapError`; `ignore-read-errors` treats an
- * unreadable target as changed and proceeds to write.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export type SkipIfUnchanged = "fail-on-read-error" | "ignore-read-errors";
-/**
- * Options for `writeFileAtomic`.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export interface WriteFileAtomicOptions<E> {
-    readonly targetPath: string;
-    readonly content: string | Uint8Array;
-    /** When set, leave the target untouched if it already has this content. */
-    readonly skipIfUnchanged?: SkipIfUnchanged;
-    /** Best-effort remove of the target before rename (Windows cannot always rename over an existing file). */
-    readonly removeTargetBeforeRename?: boolean;
-    readonly mapError: (failure: AtomicWriteFailure) => E;
-}
-export declare const atomicWriteTempPrefix: (targetPath: string) => string;
-/** Remove only stale temp siblings belonging to one atomic-write target. */
-export declare const sweepStaleAtomicWriteTemps: (fs: FileSystem.FileSystem, targetPath: string) => Effect.Effect<void, never, Path.Path>;
-/**
- * Atomically replace `targetPath` with `content` via a same-directory temp
- * file and rename. Failures at each step are mapped by the caller, so error
- * codes, details, and suggestions stay call-site specific.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export declare const writeFileAtomic: <E>(fs: FileSystem.FileSystem, options: WriteFileAtomicOptions<E>) => Effect.Effect<"written" | "skipped", E>;
-//# sourceMappingURL=atomic-write.d.ts.map

package/dist/src/utils/atomic-write.js

@@ -1,71 +0,0 @@
-/**
- * Shared atomic single-file replacement: write a uniquely named temp file in
- * the target's directory, then rename it over the target.
- *
- * The temp file lives next to the target so the rename stays on one
- * filesystem (and therefore atomic), and is removed on any failure or
- * interruption. Temp names follow `<target>.tmp.<unique>`; sweepers that
- * clean stale temps (e.g. the lockfile writer) rely on that prefix.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
-import * as Path from "effect/Path";
-/** In-process sequence so concurrent fibers never share a temp path. */
-let tempSequence = 0;
-export const atomicWriteTempPrefix = (targetPath) => `${targetPath}.tmp.`;
-/** Remove only stale temp siblings belonging to one atomic-write target. */
-export const sweepStaleAtomicWriteTemps = (fs, targetPath) => Effect.gen(function* () {
-    const path = yield* Path.Path;
-    const parent = path.dirname(targetPath);
-    const filenamePrefix = `${path.basename(targetPath)}.tmp.`;
-    const entries = yield* fs.readDirectory(parent).pipe(Effect.orElseSucceed(() => []));
-    yield* Effect.forEach(entries.filter((entry) => entry.startsWith(filenamePrefix)), (entry) => fs.remove(path.join(parent, entry), { force: true }).pipe(Effect.ignore), { discard: true });
-});
-const makeTempPath = (targetPath) => {
-    tempSequence += 1;
-    const pid = typeof process === "object" ? process.pid.toString(36) : "x";
-    const random = Math.random().toString(36).slice(2, 8);
-    return `${atomicWriteTempPrefix(targetPath)}${pid}.${tempSequence.toString(36)}.${random}`;
-};
-const bytesEqual = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
-const targetHasContent = (fs, targetPath, content) => typeof content === "string"
-    ? Effect.map(fs.readFileString(targetPath), (current) => current === content)
-    : Effect.map(fs.readFile(targetPath), (current) => bytesEqual(current, content));
-/**
- * Atomically replace `targetPath` with `content` via a same-directory temp
- * file and rename. Failures at each step are mapped by the caller, so error
- * codes, details, and suggestions stay call-site specific.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export const writeFileAtomic = (fs, options) => Effect.gen(function* () {
-    const { content, mapError, targetPath } = options;
-    const tempPath = makeTempPath(targetPath);
-    const fail = (step) => (cause) => mapError({ step, targetPath, tempPath, cause });
-    if (options.skipIfUnchanged === "fail-on-read-error") {
-        const exists = yield* fs.exists(targetPath).pipe(Effect.mapError(fail("check-target")));
-        if (exists) {
-            const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.mapError(fail("read-target")));
-            if (unchanged)
-                return "skipped";
-        }
-    }
-    else if (options.skipIfUnchanged === "ignore-read-errors") {
-        const unchanged = yield* targetHasContent(fs, targetPath, content).pipe(Effect.option);
-        if (Option.isSome(unchanged) && unchanged.value)
-            return "skipped";
-    }
-    yield* Effect.gen(function* () {
-        yield* (typeof content === "string"
-            ? fs.writeFileString(tempPath, content)
-            : fs.writeFile(tempPath, content)).pipe(Effect.mapError(fail("write-temp")));
-        if (options.removeTargetBeforeRename === true) {
-            yield* fs.remove(targetPath).pipe(Effect.ignore);
-        }
-        yield* fs.rename(tempPath, targetPath).pipe(Effect.mapError(fail("rename")));
-    }).pipe(Effect.ensuring(fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
-    return "written";
-});
-//# sourceMappingURL=atomic-write.js.map

package/dist/src/workspace/configured-entry-resolution/types.d.ts

@@ -1,32 +0,0 @@
-import type * as Option from "effect/Option";
-import type { HookExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/hook";
-import type { KnowledgeExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/knowledge";
-import type { McpServerExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/mcp-server";
-import type { PackRef } from "@agentxm/extension-model/unstable/extensions/refs/pack";
-import type { RuleExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/rule";
-import type { SkillExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/skill";
-import type { SubagentExtensionRef } from "@agentxm/extension-model/unstable/extensions/refs/subagent";
-import type { VersionRange } from "@agentxm/extension-model/unstable/version-constraints";
-import type { NamedRegistryResolution } from "@agentxm/extension-model/unstable/sources/source-host-provider";
-import type { ReleaseAgeBypassRecord, ReleaseAgeHoldbackRecord } from "@agentxm/registry-protocol/unstable/registry/release-age-policy";
-export type ConfiguredEntryFailureReason = "entry-malformed" | "source-not-found" | "source-multiple-matches" | "source-resolution-failed" | "source-timeout";
-export interface ResolvedConfiguredEntry<TRef> {
-    readonly ref: TRef;
-    readonly versionRange: Option.Option<VersionRange>;
-    readonly releaseAge?: {
-        readonly holdbacks: ReadonlyArray<ReleaseAgeHoldbackRecord>;
-        readonly bypasses: ReadonlyArray<ReleaseAgeBypassRecord>;
-    };
-}
-export type ResolvedConfiguredSkill = ResolvedConfiguredEntry<SkillExtensionRef>;
-export type ResolvedConfiguredSubagent = ResolvedConfiguredEntry<SubagentExtensionRef>;
-export type ResolvedConfiguredRule = ResolvedConfiguredEntry<RuleExtensionRef>;
-export type ResolvedConfiguredHook = ResolvedConfiguredEntry<HookExtensionRef>;
-export type ResolvedConfiguredKnowledge = ResolvedConfiguredEntry<KnowledgeExtensionRef>;
-export type ResolvedConfiguredMcpServer = ResolvedConfiguredEntry<McpServerExtensionRef>;
-export type ResolvedConfiguredPack = ResolvedConfiguredEntry<PackRef>;
-export type ConfiguredRegistryResolution = NamedRegistryResolution & {
-    readonly versionRange: Option.Option<VersionRange>;
-    readonly acceptedVersion?: string;
-};
-//# sourceMappingURL=types.d.ts.map

package/dist/src/workspace/configured-entry-resolution/types.js

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

package/dist/src/workspace/footprint-recorder.d.ts

@@ -1,30 +0,0 @@
-/**
- * Footprint recorder — observed durable changes.
- *
- * The layers that touch durable state record what they actually committed,
- * removed, or restored here; the operation resolution's footprint is these
- * observations, not planner-claimed artifact paths. Recording is a no-op when
- * no recorder is provided, so the writers stay usable outside an operation
- * boundary.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import * as Ref from "effect/Ref";
-import * as ServiceMap from "effect/Context";
-export interface FootprintObservation {
-    /** Absolute path of the durable change. */
-    readonly path: string;
-    readonly change: "created" | "modified" | "removed" | "restored";
-}
-declare const FootprintRecorder_base: ServiceMap.ServiceClass<FootprintRecorder, "@agentxm/workspace-state/workspace/footprint-recorder/FootprintRecorder", {
-    readonly ref: Ref.Ref<ReadonlyArray<FootprintObservation>>;
-}>;
-export declare class FootprintRecorder extends FootprintRecorder_base {
-}
-/** Record one observed durable change. No-op without a recorder. */
-export declare const recordFootprint: (observation: FootprintObservation) => Effect.Effect<void>;
-export declare const readFootprint: Effect.Effect<ReadonlyArray<FootprintObservation>>;
-export declare const makeFootprintRecorder: Effect.Effect<ServiceMap.Service.Shape<typeof FootprintRecorder>>;
-export {};
-//# sourceMappingURL=footprint-recorder.d.ts.map

package/dist/src/workspace/footprint-recorder.js

@@ -1,32 +0,0 @@
-/**
- * Footprint recorder — observed durable changes.
- *
- * The layers that touch durable state record what they actually committed,
- * removed, or restored here; the operation resolution's footprint is these
- * observations, not planner-claimed artifact paths. Recording is a no-op when
- * no recorder is provided, so the writers stay usable outside an operation
- * boundary.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import * as Option from "effect/Option";
-import * as Ref from "effect/Ref";
-import * as ServiceMap from "effect/Context";
-export class FootprintRecorder extends ServiceMap.Service()("@agentxm/workspace-state/workspace/footprint-recorder/FootprintRecorder") {
-}
-/** Record one observed durable change. No-op without a recorder. */
-export const recordFootprint = (observation) => Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(FootprintRecorder);
-    if (Option.isNone(service))
-        return;
-    yield* Ref.update(service.value.ref, (entries) => [...entries, observation]);
-});
-export const readFootprint = Effect.gen(function* () {
-    const service = yield* Effect.serviceOption(FootprintRecorder);
-    if (Option.isNone(service))
-        return [];
-    return yield* Ref.get(service.value.ref);
-});
-export const makeFootprintRecorder = Ref.make([]).pipe(Effect.map((ref) => ({ ref })));
-//# sourceMappingURL=footprint-recorder.js.map

package/dist/src/workspace/mcp-entry-semantics.d.ts

@@ -1,28 +0,0 @@
-/**
- * Settings-semantics predicates for MCP server entries.
- *
- * Pure derivations over workspace-owned MCP entry shapes: AXM
- * ownership/provenance metadata embedded in agent-native MCP config entries.
- *
- * @experimental This API is unstable and may change without notice.
- * @packageDocumentation
- */
-import * as Option from "effect/Option";
-import * as Schema from "effect/Schema";
-export declare const AXM_MCP_METADATA_KEY = "x-axm";
-export declare const AxmMcpMetadataSchema: Schema.Union<readonly [Schema.Struct<{
-    readonly v: Schema.Literal<1>;
-    readonly managed: Schema.Literal<true>;
-    readonly ext: Schema.NonEmptyString;
-    readonly source: Schema.Literal<"inline">;
-}>, Schema.Struct<{
-    readonly v: Schema.Literal<1>;
-    readonly managed: Schema.Literal<true>;
-    readonly ext: Schema.NonEmptyString;
-    readonly source: Schema.Literals<readonly ["github", "gitlab", "bitbucket", "azurerepos", "git", "registry", "local", "workspace"]>;
-    readonly ref: Schema.NonEmptyString;
-}>]>;
-export type AxmMcpMetadata = typeof AxmMcpMetadataSchema.Type;
-export declare const readAxmMcpMetadata: (entry: Readonly<Record<string, unknown>>) => Option.Option<AxmMcpMetadata>;
-export declare const isAxmManagedMcpEntry: (entry: Readonly<Record<string, unknown>>) => boolean;
-//# sourceMappingURL=mcp-entry-semantics.d.ts.map

package/dist/src/workspace/mcp-entry-semantics.js

@@ -1,58 +0,0 @@
-/**
- * Settings-semantics predicates for MCP server entries.
- *
- * Pure derivations over workspace-owned MCP entry shapes: AXM
- * ownership/provenance metadata embedded in agent-native MCP config entries.
- *
- * @experimental This API is unstable and may change without notice.
- * @packageDocumentation
- */
-import * as Option from "effect/Option";
-import * as Schema from "effect/Schema";
-export const AXM_MCP_METADATA_KEY = "x-axm";
-const ResolvableSourceTypeSchema = Schema.Literals([
-    "github",
-    "gitlab",
-    "bitbucket",
-    "azurerepos",
-    "git",
-    "registry",
-    "local",
-    "workspace",
-]);
-export const AxmMcpMetadataSchema = Schema.Union([
-    Schema.Struct({
-        v: Schema.Literal(1),
-        managed: Schema.Literal(true),
-        ext: Schema.NonEmptyString,
-        source: Schema.Literal("inline"),
-    }),
-    Schema.Struct({
-        v: Schema.Literal(1),
-        managed: Schema.Literal(true),
-        ext: Schema.NonEmptyString,
-        source: ResolvableSourceTypeSchema,
-        ref: Schema.NonEmptyString,
-    }),
-]).annotate({
-    identifier: "AxmMcpMetadata",
-    title: "AXM MCP Metadata",
-    description: "AXM ownership and provenance metadata for an agent MCP config entry.",
-});
-const decodeMetadataOption = Schema.decodeUnknownOption(AxmMcpMetadataSchema);
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const hasValidRefShape = (metadata) => {
-    const source = metadata["source"];
-    const ref = metadata["ref"];
-    if (source === "inline")
-        return ref === undefined;
-    return typeof ref === "string" && ref.length > 0;
-};
-export const readAxmMcpMetadata = (entry) => {
-    const metadata = entry[AXM_MCP_METADATA_KEY];
-    if (!isRecord(metadata) || !hasValidRefShape(metadata))
-        return Option.none();
-    return decodeMetadataOption(metadata);
-};
-export const isAxmManagedMcpEntry = (entry) => Option.isSome(readAxmMcpMetadata(entry));
-//# sourceMappingURL=mcp-entry-semantics.js.map

package/dist/src/workspace/read-model/agent-presence.d.ts

@@ -1,32 +0,0 @@
-/**
- * Agent-presence probe port.
- *
- * The read model records which agents are present on the machine as a
- * scoped fact. Detection itself is agent-surface integration, so the state
- * layer declares only this optional port; the application composes an
- * implementation backed by agent detection. An absent probe degrades to an
- * empty presence set, matching the read model's existing failure
- * degradation.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Effect from "effect/Effect";
-import * as ServiceMap from "effect/Context";
-import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
-import type { WorkspaceScope } from "@agentxm/extension-model/unstable/workspace-scope";
-declare const AgentPresenceUnavailable_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "AgentPresenceUnavailable";
-} & Readonly<A>;
-/** Presence detection failed; the read model degrades to an empty set. */
-export declare class AgentPresenceUnavailable extends AgentPresenceUnavailable_base<{
-    readonly message: string;
-}> {
-}
-export interface AgentPresenceProbeService {
-    readonly detect: (root: string, scope: WorkspaceScope) => Effect.Effect<ReadonlySet<AgentId>, AgentPresenceUnavailable>;
-}
-declare const AgentPresenceProbe_base: ServiceMap.ServiceClass<AgentPresenceProbe, "@agentxm/workspace-state/workspace/read-model/agent-presence/AgentPresenceProbe", AgentPresenceProbeService>;
-export declare class AgentPresenceProbe extends AgentPresenceProbe_base {
-}
-export {};
-//# sourceMappingURL=agent-presence.d.ts.map

package/dist/src/workspace/read-model/agent-presence.js

@@ -1,21 +0,0 @@
-/**
- * Agent-presence probe port.
- *
- * The read model records which agents are present on the machine as a
- * scoped fact. Detection itself is agent-surface integration, so the state
- * layer declares only this optional port; the application composes an
- * implementation backed by agent detection. An absent probe degrades to an
- * empty presence set, matching the read model's existing failure
- * degradation.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import * as Data from "effect/Data";
-import * as Effect from "effect/Effect";
-import * as ServiceMap from "effect/Context";
-/** Presence detection failed; the read model degrades to an empty set. */
-export class AgentPresenceUnavailable extends Data.TaggedError("AgentPresenceUnavailable") {
-}
-export class AgentPresenceProbe extends ServiceMap.Service()("@agentxm/workspace-state/workspace/read-model/agent-presence/AgentPresenceProbe") {
-}
-//# sourceMappingURL=agent-presence.js.map

package/dist/src/workspace/scope-refusal.d.ts

@@ -1,26 +0,0 @@
-/**
- * Refusal messages for user-scope resolves.
- *
- * AXM writes subagents to a single workspace-relative directory,
- * so every user-scope resolve is refused. The reason why differs, and the
- * catalog knows which: an agent whose capability declares the `user` scope has
- * a real user-scope surface AXM has not modeled, while an agent without it has
- * nowhere to write at all. Reporting both as "does not support" mislabels the
- * first group.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
-/** Extension types AXM resolves per scope. */
-export type UserScopedExtension = "subagents";
-/**
- * Why AXM will not resolve a user-scope directory for this agent.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export declare const userScopeRefusal: (args: {
-    readonly agentId: AgentId;
-    readonly agentName: string;
-    readonly type: UserScopedExtension;
-}) => string;
-//# sourceMappingURL=scope-refusal.d.ts.map

package/dist/src/workspace/scope-refusal.js

@@ -1,29 +0,0 @@
-/**
- * Refusal messages for user-scope resolves.
- *
- * AXM writes subagents to a single workspace-relative directory,
- * so every user-scope resolve is refused. The reason why differs, and the
- * catalog knows which: an agent whose capability declares the `user` scope has
- * a real user-scope surface AXM has not modeled, while an agent without it has
- * nowhere to write at all. Reporting both as "does not support" mislabels the
- * first group.
- *
- * @experimental This API is unstable and may change without notice.
- */
-import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
-const declaresUserScope = (agentId) => {
-    const descriptor = AGENTS[agentId];
-    if (descriptor === undefined)
-        return false;
-    const scopes = descriptor.subagents?.scopes;
-    return scopes?.includes("user") ?? false;
-};
-/**
- * Why AXM will not resolve a user-scope directory for this agent.
- *
- * @experimental This API is unstable and may change without notice.
- */
-export const userScopeRefusal = (args) => declaresUserScope(args.agentId)
-    ? `AXM manages only the project-scope ${args.type} directory for ${args.agentName}; ${args.agentName} supports user-scope ${args.type} natively but AXM has not modeled that location`
-    : `${args.agentName} does not support user-scope ${args.type}`;
-//# sourceMappingURL=scope-refusal.js.map