@foldrun/core 0.2.0

package/dist/src/kinds.js

@@ -0,0 +1,421 @@
+// Every kind of document foldrun knows about, in one place.
+//
+// The naming, settled: these are **documents**. Not "resources" — MCP already
+// owns that word for something specific, and we speak MCP, so a "resource" in
+// our docs would be genuinely ambiguous. Not "entities" or "assets" either;
+// both are ORM words for things that are, plainly, markdown files. OKF calls
+// them documents and gives every one a `type:`, and we adopted OKF — so the
+// spec says *document*, the UI says the actual noun (agent, flow, skill), and
+// "resource" stays reserved for MCP.
+//
+// That leaves one rule, which this file exists to enforce:
+//
+//   **A document's kind is its path. Only OKF documents declare anything.**
+//
+// Agents, flows, evals, skills and tools carry no field naming what they are.
+// The directory already says it — `agents/x/agent.md` is an agent — and every
+// reader here resolves by path: listAgents scans agents/, parseFlow is handed
+// files from flows/. A field restating that is derived data sitting next to
+// its source, free to disagree with it, and nothing consumed it: the runtime
+// never branched on it and the model never saw it, because a system prompt is
+// built from the body, not the frontmatter.
+//
+// `type:` is different and stays. It is OKF's one required field, an open
+// vocabulary saying what a piece of knowledge is *about*, and it is genuinely
+// not derivable — two files side by side in knowledge/ can be a Policy and a
+// Price List. It also does real work: buildIndex groups index.md by it.
+//
+// So the asymmetry is not an oversight. Ours was redundant; OKF's carries
+// information nothing else has.
+//
+// Tools declare `transport:` (http | script | mcp) — how the tool reaches the
+// thing it calls, which is a different question from what the file is. A
+// legacy `type: http` is still read as a transport; see readTransport below.
+//
+// Everything downstream — creation templates, `foldrun init`, the scaffolder,
+// the dashboard's New button — reads this table. Adding a kind means adding a
+// row here and nothing else; that is the point.
+const envName = (name) => name.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+/**
+ * A slug as a starting display label: `house-style` → `House style`.
+ *
+ * A placeholder, not a guess to keep — the author renames it to whatever the
+ * document is actually called. Its job is to make the field present, because
+ * an absent `title` is the case that silently falls back to the slug.
+ */
+const titleCase = (slug) => {
+    const words = slug.replace(/[-_]+/g, " ").trim();
+    return words ? words[0].toUpperCase() + words.slice(1) : slug;
+};
+export const KINDS = {
+    agents: {
+        kind: "agents",
+        one: "agent",
+        docType: null,
+        docKey: null,
+        scopes: ["workspace"],
+        placeholder: "researcher",
+        hint: "Someone who does one job. Its instructions are the body of the file.",
+        file: (name) => `agents/${name}/agent.md`,
+        template: (name) => `---
+name: ${name}
+description: What this agent is for, in one line.
+model: fast
+effort: high
+tools: [files]
+---
+
+# ${name}
+
+What you do, in plain English. Be specific about what "done" looks like —
+this text is the whole of the agent's instructions.
+`,
+    },
+    evals: {
+        kind: "evals",
+        one: "eval",
+        docType: null,
+        docKey: null,
+        scopes: ["workspace"],
+        placeholder: "researcher-quality",
+        hint: "Cases an agent must pass. Run them after every edit to its prompt.",
+        file: (name) => `evals/${name}.md`,
+        template: (name) => `---
+name: ${name}
+agent: agent-name
+description: What this eval protects against.
+---
+
+## a short name for the case
+task: What to ask the agent.
+expect:
+  - contains: something the answer must mention
+  - judge: a sentence describing what a good answer does
+`,
+    },
+    flows: {
+        kind: "flows",
+        one: "flow",
+        docType: null,
+        docKey: null,
+        scopes: ["workspace"],
+        placeholder: "publish",
+        hint: "An ordered list of agents. Same number means they run in parallel.",
+        file: (name) => `flows/${name}.md`,
+        template: (name, ctx) => `---
+name: ${name}
+description: What this flow accomplishes, end to end.
+trigger: manual
+---
+
+1. [[${ctx?.firstAgent ?? "agent-name"}]] — what this step does
+`,
+    },
+    tools: {
+        kind: "tools",
+        one: "tool",
+        docType: null,
+        docKey: null,
+        scopes: ["account", "workspace"],
+        placeholder: "uuid-service",
+        hint: "Something an agent can call. Pick a type, name it, and the files are written for you.",
+        file: (name) => `tools/${name}.md`,
+        template: (name) => `---
+transport: http
+name: ${name}
+description: What this does, and when to call it.
+base: https://api.example.com/v1
+methods: [GET]
+headers:
+  Authorization: Bearer \${${envName(name)}_TOKEN}
+---
+
+Notes for whoever maintains this. Agents opt in with:
+
+\`\`\`yaml
+tools: [${name}]
+\`\`\`
+`,
+    },
+    // Last, and not navigable: a folder tool holds its own code, so scripts
+    // is material a tool carries rather than a shelf anyone picks from. The
+    // directory still exists and library/x.py still resolves — it just isn't
+    // a decision, so the sidebar has no door for it.
+    knowledge: {
+        kind: "knowledge",
+        one: "knowledge doc",
+        docType: "Reference",
+        // OKF's field and OKF's vocabulary — `Reference` is only the starting point.
+        docKey: "type",
+        scopes: ["account", "workspace", "agent"],
+        placeholder: "pricing",
+        hint: "Reference material, given not learned. Agents read it, never write it.",
+        file: (name) => `knowledge/${name}.md`,
+        // See the memory template: OKF's fields only.
+        template: (name) => `---
+type: Reference
+title: ${titleCase(name)}
+description: Reference material agents look up. Given, not learned.
+status: stable
+---
+
+The reference content. Agents read this and never rewrite it.
+`,
+    },
+    memory: {
+        kind: "memory",
+        one: "memory",
+        docType: "Fact",
+        // OKF's field and OKF's vocabulary — `Fact` is only the starting point.
+        docKey: "type",
+        scopes: ["account", "workspace", "agent"],
+        placeholder: "house-tone",
+        hint: "One durable fact, learned. Agents write here themselves.",
+        file: (name) => `memory/${name}.md`,
+        // `title` and nothing of ours. A bundle carries the format's fields, so a
+        // reader that has never heard of this platform loses nothing: `name` was
+        // ours, undefined by OKF, and an outside consumer had no reason to read
+        // it — it fell back to the filename and showed a slug.
+        template: (name) => `---
+type: Fact
+title: ${titleCase(name)}
+description: One durable fact.
+status: stable
+---
+
+The fact.
+
+**Why:** what made it worth remembering.
+`,
+    },
+    skills: {
+        kind: "skills",
+        one: "skill",
+        docType: null,
+        docKey: null,
+        scopes: ["account", "workspace", "agent"],
+        placeholder: "plain-english",
+        hint: "A procedure an agent loads when it needs it. Folder, not one file.",
+        file: (name) => `skills/${name}/SKILL.md`,
+        template: (name) => `---
+name: ${name}
+description: What this skill does, and when an agent should use it.
+---
+
+# ${name}
+
+Step-by-step instructions. Bundle code in this folder's scripts/ if it needs any.
+`,
+    },
+    scripts: {
+        kind: "scripts",
+        one: "script",
+        // Code, not a document — no frontmatter to carry either field. A tool
+        // file points at it.
+        docType: null,
+        docKey: null,
+        scopes: ["account", "workspace", "agent"],
+        placeholder: "slugify",
+        hint: "Code an agent runs through a tool. Deterministic work belongs here.",
+        file: (name) => `scripts/${name}.py`,
+        template: (name) => `#!/usr/bin/env python3
+"""${name}"""
+import argparse
+
+p = argparse.ArgumentParser()
+p.add_argument("--input")
+args = p.parse_args()
+
+print(args.input)
+`,
+    },
+};
+/**
+ * What a script tool can be written in.
+ *
+ * Three, not every language the runner can execute. The runner picks an
+ * interpreter from the file extension, so `.rb` and the rest keep working the
+ * moment someone renames a file — but a picker with nine entries is a quiz,
+ * and three covers what people actually reach for. The point of asking at all
+ * is that "script tool" silently meaning JavaScript was a thing you had to
+ * find out by reading the file it made.
+ */
+export const SCRIPT_LANGUAGES = [
+    { value: "javascript", label: "JavaScript", ext: ".mjs", hint: "node — the default" },
+    { value: "python", label: "Python", ext: ".py", hint: "python3" },
+    { value: "bash", label: "Shell", ext: ".sh", hint: "bash — for wrapping a command" },
+];
+/** The starting program, in each language. Every one of them does the same
+ *  three things, because those three are the tool contract:
+ *
+ *    validate its own arguments   — every declared arg is OPTIONAL at the
+ *                                   call site, so required means checked here
+ *    print the result on stdout   — that is what the agent reads back
+ *    exit non-zero on failure     — that is what tells the agent it failed
+ */
+const PROGRAMS = {
+    javascript: `import { parseArgs } from "node:util";
+
+// Every declared arg is optional at the call site — the model may omit any of
+// them, and an empty value is never passed — so required means checked here.
+const { values } = parseArgs({ options: { input: { type: "string" } } });
+if (!values.input) {
+  console.error("need --input");
+  process.exit(1);
+}
+
+// One JSON object on stdout: small, structured, and the same shape every call.
+console.log(JSON.stringify({ input: values.input }));
+`,
+    python: `#!/usr/bin/env python3
+import argparse, json
+
+# Every declared arg is optional at the call site — the model may omit any of
+# them, and an empty value is never passed — so required means checked here.
+# argparse exits 2 with a usage line on stderr, which is exactly the signal
+# the agent should get.
+p = argparse.ArgumentParser()
+p.add_argument("--input", required=True)
+a = p.parse_args()
+
+# One JSON object on stdout: small, structured, and the same shape every call.
+print(json.dumps({"input": a.input}))
+`,
+    bash: `#!/usr/bin/env bash
+set -euo pipefail
+
+# Declared args arrive as long flags: --input value
+input=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --input) input="\${2-}"; shift 2 ;;
+    *) echo "unexpected argument: $1" >&2; exit 1 ;;
+  esac
+done
+
+# Every declared arg is optional at the call site, so required means checked
+# here. A non-zero exit is what tells the agent the call failed.
+[ -n "$input" ] || { echo "need --input" >&2; exit 1; }
+
+# Whatever this prints on stdout is what the agent reads back. Keep it small
+# and regular — print JSON when the result has structure.
+echo "$input"
+`,
+};
+/**
+ * A new tool, as the files it starts as.
+ *
+ * Three transports, two shapes. An API or an MCP server is a definition and
+ * nothing else, so it stays one flat file. A script tool is a definition and
+ * the code it runs, which cannot be separated without the tool silently
+ * resolving to nothing — so it starts as a folder holding both, with `run:`
+ * relative to itself and naming no scope.
+ *
+ * Returned as a list because "create a tool" is not always one write, and
+ * the callers that stamp templates should not have to know which case they
+ * are in.
+ */
+export function toolStarter(name, transport, language = "javascript") {
+    if (transport === "script") {
+        // A folder, because the program is a file. Code in a fenced block gets
+        // no linter, no type checker, no formatter and no way to run it except
+        // through a run — and the agents editing these are file-shaped tools:
+        // they can patch one line of run.mjs and execute it, where a fence has
+        // to be re-emitted whole and can only be tested by shipping it. The
+        // single-file form still parses, for a tool small enough to read at a
+        // glance; it is no longer what a new one starts as.
+        //
+        // The language is asked for rather than assumed. "Script tool" used to
+        // mean JavaScript silently, which you found out by opening the file it
+        // wrote; the runner has always picked an interpreter from the extension,
+        // so the choice was already real and merely hidden.
+        const lang = SCRIPT_LANGUAGES.find((l) => l.value === language) ?? SCRIPT_LANGUAGES[0];
+        const program = `run${lang.ext}`;
+        return [
+            {
+                file: `tools/${name}/tool.md`,
+                content: `---
+transport: script
+name: ${name}
+description: What this does, and when an agent should call it.
+run: ${program}
+args:
+  input: What the caller passes in
+timeout: 60
+---
+
+\`${program}\` beside this file is the tool. Arguments arrive as --flags, one
+per \`args:\` entry; whatever it prints on stdout is what the agent reads back,
+and a non-zero exit is what tells the agent the call failed.
+
+\`run:\` names the file, never the scope it sits in, so this folder is correct
+copied into any workspace or installed at the account.
+
+Needs a package? Declare it here and it is installed for every agent that
+grants this tool — the tool is the unit of code, so its dependencies travel
+with it:
+
+\`\`\`yaml
+runtime:
+  packages: [requests]      # pip
+  npm: [cheerio]            # npm
+\`\`\`
+
+Agents opt in with:
+
+\`\`\`yaml
+tools: [${name}]
+\`\`\`
+
+Run it by hand while you are writing it:
+
+\`\`\`console
+${lang.value === "python" ? "python3" : lang.value === "bash" ? "bash" : "node"} tools/${name}/${program} --input hello
+\`\`\`
+`,
+            },
+            { file: `tools/${name}/${program}`, content: PROGRAMS[lang.value] },
+        ];
+    }
+    if (transport === "mcp") {
+        return [
+            {
+                file: `tools/${name}.md`,
+                content: `---
+transport: mcp
+name: ${name}
+description: What this server provides, and when an agent should reach for it.
+command: npx
+args: ["-y", "@example/mcp-server"]
+env:
+  EXAMPLE_TOKEN: \${${envName(name)}_TOKEN}
+---
+
+Every tool this server exposes reaches the agent that opts in with:
+
+\`\`\`yaml
+tools: [${name}]
+\`\`\`
+`,
+            },
+        ];
+    }
+    return [{ file: KINDS.tools.file(name), content: KINDS.tools.template(name) }];
+}
+export const ALL_KINDS = Object.keys(KINDS);
+/** The kinds that exist at a given scope. */
+export const kindsAt = (scope) => ALL_KINDS.filter((k) => KINDS[k].scopes.includes(scope));
+/** The noun a kind declares, for asserting a file says what it is. */
+export const docTypeOf = (kind) => KINDS[kind].docType;
+/** Which frontmatter key carries that noun — `kind:` for ours, `type:` for OKF's. */
+export const docKeyOf = (kind) => KINDS[kind].docKey;
+const TRANSPORTS = new Set(["http", "script", "mcp"]);
+export function readTransport(data) {
+    const explicit = typeof data.transport === "string" ? data.transport.toLowerCase() : null;
+    if (explicit && TRANSPORTS.has(explicit))
+        return explicit;
+    const legacy = typeof data.type === "string" ? data.type.toLowerCase() : null;
+    if (legacy && TRANSPORTS.has(legacy))
+        return legacy;
+    return null;
+}

