@agentic-surfaces/core 0.1.25 → 0.1.27

package/dist/agents.d.ts

@@ -1,3 +1,4 @@
+import type { Capabilities } from "@agentic-surfaces/agent";
 export interface AgentCommand {
     name: string;
     description?: string;
@@ -16,6 +17,8 @@ export interface AgentDefinition {
         command?: string;
         args?: string[];
     }>;
+    /** Declared plugins/skills/settingSources for a `full` agent (config, not env-assumed). */
+    capabilities?: Capabilities;
     instructions: string;
 }
 /**

package/dist/agents.js

@@ -11,6 +11,13 @@ const AgentCommandSchema = z.object({
     name: z.string().min(1),
     description: z.string().optional(),
 });
+// Declared capabilities for a capable (`full`) agent — plugins/skills/settingSources the engine
+// loads explicitly (config, not an assumption about the operator's `~/.claude`).
+const CapabilitiesSchema = z.object({
+    plugins: z.array(z.object({ path: z.string().min(1) })).optional(),
+    skills: z.union([z.literal("all"), z.array(z.string())]).optional(),
+    settingSources: z.array(z.enum(["user", "project", "local"])).optional(),
+});
 const AgentFrontmatterSchema = z
     .object({
     name: z.string().min(1).optional(),
@@ -20,6 +27,7 @@ const AgentFrontmatterSchema = z
     commands: z.array(AgentCommandSchema).min(1).optional(),
     fallback: z.string().optional(),
     mcpServers: z.array(McpServerRefSchema).optional(),
+    capabilities: CapabilitiesSchema.optional(),
 })
     .superRefine((v, ctx) => {
     if (v.commands) {
@@ -70,6 +78,7 @@ export function parseAgentFile(content, defaultName) {
         commands: fm.commands,
         fallback: fm.fallback,
         mcpServers: fm.mcpServers,
+        capabilities: fm.capabilities,
         instructions: body.trim(),
     };
 }

package/dist/handlers/agent.js

@@ -39,6 +39,16 @@ export const agentHandler = {
         model = model ?? defaults.model;
         effort = effort ?? defaults.effort;
         mcpServers = mcpServers ?? defaults.mcpServers;
+        // Capabilities: per-agent frontmatter overrides project defaults field-by-field.
+        const agentCaps = (cfg.agent ? ctx.services.agents?.get(cfg.agent)?.capabilities : undefined);
+        const defCaps = defaults.capabilities;
+        const capabilities = (agentCaps || defCaps)
+            ? {
+                plugins: agentCaps?.plugins ?? defCaps?.plugins,
+                skills: agentCaps?.skills ?? defCaps?.skills,
+                settingSources: agentCaps?.settingSources ?? defCaps?.settingSources,
+            }
+            : undefined;
         const result = await ctx.services.agent.run({
             prompt: instructions,
             model,
@@ -49,6 +59,9 @@ export const agentHandler = {
             // Capability tier (default constrained) + dry-run so the runner's permission callback can
             // block + log writes for surface/full agents. Logged via the engine logger for visibility.
             profile: profile ?? "constrained",
+            capabilities,
+            // A `full` agent's working dir + base for resolving relative plugin paths = the project dir.
+            cwd: ctx.services.projectDir,
             dryRun: ctx.services.dryRun,
             log: (m) => ctx.services.logger?.info?.(m),
             // Stream the agent's reasoning + tool/MCP calls to the run observer, tagged with this node.
@@ -66,11 +79,11 @@ export const agentHandler = {
                 else
                     throw new Error(`agent ${cfg.agent} returned an off-allowlist command: ${String(raw)}`);
             }
-            return { output: { command, text: result.text } };
+            return { output: { command, text: result.text, skillsUsed: result.skillsUsed, toolsUsed: result.toolsUsed, usage: result.usage } };
         }
         // Inline decision schema: surface its fields at the top level (0.1.7 behaviour).
         if (cfg.decision && result.data && typeof result.data === "object" && !Array.isArray(result.data)) {
-            return { output: { ...result.data, text: result.text } };
+            return { output: { ...result.data, text: result.text, skillsUsed: result.skillsUsed, toolsUsed: result.toolsUsed, usage: result.usage } };
         }
         return { output: result };
     },

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./cache.js";
 export * from "./observer.js";
 export * from "./secrets.js";
 export * from "./project-config.js";
+export * from "./pause.js";
 export * from "./agents.js";
 export * from "./handlers/foreach.js";
 export * from "./handlers/run-workflow.js";

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./cache.js";
 export * from "./observer.js";
 export * from "./secrets.js";
 export * from "./project-config.js";
+export * from "./pause.js";
 export * from "./agents.js";
 export * from "./handlers/foreach.js";
 export * from "./handlers/run-workflow.js";

package/dist/pause.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A platform-wide play/pause switch. When paused, the scheduler stops firing cron workflows
+ * (in-flight runs finish; new scheduled fires are skipped). It's a master switch for the
+ * autonomous loop — manual dashboard runs still work.
+ */
+export interface PauseState {
+    isPaused(): boolean;
+    pause(): void;
+    resume(): void;
+}
+/**
+ * File-backed pause state: the presence of a sentinel file (default `.flow-paused`) means paused.
+ * A file (not in-memory) so the state survives a `start --watch` restart and is inspectable.
+ */
+export declare class FilePauseState implements PauseState {
+    private readonly path;
+    constructor(path?: string);
+    isPaused(): boolean;
+    pause(): void;
+    resume(): void;
+}

