spawnfile 0.1.1 → 0.1.3

package/dist/compiler/moltnetResolution.js

@@ -0,0 +1,182 @@
+import { SpawnfileError } from "../shared/index.js";
+import { resolveMoltnetRoomMemberships } from "./moltnetRoomMemberships.js";
+import { resolveMoltnetAttachments } from "./moltnetRepresentativeResolution.js";
+export { resolveMoltnetAttachments, resolveTeamRepresentatives } from "./moltnetRepresentativeResolution.js";
+const findTeamBySource = (plan, source) => {
+    const node = plan.nodes.find((entry) => entry.kind === "team" && entry.value.source === source);
+    if (!node || node.value.kind !== "team") {
+        throw new SpawnfileError("compile_error", `Unable to find team node at ${source}`);
+    }
+    return node.value;
+};
+const hasMoltnetIntent = (plan) => plan.nodes.some((node) => {
+    if (node.value.kind === "team") {
+        return (node.value.networks?.length ?? 0) > 0;
+    }
+    return (node.value.surfaces?.moltnet?.length ?? 0) > 0;
+});
+const validateGlobalMemberIds = (plan) => {
+    if (!hasMoltnetIntent(plan)) {
+        return;
+    }
+    const seen = new Map();
+    const uniqueContexts = new Map((plan.memberships ?? []).map((context) => [
+        `${context.teamSource}::${context.memberId}::${context.agentSource}`,
+        context
+    ]));
+    for (const context of uniqueContexts.values()) {
+        const previous = seen.get(context.memberId);
+        const label = `${context.teamName} (${context.teamSource}) member ${context.memberId}`;
+        if (previous && previous !== label) {
+            throw new SpawnfileError("validation_error", `Moltnet member_id ${context.memberId} is declared by multiple direct agent member slots: ${previous}; ${label}`);
+        }
+        seen.set(context.memberId, label);
+    }
+};
+const getRoomMemberships = (plan) => {
+    const memberships = plan.moltnetRoomMemberships ?? resolveMoltnetRoomMemberships(plan);
+    plan.moltnetRoomMemberships = memberships;
+    return memberships;
+};
+const synthesizeRepresentativeAttachments = (memberships) => memberships
+    .filter((membership) => membership.representedSlot !== undefined)
+    .map((membership) => ({
+    contextRooms: {
+        [membership.declaringTeamSource]: [membership.roomId]
+    },
+    memberId: membership.concreteMemberId,
+    network: membership.networkId,
+    rooms: {
+        [membership.roomId]: {}
+    },
+    teamSource: membership.declaringTeamSource
+}));
+const roomPolicyKey = (policy) => JSON.stringify(policy ?? {});
+const hasRoomPolicy = (policy) => policy.read !== undefined || policy.reply !== undefined;
+const mergeAttachment = (target, next, nodeName) => {
+    if (target.dms &&
+        next.dms &&
+        roomPolicyKey(target.dms) !== roomPolicyKey(next.dms)) {
+        throw new SpawnfileError("validation_error", `Agent ${nodeName} declares incompatible Moltnet dms for ${next.network}/${next.memberId ?? "unknown"}`);
+    }
+    target.dms ??= next.dms ? { ...next.dms } : undefined;
+    target.teamSource ??= next.teamSource;
+    target.rooms ??= {};
+    for (const [roomId, policy] of Object.entries(next.rooms ?? {})) {
+        const existingPolicy = target.rooms[roomId];
+        const existingHasPolicy = existingPolicy ? hasRoomPolicy(existingPolicy) : false;
+        const nextHasPolicy = hasRoomPolicy(policy);
+        if (existingHasPolicy &&
+            nextHasPolicy &&
+            roomPolicyKey(existingPolicy) !== roomPolicyKey(policy)) {
+            throw new SpawnfileError("validation_error", `Agent ${nodeName} declares incompatible Moltnet room policy for ${next.network}/${next.memberId ?? "unknown"} room ${roomId}`);
+        }
+        target.rooms[roomId] = existingPolicy && existingHasPolicy && !nextHasPolicy
+            ? { ...existingPolicy }
+            : { ...policy };
+    }
+    if (next.contextRooms) {
+        target.contextRooms ??= {};
+        for (const [teamSource, roomIds] of Object.entries(next.contextRooms)) {
+            target.contextRooms[teamSource] = [
+                ...new Set([...(target.contextRooms[teamSource] ?? []), ...roomIds])
+            ].sort();
+        }
+    }
+    else if (next.teamSource) {
+        target.contextRooms ??= {};
+        target.contextRooms[next.teamSource] = [
+            ...new Set([
+                ...(target.contextRooms[next.teamSource] ?? []),
+                ...Object.keys(next.rooms ?? {})
+            ])
+        ].sort();
+    }
+};
+const mergeAgentAttachments = (agentNode, attachments) => {
+    const merged = new Map();
+    for (const attachment of attachments) {
+        const key = `${attachment.network}::${attachment.memberId ?? ""}`;
+        const existing = merged.get(key);
+        if (existing) {
+            mergeAttachment(existing, attachment, agentNode.name);
+            continue;
+        }
+        merged.set(key, {
+            contextRooms: attachment.contextRooms
+                ? Object.fromEntries(Object.entries(attachment.contextRooms).map(([teamSource, roomIds]) => [
+                    teamSource,
+                    [...roomIds].sort()
+                ]))
+                : attachment.teamSource
+                    ? { [attachment.teamSource]: Object.keys(attachment.rooms ?? {}).sort() }
+                    : undefined,
+            ...(attachment.dms ? { dms: { ...attachment.dms } } : {}),
+            memberId: attachment.memberId,
+            network: attachment.network,
+            ...(attachment.rooms
+                ? {
+                    rooms: Object.fromEntries(Object.entries(attachment.rooms).map(([roomId, policy]) => [
+                        roomId,
+                        { ...policy }
+                    ]))
+                }
+                : {}),
+            teamSource: attachment.teamSource
+        });
+    }
+    return [...merged.values()].sort((left, right) => `${left.network}:${left.memberId ?? ""}`.localeCompare(`${right.network}:${right.memberId ?? ""}`));
+};
+export const resolvePlanMoltnetAttachments = (plan) => {
+    validateGlobalMemberIds(plan);
+    const roomMemberships = getRoomMemberships(plan);
+    const synthesizedAttachments = synthesizeRepresentativeAttachments(roomMemberships);
+    const synthesizedByAgent = new Map();
+    for (const attachment of synthesizedAttachments) {
+        const representativeContext = (plan.memberships ?? []).find((context) => context.memberId === attachment.memberId);
+        if (!representativeContext) {
+            throw new SpawnfileError("validation_error", `Unable to find direct member context for synthesized Moltnet member ${attachment.memberId ?? "unknown"}`);
+        }
+        const group = synthesizedByAgent.get(representativeContext.agentSource) ?? [];
+        group.push(attachment);
+        synthesizedByAgent.set(representativeContext.agentSource, group);
+    }
+    for (const node of plan.nodes) {
+        if (node.value.kind !== "agent") {
+            continue;
+        }
+        const agentNode = node.value;
+        const declaredAttachments = agentNode.surfaces?.moltnet;
+        const directContexts = (plan.memberships ?? []).filter((context) => context.agentSource === agentNode.source);
+        const resolvedAttachments = [];
+        if (declaredAttachments && directContexts.length === 0) {
+            throw new SpawnfileError("validation_error", `Agent ${agentNode.name} declares Moltnet surfaces but is not attached to a team network`);
+        }
+        for (const context of directContexts) {
+            if (!declaredAttachments) {
+                continue;
+            }
+            const teamNode = findTeamBySource(plan, context.teamSource);
+            const resolved = resolveMoltnetAttachments(declaredAttachments, {
+                memberId: context.memberId,
+                networks: teamNode.networks ?? [],
+                teamName: context.teamName,
+                teamSource: context.teamSource
+            }, agentNode.name);
+            resolvedAttachments.push(...(resolved ?? []));
+        }
+        resolvedAttachments.push(...(synthesizedByAgent.get(agentNode.source) ?? []));
+        if (resolvedAttachments.length > 0) {
+            agentNode.surfaces = {
+                ...agentNode.surfaces,
+                moltnet: mergeAgentAttachments(agentNode, resolvedAttachments)
+            };
+        }
+        else if (agentNode.surfaces?.moltnet) {
+            agentNode.surfaces = {
+                ...agentNode.surfaces,
+                moltnet: undefined
+            };
+        }
+    }
+};

