alp-code 0.9.0

package/dist/src/memory/errors.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryEntryAlreadyExistsError = exports.MemoryEntryNotFoundError = exports.MemoryVersionConflictError = exports.UnauthorizedMemoryAccessError = exports.InvalidMemoryIdError = void 0;
+class InvalidMemoryIdError extends Error {
+    id;
+    constructor(id) {
+        super(`invalid logical memory ID \`${id}\``);
+        this.id = id;
+        this.name = "InvalidMemoryIdError";
+    }
+}
+exports.InvalidMemoryIdError = InvalidMemoryIdError;
+class UnauthorizedMemoryAccessError extends Error {
+    actor;
+    operation;
+    scope;
+    code;
+    constructor(actor, operation, scope, code) {
+        super(`\`${actor}\` cannot ${operation} memory scope \`${scope}\`: ${code}`);
+        this.actor = actor;
+        this.operation = operation;
+        this.scope = scope;
+        this.code = code;
+        this.name = "UnauthorizedMemoryAccessError";
+    }
+}
+exports.UnauthorizedMemoryAccessError = UnauthorizedMemoryAccessError;
+class MemoryVersionConflictError extends Error {
+    id;
+    expectedVersion;
+    actualVersion;
+    constructor(id, expectedVersion, actualVersion) {
+        super(`memory \`${id}\` version conflict: expected ${expectedVersion}, actual ${actualVersion}`);
+        this.id = id;
+        this.expectedVersion = expectedVersion;
+        this.actualVersion = actualVersion;
+        this.name = "MemoryVersionConflictError";
+    }
+}
+exports.MemoryVersionConflictError = MemoryVersionConflictError;
+class MemoryEntryNotFoundError extends Error {
+    id;
+    constructor(id) {
+        super(`memory \`${id}\` does not exist`);
+        this.id = id;
+        this.name = "MemoryEntryNotFoundError";
+    }
+}
+exports.MemoryEntryNotFoundError = MemoryEntryNotFoundError;
+class MemoryEntryAlreadyExistsError extends Error {
+    id;
+    constructor(id) {
+        super(`memory \`${id}\` already exists`);
+        this.id = id;
+        this.name = "MemoryEntryAlreadyExistsError";
+    }
+}
+exports.MemoryEntryAlreadyExistsError = MemoryEntryAlreadyExistsError;