package/dist/pause.js

@@ -0,0 +1,26 @@
+import { existsSync, writeFileSync, rmSync } from "node:fs";
+/**
+ * File-backed pause state: the presence of a sentinel file (default `.flow-paused`) means paused.
+ * A file (not in-memory) so the state survives a `start --watch` restart and is inspectable.
+ */
+export class FilePauseState {
+    path;
+    constructor(path = ".flow-paused") {
+        this.path = path;
+    }
+    isPaused() {
+        return existsSync(this.path);
+    }
+    pause() {
+        if (!this.isPaused())
+            writeFileSync(this.path, `paused ${new Date().toISOString()}\n`);
+    }
+    resume() {
+        try {
+            rmSync(this.path);
+        }
+        catch {
+            /* already gone — nothing to do */
+        }
+    }
+}

package/dist/project-config.d.ts

@@ -19,6 +19,17 @@ declare const ProjectConfigSchema: z.ZodObject<{
             command: z.ZodString;
             args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>]>>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            plugins: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+            }, z.core.$strip>>>;
+            skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>>;
+            settingSources: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                user: "user";
+                project: "project";
+                local: "local";
+            }>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     workflows: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;

package/dist/project-config.js

@@ -16,6 +16,15 @@ const ProjectConfigSchema = z.object({
         model: z.string().default("claude-opus-4-8"),
         effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional(),
         mcpServers: z.array(McpServerRefSchema).optional(),
+        // Project-wide default capabilities for `full` agents — declared, the engine loads them.
+        // A per-agent `capabilities` block (frontmatter) overrides this field-by-field.
+        capabilities: z
+            .object({
+            plugins: z.array(z.object({ path: z.string().min(1) })).optional(),
+            skills: z.union([z.literal("all"), z.array(z.string())]).optional(),
+            settingSources: z.array(z.enum(["user", "project", "local"])).optional(),
+        })
+            .optional(),
     })
         .default({ runner: "claude", model: "claude-opus-4-8" }),
     workflows: z.string().optional(), // relative subdir; omitted = use dir itself

package/dist/scheduler.d.ts

@@ -1,4 +1,5 @@
 import { HandlerRegistry } from "./registry.js";
