@codemation/agent-skills 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @codemation/agent-skills
 
+## 0.1.8
+
+### Patch Changes
+
+- [#78](https://github.com/MadeRelevant/codemation/pull/78) [`f451b1b`](https://github.com/MadeRelevant/codemation/commit/f451b1b4657b59406e15ce5f50b243e487ff99ed) Thanks [@cblokland90](https://github.com/cblokland90)! - Normalize fluent workflow DSL callback helpers around the runtime item contract.
+
+  `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` now receive `(item, ctx)` so workflow authors can use `item.json` consistently and read prior completed outputs through `ctx.data` without dropping down to direct node configs.
+
+## 0.1.7
+
+### Patch Changes
+
+- [#77](https://github.com/MadeRelevant/codemation/pull/77) [`525a311`](https://github.com/MadeRelevant/codemation/commit/525a311fe7868772c923f92e268730dab422cf97) Thanks [@cblokland90](https://github.com/cblokland90)! - Expose the packaged agent skills extractor as an importable module and refresh `.agents/skills/extracted` automatically when running `codemation dev`, `codemation build`, `codemation serve web`, or `codemation dev:plugin`. Add `codemation skills sync` for manual or CI refreshes after upgrading the CLI.
+
+- [#71](https://github.com/MadeRelevant/codemation/pull/71) [`3044e73`](https://github.com/MadeRelevant/codemation/commit/3044e73fd3cfb33f8e2cbc579c10baf97ed94658) Thanks [@cblokland90](https://github.com/cblokland90)! - Add inline callable agent tools to the workflow DSL.
+
+  This introduces `callableTool(...)` as a workflow-friendly helper for app-local agent tools, keeps
+  `CallableToolFactory.callableTool(...)` as a compatible factory entry point, teaches `AIAgentNode`
+  to execute callable tools with the same tracing and validation model as other tool kinds, and
+  updates docs, skills, and the test-dev sample to show the new path.
+
+- [#73](https://github.com/MadeRelevant/codemation/pull/73) [`418434a`](https://github.com/MadeRelevant/codemation/commit/418434a6a2ad88a6254a94cb70e6f14b886df348) Thanks [@cblokland90](https://github.com/cblokland90)! - Improve credential UX and add extensible advanced field presentation.
+  - Run automatic credential health tests after create/save (including OAuth) and keep the dialog open when the test fails; auto-bind newly created credentials to empty workflow slots; auto-bind when picking an existing credential from the workflow slot dropdown while the slot is unbound.
+  - Add `CredentialFieldSchema.visibility` (`default` | `advanced`) and optional `CredentialTypeDefinition.advancedSection` (advanced fields always render in a collapsible block; section labels default when omitted). Next host uses stable test ids and fixes collapsible chevron styling.
+  - Credential dialog: title uses the credential type name (e.g. **Add …** / type display name on edit); hide the redundant type dropdown in edit mode.
+  - Gmail OAuth: group Client ID with Client secret, move scope preset and custom scopes under an **OAuth scopes** advanced section (collapsed by default).
+  - Documentation: `packages/core/docs/credential-ui-fields.md`, AGENTS.md, and credential development skill reference.
+
+- [#74](https://github.com/MadeRelevant/codemation/pull/74) [`26ebe63`](https://github.com/MadeRelevant/codemation/commit/26ebe6346db0e9133a2133435a463c3dcd2dc537) Thanks [@cblokland90](https://github.com/cblokland90)! - Unify `workflow().agent()` message authoring with `AIAgent`.
+
+  `WorkflowAgentOptions` now takes `messages` (the same `AgentMessageConfig` as `AIAgent`) instead of
+  `prompt`. The workflow helper passes `messages` through unchanged. Docs, workflow DSL skills, and the
+  test-dev sample use `itemValue(...)` for per-item prompts; execution docs note `itemValue` on agent
+  `messages`.
+
+## Unreleased
+
+### Patch Changes
+
+- Workflow DSL skill: document **`callableTool(...)`** for inline agent tools (with **`CallableToolFactory.callableTool(...)`** as the equivalent factory entry point).
+
 ## 0.1.6
 
 ### Patch Changes

package/README.md

@@ -6,6 +6,7 @@ Publishable Codemation agent skills packaged as `SKILL.md` directories.
 
 - shared Codemation skills for CLI usage, workflow authoring, plugin development, credentials, and framework concepts
 - a small extraction CLI that copies the packaged skills into a project-local `.agents/skills` directory
+- a programmatic API (`@codemation/agent-skills`) used by `@codemation/cli` to refresh packaged skills on consumer workflows
 
 ## Install in a project
 
@@ -16,6 +17,25 @@ codemation-agent-skills extract --output .agents/skills/extracted
 
 The starter templates call the extractor automatically after `pnpm install`.
 
+## Framework-managed copy
+
+The directory `.agents/skills/extracted` is **framework-managed**: Codemation overwrites packaged `codemation-*` skill folders there and removes stale packaged skill directories when you run `codemation dev`, `codemation build`, `codemation serve web`, or `codemation dev:plugin` (or `codemation skills sync`). Put project-local skills in sibling folders under `.agents/skills`, not inside `extracted`, unless you accept them being replaced.
+
+## Programmatic use
+
+```js
+import { FileSystemGateway, SkillExtractor, resolveAgentSkillsPackageRoot } from "@codemation/agent-skills";
+
+const consumerRoot = process.cwd();
+const extractor = new SkillExtractor(
+  new FileSystemGateway(),
+  resolveAgentSkillsPackageRoot(),
+  consumerRoot,
+  process.stdout,
+);
+await extractor.extract(".agents/skills/extracted");
+```
+
 ## Published layout
 
 ```text

package/bin/codemation-agent-skills.mjs

@@ -2,171 +2,18 @@
 
 import path from "node:path";
 import process from "node:process";
-import { cp, mkdir, readdir, rm, stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
-export class CommandError extends Error {}
+export {
+  CodemationAgentSkillsCli,
+  CommandError,
+  CommandLineParser,
+  FileSystemGateway,
+  SkillExtractor,
+  resolveAgentSkillsPackageRoot,
+} from "../lib/agent-skills-extractor.mjs";
 
-export class FileSystemGateway {
-  async copyDirectory(sourcePath, destinationPath) {
-    await cp(sourcePath, destinationPath, { force: true, recursive: true });
-  }
-
-  async createDirectory(targetPath) {
-    await mkdir(targetPath, { recursive: true });
-  }
-
-  async listDirectoryEntries(targetPath) {
-    return readdir(targetPath, { withFileTypes: true });
-  }
-
-  async removePath(targetPath) {
-    await rm(targetPath, { force: true, recursive: true });
-  }
-
-  async statPath(targetPath) {
-    return stat(targetPath);
-  }
-}
-
-export class SkillExtractor {
-  constructor(fileSystem, packageRoot, cwd, stdout) {
-    this.fileSystem = fileSystem;
-    this.packageRoot = packageRoot;
-    this.cwd = cwd;
-    this.stdout = stdout;
-  }
-
-  async extract(outputArgument) {
-    const outputPath = path.resolve(this.cwd, outputArgument);
-    const skillsRoot = path.join(this.packageRoot, "skills");
-
-    await this.fileSystem.createDirectory(outputPath);
-    const packagedEntries = await this.fileSystem.listDirectoryEntries(skillsRoot);
-    const packagedSkillNames = new Set(
-      packagedEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
-    );
-
-    await this.#removeStaleSkillDirectories(outputPath, packagedSkillNames);
-
-    for (const skillName of packagedSkillNames) {
-      const sourcePath = path.join(skillsRoot, skillName);
-      const destinationPath = path.join(outputPath, skillName);
-      await this.fileSystem.removePath(destinationPath);
-      await this.fileSystem.copyDirectory(sourcePath, destinationPath);
-      this.stdout.write(`[codemation-agent-skills] extracted ${skillName}\n`);
-    }
-  }
-
-  async #removeStaleSkillDirectories(outputPath, packagedSkillNames) {
-    let existingEntries;
-    try {
-      existingEntries = await this.fileSystem.listDirectoryEntries(outputPath);
-    } catch {
-      return;
-    }
-
-    for (const entry of existingEntries) {
-      if (!entry.isDirectory()) {
-        continue;
-      }
-      if (!entry.name.startsWith("codemation-")) {
-        continue;
-      }
-      if (packagedSkillNames.has(entry.name)) {
-        continue;
-      }
-      await this.fileSystem.removePath(path.join(outputPath, entry.name));
-    }
-  }
-}
-
-export class CommandLineParser {
-  constructor(argv) {
-    this.argv = argv;
-  }
-
-  parse() {
-    const [command, ...rest] = this.argv;
-    if (!command || command === "--help" || command === "-h") {
-      return { command: "help" };
-    }
-    if (command !== "extract") {
-      throw new CommandError(`Unknown command "${command}".`);
-    }
-
-    let output = ".agents/skills/extracted";
-    for (let index = 0; index < rest.length; index += 1) {
-      const argument = rest[index];
-      if (argument === "--output") {
-        const value = rest[index + 1];
-        if (!value) {
-          throw new CommandError("Missing value for --output.");
-        }
-        output = value;
-        index += 1;
-        continue;
-      }
-      if (argument === "--help" || argument === "-h") {
-        return { command: "help" };
-      }
-      throw new CommandError(`Unknown argument "${argument}".`);
-    }
-
-    return { command: "extract", output };
-  }
-}
-
-export class CodemationAgentSkillsCli {
-  constructor(argv, cwd, stdout, stderr) {
-    this.argv = argv;
-    this.cwd = cwd;
-    this.stdout = stdout;
-    this.stderr = stderr;
-    this.fileSystem = new FileSystemGateway();
-  }
-
-  async run() {
-    try {
-      const parsed = new CommandLineParser(this.argv).parse();
-      if (parsed.command === "help") {
-        this.#writeHelp();
-        return;
-      }
-
-      const packageRoot = path.resolve(import.meta.dirname, "..");
-      const extractor = new SkillExtractor(this.fileSystem, packageRoot, this.cwd, this.stdout);
-      await extractor.extract(parsed.output);
-    } catch (error) {
-      if (error instanceof CommandError) {
-        this.stderr.write(`${error.message}\n\n`);
-        this.#writeHelp();
-        process.exitCode = 1;
-        return;
-      }
-      this.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-      process.exitCode = 1;
-    }
-  }
-
-  #writeHelp() {
-    this.stdout.write(
-      [
-        "codemation-agent-skills",
-        "",
-        "Usage:",
-        "  codemation-agent-skills extract [--output <path>]",
-        "",
-        "Commands:",
-        "  extract    Copy packaged Codemation skills into a project directory.",
-        "",
-        "Options:",
-        "  --output   Destination directory. Defaults to .agents/skills/extracted.",
-        "",
-      ].join("\n"),
-    );
-  }
-}
+import { CodemationAgentSkillsCli } from "../lib/agent-skills-extractor.mjs";
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   await new CodemationAgentSkillsCli(process.argv.slice(2), process.cwd(), process.stdout, process.stderr).run();

package/lib/agent-skills-extractor.d.ts

@@ -0,0 +1,41 @@
+import type { Dirent } from "node:fs";
+
+export class CommandError extends Error {}
+
+export class FileSystemGateway {
+  copyDirectory(sourcePath: string, destinationPath: string): Promise<void>;
+  createDirectory(targetPath: string): Promise<void>;
+  listDirectoryEntries(targetPath: string): Promise<Dirent[]>;
+  removePath(targetPath: string): Promise<void>;
+  statPath(targetPath: string): Promise<import("node:fs").Stats>;
+}
+
+export function resolveAgentSkillsPackageRoot(): string;
+
+export class SkillExtractor {
+  constructor(
+    fileSystem: FileSystemGateway,
+    packageRoot: string,
+    cwd: string,
+    stdout: { write: (chunk: string) => void },
+  );
+
+  extract(outputArgument: string): Promise<void>;
+}
+
+export class CommandLineParser {
+  constructor(argv: ReadonlyArray<string>);
+
+  parse(): { command: "help" } | { command: "extract"; output: string };
+}
+
+export class CodemationAgentSkillsCli {
+  constructor(
+    argv: ReadonlyArray<string>,
+    cwd: string,
+    stdout: { write: (chunk: string) => void },
+    stderr: { write: (chunk: string) => void },
+  );
+
+  run(): Promise<void>;
+}

package/lib/agent-skills-extractor.mjs

@@ -0,0 +1,178 @@
+import path from "node:path";
+import process from "node:process";
+import { cp, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export class CommandError extends Error {}
+
+export class FileSystemGateway {
+  async copyDirectory(sourcePath, destinationPath) {
+    await cp(sourcePath, destinationPath, { force: true, recursive: true });
+  }
+
+  async createDirectory(targetPath) {
+    await mkdir(targetPath, { recursive: true });
+  }
+
+  async listDirectoryEntries(targetPath) {
+    return readdir(targetPath, { withFileTypes: true });
+  }
+
+  async removePath(targetPath) {
+    await rm(targetPath, { force: true, recursive: true });
+  }
+
+  async statPath(targetPath) {
+    return stat(targetPath);
+  }
+}
+
+/**
+ * Resolves the root directory of the `@codemation/agent-skills` package (contains `skills/`).
+ */
+export function resolveAgentSkillsPackageRoot() {
+  const libDir = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(libDir, "..");
+}
+
+export class SkillExtractor {
+  constructor(fileSystem, packageRoot, cwd, stdout) {
+    this.fileSystem = fileSystem;
+    this.packageRoot = packageRoot;
+    this.cwd = cwd;
+    this.stdout = stdout;
+  }
+
+  /**
+   * @param {string} outputArgument relative or absolute path for extracted skills
+   */
+  async extract(outputArgument) {
+    const outputPath = path.resolve(this.cwd, outputArgument);
+    const skillsRoot = path.join(this.packageRoot, "skills");
+
+    await this.fileSystem.createDirectory(outputPath);
+    const packagedEntries = await this.fileSystem.listDirectoryEntries(skillsRoot);
+    const packagedSkillNames = new Set(
+      packagedEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name),
+    );
+
+    await this.#removeStaleSkillDirectories(outputPath, packagedSkillNames);
+
+    for (const skillName of packagedSkillNames) {
+      const sourcePath = path.join(skillsRoot, skillName);
+      const destinationPath = path.join(outputPath, skillName);
+      await this.fileSystem.removePath(destinationPath);
+      await this.fileSystem.copyDirectory(sourcePath, destinationPath);
+      this.stdout.write(`[codemation-agent-skills] extracted ${skillName}\n`);
+    }
+  }
+
+  async #removeStaleSkillDirectories(outputPath, packagedSkillNames) {
+    let existingEntries;
+    try {
+      existingEntries = await this.fileSystem.listDirectoryEntries(outputPath);
+    } catch {
+      return;
+    }
+
+    for (const entry of existingEntries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      if (!entry.name.startsWith("codemation-")) {
+        continue;
+      }
+      if (packagedSkillNames.has(entry.name)) {
+        continue;
+      }
+      await this.fileSystem.removePath(path.join(outputPath, entry.name));
+    }
+  }
+}
+
+export class CommandLineParser {
+  constructor(argv) {
+    this.argv = argv;
+  }
+
+  parse() {
+    const [command, ...rest] = this.argv;
+    if (!command || command === "--help" || command === "-h") {
+      return { command: "help" };
+    }
+    if (command !== "extract") {
+      throw new CommandError(`Unknown command "${command}".`);
+    }
+
+    let output = ".agents/skills/extracted";
+    for (let index = 0; index < rest.length; index += 1) {
+      const argument = rest[index];
+      if (argument === "--output") {
+        const value = rest[index + 1];
+        if (!value) {
+          throw new CommandError("Missing value for --output.");
+        }
+        output = value;
+        index += 1;
+        continue;
+      }
+      if (argument === "--help" || argument === "-h") {
+        return { command: "help" };
+      }
+      throw new CommandError(`Unknown argument "${argument}".`);
+    }
+
+    return { command: "extract", output };
+  }
+}
+
+export class CodemationAgentSkillsCli {
+  constructor(argv, cwd, stdout, stderr) {
+    this.argv = argv;
+    this.cwd = cwd;
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.fileSystem = new FileSystemGateway();
+  }
+
+  async run() {
+    try {
+      const parsed = new CommandLineParser(this.argv).parse();
+      if (parsed.command === "help") {
+        this.#writeHelp();
+        return;
+      }
+
+      const packageRoot = resolveAgentSkillsPackageRoot();
+      const extractor = new SkillExtractor(this.fileSystem, packageRoot, this.cwd, this.stdout);
+      await extractor.extract(parsed.output);
+    } catch (error) {
+      if (error instanceof CommandError) {
+        this.stderr.write(`${error.message}\n\n`);
+        this.#writeHelp();
+        process.exitCode = 1;
+        return;
+      }
+      this.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+      process.exitCode = 1;
+    }
+  }
+
+  #writeHelp() {
+    this.stdout.write(
+      [
+        "codemation-agent-skills",
+        "",
+        "Usage:",
+        "  codemation-agent-skills extract [--output <path>]",
+        "",
+        "Commands:",
+        "  extract    Copy packaged Codemation skills into a project directory.",
+        "",
+        "Options:",
+        "  --output   Destination directory. Defaults to .agents/skills/extracted.",
+        "",
+      ].join("\n"),
+    );
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/agent-skills",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Reusable agent skills for Codemation projects and plugin development.",
   "publishConfig": {
     "access": "public"
@@ -14,6 +14,13 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/agent-skills-extractor.d.ts",
+      "import": "./lib/agent-skills-extractor.mjs",
+      "default": "./lib/agent-skills-extractor.mjs"
+    }
+  },
   "bin": {
     "codemation-agent-skills": "./bin/codemation-agent-skills.mjs"
   },
@@ -34,6 +41,7 @@
     "README.md",
     "CHANGELOG.md",
     "bin",
+    "lib",
     "skills"
   ],
   "scripts": {

package/skills/codemation-credential-development/references/credential-patterns.md

@@ -31,6 +31,15 @@ credentials: {
 
 Then the runtime can supply a typed session through the named slot.
 
+## Advanced fields in the credential dialog
+
+Optional or power-user fields (for example custom OAuth scopes) can be tucked behind a single collapsible section:
+
+- Set `visibility: "advanced"` on each relevant `CredentialFieldSchema` entry in `publicFields` / `secretFields`.
+- Optionally set `advancedSection: { title?, description?, defaultOpen? }` on `CredentialTypeDefinition` to customize the collapsible header (if omitted, the UI still wraps advanced fields in a collapsed section titled **Advanced**).
+
+See **`packages/core/docs/credential-ui-fields.md`** in the repository root layout.
+
 ## Health and activation
 
 - deploy the workflow and credential type

package/skills/codemation-workflow-dsl/SKILL.md

@@ -18,6 +18,7 @@ Do not use this skill for CLI-only troubleshooting or deep host architecture que
 2. The fluent authoring chain is the normal starting point for Codemation apps.
 3. Finish fluent workflow definitions with `.build()`.
 4. Activations are **batch-shaped** (`Items`); many steps use **per-item** execution (`execute`, including helper **`defineNode`**) with optional **`inputSchema`** and **`itemValue`** on config fields. Batch reshape steps (split/filter/aggregate, **`defineBatchNode`**) work on the whole batch.
+5. Fluent callback helpers follow the runtime item contract: `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` receive `(item, ctx)`, so row fields live under `item.json` and earlier completed outputs are available through `ctx.data`.
 
 ## Authoring rules
 
@@ -34,6 +35,20 @@ Do not use this skill for CLI-only troubleshooting or deep host architecture que
 4. Add transformations or nodes in execution order.
 5. End with `.build()`.
 
+## Agent tools (callable helpers)
+
+- For **inline** agent tools in workflow files (no separate `@tool()` class), use **`callableTool(...)`** from `@codemation/core`: supply `name`, Zod `inputSchema` / `outputSchema`, and `execute({ input, item, ctx, ... })`. **`CallableToolFactory.callableTool(...)`** is the same implementation if you prefer the factory style.
+- Prefer **plugin `Tool` classes** when the tool is reusable across packages; use **`AgentToolFactory.asTool(...)`** when exposing an existing runnable node to the agent.
+
+## Workflow agent authoring
+
+- Use `.agent(...)` for fluent workflow-defined agent steps.
+- Define agent messages with `messages`, not a workflow-specific prompt shortcut.
+- Use a static `messages` array for fixed prompts.
+- Use `itemValue(...)` when agent messages depend on the current item.
+- Use fluent `.map((item, ctx) => ...)` when workflow data itself needs reshaping before the agent step.
+- `model` may be a provider string such as `"openai:gpt-4o-mini"` or a `ChatModelConfig`.
+
 ## Read next when needed
 
 - Read `references/builder-patterns.md` for item-flow rules and fluent authoring patterns.

package/skills/codemation-workflow-dsl/references/builder-patterns.md

@@ -8,8 +8,8 @@ export default workflow("wf.example.id")
   .manualTrigger("Start", {
     step: "start",
   })
-  .map("Transform", (item) => ({
-    ...item,
+  .map("Transform", (item, _ctx) => ({
+    ...item.json,
     transformed: true,
   }))
   .build();
@@ -27,6 +27,8 @@ export default workflow("wf.example.id")
 - items usually carry `json` data and optional `binary` data
 - runtime nodes receive batches of items, not just one record
 - author workflow steps with batching in mind
+- fluent `.map(...)`, `.if(...)`, and `.switch({ resolveCaseKey })` callbacks receive `(item, ctx)`
+- read row fields from `item.json` and earlier completed outputs from `ctx.data`
 
 ## When to move beyond callbacks
 
@@ -42,3 +44,16 @@ Promote inline callbacks into custom nodes when:
 - the fluent DSL is the friendly authoring surface
 - `@codemation/core` still owns planning, execution, continuation, and runtime contracts
 - host and node packages add the surrounding product capabilities
+
+## Inline callable agent tools
+
+- import `callableTool` from `@codemation/core`
+- build tools with `callableTool({ name, inputSchema, outputSchema, execute, credentialRequirements? })` (equivalent to `CallableToolFactory.callableTool(...)`)
+- pass the result in `AIAgent` `tools: [...]` alongside other tool configs
+
+## Fluent agent steps
+
+- use `.agent(...)` for agent steps in fluent workflow definitions
+- define agent prompts with `messages`
+- use `itemValue(...)` when message content depends on `item.json`
+- use `outputSchema` when the workflow should expose typed structured agent output