package/dist/src/memory/memory-service.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryService = void 0;
+exports.parseMemoryId = parseMemoryId;
+const memory_grant_1 = require("../agents/memory-grant");
+const context_ranker_1 = require("./context-ranker");
+const errors_1 = require("./errors");
+function validSegment(segment) {
+    return segment.length > 0 && segment !== "." && segment !== ".." && !segment.includes("/") && !segment.includes("\\");
+}
+function parseMemoryId(id) {
+    const segments = id.split(":");
+    if (segments[0] === "shared" && segments.length >= 2 && segments.slice(1).every(validSegment)) {
+        const pathSegments = Object.freeze(segments.slice(1));
+        return { id, scope: "shared", grant: id, name: pathSegments.join(":"), pathSegments };
+    }
+    if (segments[0] === "project" &&
+        segments.length >= 3 &&
+        segments.slice(1).every(validSegment)) {
+        const pathSegments = Object.freeze(segments.slice(2));
+        return {
+            id,
+            scope: "project",
+            grant: id,
+            projectId: segments[1],
+            name: pathSegments.join(":"),
+            pathSegments,
+        };
+    }
+    if (segments[0] === "private" &&
+        segments.length >= 3 &&
+        segments.slice(1).every(validSegment)) {
+        const pathSegments = Object.freeze(segments.slice(2));
+        return {
+            id,
+            scope: "private",
+            grant: id,
+            ownerRole: segments[1],
+            name: pathSegments.join(":"),
+            pathSegments,
+        };
+    }
+    throw new errors_1.InvalidMemoryIdError(id);
+}
+class MemoryService {
+    store;
+    policy;
+    audit;
+    ranker;
+    now;
+    constructor(options) {
+        this.store = options.store;
+        this.policy = options.policy;
+        this.audit = options.audit;
+        this.ranker = options.ranker ?? new context_ranker_1.DeterministicContextRanker();
+        this.now = options.now ?? (() => new Date());
+    }
+    async record(actor, operation, logicalId, result, detail) {
+        await this.audit.record({
+            actor,
+            operation,
+            logicalId,
+            result,
+            timestamp: this.now().toISOString(),
+            ...(detail === undefined ? {} : { detail }),
+        });
+    }
+    async authorize(actor, operation, access, scope, logicalId) {
+        const authorization = this.policy.authorize({ type: "memory", actor, operation: access, scope });
+        if (!authorization.allowed) {
+            await this.record(actor, operation, logicalId, "denied", authorization.code);
+            throw new errors_1.UnauthorizedMemoryAccessError(actor, access, scope, authorization.code);
+        }
+    }
+    async call(actor, operation, logicalId, action) {
+        try {
+            const result = await action();
+            await this.record(actor, operation, logicalId, "allowed");
+            return result;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.name : String(error);
+            await this.record(actor, operation, logicalId, "error", detail);
+            throw error;
+        }
+    }
+    async search(actor, query) {
+        await this.authorize(actor, "search", "read", query.scope, query.scope);
+        return this.call(actor, "search", query.scope, async () => {
+            const entries = await this.store.search(query);
+            return entries.filter((entry) => (0, memory_grant_1.memoryGrantCovers)(query.scope, entry.id));
+        });
+    }
+    async get(actor, id) {
+        const parsed = parseMemoryId(id);
+        await this.authorize(actor, "get", "read", parsed.grant, id);
+        return this.call(actor, "get", id, () => this.store.get(id));
+    }
+    async create(actor, input) {
+        const parsed = parseMemoryId(input.id);
+        await this.authorize(actor, "create", "write", parsed.grant, input.id);
+        return this.call(actor, "create", input.id, () => this.store.create(input));
+    }
+    async update(actor, id, input) {
+        const parsed = parseMemoryId(id);
+        await this.authorize(actor, "update", "write", parsed.grant, id);
+        return this.call(actor, "update", id, () => this.store.update(id, input));
+    }
+    async delete(actor, id, expectedVersion) {
+        const parsed = parseMemoryId(id);
+        await this.authorize(actor, "delete", "write", parsed.grant, id);
+        return this.call(actor, "delete", id, () => this.store.delete(id, expectedVersion));
+    }
+    async buildContext(input) {
+        if (!Number.isInteger(input.characterBudget) || input.characterBudget < 0) {
+            throw new RangeError("characterBudget must be a non-negative integer");
+        }
+        const byId = new Map();
+        for (const query of input.queries) {
+            for (const entry of await this.search(input.actor, query))
+                byId.set(entry.id, entry);
+        }
+        const ranked = this.ranker.rank([...byId.values()], input.queries);
+        const entries = [];
+        const omittedEntryIds = [];
+        let charactersUsed = 0;
+        for (const entry of ranked) {
+            if (charactersUsed + entry.content.length <= input.characterBudget) {
+                entries.push(entry);
+                charactersUsed += entry.content.length;
+            }
+            else {
+                omittedEntryIds.push(entry.id);
+            }
+        }
+        return Object.freeze({
+            invariantContext: input.invariantContext,
+            policyContext: input.policyContext,
+            entries: Object.freeze(entries),
+            diagnostics: Object.freeze({
+                characterBudget: input.characterBudget,
+                charactersUsed,
+                truncated: omittedEntryIds.length > 0,
+                omittedEntryIds: Object.freeze(omittedEntryIds),
+            }),
+        });
+    }
+}
+exports.MemoryService = MemoryService;

