@agentic-surfaces/core 0.1.26 → 0.1.28

package/dist/executor.js

@@ -1,4 +1,10 @@
 import { withRetry } from "./policy.js";
+// Process-global, monotonic run-id counter. Each runWorkflow() call (top-level or a foreach
+// sub-run) gets a distinct id so the dashboard can attribute every event to its own run.
+let runSeq = 0;
+function newRunId() {
+    return `run_${(++runSeq).toString(16).padStart(6, "0")}`;
+}
 export async function runWorkflow(opts) {
     const { workflow, triggerNodeId, registry, services, payload, observer } = opts;
     const byId = new Map(workflow.nodes.map(n => [n.id, n]));
@@ -10,9 +16,11 @@ export async function runWorkflow(opts) {
         services,
         observer,
     };
+    const runId = newRunId();
+    ctx.runId = runId; // so handlers (agent.run) can tag their activity with this run
     const queue = [triggerNodeId];
     const visited = new Set();
-    observer?.onRunStart?.(workflow.name, ctx.triggerPayload);
+    observer?.onRunStart?.(workflow.name, ctx.triggerPayload, runId);
     while (queue.length > 0) {
         const id = queue.shift();
         if (visited.has(id))
@@ -22,7 +30,7 @@ export async function runWorkflow(opts) {
         if (!node)
             throw new Error(`workflow references missing node: ${id}`);
         const handler = registry.get(node.type);
-        observer?.onNodeStart?.(id);
+        observer?.onNodeStart?.(id, runId);
         let result;
         let nodeErrored = false;
         try {
@@ -32,12 +40,12 @@ export async function runWorkflow(opts) {
             nodeErrored = true;
             const message = err instanceof Error ? err.message : String(err);
             services.logger?.error?.(`node ${node.id} failed`, { workflow: workflow.name, error: message });
-            observer?.onNodeFinish?.(id, "failed", { error: message });
+            observer?.onNodeFinish?.(id, "failed", { error: message }, runId);
             if (node.onError === "continue") {
                 result = { output: { error: message } };
             }
             else {
-                observer?.onRunFinish?.(workflow.name, "failed");
+                observer?.onRunFinish?.(workflow.name, "failed", runId);
                 throw err;
             }
         }
@@ -45,7 +53,7 @@ export async function runWorkflow(opts) {
         // Surface the node's output so observers (e.g. the live UI) can show what each
         // node produced/fetched — the data is what you need when debugging a run.
         if (!nodeErrored)
-            observer?.onNodeFinish?.(id, "success", { output: result.output });
+            observer?.onNodeFinish?.(id, "success", { output: result.output }, runId);
         const branches = result.branches;
         for (const edge of workflow.edges) {
             if (edge.from !== id)
@@ -55,6 +63,6 @@ export async function runWorkflow(opts) {
             }
         }
     }
-    observer?.onRunFinish?.(workflow.name, "success");
+    observer?.onRunFinish?.(workflow.name, "success", runId);
     return ctx.outputs;
 }

package/dist/handlers/agent.js

@@ -64,8 +64,8 @@ export const agentHandler = {
             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.
-            onActivity: (a) => ctx.observer?.onNodeActivity?.(node.id, a),
+            // Stream the agent's reasoning + tool/MCP calls to the run observer, tagged with node + run.
+            onActivity: (a) => ctx.observer?.onNodeActivity?.(node.id, a, ctx.runId),
         });
         // Decision agent: guarantee the chosen command is on the allowlist (else use
         // the fallback), and surface it at the top level so task.branch can route.
@@ -79,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, skillsUsed: result.skillsUsed, toolsUsed: result.toolsUsed } };
+            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, skillsUsed: result.skillsUsed, toolsUsed: result.toolsUsed } };
+            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

@@ -32,6 +32,7 @@ declare const ProjectConfigSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     workflows: z.ZodOptional<z.ZodString>;
+    atlassianSite: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 /**

package/dist/project-config.js

@@ -28,6 +28,9 @@ const ProjectConfigSchema = z.object({
     })
         .default({ runner: "claude", model: "claude-opus-4-8" }),
     workflows: z.string().optional(), // relative subdir; omitted = use dir itself
+    // Atlassian site host (e.g. "sojournii.atlassian.net") — lets the dashboard build browse/wiki
+    // links to the issues/pages a run touched. Optional; links also come from MCP tool results.
+    atlassianSite: z.string().optional(),
 });
 const CONFIG_FILENAME = "agentic-surfaces.config.yaml";
 /**

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

@@ -72,6 +72,8 @@ export interface Services {
 }
 export interface RunContext {
     workflow: Workflow;
+    /** Unique id for this run, set by the executor — handlers tag their observer activity with it. */
+    runId?: string;
     outputs: Map<string, unknown>;
     triggerNodeId: string;
     triggerPayload?: unknown;
@@ -88,10 +90,10 @@ export interface NodeHandler {
     execute(node: WorkflowNode, ctx: RunContext): Promise<NodeResult>;
 }
 export interface RunObserver {
-    onRunStart?(workflow: string, payload?: unknown): void;
-    onNodeStart?(nodeId: string): void;
-    onNodeFinish?(nodeId: string, status: "success" | "failed", meta?: unknown): void;
+    onRunStart?(workflow: string, payload?: unknown, runId?: string): void;
+    onNodeStart?(nodeId: string, runId?: string): void;
+    onNodeFinish?(nodeId: string, status: "success" | "failed", meta?: unknown, runId?: string): void;
     /** A live step of an agent node's work (reasoning, a tool/MCP call, or a result). */
-    onNodeActivity?(nodeId: string, activity: AgentActivity): void;
-    onRunFinish?(workflow: string, status: "success" | "failed"): void;
+    onNodeActivity?(nodeId: string, activity: AgentActivity, runId?: string): void;
+    onRunFinish?(workflow: string, status: "success" | "failed", runId?: string): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-surfaces/core",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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.26"
+    "@agentic-surfaces/agent": "0.1.28"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",