package/dist/src/library.d.ts

@@ -0,0 +1,94 @@
+import { type ToolDef } from "./store.ts";
+export type LibraryKind = "skills" | "scripts" | "memory" | "knowledge" | "tools";
+export declare const LIBRARY_KINDS: LibraryKind[];
+export declare function libraryDir(tenant: string, kind?: LibraryKind): string;
+export interface LibraryEntry {
+    /** Path relative to this kind's directory. */
+    path: string;
+    name: string;
+    description: string;
+    /** For skills: true when the folder bundles scripts/. */
+    hasScripts?: boolean;
+    /**
+     * For tools: how this one connects — http, script or mcp. Surfaced so a
+     * list of tools reads as one vocabulary with three transports, rather
+     * than a page of names whose differences are invisible until you open
+     * them. For a script tool it also names the file it runs, which is the
+     * link between this shelf and the code shelf.
+     */
+    transport?: "http" | "script" | "mcp";
+    runs?: string;
+    updatedAt: string;
+}
+export declare function listLibrary(tenant: string, kind: LibraryKind): LibraryEntry[];
+export declare function readLibraryFile(tenant: string, kind: LibraryKind, rel: string): string;
+/** Is there already something here? For refusing to create over it. */
+export declare function libraryFileExists(tenant: string, kind: LibraryKind, rel: string): boolean;
+export declare function writeLibraryFile(tenant: string, kind: LibraryKind, rel: string, content: string, meta?: {
+    by?: string;
+    message?: string;
+}): void;
+export declare function deleteLibraryPath(tenant: string, kind: LibraryKind, rel: string, meta?: {
+    by?: string;
+    message?: string;
+}): void;
+/** Library tool definitions, keyed by name — http or script, both grantable by name in `tools:`. */
+export declare function libraryTools(tenant: string): Record<string, ToolDef>;
+/** Shared memory index — derived from the files, like every other scope. */
+export declare function libraryMemoryIndex(tenant: string): string | null;
+/**
+ * Account-scope creation, expressed as a path inside `library/<kind>/`.
+ *
+ * The content comes from KINDS — an account skill and a workspace skill are
+ * the same document in a different place, and used to be two templates that
+ * drifted. `file()` returns a path from the scope root (`skills/x/SKILL.md`);
+ * here the kind directory is already the root, so the leading segment goes.
+ */
+export declare const LIBRARY_TEMPLATES: Record<LibraryKind, (name: string) => {
+    path: string;
+    content: string;
+}>;
+/**
+ * Who actually depends on a shared file.
+ *
+ * The account library is the one place where editing a single file changes
+ * behaviour in workspaces you are not looking at, and nothing in the product
+ * could answer "if I rotate this credential, what breaks?" The graph shows
+ * containment — a library tool hangs off the account node — never consumption,
+ * so the edge that matters was the one edge missing.
+ *
+ * Two relations, because the shared scopes work in two different ways:
+ *
+ *   use       an explicit grant. Only tools have one (`tools: [name]`), which
+ *             is exactly why tools are the kind worth tracing: a credential
+ *             reaches precisely the agents that named it, and no others.
+ *
+ *   shadowed  a nearer file of the same name wins. This is the quiet one — the
+ *             account file still exists, still looks live on this page, and is
+ *             not what runs in that workspace. Resolution is nearest-wins, so
+ *             a name collision is a silent override rather than an error.
+ *
+ * Everything else (memory, knowledge) is indexed for every agent in scope with
+ * no per-agent opt-in, so "used by" is "everyone" — true, and not information.
+ * Those kinds report shadowing only.
+ */
+export interface LibraryUse {
+    workspace: string;
+    /** The agent that opted in or overrides it; null when it is workspace-wide. */
+    agent: string | null;
+    relation: "use" | "shadowed";
+}
+export declare function libraryUsage(tenant: string, kind: LibraryKind, name: string): LibraryUse[];
+/**
+ * Make the shelf match a tree — what a push to the library repository does.
+ * Written with plain fs and recorded as ONE revision at the end: going
+ * through writeLibraryFile per file would commit each one on top of the
+ * pushed commit, and the history would show a push as fifty edits.
+ */
+export declare function syncLibraryFromTree(tenant: string, files: {
+    path: string;
+    content: string;
+}[], meta?: {
+    by?: string;
+    commit?: string | null;
+}): number;