package/dist/src/memory/memory-store.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/memory/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/policy/capability-policy.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapabilityPolicy = void 0;
+exports.mcpServerOf = mcpServerOf;
+const types_1 = require("./types");
+/**
+ * The three grants a definition declares by name: skills, in-process subagents, MCP servers.
+ *
+ * Each is answered from the definition, the same way tools and memory are — the grant is a
+ * list of names, and anything not on it is denied with the name in the message, so a blocked
+ * run says which grant would unblock it rather than only that something was refused.
+ */
+class CapabilityPolicy {
+    authorize(actor, kind, name, granted, code) {
+        return granted.includes(name)
+            ? types_1.ALLOW
+            : (0, types_1.deny)(code, `${kind} \`${name}\` is not granted to \`${actor.id}\``);
+    }
+}
+exports.CapabilityPolicy = CapabilityPolicy;
+/**
+ * Both runtimes name an MCP tool `mcp__<server>__<tool>`. The server segment is what policy
+ * decided on, so the tool request is routed to that grant rather than to `TOOL_CATALOG`,
+ * which does not contain it and could only ever answer `TOOL_NOT_GRANTED` — true today, and
+ * still true on the day the server *is* granted.
+ */
+function mcpServerOf(tool) {
+    return /^mcp__(.+?)__(.+)$/.exec(tool)?.[1] ?? null;
+}

package/dist/src/policy/delegation-policy.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationPolicy = void 0;
+const types_1 = require("./types");
+class DelegationPolicy {
+    registry;
+    constructor(registry) {
+        this.registry = registry;
+    }
+    authorize(actor, target) {
+        const parent = this.registry.get(actor);
+        if (!this.registry.has(target)) {
+            return (0, types_1.deny)("UNKNOWN_TARGET", `unknown delegation target \`${target}\``);
+        }
+        if (!parent.delegatesTo.includes(target)) {
+            return (0, types_1.deny)("DELEGATION_NOT_ALLOWED", `\`${actor}\` cannot delegate to \`${target}\``);
+        }
+        const child = this.registry.get(target);
+        if (child.reportsTo !== actor) {
+            return (0, types_1.deny)("DELEGATION_PARENT_MISMATCH", `\`${target}\` reports to \`${child.reportsTo}\`, not \`${actor}\``);
+        }
+        return types_1.ALLOW;
+    }
+}
+exports.DelegationPolicy = DelegationPolicy;

package/dist/src/policy/errors.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidPolicyStateError = void 0;
+class InvalidPolicyStateError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "InvalidPolicyStateError";
+    }
+}
+exports.InvalidPolicyStateError = InvalidPolicyStateError;

package/dist/src/policy/invariants.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POLICY_GUARDRAIL_LIMITATION = void 0;
+exports.isRawRuntimeTool = isRawRuntimeTool;
+exports.hasIndirectCommand = hasIndirectCommand;
+exports.invokesRawRuntime = invokesRawRuntime;
+const RAW_RUNTIME_TOOL = /(?:^|__)(?:herdr|paseo|create_agent|spawn_agent)(?:__|$)/i;
+const INDIRECT_COMMAND = /(^|[^\w])eval[^\w]|`|\$(?:\(|[A-Za-z_{])|[<>]\(|\bbase64\b|\bxxd\b|\b(?:sh|bash|zsh|python3?|node)\s+-c\b|\bperl\s+-e\b|\bruby\s+-e\b|\bxargs\b/;
+const RUNTIME_BINARY = /^(?:herdr|paseo(?:\.exe)?)$/i;
+const SHELL_WRAPPER = /^(?:env|command|sudo)$/;
+exports.POLICY_GUARDRAIL_LIMITATION = "Command inspection is a guardrail, not hostile-process isolation; use an OS sandbox or container for adversarial code.";
+function isRawRuntimeTool(tool) {
+    return RAW_RUNTIME_TOOL.test(tool);
+}
+function hasIndirectCommand(command) {
+    return INDIRECT_COMMAND.test(command);
+}
+function invokesRawRuntime(command) {
+    for (const segment of command.split(/[;\n]|&&|\|\||\|/)) {
+        const words = segment.trim().split(/\s+/).filter(Boolean);
+        let index = 0;
+        while (index < words.length && /^[A-Za-z_]\w*=/.test(words[index]))
+            index++;
+        while (index < words.length && SHELL_WRAPPER.test(words[index]))
+            index++;
+        const binary = words[index]?.replace(/^['"]|['"]$/g, "").split("/").at(-1);
+        if (binary && RUNTIME_BINARY.test(binary))
+            return true;
+    }
+    return false;
+}

package/dist/src/policy/memory-policy.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryPolicy = void 0;
+const memory_grant_1 = require("../agents/memory-grant");
+const types_1 = require("./types");
+function privateOwner(scope) {
+    return scope.startsWith("private:") ? scope.split(":")[1] ?? null : null;
+}
+class MemoryPolicy {
+    authorize(actor, operation, scope) {
+        const owner = privateOwner(scope);
+        if (owner !== null && owner !== actor.id) {
+            return (0, types_1.deny)("PRIVATE_MEMORY_DENIED", `\`${actor.id}\` cannot ${operation} private memory for \`${owner}\``);
+        }
+        const grants = actor.capabilities.memory[operation];
+        if (!grants.some((grant) => (0, memory_grant_1.memoryGrantCovers)(grant, scope))) {
+            return (0, types_1.deny)("MEMORY_NOT_GRANTED", `\`${actor.id}\` has no ${operation} grant for \`${scope}\``);
+        }
+        return types_1.ALLOW;
+    }
+}
+exports.MemoryPolicy = MemoryPolicy;

