spawnfile 0.1.14 → 0.1.18

package/dist/manifest/mcpSchemas.d.ts

@@ -13,5 +13,67 @@ export declare const mcpServerSchema: z.ZodObject<{
         stdio: "stdio";
         streamable_http: "streamable_http";
     }>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
     url: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/**
+ * A team `shared.environment.mcp_servers` entry. `opt_in: true` means members
+ * do not inherit it unless they list its name in their own `mcp_servers`
+ * (a bare `{ name }` or a narrowing override). Absent or false keeps today's
+ * behaviour: every direct member inherits it.
+ */
+export declare const sharedMcpServerSchema: z.ZodObject<{
+    opt_in: z.ZodOptional<z.ZodBoolean>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodOptional<z.ZodLiteral<"bearer">>;
+        secret: z.ZodString;
+    }, z.core.$strict>>;
+    command: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    name: z.ZodString;
+    transport: z.ZodEnum<{
+        sse: "sse";
+        stdio: "stdio";
+        streamable_http: "streamable_http";
+    }>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SharedMcpServer = z.infer<typeof sharedMcpServerSchema>;
+/**
+ * An agent-level entry without `transport` narrows the inherited
+ * `shared.environment.mcp_servers` entry of the same name instead of replacing
+ * it: `tools` replaces the inherited allowlist and `env` is merged key by key.
+ * A bare `{ name }` takes the inherited server unchanged, which is how a
+ * member opts in to an `opt_in` shared server.
+ * Whether a server of that name is inherited is only known during graph
+ * resolution, so the compiler (not this schema) rejects an orphan override.
+ */
+export declare const mcpServerOverrideSchema: z.ZodObject<{
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    name: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type McpServerDeclaration = z.infer<typeof mcpServerSchema>;
+export type McpServerOverride = z.infer<typeof mcpServerOverrideSchema>;
+export type McpServerEntry = McpServerDeclaration | McpServerOverride;
+/** Agent-scope MCP entry: a complete server (has `transport`) or an override of an inherited one. */
+export declare const mcpServerEntrySchema: z.ZodPipe<z.ZodUnknown, z.ZodTransform<{
+    name: string;
+    transport: "sse" | "stdio" | "streamable_http";
+    args?: string[] | undefined;
+    auth?: {
+        secret: string;
+        mode?: "bearer" | undefined;
+    } | undefined;
+    command?: string | undefined;
+    env?: Record<string, string> | undefined;
+    tools?: string[] | undefined;
+    url?: string | undefined;
+} | {
+    name: string;
+    env?: Record<string, string> | undefined;
+    tools?: string[] | undefined;
+}, unknown>>;
+export declare const isMcpServerDeclaration: (entry: McpServerEntry) => entry is McpServerDeclaration;

package/dist/manifest/mcpSchemas.js

@@ -14,21 +14,26 @@ const mcpAuthSchema = z
         });
     }
 });