+import type { PauseState } from "./pause.js";
 import type { RunObserver, Services, Workflow } from "./types.js";
 export declare function defaultRegistry(): HandlerRegistry;
 export declare function runWorkflowOnce(workflow: Workflow, opts: {
@@ -19,11 +20,15 @@ export declare class Scheduler {
     private services;
     private registry;
     private observer;
+    /** When set + paused, scheduled cron fires are skipped (the platform-wide play/pause switch). */
+    private pause?;
     private crons;
     private active;
     private pending;
     private workflows;
-    constructor(services: Services, registry?: HandlerRegistry, observer?: RunObserver);
+    constructor(services: Services, registry?: HandlerRegistry, observer?: RunObserver, 
+    /** When set + paused, scheduled cron fires are skipped (the platform-wide play/pause switch). */
+    pause?: PauseState | undefined);
     add(workflow: Workflow): void;
     start(): void;
     private enqueue;

package/dist/scheduler.js

@@ -58,14 +58,18 @@ export class Scheduler {
     services;
     registry;
     observer;
+    pause;
     crons = [];
     active = 0;
     pending = [];
     workflows = [];
-    constructor(services, registry = defaultRegistry(), observer = new ConsoleObserver()) {
+    constructor(services, registry = defaultRegistry(), observer = new ConsoleObserver(), 
+    /** When set + paused, scheduled cron fires are skipped (the platform-wide play/pause switch). */
+    pause) {
         this.services = services;
         this.registry = registry;
         this.observer = observer;
+        this.pause = pause;
     }
     add(workflow) { this.workflows.push(workflow); }
     start() {
@@ -74,14 +78,21 @@ export class Scheduler {
                 if (node.type !== "trigger.cron")
                     continue;
                 const pattern = String(node.config.cron);
-                this.crons.push(new Cron(pattern, () => this.enqueue(() => runWorkflowOnce(wf, { registry: this.registry, services: this.services, triggerNodeId: node.id, observer: this.observer })
-                    .then(() => { })
-                    // A failed scheduled run must not crash the scheduler (unhandled
-                    // rejection). The failure is already reported to the observer; log
-                    // and carry on so the next trigger still fires.
-                    .catch((err) => this.services.logger?.error?.("scheduled run failed", {
-                    workflow: wf.name, error: err instanceof Error ? err.message : String(err),
-                })))));
+                this.crons.push(new Cron(pattern, () => {
+                    // Platform-wide pause: skip this scheduled fire (in-flight runs are unaffected).
+                    if (this.pause?.isPaused()) {
+                        this.services.logger?.info?.(`paused — skipping scheduled run of ${wf.name}`);
+                        return;
+                    }
+                    this.enqueue(() => runWorkflowOnce(wf, { registry: this.registry, services: this.services, triggerNodeId: node.id, observer: this.observer })
+                        .then(() => { })
+                        // A failed scheduled run must not crash the scheduler (unhandled
+                        // rejection). The failure is already reported to the observer; log
+                        // and carry on so the next trigger still fires.
+                        .catch((err) => this.services.logger?.error?.("scheduled run failed", {
+                        workflow: wf.name, error: err instanceof Error ? err.message : String(err),
+                    })));
+                }));
             }
         }
     }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
-import type { AgentRunner, McpServerRef, AgentActivity } from "@agentic-surfaces/agent";
+import type { AgentRunner, McpServerRef, AgentActivity, Capabilities } from "@agentic-surfaces/agent";
 import type { AgentDefinition } from "./agents.js";
-export type { AgentRunner, McpServerRef, AgentActivity };
+export type { AgentRunner, McpServerRef, AgentActivity, Capabilities };
 export type NodeType = "trigger.cron" | "trigger.webhook" | "trigger.command" | "task.http" | "task.transform" | "task.branch" | "task.run-workflow" | "task.foreach" | "task.cache-unseen" | "task.cache-mark" | "agent.run";
 export interface RetryPolicy {
     maxAttempts: number;
@@ -62,7 +62,11 @@ export interface Services {
         effort?: "low" | "medium" | "high" | "xhigh" | "max";
         runner?: string;
         mcpServers?: McpServerRef[];
+        capabilities?: Capabilities;
     };
+    /** The project directory (where agentic-surfaces.config.yaml lives). Base for a `full` agent's
+     *  cwd and for resolving relative capability plugin paths. */
+    projectDir?: string;
     runWorkflow?: (name: string, payload: unknown) => Promise<Map<string, unknown>>;
     agents?: Map<string, AgentDefinition>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-surfaces/core",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -24,7 +24,7 @@
     "jsonata": "^2.2.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@agentic-surfaces/agent": "0.1.25"
+    "@agentic-surfaces/agent": "0.1.27"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",