package/dist/src/policy/policy-engine.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyEngine = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const capability_policy_1 = require("./capability-policy");
+const delegation_policy_1 = require("./delegation-policy");
+const invariants_1 = require("./invariants");
+const memory_policy_1 = require("./memory-policy");
+const types_1 = require("./types");
+const workspace_policy_1 = require("./workspace-policy");
+function canonicalizePath(value) {
+    const absolute = (0, node_path_1.resolve)(value);
+    try {
+        return (0, node_fs_1.realpathSync)(absolute);
+    }
+    catch {
+        try {
+            return (0, node_path_1.join)((0, node_fs_1.realpathSync)((0, node_path_1.dirname)(absolute)), (0, node_path_1.basename)(absolute));
+        }
+        catch {
+            return absolute;
+        }
+    }
+}
+class PolicyEngine {
+    registry;
+    delegation;
+    memory = new memory_policy_1.MemoryPolicy();
+    capability = new capability_policy_1.CapabilityPolicy();
+    workspace;
+    constructor(options) {
+        this.registry = options.registry;
+        this.delegation = new delegation_policy_1.DelegationPolicy(options.registry);
+        this.workspace = new workspace_policy_1.WorkspacePolicy(options.registry, options.canonicalizePath ?? canonicalizePath);
+    }
+    authorize(request) {
+        if (!request || typeof request !== "object" || !("actor" in request)) {
+            return (0, types_1.deny)("UNKNOWN_REQUEST", "unrecognized policy request");
+        }
+        if (!this.registry.has(request.actor)) {
+            return (0, types_1.deny)("UNKNOWN_ACTOR", `unknown actor \`${request.actor}\``);
+        }
+        const actor = this.registry.get(request.actor);
+        switch (request.type) {
+            case "delegation":
+                return this.delegation.authorize(request.actor, request.target);
+            case "memory":
+                return this.memory.authorize(actor, request.operation, request.scope);
+            case "workspace":
+                return this.workspace.authorize(request.actor, request.operation, request.path, request.execution);
+            case "configuration":
+                return request.target.kind === "policy-source"
+                    ? (0, types_1.deny)("POLICY_MUTATION_DENIED", `\`${request.actor}\` cannot mutate policy source`)
+                    : (0, types_1.deny)("DEFINITION_MUTATION_DENIED", `\`${request.actor}\` cannot mutate agent definition \`${request.target.agentId}\``);
+            case "skill":
+                return this.capability.authorize(actor, "skill", request.skill, actor.capabilities.skills, "SKILL_NOT_GRANTED");
+            case "subagent":
+                return this.capability.authorize(actor, "subagent", request.subagent, actor.capabilities.subagents, "SUBAGENT_NOT_GRANTED");
+            case "mcp":
+                return this.capability.authorize(actor, "mcp server", request.server, actor.capabilities.mcpServers, "MCP_SERVER_NOT_GRANTED");
+            case "tool": {
+                if ((0, invariants_1.isRawRuntimeTool)(request.tool) ||
+                    (request.command !== undefined && (0, invariants_1.invokesRawRuntime)(request.command))) {
+                    return (0, types_1.deny)("RAW_RUNTIME_TOOL_DENIED", `raw runtime tool \`${request.tool}\` is not part of the ALP delegation API`);
+                }
+                if (request.command !== undefined &&
+                    (0, invariants_1.hasIndirectCommand)(request.command)) {
+                    return (0, types_1.deny)("INDIRECT_TOOL_REQUEST", `indirect command cannot be authorized safely`);
+                }
+                const server = (0, capability_policy_1.mcpServerOf)(request.tool);
+                if (server !== null) {
+                    return this.capability.authorize(actor, "mcp server", server, actor.capabilities.mcpServers, "MCP_SERVER_NOT_GRANTED");
+                }
+                if (!actor.capabilities.tools.some((tool) => tool === request.tool)) {
+                    return (0, types_1.deny)("TOOL_NOT_GRANTED", `\`${request.tool}\` is not granted to \`${request.actor}\``);
+                }
+                return types_1.ALLOW;
+            }
+            default:
+                return (0, types_1.deny)("UNKNOWN_REQUEST", "unrecognized policy request");
+        }
+    }
+}
+exports.PolicyEngine = PolicyEngine;

