@sweny-ai/core 0.1.62 → 0.1.64

package/dist/schema.js

@@ -63,12 +63,26 @@ export const skillZ = z
     .refine((s) => s.tools.length > 0 || s.instruction || s.mcp, {
     message: "Skill must provide at least one of: tools, instruction, or mcp",
 });
+/**
+ * NodeSources: either an array of Sources (additive — inherits cascade)
+ * or an object `{ only?: boolean, sources: Source[] }` where `only: true`
+ * blocks the cascade for that field.
+ */
+export const nodeSourcesZ = z.union([
+    z.array(sourceZ),
+    z.object({
+        only: z.boolean().optional(),
+        sources: z.array(sourceZ),
+    }),
+]);
 export const nodeZ = z.object({
     name: z.string().min(1),
     instruction: sourceZ,
     skills: z.array(z.string()).default([]),
     output: jsonSchemaZ.optional(),
     max_turns: z.number().int().min(1).optional(),
+    rules: nodeSourcesZ.optional(),
+    context: nodeSourcesZ.optional(),
 });
 export const edgeZ = z.object({
     from: z.string().min(1),
@@ -84,6 +98,8 @@ export const workflowZ = z.object({
     edges: z.array(edgeZ),
     entry: z.string().min(1),
     skills: z.record(skillDefinitionZ).default({}),
+    rules: z.array(sourceZ).optional(),
+    context: z.array(sourceZ).optional(),
 });
 /** Parse + validate a raw object as a Workflow. Throws on invalid input. */
 export function parseWorkflow(raw) {
@@ -269,12 +285,38 @@ export const workflowJsonSchema = {
     type: "object",
     required: ["id", "name", "nodes", "edges", "entry"],
     additionalProperties: false,
-    $defs: { Source: sourceJsonSchema },
+    $defs: {
+        Source: sourceJsonSchema,
+        NodeSources: {
+            oneOf: [
+                { type: "array", items: { $ref: "#/$defs/Source" } },
+                {
+                    type: "object",
+                    required: ["sources"],
+                    additionalProperties: false,
+                    properties: {
+                        only: { type: "boolean" },
+                        sources: { type: "array", items: { $ref: "#/$defs/Source" } },
+                    },
+                },
+            ],
+        },
+    },
     properties: {
         id: { type: "string", minLength: 1 },
         name: { type: "string", minLength: 1 },
         description: { type: "string" },
         entry: { type: "string", minLength: 1, description: "ID of the entry node" },
+        rules: {
+            type: "array",
+            items: { $ref: "#/$defs/Source" },
+            description: "Directives prepended to every node's instruction.",
+        },
+        context: {
+            type: "array",
+            items: { $ref: "#/$defs/Source" },
+            description: "Background knowledge prepended to every node's instruction.",
+        },
         nodes: {
             type: "object",
             additionalProperties: {
@@ -298,6 +340,14 @@ export const workflowJsonSchema = {
                         minimum: 1,
                         description: "Max AI model turns for this node. When absent, the executor's default applies.",
                     },
+                    rules: {
+                        $ref: "#/$defs/NodeSources",
+                        description: "Per-node rules. Additive by default; set { only: true } to block cascade.",
+                    },
+                    context: {
+                        $ref: "#/$defs/NodeSources",
+                        description: "Per-node context. Additive by default; set { only: true } to block cascade.",
+                    },
                 },
             },
         },

package/dist/source-resolver.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Source resolution (Node-only).
+ *
+ * Runtime helpers that read files, hash content, and fetch URLs. These are
+ * separated from `./sources.ts` so the browser-safe bits of the Source type
+ * (Zod schema, classifier, types) can be imported without pulling `node:fs`
+ * or `node:crypto` into bundlers that target the browser.
+ */
+import type { ResolvedSource, Source, SourceResolutionContext, SourceResolutionMap } from "./sources.js";
+/**
+ * Produce a stable 16-hex-char hash of `content` for use as a cache key /
+ * change-detection ID.
+ *
+ * Intentionally avoids `node:crypto` so this module can be bundled for the
+ * browser (studio SPA's in-browser simulator reaches this via the inline
+ * Source resolver). `cyrb64` is a well-known non-crypto 64-bit hash — fine
+ * for cache keys, not fine for security. Deterministic across Node and
+ * browser (both operate on UTF-16 code units).
+ */
+export declare function hashContent(content: string): string;
+export declare function resolveSource(source: Source, fieldPath: string, ctx: SourceResolutionContext): Promise<ResolvedSource>;
+export declare function resolveSources(sources: Record<string, Source>, ctx: SourceResolutionContext): Promise<SourceResolutionMap>;

package/dist/source-resolver.js

@@ -0,0 +1,174 @@
+/**
+ * Source resolution (Node-only).
+ *
+ * Runtime helpers that read files, hash content, and fetch URLs. These are
+ * separated from `./sources.ts` so the browser-safe bits of the Source type
+ * (Zod schema, classifier, types) can be imported without pulling `node:fs`
+ * or `node:crypto` into bundlers that target the browser.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { normalizeSource } from "./sources.js";
+/**
+ * Produce a stable 16-hex-char hash of `content` for use as a cache key /
+ * change-detection ID.
+ *
+ * Intentionally avoids `node:crypto` so this module can be bundled for the
+ * browser (studio SPA's in-browser simulator reaches this via the inline
+ * Source resolver). `cyrb64` is a well-known non-crypto 64-bit hash — fine
+ * for cache keys, not fine for security. Deterministic across Node and
+ * browser (both operate on UTF-16 code units).
+ */
+export function hashContent(content) {
+    let h1 = 0xdeadbeef;
+    let h2 = 0x41c6ce57;
+    for (let i = 0; i < content.length; i++) {
+        const ch = content.charCodeAt(i);
+        h1 = Math.imul(h1 ^ ch, 2654435761);
+        h2 = Math.imul(h2 ^ ch, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+    h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+    h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    return (h2 >>> 0).toString(16).padStart(8, "0") + (h1 >>> 0).toString(16).padStart(8, "0");
+}
+export async function resolveSource(source, fieldPath, ctx) {
+    const [kind, value] = normalizeSource(source);
+    if (kind === "inline") {
+        return {
+            content: value,
+            kind: "inline",
+            origin: source,
+            resolver: "inline",
+            hash: hashContent(value),
+        };
+    }
+    if (kind === "file") {
+        const absolute = path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value);
+        let content;
+        try {
+            content = await fs.readFile(absolute, "utf-8");
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === "ENOENT") {
+                throw new Error(`SOURCE_FILE_NOT_FOUND: file not found: ${absolute} (referenced by ${fieldPath})`);
+            }
+            throw new Error(`SOURCE_FILE_READ_FAILED: could not read ${absolute} (referenced by ${fieldPath}): ${e.message}`);
+        }
+        // Strip UTF-8 BOM (Windows editors emit this)
+        if (content.charCodeAt(0) === 0xfeff)
+            content = content.slice(1);
+        return {
+            content,
+            kind: "file",
+            origin: source,
+            resolver: "file",
+            hash: hashContent(content),
+            sourcePath: absolute,
+        };
+    }
+    if (kind === "url") {
+        if (ctx.offline) {
+            throw new Error(`SOURCE_OFFLINE_REQUIRES_FETCH: cannot fetch ${value} in --offline mode (referenced by ${fieldPath}).`);
+        }
+        // Validate type field on tagged URL forms — v1 only accepts "fetch" (the default).
+        if (typeof source === "object" && "url" in source && source.type && source.type !== "fetch") {
+            throw new Error(`SOURCE_INVALID_TYPE: unknown resolver type "${source.type}" on ${value} (referenced by ${fieldPath}). v1 supports only "fetch".`);
+        }
+        const url = value;
+        const headers = buildFetchHeaders(url, ctx);
+        const res = await fetchWithRetry(url, headers, fieldPath);
+        if (res.status === 401 || res.status === 403) {
+            throw new Error(`SOURCE_URL_AUTH_REQUIRED: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}). Configure fetch.auth in .sweny.yml or set SWENY_FETCH_TOKEN.`);
+        }
+        if (!res.ok) {
+            throw new Error(`SOURCE_URL_HTTP_ERROR: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}).`);
+        }
+        const content = await res.text();
+        return {
+            content,
+            kind: "url",
+            origin: source,
+            resolver: "fetch",
+            hash: hashContent(content),
+            fetchedAt: new Date().toISOString(),
+        };
+    }
+    throw new Error(`source error: unreachable (kind: ${kind}, field: ${fieldPath})`);
+}
+export async function resolveSources(sources, ctx) {
+    const cache = new Map();
+    const out = {};
+    const entries = Object.entries(sources);
+    await Promise.all(entries.map(async ([fieldPath, source]) => {
+        const key = canonicalKey(source, ctx);
+        let promise = key ? cache.get(key) : undefined;
+        if (!promise) {
+            promise = resolveSource(source, fieldPath, ctx);
+            if (key)
+                cache.set(key, promise);
+        }
+        out[fieldPath] = await promise;
+    }));
+    return out;
+}
+function canonicalKey(source, ctx) {
+    const [kind, value] = normalizeSource(source);
+    if (kind === "file") {
+        return "file:" + (path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value));
+    }
+    if (kind === "url")
+        return "url:" + value;
+    return null;
+}
+const RETRY_DELAYS = [250, 1000]; // ms — exponential backoff for 5xx
+async function fetchWithRetry(url, headers, fieldPath) {
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
+        try {
+            const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+            // Don't retry on 4xx (client errors) or 2xx (success)
+            if (res.status < 500)
+                return res;
+            // 5xx — retry if attempts remain
+            if (attempt < RETRY_DELAYS.length) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
+                continue;
+            }
+            return res; // final 5xx — let caller handle it
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < RETRY_DELAYS.length) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
+                continue;
+            }
+        }
+    }
+    throw new Error(`SOURCE_URL_UNREACHABLE: ${url} (referenced by ${fieldPath}): ${lastError?.message ?? "unknown error"}. Pass --offline to skip URL sources.`);
+}
+function buildFetchHeaders(url, ctx) {
+    const headers = {
+        Accept: "text/plain, text/markdown, */*",
+    };
+    const token = resolveFetchToken(url, ctx);
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    return headers;
+}
+function resolveFetchToken(url, ctx) {
+    let host;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        return undefined;
+    }
+    const envVar = ctx.authConfig[host];
+    if (envVar && ctx.env[envVar])
+        return ctx.env[envVar];
+    const fallback = ctx.env.SWENY_FETCH_TOKEN;
+    return fallback || undefined;
+}

