@reallyartificial/grain 0.2.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { Grain } from "./grain.js";
+const args = process.argv.slice(2);
+const command = args[0];
+function printHelp() {
+    console.log(`grain — CLI for Grain agent definitions
+
+Usage:
+  grain validate <file>              Validate a .agent.yaml file
+  grain generate <file> [--channel]  Generate system prompt
+  grain info <file>                  Show agent summary
+
+Examples:
+  grain validate my-agent.agent.yaml
+  grain generate my-agent.agent.yaml --channel slack
+  grain info my-agent.agent.yaml`);
+}
+function validate(file) {
+    try {
+        const g = Grain.load(file);
+        const errors = g.validate();
+        if (errors.length > 0) {
+            console.error(`Validation warnings for ${file}:`);
+            for (const err of errors) {
+                console.error(`  ${err.path}: ${err.message}`);
+            }
+            process.exit(1);
+        }
+        console.log(`${file} is valid`);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+}
+function generate(file, channel) {
+    try {
+        const g = Grain.load(file);
+        const prompt = g.toPrompt(channel);
+        console.log(prompt);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+}
+function info(file) {
+    try {
+        const g = Grain.load(file);
+        console.log(`Name:        ${g.name}`);
+        console.log(`ID:          ${g.id}`);
+        console.log(`Version:     ${g.version}`);
+        console.log(`Description: ${g.data.meta.description}`);
+        console.log(`Role:        ${g.data.identity.role}`);
+        if (g.data.voice.channelOverrides) {
+            const channels = Object.keys(g.data.voice.channelOverrides);
+            console.log(`Channels:    ${channels.join(", ")}`);
+        }
+        const p = g.personality;
+        const traits = [];
+        if (p.formality > 0.7)
+            traits.push("formal");
+        else if (p.formality < 0.3)
+            traits.push("casual");
+        if (p.warmth > 0.7)
+            traits.push("warm");
+        if (p.humor > 0.5)
+            traits.push("humorous");
+        if (p.assertiveness > 0.7)
+            traits.push("assertive");
+        if (p.confidence > 0.7)
+            traits.push("confident");
+        if (p.concreteness > 0.7)
+            traits.push("concrete");
+        if (traits.length) {
+            console.log(`Personality: ${traits.join(", ")}`);
+        }
+        console.log(`Rules:       ${g.rules.length}`);
+        console.log(`Boundaries:  ${g.boundaries.length}`);
+        if (g.tools.length) {
+            console.log(`Tools:       ${g.tools.map(t => t.id).join(", ")}`);
+        }
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+}
+if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    process.exit(0);
+}
+const file = args[1];
+if (!file) {
+    console.error(`Error: missing file argument\n`);
+    printHelp();
+    process.exit(1);
+}
+switch (command) {
+    case "validate":
+        validate(file);
+        break;
+    case "generate": {
+        const channelIdx = args.indexOf("--channel");
+        const channel = channelIdx !== -1 ? args[channelIdx + 1] : undefined;
+        generate(file, channel);
+        break;
+    }
+    case "info":
+        info(file);
+        break;
+    default:
+        console.error(`Unknown command: ${command}\n`);
+        printHelp();
+        process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import type { AgentSpec } from "./types.js";
+/**
+ * Fills in missing sections with sensible defaults.
+ * Allows minimal specs (just specVersion, id, version, meta) to work
+ * by providing neutral defaults for all other sections.
+ */
+export declare function resolveDefaults(partial: Record<string, unknown>): AgentSpec;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAwH3E"}

package/dist/defaults.js

@@ -0,0 +1,117 @@
+/**
+ * Fills in missing sections with sensible defaults.
+ * Allows minimal specs (just specVersion, id, version, meta) to work
+ * by providing neutral defaults for all other sections.
+ */
+export function resolveDefaults(partial) {
+    const spec = { ...partial };
+    if (!spec.identity) {
+        const meta = spec.meta;
+        spec.identity = {
+            name: meta.name,
+            role: "AI Assistant",
+            purpose: { primary: meta.description || "Assist the user" },
+            expertise: [],
+        };
+    }
+    if (!spec.voice) {
+        spec.voice = {
+            personality: {
+                formality: 0.5,
+                warmth: 0.5,
+                humor: 0.3,
+                assertiveness: 0.5,
+                verbosity: 0.5,
+                confidence: 0.6,
+                concreteness: 0.6,
+                urgency: 0.4,
+            },
+            language: {
+                locale: "en",
+                sentenceLength: "medium",
+                jargonLevel: "moderate",
+                emojiUsage: "never",
+                structure: "mixed",
+                usesAnalogies: false,
+                addressing: "first-person",
+            },
+        };
+    }
+    if (!spec.cognition) {
+        spec.cognition = {
+            reasoningStyle: {
+                primary: "analytical",
+                showReasoning: false,
+                analysisDepth: "moderate",
+                multiPerspective: false,
+            },
+            decisionMaking: {
+                speed: 0.5,
+                evidenceThreshold: 0.5,
+                reversibilityPreference: "neutral",
+                autonomy: "ask-for-major",
+            },
+            uncertainty: {
+                lowConfidenceAction: "ask",
+                confidenceFloor: 0.3,
+                communicateUncertainty: true,
+                conflictResolution: "ask-user",
+            },
+            taskStrategy: {
+                decomposition: "top-down",
+                maxParallelism: 1,
+                checkpointing: false,
+                blockingStrategy: "escalate",
+            },
+        };
+    }
+    if (!spec.capabilities) {
+        spec.capabilities = {};
+    }
+    if (!spec.behavior) {
+        spec.behavior = { rules: [], boundaries: [] };
+    }
+    if (!spec.memory) {
+        spec.memory = {
+            retention: [{ category: "conversation-history", duration: "session" }],
+            contextStrategy: {
+                overflow: "summarize",
+                prioritize: ["recent"],
+                autoSummarize: false,
+            },
+        };
+    }
+    if (!spec.communication) {
+        spec.communication = {
+            channels: [{ channel: "api", enabled: true }],
+            input: {
+                languages: ["en"],
+                typoTolerance: true,
+                ambiguityResolution: "ask",
+                modalities: ["text"],
+            },
+            output: {
+                defaultFormat: "text",
+                citations: "never",
+                structuredOutput: false,
+            },
+        };
+    }
+    if (!spec.adaptation) {
+        spec.adaptation = { enabled: false };
+    }
+    if (!spec.observability) {
+        spec.observability = {
+            logging: {
+                level: "info",
+                alwaysLog: ["error"],
+                conversationLogging: "none",
+                piiHandling: "redact",
+            },
+            metrics: [],
+            successCriteria: [],
+        };
+    }
+    return spec;
+}
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"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"}

package/dist/grain.d.ts

@@ -0,0 +1,78 @@
+import type { AgentSpec, PersonalityVector, BehaviorRule, Boundary, ToolCapability, SkillDefinition, DomainExpertise } from "./types.js";
+import { type ValidationError } from "./validate.js";
+/**
+ * Grain — immutable wrapper around an AgentSpec.
+ * Every mutation returns a new Grain; the original is never modified.
+ */
+export declare class Grain {
+    private readonly _data;
+    private constructor();
+    /** Create a Grain programmatically with an id and optional overrides. */
+    static create(id: string, overrides?: {
+        name?: string;
+        description?: string;
+    }): Grain;
+    /** Create a Grain from a YAML or JSON string. */
+    static from(content: string): Grain;
+    /** Load a Grain from a .agent.yaml or .agent.json file. */
+    static load(filePath: string): Grain;
+    /** Create a Grain from a plain AgentSpec object. */
+    static of(spec: AgentSpec): Grain;
+    private with;
+    get id(): string;
+    get name(): string;
+    get version(): string;
+    get personality(): PersonalityVector;
+    get rules(): BehaviorRule[];
+    get boundaries(): Boundary[];
+    get tools(): ToolCapability[];
+    get skills(): SkillDefinition[];
+    get expertise(): DomainExpertise[];
+    get data(): AgentSpec;
+    get isValid(): boolean;
+    hasRule(id: string): boolean;
+    hasTool(name: string): boolean;
+    hasSkill(name: string): boolean;
+    addRule(rule: BehaviorRule): Grain;
+    removeRule(id: string): Grain;
+    addRules(rules: BehaviorRule[]): Grain;
+    addBoundary(boundary: Boundary): Grain;
+    removeBoundary(description: string): Grain;
+    addBoundaries(boundaries: Boundary[]): Grain;
+    addTool(tool: ToolCapability): Grain;
+    removeTool(name: string): Grain;
+    addTools(tools: ToolCapability[]): Grain;
+    addSkill(skill: SkillDefinition): Grain;
+    removeSkill(name: string): Grain;
+    addSkills(skills: SkillDefinition[]): Grain;
+    addExpertise(domain: string, proficiency: number): Grain;
+    removeExpertise(domain: string): Grain;
+    setPersonality(dim: keyof PersonalityVector, value: number): Grain;
+    set(path: string, value: unknown): Grain;
+    get<T = unknown>(path: string): T;
+    merge(other: Grain): Grain;
+    /**
+     * Clean YAML for LLM consumption.
+     * Strips SDK metadata (specVersion, id, version, meta.model, meta.tags,
+     * observability, adaptation). Keeps agent-facing content.
+     * Applies channel overrides if specified.
+     */
+    toString(channel?: string): string;
+    /**
+     * Expanded natural language prompt with behavioral directives.
+     * Delegates to the existing prompt generator.
+     */
+    toPrompt(channel?: string): string;
+    /** Full YAML including all metadata (for saving to file). */
+    toYAML(): string;
+    /** Full JSON including all metadata. */
+    toJSON(): string;
+    /** Validate and return errors. */
+    validate(): ValidationError[];
+    /** Diff this Grain against another. Returns paths with before/after values. */
+    diff(other: Grain): Record<string, {
+        before: unknown;
+        after: unknown;
+    }>;
+}
+//# sourceMappingURL=grain.d.ts.map

package/dist/grain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grain.d.ts","sourceRoot":"","sources":["../src/grain.ts"],"names":[],"mappings":"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"}

package/dist/grain.js

@@ -0,0 +1,317 @@
+import { readFileSync } from "node:fs";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { validateSpec, assertValid } from "./validate.js";
+import { resolveDefaults } from "./defaults.js";
+import { generateSystemPrompt } from "./prompt-generator.js";
+/**
+ * Grain — immutable wrapper around an AgentSpec.
+ * Every mutation returns a new Grain; the original is never modified.
+ */
+export class Grain {
+    _data;
+    constructor(data) {
+        this._data = Object.freeze(data);
+    }
+    // ===========================================================================
+    // CONSTRUCTORS
+    // ===========================================================================
+    /** Create a Grain programmatically with an id and optional overrides. */
+    static create(id, overrides = {}) {
+        const raw = {
+            specVersion: "1.0",
+            id,
+            version: "1.0.0",
+            meta: {
+                name: overrides.name ?? id,
+                description: overrides.description ?? "",
+            },
+        };
+        const spec = resolveDefaults(raw);
+        assertValid(spec);
+        return new Grain(spec);
+    }
+    /** Create a Grain from a YAML or JSON string. */
+    static from(content) {
+        let data;
+        try {
+            data = JSON.parse(content);
+        }
+        catch {
+            data = parseYaml(content);
+        }
+        assertValid(data);
+        return new Grain(resolveDefaults(data));
+    }
+    /** Load a Grain from a .agent.yaml or .agent.json file. */
+    static load(filePath) {
+        const content = readFileSync(filePath, "utf-8");
+        let data;
+        if (filePath.endsWith(".json")) {
+            data = JSON.parse(content);
+        }
+        else {
+            data = parseYaml(content);
+        }
+        assertValid(data);
+        return new Grain(resolveDefaults(data));
+    }
+    /** Create a Grain from a plain AgentSpec object. */
+    static of(spec) {
+        assertValid(spec);
+        return new Grain(resolveDefaults(spec));
+    }
+    // ===========================================================================
+    // INTERNAL HELPER
+    // ===========================================================================
+    with(updater) {
+        const clone = structuredClone(this._data);
+        updater(clone);
+        return new Grain(clone);
+    }
+    // ===========================================================================
+    // READ ACCESSORS
+    // ===========================================================================
+    get id() { return this._data.id; }
+    get name() { return this._data.meta.name; }
+    get version() { return this._data.version; }
+    get personality() {
+        return { ...this._data.voice.personality };
+    }
+    get rules() {
+        return structuredClone(this._data.behavior.rules);
+    }
+    get boundaries() {
+        return structuredClone(this._data.behavior.boundaries);
+    }
+    get tools() {
+        return structuredClone(this._data.capabilities.tools ?? []);
+    }
+    get skills() {
+        return structuredClone(this._data.capabilities.skills ?? []);
+    }
+    get expertise() {
+        return structuredClone(this._data.identity.expertise);
+    }
+    get data() {
+        return this._data;
+    }
+    get isValid() {
+        return validateSpec(this._data).length === 0;
+    }
+    // ===========================================================================
+    // QUERY
+    // ===========================================================================
+    hasRule(id) {
+        return this._data.behavior.rules.some(r => r.id === id);
+    }
+    hasTool(name) {
+        return (this._data.capabilities.tools ?? []).some(t => t.id === name);
+    }
+    hasSkill(name) {
+        return (this._data.capabilities.skills ?? []).some(s => s.name === name);
+    }
+    // ===========================================================================
+    // MUTATIONS (all return new Grain)
+    // ===========================================================================
+    addRule(rule) {
+        return this.with(d => { d.behavior.rules.push(rule); });
+    }
+    removeRule(id) {
+        return this.with(d => { d.behavior.rules = d.behavior.rules.filter(r => r.id !== id); });
+    }
+    addRules(rules) {
+        return this.with(d => { d.behavior.rules.push(...rules); });
+    }
+    addBoundary(boundary) {
+        return this.with(d => { d.behavior.boundaries.push(boundary); });
+    }
+    removeBoundary(description) {
+        return this.with(d => {
+            d.behavior.boundaries = d.behavior.boundaries.filter(b => b.description !== description);
+        });
+    }
+    addBoundaries(boundaries) {
+        return this.with(d => { d.behavior.boundaries.push(...boundaries); });
+    }
+    addTool(tool) {
+        return this.with(d => {
+            if (!d.capabilities.tools)
+                d.capabilities.tools = [];
+            d.capabilities.tools.push(tool);
+        });
+    }
+    removeTool(name) {
+        return this.with(d => {
+            d.capabilities.tools = (d.capabilities.tools ?? []).filter(t => t.id !== name);
+        });
+    }
+    addTools(tools) {
+        return this.with(d => {
+            if (!d.capabilities.tools)
+                d.capabilities.tools = [];
+            d.capabilities.tools.push(...tools);
+        });
+    }
+    addSkill(skill) {
+        return this.with(d => {
+            if (!d.capabilities.skills)
+                d.capabilities.skills = [];
+            d.capabilities.skills.push(skill);
+        });
+    }
+    removeSkill(name) {
+        return this.with(d => {
+            d.capabilities.skills = (d.capabilities.skills ?? []).filter(s => s.name !== name);
+        });
+    }
+    addSkills(skills) {
+        return this.with(d => {
+            if (!d.capabilities.skills)
+                d.capabilities.skills = [];
+            d.capabilities.skills.push(...skills);
+        });
+    }
+    addExpertise(domain, proficiency) {
+        if (proficiency < 0 || proficiency > 1) {
+            throw new RangeError(`Proficiency must be between 0 and 1, got ${proficiency}`);
+        }
+        return this.with(d => {
+            d.identity.expertise.push({ domain, proficiency });
+        });
+    }
+    removeExpertise(domain) {
+        return this.with(d => {
+            d.identity.expertise = d.identity.expertise.filter(e => e.domain !== domain);
+        });
+    }
+    setPersonality(dim, value) {
+        if (value < 0 || value > 1) {
+            throw new RangeError(`Personality value must be between 0 and 1, got ${value} for ${dim}`);
+        }
+        return this.with(d => {
+            d.voice.personality[dim] = value;
+        });
+    }
+    set(path, value) {
+        return this.with(d => {
+            const parts = path.split(".");
+            let obj = d;
+            for (let i = 0; i < parts.length - 1; i++) {
+                obj = obj[parts[i]];
+            }
+            obj[parts[parts.length - 1]] = value;
+        });
+    }
+    get(path) {
+        const parts = path.split(".");
+        let obj = this._data;
+        for (const part of parts) {
+            obj = obj[part];
+        }
+        return obj;
+    }
+    merge(other) {
+        return this.with(d => {
+            deepMerge(d, other._data);
+        });
+    }
+    // ===========================================================================
+    // OUTPUT
+    // ===========================================================================
+    /**
+     * Clean YAML for LLM consumption.
+     * Strips SDK metadata (specVersion, id, version, meta.model, meta.tags,
+     * observability, adaptation). Keeps agent-facing content.
+     * Applies channel overrides if specified.
+     */
+    toString(channel) {
+        const clone = structuredClone(this._data);
+        // Apply channel overrides to voice
+        if (channel) {
+            const voice = clone.voice;
+            const overrides = voice.channelOverrides?.[channel];
+            if (overrides) {
+                const personality = voice.personality;
+                const language = voice.language;
+                Object.assign(personality, overrides);
+                Object.assign(language, overrides);
+            }
+        }
+        // Strip SDK metadata
+        delete clone.specVersion;
+        delete clone.id;
+        delete clone.version;
+        delete clone.observability;
+        delete clone.adaptation;
+        const meta = clone.meta;
+        delete meta.model;
+        delete meta.tags;
+        // Remove channelOverrides from voice (already applied or not needed)
+        const voice = clone.voice;
+        delete voice.channelOverrides;
+        return stringifyYaml(clone, { lineWidth: 0 });
+    }
+    /**
+     * Expanded natural language prompt with behavioral directives.
+     * Delegates to the existing prompt generator.
+     */
+    toPrompt(channel) {
+        return generateSystemPrompt(this._data, channel);
+    }
+    /** Full YAML including all metadata (for saving to file). */
+    toYAML() {
+        return stringifyYaml(structuredClone(this._data), { lineWidth: 0 });
+    }
+    /** Full JSON including all metadata. */
+    toJSON() {
+        return JSON.stringify(this._data, null, 2);
+    }
+    /** Validate and return errors. */
+    validate() {
+        return validateSpec(this._data);
+    }
+    /** Diff this Grain against another. Returns paths with before/after values. */
+    diff(other) {
+        const result = {};
+        diffObjects(this._data, other._data, "", result);
+        return result;
+    }
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+function deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+        const sv = source[key];
+        const tv = target[key];
+        if (isPlainObject(sv) && isPlainObject(tv)) {
+            deepMerge(tv, sv);
+        }
+        else {
+            target[key] = structuredClone(sv);
+        }
+    }
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function diffObjects(a, b, prefix, result) {
+    const allKeys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of allKeys) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        const av = a[key];
+        const bv = b[key];
+        if (isPlainObject(av) && isPlainObject(bv)) {
+            diffObjects(av, bv, path, result);
+        }
+        else if (Array.isArray(av) && Array.isArray(bv)) {
+            if (JSON.stringify(av) !== JSON.stringify(bv)) {
+                result[path] = { before: av, after: bv };
+            }
+        }
+        else if (av !== bv) {
+            result[path] = { before: av, after: bv };
+        }
+    }
+}
+//# sourceMappingURL=grain.js.map