package/dist/src/policy/types.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOW = void 0;
+exports.deny = deny;
+exports.ALLOW = Object.freeze({ allowed: true });
+function deny(code, reason) {
+    return Object.freeze({ allowed: false, code, reason });
+}

package/dist/src/policy/workspace-policy.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspacePolicy = void 0;
+const node_path_1 = require("node:path");
+const errors_1 = require("./errors");
+const types_1 = require("./types");
+function within(root, target) {
+    const relation = (0, node_path_1.relative)(root, target);
+    return relation === "" || (!relation.startsWith("..") && !(0, node_path_1.isAbsolute)(relation));
+}
+/**
+ * Resolves a role's declared roots for *this* execution.
+ *
+ * A relative root — `"."`, which every code-native role declares — means "the workspace
+ * this execution was launched against", not "wherever the launcher process happened to be
+ * standing". Resolving it once, at construction, against the launcher's cwd is what made
+ * `alp delegate review --project ~/code/api` deny every path inside the project it was
+ * pointed at, from any directory but the launcher's own. Absolute roots are unaffected and
+ * still mean exactly what they say.
+ *
+ * Per-request rather than cached: an execution's active workspace is what a grant is
+ * relative to, so there is nothing stable to cache under the role's id.
+ */
+function canonicalizeRoots(definition, activeWorkspace, canonicalizePath) {
+    const resolve = (root) => canonicalizePath((0, node_path_1.isAbsolute)(root) ? root : (0, node_path_1.join)(activeWorkspace, root));
+    try {
+        return Object.freeze({
+            readRoots: Object.freeze(definition.capabilities.workspace.readRoots.map(resolve)),
+            writeRoots: Object.freeze(definition.capabilities.workspace.writeRoots.map(resolve)),
+        });
+    }
+    catch (error) {
+        throw new errors_1.InvalidPolicyStateError(`cannot canonicalize workspace grants for \`${definition.id}\``, { cause: error });
+    }
+}
+class WorkspacePolicy {
+    canonicalizePath;
+    definitions = new Map();
+    constructor(registry, canonicalizePath) {
+        this.canonicalizePath = canonicalizePath;
+        for (const definition of registry.list()) {
+            this.definitions.set(definition.id, definition);
+        }
+    }
+    authorize(actor, operation, inputPath, execution) {
+        if (operation === "write" && execution.workspaceMode === "read-only") {
+            return (0, types_1.deny)("WORKSPACE_READ_ONLY", `execution workspace \`${execution.activeWorkspace}\` is read-only`);
+        }
+        let target;
+        let activeWorkspace;
+        try {
+            target = this.canonicalizePath(inputPath);
+            activeWorkspace = this.canonicalizePath(execution.activeWorkspace);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return (0, types_1.deny)("PATH_RESOLUTION_FAILED", `cannot canonicalize workspace path: ${reason}`);
+        }
+        const definition = this.definitions.get(actor);
+        if (!definition) {
+            throw new errors_1.InvalidPolicyStateError(`missing workspace grants for \`${actor}\``);
+        }
+        const grants = canonicalizeRoots(definition, activeWorkspace, this.canonicalizePath);
+        if (execution.delegated && !within(activeWorkspace, target)) {
+            return (0, types_1.deny)("WORKSPACE_SCOPE_MISMATCH", `delegated execution is scoped to \`${activeWorkspace}\`, not \`${target}\``);
+        }
+        if (!grants.readRoots.some((root) => within(root, target))) {
+            return (0, types_1.deny)("WORKSPACE_NOT_GRANTED", `\`${actor}\` cannot read workspace path \`${target}\``);
+        }
+        if (operation === "write" &&
+            !grants.writeRoots.some((root) => within(root, target))) {
+            return (0, types_1.deny)("WORKSPACE_NOT_GRANTED", `\`${actor}\` cannot write workspace path \`${target}\``);
+        }
+        return types_1.ALLOW;
+    }
+}
+exports.WorkspacePolicy = WorkspacePolicy;