package/dist/sources.d.ts

@@ -4,6 +4,11 @@
  * absolute file paths, and HTTP(S) URLs via a single ergonomic form.
  *
  * See docs/superpowers/specs/2026-04-12-unified-source-type-design.md.
+ *
+ * This module is browser-safe. Runtime resolution (fs/crypto/fetch helpers)
+ * lives in `./source-resolver.ts` so bundlers that target the browser (studio
+ * SPA, docs site) can import `sourceZ` and the Source types without dragging
+ * in `node:crypto` / `node:fs`.
  */
 import { z } from "zod";
 import type { Logger } from "./types.js";
@@ -44,9 +49,6 @@ export declare const sourceZ: z.ZodUnion<[z.ZodString, z.ZodObject<{
     url: string;
     type?: string | undefined;
 }>]>;
-/**
- * Classify a plain-string Source by prefix. Throws on empty strings.
- */
 export type ResolvedSource = {
     content: string;
     kind: SourceKind;
@@ -57,8 +59,11 @@ export type ResolvedSource = {
     sourcePath?: string;
 };
 export type SourceResolutionMap = Record<string, ResolvedSource>;
-export declare function hashContent(content: string): string;
+/**
+ * Classify a plain-string Source by prefix. Throws on empty strings.
+ */
 export declare function classifySource(raw: string): SourceKind;
+export declare function normalizeSource(source: Source): [SourceKind, string];
 export type SourceResolutionContext = {
     cwd: string;
     env: NodeJS.ProcessEnv;
@@ -66,5 +71,3 @@ export type SourceResolutionContext = {
     offline: boolean;
     logger: Logger;
 };
-export declare function resolveSource(source: Source, fieldPath: string, ctx: SourceResolutionContext): Promise<ResolvedSource>;
-export declare function resolveSources(sources: Record<string, Source>, ctx: SourceResolutionContext): Promise<SourceResolutionMap>;

package/dist/sources.js

@@ -4,10 +4,12 @@
  * absolute file paths, and HTTP(S) URLs via a single ergonomic form.
  *
  * See docs/superpowers/specs/2026-04-12-unified-source-type-design.md.
+ *
+ * This module is browser-safe. Runtime resolution (fs/crypto/fetch helpers)
+ * lives in `./source-resolver.ts` so bundlers that target the browser (studio
+ * SPA, docs site) can import `sourceZ` and the Source types without dragging
+ * in `node:crypto` / `node:fs`.
  */
-import { createHash } from "node:crypto";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
 import { z } from "zod";
 const inlineTagZ = z.object({ inline: z.string().min(1) }).strict();
 const fileTagZ = z.object({ file: z.string().min(1) }).strict();
@@ -24,9 +26,9 @@ const urlTagZ = z
  * the schema stays permissive so new resolvers slot in without schema bumps.
  */
 export const sourceZ = z.union([z.string().min(1), inlineTagZ, fileTagZ, urlTagZ]);
-export function hashContent(content) {
-    return createHash("sha256").update(content, "utf8").digest("hex").slice(0, 16);
-}
+/**
+ * Classify a plain-string Source by prefix. Throws on empty strings.
+ */
 export function classifySource(raw) {
     const trimmed = raw.trim();
     if (!trimmed) {
@@ -40,146 +42,7 @@ export function classifySource(raw) {
     }
     return "inline";
 }
-export async function resolveSource(source, fieldPath, ctx) {
-    const [kind, value] = normalizeSource(source);
-    if (kind === "inline") {
-        return {
-            content: value,
-            kind: "inline",
-            origin: source,
-            resolver: "inline",
-            hash: hashContent(value),
-        };
-    }
-    if (kind === "file") {
-        const absolute = path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value);
-        let content;
-        try {
-            content = await fs.readFile(absolute, "utf-8");
-        }
-        catch (err) {
-            const e = err;
-            if (e.code === "ENOENT") {
-                throw new Error(`SOURCE_FILE_NOT_FOUND: file not found: ${absolute} (referenced by ${fieldPath})`);
-            }
-            throw new Error(`SOURCE_FILE_READ_FAILED: could not read ${absolute} (referenced by ${fieldPath}): ${e.message}`);
-        }
-        // Strip UTF-8 BOM (Windows editors emit this)
-        if (content.charCodeAt(0) === 0xfeff)
-            content = content.slice(1);
-        return {
-            content,
-            kind: "file",
-            origin: source,
-            resolver: "file",
-            hash: hashContent(content),
-            sourcePath: absolute,
-        };
-    }
-    if (kind === "url") {
-        if (ctx.offline) {
-            throw new Error(`SOURCE_OFFLINE_REQUIRES_FETCH: cannot fetch ${value} in --offline mode (referenced by ${fieldPath}).`);
-        }
-        // Validate type field on tagged URL forms — v1 only accepts "fetch" (the default).
-        if (typeof source === "object" && "url" in source && source.type && source.type !== "fetch") {
-            throw new Error(`SOURCE_INVALID_TYPE: unknown resolver type "${source.type}" on ${value} (referenced by ${fieldPath}). v1 supports only "fetch".`);
-        }
-        const url = value;
-        const headers = buildFetchHeaders(url, ctx);
-        const res = await fetchWithRetry(url, headers, fieldPath);
-        if (res.status === 401 || res.status === 403) {
-            throw new Error(`SOURCE_URL_AUTH_REQUIRED: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}). Configure fetch.auth in .sweny.yml or set SWENY_FETCH_TOKEN.`);
-        }
-        if (!res.ok) {
-            throw new Error(`SOURCE_URL_HTTP_ERROR: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}).`);
-        }
-        const content = await res.text();
-        return {
-            content,
-            kind: "url",
-            origin: source,
-            resolver: "fetch",
-            hash: hashContent(content),
-            fetchedAt: new Date().toISOString(),
-        };
-    }
-    throw new Error(`source error: unreachable (kind: ${kind}, field: ${fieldPath})`);
-}
-export async function resolveSources(sources, ctx) {
-    const cache = new Map();
-    const out = {};
-    const entries = Object.entries(sources);
-    await Promise.all(entries.map(async ([fieldPath, source]) => {
-        const key = canonicalKey(source, ctx);
-        let promise = key ? cache.get(key) : undefined;
-        if (!promise) {
-            promise = resolveSource(source, fieldPath, ctx);
-            if (key)
-                cache.set(key, promise);
-        }
-        out[fieldPath] = await promise;
-    }));
-    return out;
-}
-function canonicalKey(source, ctx) {
-    const [kind, value] = normalizeSource(source);
-    if (kind === "file") {
-        return "file:" + (path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value));
-    }
-    if (kind === "url")
-        return "url:" + value;
-    return null;
-}
-const RETRY_DELAYS = [250, 1000]; // ms — exponential backoff for 5xx
-async function fetchWithRetry(url, headers, fieldPath) {
-    let lastError;
-    for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
-        try {
-            const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
-            // Don't retry on 4xx (client errors) or 2xx (success)
-            if (res.status < 500)
-                return res;
-            // 5xx — retry if attempts remain
-            if (attempt < RETRY_DELAYS.length) {
-                await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
-                continue;
-            }
-            return res; // final 5xx — let caller handle it
-        }
-        catch (err) {
-            lastError = err instanceof Error ? err : new Error(String(err));
-            if (attempt < RETRY_DELAYS.length) {
-                await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
-                continue;
-            }
-        }
-    }
-    throw new Error(`SOURCE_URL_UNREACHABLE: ${url} (referenced by ${fieldPath}): ${lastError?.message ?? "unknown error"}. Pass --offline to skip URL sources.`);
-}
-function buildFetchHeaders(url, ctx) {
-    const headers = {
-        Accept: "text/plain, text/markdown, */*",
-    };
-    const token = resolveFetchToken(url, ctx);
-    if (token)
-        headers.Authorization = `Bearer ${token}`;
-    return headers;
-}
-function resolveFetchToken(url, ctx) {
-    let host;
-    try {
-        host = new URL(url).host;
-    }
-    catch {
-        return undefined;
-    }
-    const envVar = ctx.authConfig[host];
-    if (envVar && ctx.env[envVar])
-        return ctx.env[envVar];
-    const fallback = ctx.env.SWENY_FETCH_TOKEN;
-    return fallback || undefined;
-}
-function normalizeSource(source) {
+export function normalizeSource(source) {
     if (typeof source === "string") {
         const kind = classifySource(source);
         return [kind, source.trim()];
@@ -192,3 +55,7 @@ function normalizeSource(source) {
         return ["url", source.url.trim()];
     throw new Error("source error: unrecognised Source shape");
 }
+// Runtime resolvers (hashContent, resolveSource, resolveSources) live in
+// `./source-resolver.ts`. They are Node-only (fs, crypto, fetch). Importing
+// them from here would drag `node:crypto` into browser bundles that only
+// need `sourceZ`/types from this file.

package/dist/sources.test.js

@@ -2,7 +2,8 @@ import { mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
 import { describe, it, expect, beforeEach, vi } from "vitest";
-import { classifySource, sourceZ, hashContent, resolveSource, resolveSources } from "./sources.js";
+import { classifySource, sourceZ } from "./sources.js";
+import { hashContent, resolveSource, resolveSources } from "./source-resolver.js";
 const fileTmp = path.join(tmpdir(), "sweny-sources-file-test");
 const baseCtx = () => ({
     cwd: "/tmp",

package/dist/sources.validation.test.js

@@ -14,7 +14,8 @@ import { randomBytes } from "node:crypto";
 import { tmpdir } from "node:os";
 import * as path from "node:path";
 import { describe, it, expect, beforeEach, vi } from "vitest";
-import { classifySource, sourceZ, hashContent, resolveSource, resolveSources, } from "./sources.js";
+import { classifySource, sourceZ } from "./sources.js";
+import { hashContent, resolveSource, resolveSources } from "./source-resolver.js";
 const fileTmp = path.join(tmpdir(), `sweny-sources-validation-test-${randomBytes(4).toString("hex")}`);
 const baseCtx = () => ({
     cwd: "/tmp",

package/dist/templates.js

@@ -10,7 +10,8 @@
  * backwards-compatible wrappers with fallback semantics.
  */
 import * as path from "node:path";
-import { resolveSource, classifySource } from "./sources.js";
+import { classifySource } from "./sources.js";
+import { resolveSource } from "./source-resolver.js";
 import { consoleLogger } from "./types.js";
 export const DEFAULT_ISSUE_TEMPLATE = `## Summary
 <!-- One-line description of the issue -->

package/dist/types.d.ts

@@ -37,6 +37,18 @@ export interface Skill {
     /** External MCP server definition wired for nodes referencing this skill. */
     mcp?: McpServerConfig;
 }
+/**
+ * Per-node rules or context.
+ *
+ * - Array form (additive): inherits workflow/runtime sources AND adds these.
+ * - Object form: when `only: true`, blocks the cascade for this field and
+ *   uses only `sources`. When `only` is absent/false, behaves like the
+ *   array form.
+ */
+export type NodeSources = _Source[] | {
+    only?: boolean;
+    sources: _Source[];
+};
 /** A node in the workflow DAG */
 export interface Node {
     /** Human-readable name */
@@ -49,6 +61,10 @@ export interface Node {
     output?: JSONSchema;
     /** Max AI model turns for this node. When absent, the executor's default applies. */
     max_turns?: number;
+    /** Per-node directives. Additive by default; set `{ only: true, sources: [...] }` to block cascade. */
+    rules?: NodeSources;
+    /** Per-node background knowledge. Additive by default; set `{ only: true, sources: [...] }` to block cascade. */
+    context?: NodeSources;
 }
 /** An edge connecting two nodes */
 export interface Edge {
@@ -68,6 +84,10 @@ export interface Workflow {
     edges: Edge[];
     entry: string;
     skills?: Record<string, SkillDefinition>;
+    /** Directives prepended to every node's instruction. Cascade into per-node rules. */
+    rules?: _Source[];
+    /** Background knowledge prepended to every node's instruction. Cascade into per-node context. */
+    context?: _Source[];
 }
 /**
  * Inline skill definition in a workflow's `skills` block.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"