package/dist/compiler/moltnetRoomMemberships.d.ts

@@ -0,0 +1,3 @@
+import type { CompilePlan, ResolvedMoltnetRoomMembership, ResolvedTeamNetworkRoom, ResolvedTeamNode } from "./types.js";
+export declare const listConcreteMoltnetRoomMemberIds: (plan: CompilePlan, teamNode: ResolvedTeamNode, networkId: string, room: ResolvedTeamNetworkRoom, memberships?: ResolvedMoltnetRoomMembership[] | undefined) => string[];
+export declare const resolveMoltnetRoomMemberships: (plan: CompilePlan) => ResolvedMoltnetRoomMembership[];

package/dist/compiler/moltnetRoomMemberships.js

@@ -0,0 +1,140 @@
+import { SpawnfileError } from "../shared/index.js";
+import { resolveTeamRepresentatives } from "./moltnetRepresentativeResolution.js";
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const findAgentBySource = (plan, source) => {
+    const node = plan.nodes.find((entry) => entry.kind === "agent" && entry.value.source === source);
+    if (!node || node.value.kind !== "agent") {
+        throw new SpawnfileError("compile_error", `Unable to find agent node at ${source}`);
+    }
+    return node.value;
+};
+const findTeamBySource = (plan, source) => {
+    const node = plan.nodes.find((entry) => entry.kind === "team" && entry.value.source === source);
+    if (!node || node.value.kind !== "team") {
+        throw new SpawnfileError("compile_error", `Unable to find team node at ${source}`);
+    }
+    return node.value;
+};
+const clonePolicy = (policy) => ({
+    ...(policy.read ? { read: policy.read } : {}),
+    ...(policy.reply ? { reply: policy.reply } : {})
+});
+const findDirectRoomPolicy = (plan, teamNode, agentSource, memberId, networkId, roomId) => {
+    const agentNode = findAgentBySource(plan, agentSource);
+    for (const attachment of agentNode.surfaces?.moltnet ?? []) {
+        if (attachment.network !== networkId) {
+            continue;
+        }
+        if (attachment.teamSource && attachment.teamSource !== teamNode.source) {
+            continue;
+        }
+        if (attachment.memberId && attachment.memberId !== memberId) {
+            continue;
+        }
+        if (!attachment.rooms || !hasOwn(attachment.rooms, roomId)) {
+            continue;
+        }
+        return clonePolicy(attachment.rooms[roomId] ?? {});
+    }
+    return undefined;
+};
+const compareRoomMemberships = (left, right) => [
+    left.declaringTeamSource.localeCompare(right.declaringTeamSource),
+    left.networkId.localeCompare(right.networkId),
+    left.roomId.localeCompare(right.roomId),
+    left.declaredSlot.localeCompare(right.declaredSlot),
+    (left.representativePath ?? []).join("/").localeCompare((right.representativePath ?? []).join("/")),
+    left.concreteMemberId.localeCompare(right.concreteMemberId),
+    left.agentSource.localeCompare(right.agentSource)
+].find((result) => result !== 0) ?? 0;
+export const listConcreteMoltnetRoomMemberIds = (plan, teamNode, networkId, room, memberships = plan.moltnetRoomMemberships) => {
+    if (memberships) {
+        return [
+            ...new Set(memberships
+                .filter((membership) => membership.declaringTeamSource === teamNode.source
+                && membership.networkId === networkId
+                && membership.roomId === room.id)
+                .map((membership) => membership.concreteMemberId))
+        ].sort();
+    }
+    const concreteMembers = [];
+    for (const declaredSlot of room.members) {
+        const member = teamNode.members.find((entry) => entry.id === declaredSlot);
+        if (!member) {
+            throw new SpawnfileError("validation_error", `Team ${teamNode.name} Moltnet room ${room.id} references unknown member ${declaredSlot}`);
+        }
+        if (member.kind === "agent") {
+            concreteMembers.push(member.id);
+            continue;
+        }
+        const childTeam = findTeamBySource(plan, member.nodeSource);
+        const representatives = resolveTeamRepresentatives(plan, childTeam);
+        if (representatives.length === 0) {
+            throw new SpawnfileError("validation_error", `Team ${childTeam.name} has no concrete representative for Moltnet room ${room.id} on ${teamNode.name}`);
+        }
+        concreteMembers.push(...representatives.map((representative) => representative.memberId));
+    }
+    return [...new Set(concreteMembers)].sort();
+};
+export const resolveMoltnetRoomMemberships = (plan) => {
+    const memberships = [];
+    for (const node of plan.nodes) {
+        if (node.value.kind !== "team") {
+            continue;
+        }
+        const teamNode = node.value;
+        for (const network of teamNode.networks ?? []) {
+            for (const room of network.rooms) {
+                for (const declaredSlot of room.members) {
+                    const declaredMember = teamNode.members.find((member) => member.id === declaredSlot);
+                    if (!declaredMember) {
+                        throw new SpawnfileError("validation_error", `Team ${teamNode.name} Moltnet room ${room.id} references unknown member ${declaredSlot}`);
+                    }
+                    if (declaredMember.kind === "agent") {
+                        const agentNode = findAgentBySource(plan, declaredMember.nodeSource);
+                        const policy = findDirectRoomPolicy(plan, teamNode, agentNode.source, declaredSlot, network.id, room.id);
+                        memberships.push({
+                            agentName: agentNode.name,
+                            agentSource: agentNode.source,
+                            concreteMemberId: declaredSlot,
+                            declaredSlot,
+                            declaringTeamName: teamNode.name,
+                            declaringTeamSource: teamNode.source,
+                            directTeamName: teamNode.name,
+                            directTeamSource: teamNode.source,
+                            networkId: network.id,
+                            ...(policy ? { policy } : {}),
+                            roomId: room.id
+                        });
+                        continue;
+                    }
+                    const childTeam = findTeamBySource(plan, declaredMember.nodeSource);
+                    const representatives = resolveTeamRepresentatives(plan, childTeam);
+                    if (representatives.length === 0) {
+                        throw new SpawnfileError("validation_error", `Team ${childTeam.name} has no concrete representative for Moltnet room ${room.id} on ${teamNode.name}`);
+                    }
+                    for (const representative of representatives) {
+                        const agentNode = findAgentBySource(plan, representative.agentSource);
+                        memberships.push({
+                            agentName: agentNode.name,
+                            agentSource: agentNode.source,
+                            concreteMemberId: representative.memberId,
+                            declaredSlot,
+                            declaringTeamName: teamNode.name,
+                            declaringTeamSource: teamNode.source,
+                            directTeamName: representative.sourceTeamName,
+                            directTeamSource: representative.sourceTeamSource,
+                            networkId: network.id,
+                            representedSlot: declaredSlot,
+                            representedTeamName: childTeam.name,
+                            representedTeamSource: childTeam.source,
+                            representativePath: [declaredSlot, ...representative.path],
+                            roomId: room.id
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return memberships.sort(compareRoomMemberships);
+};

package/dist/compiler/runProject.js

@@ -22,7 +22,7 @@ const createDefaultContainerName = (imageTag) => {
 };
 const getImportMountTargetName = (kind) => kind === "claude-code" ? ".claude" : ".codex";
 const createGeneratedRuntimeSecret = (secretName) => {
-    if (secretName === "OPENCLAW_GATEWAY_TOKEN") {
+    if (secretName === "OPENCLAW_GATEWAY_TOKEN" || secretName === "OPENCLAW_HOOKS_TOKEN") {
         return randomBytes(24).toString("hex");
     }
     return null;

package/dist/compiler/surfaceDefinitions.d.ts

@@ -0,0 +1,55 @@
+import type { AgentManifest, SurfacesBlock, TeamManifest } from "../manifest/index.js";
+type ProjectManifest = AgentManifest | TeamManifest;
+export type SurfaceAccessMode = "allowlist" | "open" | "pairing";
+export declare const PORTABLE_SURFACE_NAMES: readonly ["discord", "slack", "telegram", "whatsapp"];
+export type SurfaceName = (typeof PORTABLE_SURFACE_NAMES)[number];
+export interface ProjectSurfaceSecretOptions {
+    appTokenSecret?: string;
+    botTokenSecret?: string;
+}
+export interface AddProjectSurfaceOptions extends ProjectSurfaceSecretOptions {
+    path?: string;
+    recursive?: boolean;
+    surface: string;
+}
+export interface ProjectSurfaceAccessOptions {
+    channels?: string[];
+    chats?: string[];
+    groups?: string[];
+    guilds?: string[];
+    mode: SurfaceAccessMode;
+    path?: string;
+    recursive?: boolean;
+    surface: string;
+    users?: string[];
+}
+export interface RemoveProjectSurfaceOptions {
+    path?: string;
+    recursive?: boolean;
+    surface: string;
+}
+export interface ShowProjectSurfacesOptions {
+    path?: string;
+    recursive?: boolean;
+}
+export interface ProjectSurfaceSummary {
+    kind: "agent" | "team";
+    manifestPath: string;
+    name: string;
+    surfaces?: SurfacesBlock;
+}
+export interface ProjectSurfaceSummariesResult {
+    entries: ProjectSurfaceSummary[];
+}
+export interface UpdateProjectSurfacesResult {
+    updatedFiles: string[];
+}
+export declare const TEAM_SURFACE_COMMAND_ERROR = "spawnfile surface commands only write agent manifests; use --recursive to update descendant agents of a team project";
+export declare const getRuntimeName: (runtime: AgentManifest["runtime"]) => string | undefined;
+export declare const resolvePortableSurfaceName: (surface: string) => SurfaceName;
+export declare const assertSurfaceMutationAllowed: (manifest: ProjectManifest, recursive: boolean) => manifest is AgentManifest;
+export declare const upsertSurface: (surfaces: SurfacesBlock | undefined, options: AddProjectSurfaceOptions) => SurfacesBlock;
+export declare const updateSurfaceAccess: (surfaces: SurfacesBlock | undefined, options: ProjectSurfaceAccessOptions, manifestPath: string, recursive: boolean) => SurfacesBlock | null;
+export declare const removeSurface: (surfaces: SurfacesBlock | undefined, surface: string) => SurfacesBlock | undefined;
+export declare const validateAgentSurfaceSupport: (manifest: AgentManifest) => void;
+export {};

package/dist/compiler/surfaceDefinitions.js

@@ -0,0 +1,204 @@
+import { SpawnfileError } from "../shared/index.js";
+import { resolveAgentSurfaces } from "./agentSurfaces.js";
+import { assertRuntimeSupportsAgentSurfaces } from "./surfaceSupport.js";
+export const PORTABLE_SURFACE_NAMES = ["discord", "slack", "telegram", "whatsapp"];
+export const TEAM_SURFACE_COMMAND_ERROR = "spawnfile surface commands only write agent manifests; use --recursive to update descendant agents of a team project";
+export const getRuntimeName = (runtime) => typeof runtime === "string" ? runtime : runtime?.name;
+export const resolvePortableSurfaceName = (surface) => {
+    if (!PORTABLE_SURFACE_NAMES.includes(surface)) {
+        throw new SpawnfileError("validation_error", `Unsupported portable surface ${surface}; expected one of: ${PORTABLE_SURFACE_NAMES.join(", ")}`);
+    }
+    return surface;
+};
+export const assertSurfaceMutationAllowed = (manifest, recursive) => {
+    if (manifest.kind === "agent") {
+        return true;
+    }
+    if (recursive) {
+        return false;
+    }
+    throw new SpawnfileError("validation_error", TEAM_SURFACE_COMMAND_ERROR);
+};
+const normalizeEntries = (values) => {
+    const normalized = [...new Set((values ?? []).map((value) => value.trim()).filter(Boolean))].sort();
+    return normalized.length > 0 ? normalized : undefined;
+};
+const validateSecrets = (surface, options) => {
+    if (options.appTokenSecret && surface !== "slack") {
+        throw new SpawnfileError("validation_error", "--app-token-secret is only valid for slack surfaces");
+    }
+    if (options.botTokenSecret && !["discord", "slack", "telegram"].includes(surface)) {
+        throw new SpawnfileError("validation_error", `--bot-token-secret is not valid for ${surface} surfaces`);
+    }
+};
+const buildDiscordAccess = (options) => {
+    const users = normalizeEntries(options.users);
+    const guilds = normalizeEntries(options.guilds);
+    const channels = normalizeEntries(options.channels);
+    const hasAllowlistEntries = Boolean(users || guilds || channels);
+    if (options.mode === "allowlist" && !hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "discord allowlist access requires at least one --user, --guild, or --channel");
+    }
+    if (options.mode !== "allowlist" && hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "discord allowlist entries are only valid with --mode allowlist");
+    }
+    return {
+        ...(channels ? { channels } : {}),
+        ...(guilds ? { guilds } : {}),
+        mode: options.mode,
+        ...(users ? { users } : {})
+    };
+};
+const buildTelegramAccess = (options) => {
+    const users = normalizeEntries(options.users);
+    const chats = normalizeEntries(options.chats);
+    const hasAllowlistEntries = Boolean(users || chats);
+    if (options.mode === "allowlist" && !hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "telegram allowlist access requires at least one --user or --chat");
+    }
+    if (options.mode !== "allowlist" && hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "telegram allowlist entries are only valid with --mode allowlist");
+    }
+    return {
+        ...(chats ? { chats } : {}),
+        mode: options.mode,
+        ...(users ? { users } : {})
+    };
+};
+const buildWhatsAppAccess = (options) => {
+    const users = normalizeEntries(options.users);
+    const groups = normalizeEntries(options.groups);
+    const hasAllowlistEntries = Boolean(users || groups);
+    if (options.mode === "allowlist" && !hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "whatsapp allowlist access requires at least one --user or --group");
+    }
+    if (options.mode !== "allowlist" && hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "whatsapp allowlist entries are only valid with --mode allowlist");
+    }
+    return {
+        ...(groups ? { groups } : {}),
+        mode: options.mode,
+        ...(users ? { users } : {})
+    };
+};
+const buildSlackAccess = (options) => {
+    const users = normalizeEntries(options.users);
+    const channels = normalizeEntries(options.channels);
+    const hasAllowlistEntries = Boolean(users || channels);
+    if (options.mode === "allowlist" && !hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "slack allowlist access requires at least one --user or --channel");
+    }
+    if (options.mode !== "allowlist" && hasAllowlistEntries) {
+        throw new SpawnfileError("validation_error", "slack allowlist entries are only valid with --mode allowlist");
+    }
+    return {
+        ...(channels ? { channels } : {}),
+        mode: options.mode,
+        ...(users ? { users } : {})
+    };
+};
+const buildSurfaceAccess = (options) => {
+    const surface = resolvePortableSurfaceName(options.surface);
+    switch (surface) {
+        case "discord":
+            return buildDiscordAccess(options);
+        case "telegram":
+            return buildTelegramAccess(options);
+        case "whatsapp":
+            return buildWhatsAppAccess(options);
+        case "slack":
+            return buildSlackAccess(options);
+    }
+};
+export const upsertSurface = (surfaces, options) => {
+    const surface = resolvePortableSurfaceName(options.surface);
+    validateSecrets(surface, options);
+    const nextSurfaces = { ...(surfaces ?? {}) };
+    switch (surface) {
+        case "discord":
+            nextSurfaces.discord = {
+                ...(surfaces?.discord ?? {}),
+                ...(options.botTokenSecret ? { bot_token_secret: options.botTokenSecret } : {})
+            };
+            break;
+        case "telegram":
+            nextSurfaces.telegram = {
+                ...(surfaces?.telegram ?? {}),
+                ...(options.botTokenSecret ? { bot_token_secret: options.botTokenSecret } : {})
+            };
+            break;
+        case "whatsapp":
+            nextSurfaces.whatsapp = {
+                ...(surfaces?.whatsapp ?? {})
+            };
+            break;
+        case "slack":
+            nextSurfaces.slack = {
+                ...(surfaces?.slack ?? {}),
+                ...(options.appTokenSecret ? { app_token_secret: options.appTokenSecret } : {}),
+                ...(options.botTokenSecret ? { bot_token_secret: options.botTokenSecret } : {})
+            };
+            break;
+    }
+    return nextSurfaces;
+};
+export const updateSurfaceAccess = (surfaces, options, manifestPath, recursive) => {
+    const surface = resolvePortableSurfaceName(options.surface);
+    const nextSurfaces = { ...(surfaces ?? {}) };
+    const access = buildSurfaceAccess({ ...options, surface });
+    switch (surface) {
+        case "discord":
+            if (!nextSurfaces.discord) {
+                if (recursive) {
+                    return null;
+                }
+                throw new SpawnfileError("validation_error", `Surface discord is not declared in ${manifestPath}; use spawnfile surface add discord first`);
+            }
+            nextSurfaces.discord = { ...nextSurfaces.discord, access: access };
+            break;
+        case "telegram":
+            if (!nextSurfaces.telegram) {
+                if (recursive) {
+                    return null;
+                }
+                throw new SpawnfileError("validation_error", `Surface telegram is not declared in ${manifestPath}; use spawnfile surface add telegram first`);
+            }
+            nextSurfaces.telegram = { ...nextSurfaces.telegram, access: access };
+            break;
+        case "whatsapp":
+            if (!nextSurfaces.whatsapp) {
+                if (recursive) {
+                    return null;
+                }
+                throw new SpawnfileError("validation_error", `Surface whatsapp is not declared in ${manifestPath}; use spawnfile surface add whatsapp first`);
+            }
+            nextSurfaces.whatsapp = { ...nextSurfaces.whatsapp, access: access };
+            break;
+        case "slack":
+            if (!nextSurfaces.slack) {
+                if (recursive) {
+                    return null;
+                }
+                throw new SpawnfileError("validation_error", `Surface slack is not declared in ${manifestPath}; use spawnfile surface add slack first`);
+            }
+            nextSurfaces.slack = { ...nextSurfaces.slack, access: access };
+            break;
+    }
+    return nextSurfaces;
+};
+export const removeSurface = (surfaces, surface) => {
+    const surfaceName = resolvePortableSurfaceName(surface);
+    if (!surfaces?.[surfaceName]) {
+        return surfaces;
+    }
+    const nextSurfaces = { ...surfaces };
+    delete nextSurfaces[surfaceName];
+    return Object.keys(nextSurfaces).length > 0 ? nextSurfaces : undefined;
+};
+export const validateAgentSurfaceSupport = (manifest) => {
+    const runtimeName = getRuntimeName(manifest.runtime);
+    if (!runtimeName) {
+        return;
+    }
+    assertRuntimeSupportsAgentSurfaces(runtimeName, resolveAgentSurfaces(manifest.surfaces), manifest.name);
+};

package/dist/compiler/teamContextHelpers.d.ts

@@ -0,0 +1,18 @@
+import type { EmittedFile } from "../runtime/index.js";
+import type { CompilePlan, ResolvedAgentNode, ResolvedMemberRef, ResolvedTeamNode } from "./types.js";
+import type { AgentContext, TeamContextIndex } from "./teamContextTypes.js";
+export declare const pathSafe: (value: string) => string;
+export declare const shortHash: (value: string) => string;
+export declare const reportKeySegment: (value: string) => string;
+export declare const findTeamBySource: (plan: CompilePlan, source: string) => ResolvedTeamNode | null;
+export declare const findAgentBySource: (plan: CompilePlan, source: string) => ResolvedAgentNode | null;
+export declare const getSystemTeamDoc: (teamNode: ResolvedTeamNode) => string;
+export declare const createContextBaseKey: (context: AgentContext) => string;
+export declare const collectMoltnetBindings: (agentNode: ResolvedAgentNode, teamSource: string, memberId: string) => Array<{
+    network: string;
+    rooms: string[];
+}>;
+export declare const createTeamCard: (contextKey: string, member: ResolvedMemberRef, childTeam: ResolvedTeamNode, representatives: string[]) => EmittedFile;
+export declare const buildContextOrientation: (index: TeamContextIndex) => string;
+export declare const createVisibleTeamCards: (plan: CompilePlan, contextKey: string, teamNode: ResolvedTeamNode, visibleMembers: ResolvedMemberRef[]) => EmittedFile[];
+export declare const generateContextRoster: (teamNode: ResolvedTeamNode, plan: CompilePlan, options: import("./teamRosterTypes.js").GenerateTeamRosterOptions) => import("./teamRosterTypes.js").GeneratedTeamRoster;