package/dist/src/principal/principal-profile-store.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRINCIPAL_FIELD_LIMIT = void 0;
+exports.principalProfileFile = principalProfileFile;
+exports.normalizePrincipalField = normalizePrincipalField;
+exports.normalizePrincipalProfile = normalizePrincipalProfile;
+exports.readPrincipalProfile = readPrincipalProfile;
+exports.writePrincipalProfile = writePrincipalProfile;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** Long enough for a full name, short enough that a stray paste cannot flood every prompt. */
+exports.PRINCIPAL_FIELD_LIMIT = 60;
+function principalProfileFile(env = process.env) {
+    return (0, node_path_1.join)(env.HOME || (0, node_os_1.homedir)(), ".alp", "principal.json");
+}
+/**
+ * Collapses whitespace and rejects empties — these strings are interpolated straight into
+ * every role's instructions, so a newline here would silently become a new prompt line.
+ */
+function normalizePrincipalField(label, value) {
+    const cleaned = value.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim();
+    if (cleaned === "")
+        throw new Error(`${label} is required`);
+    if (cleaned.length > exports.PRINCIPAL_FIELD_LIMIT) {
+        throw new Error(`${label} must be at most ${exports.PRINCIPAL_FIELD_LIMIT} characters`);
+    }
+    return cleaned;
+}
+function normalizePrincipalProfile(input) {
+    return Object.freeze({
+        name: normalizePrincipalField("name", input.name),
+        addressAs: normalizePrincipalField("form of address", input.addressAs),
+        selfAs: normalizePrincipalField("agent self-reference", input.selfAs),
+    });
+}
+/**
+ * Synchronous on purpose: `AgentDefinition.instructions()` is sync and is called while
+ * rendering identity documents and identity capsules. The file is a few dozen bytes and is
+ * read at most once per role render, so there is no cache to go stale after `alp init`
+ * writes the profile in the same process.
+ */
+function readPrincipalProfile(file = principalProfileFile()) {
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { profile: null };
+        return { profile: null, warning: `cannot read principal profile at ${file}` };
+    }
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed === null || typeof parsed !== "object" || parsed.version !== 1) {
+            throw new Error("unsupported principal profile");
+        }
+        return {
+            profile: normalizePrincipalProfile({
+                name: String(parsed.name ?? ""),
+                addressAs: String(parsed.addressAs ?? ""),
+                selfAs: String(parsed.selfAs ?? ""),
+            }),
+        };
+    }
+    catch {
+        return { profile: null, warning: `invalid principal profile at ${file}; run \`alp principal set\`` };
+    }
+}
+async function writePrincipalProfile(profile, file = principalProfileFile()) {
+    const normalized = normalizePrincipalProfile(profile);
+    const directory = (0, node_path_1.dirname)(file);
+    await (0, promises_1.mkdir)(directory, { recursive: true, mode: 0o700 });
+    await (0, promises_1.chmod)(directory, 0o700);
+    const temporary = (0, node_path_1.join)(directory, `.${(0, node_crypto_1.randomUUID)()}.principal.tmp`);
+    try {
+        await (0, promises_1.writeFile)(temporary, `${JSON.stringify({ version: 1, ...normalized }, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+        await (0, promises_1.chmod)(temporary, 0o600);
+        await (0, promises_1.rename)(temporary, file);
+        await (0, promises_1.chmod)(file, 0o600);
+    }
+    catch (error) {
+        await (0, promises_1.rm)(temporary, { force: true });
+        throw error;
+    }
+    return normalized;
+}