-export const mcpServerSchema = z
-    .object({
+const mcpToolsSchema = z.array(z.string().min(1)).max(32);
+const refineToolsAndName = (value, context) => {
+    if (value.tools !== undefined && (value.tools.length === 0 || new Set(value.tools).size !== value.tools.length))
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "MCP tools must be a nonempty unique allowlist" });
+    if (value.name.startsWith("spawnfile.") || value.name.startsWith("mneme-")) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "MCP server name is reserved for compiler-owned generated services" });
+    }
+};
+const mcpServerFields = {
     args: z.array(z.string()).optional(),
     auth: mcpAuthSchema.optional(),
     command: z.string().optional(),
     env: z.record(z.string(), z.string()).optional(),
     name: z.string().min(1),
     transport: z.enum(["sse", "stdio", "streamable_http"]),
+    tools: mcpToolsSchema.optional(),
     url: z.string().optional()
-})
-    .strict()
-    .superRefine((value, context) => {
-    if (value.name.startsWith("spawnfile.") || value.name.startsWith("mneme-")) {
-        context.addIssue({ code: z.ZodIssueCode.custom, message: "MCP server name is reserved for compiler-owned generated services" });
-    }
+};
+const refineServer = (value, context) => {
+    refineToolsAndName(value, context);
     if (value.transport === "stdio" && !value.command) {
         context.addIssue({ code: z.ZodIssueCode.custom, message: "stdio MCP servers must declare command" });
     }
@@ -38,4 +43,48 @@ export const mcpServerSchema = z
     if (value.transport !== "stdio" && !value.url) {
         context.addIssue({ code: z.ZodIssueCode.custom, message: `${value.transport} MCP servers must declare url` });
     }
+};
+export const mcpServerSchema = z.object(mcpServerFields).strict().superRefine(refineServer);
+/**
+ * A team `shared.environment.mcp_servers` entry. `opt_in: true` means members
+ * do not inherit it unless they list its name in their own `mcp_servers`
+ * (a bare `{ name }` or a narrowing override). Absent or false keeps today's
+ * behaviour: every direct member inherits it.
+ */
+export const sharedMcpServerSchema = z
+    .object({ ...mcpServerFields, opt_in: z.boolean().optional() })
+    .strict()
+    .superRefine(refineServer);
+/**
+ * An agent-level entry without `transport` narrows the inherited
+ * `shared.environment.mcp_servers` entry of the same name instead of replacing
+ * it: `tools` replaces the inherited allowlist and `env` is merged key by key.
+ * A bare `{ name }` takes the inherited server unchanged, which is how a
+ * member opts in to an `opt_in` shared server.
+ * Whether a server of that name is inherited is only known during graph
+ * resolution, so the compiler (not this schema) rejects an orphan override.
+ */
+export const mcpServerOverrideSchema = z
+    .object({
+    env: z.record(z.string(), z.string()).optional(),
+    name: z.string().min(1),
+    tools: mcpToolsSchema.optional()
+})
+    .strict()
+    .superRefine((value, context) => {
+    refineToolsAndName(value, context);
+});
+const hasTransportKey = (value) => typeof value === "object" && value !== null && Object.hasOwn(value, "transport");
+/** Agent-scope MCP entry: a complete server (has `transport`) or an override of an inherited one. */
+export const mcpServerEntrySchema = z.unknown().transform((value, context) => {
+    const result = hasTransportKey(value)
+        ? mcpServerSchema.safeParse(value)
+        : mcpServerOverrideSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    for (const issue of result.error.issues) {
+        context.addIssue({ code: "custom", message: issue.message, path: issue.path });
+    }
+    return z.NEVER;
 });
+export const isMcpServerDeclaration = (entry) => "transport" in entry;

package/dist/manifest/memorySchemas.d.ts

@@ -76,7 +76,7 @@ declare const memoryRetentionSchema: z.ZodObject<{
 declare const memoryAccessSchema: z.ZodObject<{
     members: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
-declare const memoryBankSchema: z.ZodObject<{
+export declare const memoryBankSchema: z.ZodObject<{
     access: z.ZodOptional<z.ZodObject<{
         members: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;

package/dist/manifest/memorySchemas.js

@@ -127,7 +127,7 @@ const memoryAccessSchema = z
     members: z.array(z.string().trim().min(1)).optional()
 })
     .strict();
-const memoryBankSchema = z
+export const memoryBankSchema = z
     .object({
     access: memoryAccessSchema.optional(),
     consolidation: memoryConsolidationSchema.optional(),

package/dist/manifest/parseManifest.d.ts

@@ -0,0 +1,7 @@
+import { type Manifest } from "./schemas.js";
+/**
+ * Parses one Spawnfile. Errors name the file, and the declared kind and name
+ * when the YAML got far enough to have them, so a member's malformed manifest
+ * is attributable from `spawnfile validate` on the organization root.
+ */
+export declare const parseManifest: (source: string, manifestPath: string) => Manifest;

package/dist/manifest/parseManifest.js

@@ -0,0 +1,65 @@
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { SpawnfileError } from "../shared/index.js";
+import { manifestSchema } from "./schemas.js";
+const describeManifest = (parsed, manifestPath) => {
+    const record = typeof parsed === "object" && parsed !== null ? parsed : {};
+    const kind = typeof record.kind === "string" ? record.kind : "manifest";
+    return typeof record.name === "string" && record.name.length > 0
+        ? `${kind} ${record.name} (${manifestPath})`
+        : manifestPath;
+};
+/**
+ * A union failure (a team member that is neither `{id, ref}` nor a valid inline
+ * agent) reports the branch that matched furthest, when exactly one did, so an
+ * inline agent's real defect surfaces instead of the generic union message.
+ * Nested unions resolve first, so depth compares the most specific issues.
+ */
+const specificIssue = (issue) => {
+    if (issue.code !== "invalid_union" || !issue.errors?.length)
+        return issue;
+    const candidates = issue.errors.map((branch) => branch
+        .map(specificIssue)
+        .reduce((deepest, candidate) => deepest === undefined || candidate.path.length > deepest.path.length ? candidate : deepest, undefined));
+    const depths = candidates.map((candidate) => candidate?.path.length ?? -1);
+    const best = Math.max(...depths);
+    if (best <= 0 || depths.filter((depth) => depth === best).length !== 1)
+        return issue;
+    const nested = candidates[depths.indexOf(best)];
+    return { ...nested, path: [...issue.path, ...nested.path] };
+};
+const describeMember = (parsed, path) => {
+    if (path[0] !== "members" || typeof path[1] !== "number")
+        return "";
+    const members = parsed.members;
+    const member = Array.isArray(members) ? members[path[1]] : undefined;
+    return typeof member?.id === "string" ? ` member ${member.id}` : "";
+};
+/**
+ * Parses one Spawnfile. Errors name the file, and the declared kind and name
+ * when the YAML got far enough to have them, so a member's malformed manifest
+ * is attributable from `spawnfile validate` on the organization root.
+ */
+export const parseManifest = (source, manifestPath) => {
+    let parsed;
+    try {
+        parsed = parseYaml(source);
+    }
+    catch (error) {
+        // A YAML syntax error is a malformed manifest, not a runtime failure — wrap
+        // it so it exits as a usage error instead of leaking the parser's wording.
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SpawnfileError("invalid_manifest", `Invalid Spawnfile manifest ${manifestPath}: ${reason}`);
+    }
+    try {
+        return manifestSchema.parse(parsed);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const issue = specificIssue(error.issues[0]);
+            const location = issue.path.length > 0 ? ` at ${issue.path.map(String).join(".")}` : "";
+            throw new SpawnfileError("invalid_manifest", `Invalid Spawnfile manifest for ${describeManifest(parsed, manifestPath)}${describeMember(parsed, issue.path)}${location}: ${issue.message}`);
+        }
+        throw error;
+    }
+};

package/dist/manifest/renderSpawnfile.js

@@ -91,7 +91,8 @@ const orderSharedSurface = (shared) => {
     }
     return withDefinedEntries([
         ["workspace", orderWorkspace(shared.workspace)],
-        ["environment", orderEnvironment(shared.environment)]
+        ["environment", orderEnvironment(shared.environment)],
+        ["training", shared.training]
     ]);
 };
 const orderMember = (member) => {
@@ -108,6 +109,7 @@ const orderMember = (member) => {
         ["runtime", orderRuntimeBinding(member.runtime)],
         ["execution", orderExecution(member.execution)],
         ["schedule", orderAgentSchedule(member.schedule)],
+        ["training", member.training],
         ["workspace", orderWorkspace(member.workspace)],
         ["environment", orderEnvironment(member.environment)],
         ["surfaces", orderSurfaces(member.surfaces)],
@@ -129,6 +131,7 @@ const orderAgentManifestSections = (manifest) => [
     withDefinedEntries([["runtime", orderRuntimeBinding(manifest.runtime)]]),
     withDefinedEntries([["execution", orderExecution(manifest.execution)]]),
     withDefinedEntries([["schedule", orderAgentSchedule(manifest.schedule)]]),
+    withDefinedEntries([["training", manifest.training]]),
     withDefinedEntries([["workspace", orderWorkspace(manifest.workspace)]]),
     withDefinedEntries([["environment", orderEnvironment(manifest.environment)]]),
     withDefinedEntries([["surfaces", orderSurfaces(manifest.surfaces)]]),

package/dist/manifest/renderSpawnfileNetworks.js

@@ -8,6 +8,16 @@ const orderTeamAuthToken = (token) => withDefinedEntries([
 const orderTeamAuthPairing = (pairing) => withDefinedEntries([
     ["id", pairing.id],
     ["remote_base_url", pairing.remote_base_url],
+    [
+        "relay",
+        pairing.relay
+            ? withDefinedEntries([
+                ["url", pairing.relay.url],
+                ["room", pairing.relay.room],
+                ["token_secret", pairing.relay.token_secret]
+            ])
+            : undefined
+    ],
     ["remote_network_id", pairing.remote_network_id],
     ["remote_network_name", pairing.remote_network_name],
     ["token_secret", pairing.token_secret]
@@ -87,6 +97,7 @@ export const orderTeamNetworks = (networks) => networks?.map((network) => withDe
             ["name", room.name],
             ["visibility", room.visibility],
             ["write_policy", room.write_policy],
+            ["federation", room.federation],
             ["members", room.members]
         ]))
     ]

package/dist/manifest/renderSpawnfileWorkspace.js

@@ -21,18 +21,27 @@ const orderWorkspaceResource = (resource) => {
             ["branch", resource.branch],
             ["ref", resource.ref],
             ["tag", resource.tag],
+            ["fetch", resource.fetch],
+            ["auth", resource.auth],
+            ["exclude", resource.exclude],
             ["mount", resource.mount],
             ["mode", resource.mode],
             ["sharing", resource.sharing]
         ]);
     }
+    if (resource.kind === "bundle")
+        return withDefinedEntries([
+            ["id", resource.id], ["kind", resource.kind], ["source", resource.source], ["build", resource.build],
+            ["sha256", resource.sha256], ["mount", resource.mount], ["mode", resource.mode], ["sharing", resource.sharing]
+        ]);
     return withDefinedEntries([
         ["id", resource.id],
         ["kind", resource.kind],
         ["mount", resource.mount],
         ["mode", resource.mode],
         ["name", resource.name],
-        ["sharing", resource.sharing]
+        ["sharing", resource.sharing],
+        ["feed", resource.feed]
     ]);
 };
 export const orderWorkspace = (workspace) => {

package/dist/manifest/scheduleSchemas.d.ts

@@ -1,11 +1,13 @@
 import { z } from "zod";
 export declare const agentScheduleSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    cron: z.ZodString;
+    cron: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    jitter_seconds: z.ZodOptional<z.ZodNumber>;
     kind: z.ZodLiteral<"cron">;
     prompt: z.ZodOptional<z.ZodString>;
     timezone: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<{
     every: z.ZodString;
+    jitter_seconds: z.ZodOptional<z.ZodNumber>;
     kind: z.ZodLiteral<"every">;
     prompt: z.ZodOptional<z.ZodString>;
     timezone: z.ZodOptional<z.ZodString>;

package/dist/manifest/scheduleSchemas.js

@@ -1,10 +1,91 @@
 import { z } from "zod";
-const schedulePromptSchema = z.string().min(1);
-const scheduleTimezoneSchema = z.string().min(1);
+import { parseEveryScheduleMs } from "../runtime/scheduleUtils.js";
+const MAX_RUNTIME_STRING_BYTES = 16_384;
+const MAX_RUNTIME_STRING_CODEPOINTS = 4_096;
+const schedulePromptSchema = z.string().min(1).superRefine((value, context) => {
+    if (!value.trim()) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "prompt must not be empty" });
+    }
+    else if (Buffer.byteLength(value, "utf8") > MAX_RUNTIME_STRING_BYTES || [...value].length > MAX_RUNTIME_STRING_CODEPOINTS) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "prompt exceeds Daimon's schedule string bound" });
+    }
+});
+const CRON_FIELD_BOUNDS = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+const scheduleTimezoneSchema = z.string().min(1).superRefine((value, context) => {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+    }
+    catch {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "timezone must be a valid IANA timezone" });
+    }
+});
+const cronSchema = z.string().trim().min(1).superRefine((value, context) => {
+    const fields = value.split(/\s+/u);
+    if ([...value].length > MAX_RUNTIME_STRING_CODEPOINTS) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "cron exceeds Daimon's runtime string bound" });
+    }
+    if (fields.length !== 5 || !fields.every((field, index) => validCronField(field, CRON_FIELD_BOUNDS[index])) || !cronCalendarPossible(fields)) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "cron must contain five supported numeric fields within their bounds" });
+    }
+}).transform((value) => value.replace(/\s+/gu, " "));
+const validCronField = (field, [minimum, maximum]) => field.split(",").every((part) => {
+    const pieces = part.split("/");
+    const step = Number(pieces[1] ?? 1);
+    if (pieces.length > 2 || !pieces[0] || (pieces[1] !== undefined && !/^\d+$/u.test(pieces[1])) || !Number.isSafeInteger(step) || step < 1)
+        return false;
+    const range = pieces[0];
+    if (range === "*")
+        return true;
+    const bounds = range.split("-");
+    if (bounds.length > 2 || !bounds.every((bound) => /^\d+$/u.test(bound)))
+        return false;
+    const first = Number(bounds[0]);
+    const last = Number(bounds[1] ?? bounds[0]);
+    return first >= minimum && last <= maximum && first <= last;
+});
+const cronCalendarPossible = (raw) => {
+    if (raw.length !== 5)
+        return false;
+    const fields = raw.map((field, index) => cronValues(field, CRON_FIELD_BOUNDS[index]));
+    for (let year = 2000; year < 2400; year += 1)
+        for (const month of fields[3]) {
+            const days = new Date(Date.UTC(year, month, 0)).getUTCDate();
+            for (const day of fields[2])
+                if (day <= days && fields[4].includes(new Date(Date.UTC(year, month - 1, day)).getUTCDay()))
+                    return true;
+        }
+    return false;
+};
+const cronValues = (field, [minimum, maximum]) => {
+    const result = new Set();
+    for (const part of field.split(",")) {
+        const [range, rawStep] = part.split("/");
+        const step = Number(rawStep ?? 1);
+        const bounds = range === "*" ? [minimum, maximum] : range.split("-").map(Number);
+        for (let value = bounds[0]; value <= (bounds[1] ?? bounds[0]); value += step)
+            result.add(value === 7 && maximum === 7 ? 0 : value);
+    }
+    return [...result];
+};
+const everySchema = z.string().trim().min(1).superRefine((value, context) => {
+    if (parseEveryScheduleMs(value) === null)
+        context.addIssue({ code: z.ZodIssueCode.custom, message: "every must be a positive duration" });
+});
+/**
+ * Upper bound on `schedule.jitter_seconds`, mirroring Daimon's
+ * `ORGANIZATION_RUNTIME_MAX_SCHEDULE_JITTER_SECONDS` so every jitter value this
+ * schema accepts also lowers cleanly into the Daimon runtime config: one hour,
+ * generous next to the finest cron granularity (a minute) while staying small
+ * relative to the daily/sub-daily cadences jitter exists to blur, so a
+ * jittered wake still lands recognizably near its scheduled instant.
+ */
+const MAX_SCHEDULE_JITTER_SECONDS = 3_600;
+const jitterSecondsSchema = z.number().int().min(0).max(MAX_SCHEDULE_JITTER_SECONDS);
 export const agentScheduleSchema = z.discriminatedUnion("kind", [
     z
         .object({
-        cron: z.string().min(1),
+        cron: cronSchema,
+        jitter_seconds: jitterSecondsSchema.optional(),
         kind: z.literal("cron"),
         prompt: schedulePromptSchema.optional(),
         timezone: scheduleTimezoneSchema.optional()
@@ -12,12 +93,17 @@ export const agentScheduleSchema = z.discriminatedUnion("kind", [
         .strict(),
     z
         .object({
-        every: z.string().min(1),
+        every: everySchema,
+        jitter_seconds: jitterSecondsSchema.optional(),
         kind: z.literal("every"),
         prompt: schedulePromptSchema.optional(),
         timezone: scheduleTimezoneSchema.optional()
     })
-        .strict(),
+        .strict()
+        .superRefine((value, context) => {
+        if (value.timezone !== undefined)
+            context.addIssue({ code: z.ZodIssueCode.custom, message: "every schedules cannot declare a timezone" });
+    }),
     z
         .object({
         kind: z.literal("disabled")