@agentic-surfaces/core 0.1.18 → 0.1.20

package/dist/cache.d.ts

@@ -5,7 +5,19 @@ export declare class SqliteCache implements Cache {
     getCursor(k: string): string | undefined;
     setCursor(k: string, v: string): void;
     isSeen(k: string): boolean;
-    markSeen(k: string): void;
+    markSeen(k: string, label?: string): void;
+    entries(): {
+        seen: Array<{
+            key: string;
+            ts?: number;
+            label?: string;
+        }>;
+        cursors: Array<{
+            key: string;
+            value: string;
+        }>;
+    };
+    forget(k: string): void;
     wipe(): void;
     close(): void;
 }

package/dist/cache.js

@@ -7,6 +7,13 @@ export class SqliteCache {
       CREATE TABLE IF NOT EXISTS cursors (key TEXT PRIMARY KEY, value TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS seen (key TEXT PRIMARY KEY);
     `);
+        // Migrate older DBs: add when-seen + a human label so the cache view is legible.
+        for (const col of ["ts INTEGER", "label TEXT"]) {
+            try {
+                this.db.exec(`ALTER TABLE seen ADD COLUMN ${col}`);
+            }
+            catch { /* already present */ }
+        }
     }
     getCursor(k) {
         const row = this.db.prepare("SELECT value FROM cursors WHERE key = ?").get(k);
@@ -18,8 +25,20 @@ export class SqliteCache {
     isSeen(k) {
         return !!this.db.prepare("SELECT 1 FROM seen WHERE key = ?").get(k);
     }
-    markSeen(k) {
-        this.db.prepare("INSERT OR IGNORE INTO seen(key) VALUES(?)").run(k);
+    markSeen(k, label) {
+        this.db
+            .prepare("INSERT INTO seen(key, ts, label) VALUES(?,?,?) ON CONFLICT(key) DO UPDATE SET ts=excluded.ts, label=COALESCE(excluded.label, seen.label)")
+            .run(k, Date.now(), label ?? null);
+    }
+    entries() {
+        const seen = this.db.prepare("SELECT key, ts, label FROM seen ORDER BY ts DESC, key").all()
+            .map((r) => ({ key: r.key, ts: r.ts ?? undefined, label: r.label ?? undefined }));
+        const cursors = this.db.prepare("SELECT key, value FROM cursors ORDER BY key").all();
+        return { seen, cursors };
+    }
+    forget(k) {
+        this.db.prepare("DELETE FROM seen WHERE key = ?").run(k);
+        this.db.prepare("DELETE FROM cursors WHERE key = ?").run(k);
     }
     wipe() {
         this.db.exec("DELETE FROM cursors; DELETE FROM seen;");

package/dist/executor.js

@@ -8,6 +8,7 @@ export async function runWorkflow(opts) {
         triggerNodeId,
         triggerPayload: payload,
         services,
+        observer,
     };
     const queue = [triggerNodeId];
     const visited = new Set();

package/dist/handlers/agent.js

@@ -51,6 +51,8 @@ export const agentHandler = {
             profile: profile ?? "constrained",
             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),
         });
         // 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.

package/dist/schema.js

@@ -23,6 +23,7 @@ const node = z.object({
 const edge = z.object({ from: z.string().min(1), to: z.string().min(1), when: z.string().optional() });
 const workflow = z.object({
     name: z.string().min(1),
+    title: z.string().min(1).optional(),
     nodes: z.array(node).min(1),
     edges: z.array(edge).default([]),
 }).superRefine((wf, ctx) => {

package/dist/types.d.ts

@@ -1,6 +1,6 @@
-import type { AgentRunner, McpServerRef } from "@agentic-surfaces/agent";
+import type { AgentRunner, McpServerRef, AgentActivity } from "@agentic-surfaces/agent";
 import type { AgentDefinition } from "./agents.js";
-export type { AgentRunner, McpServerRef };
+export type { AgentRunner, McpServerRef, AgentActivity };
 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;
@@ -20,6 +20,8 @@ export interface WorkflowEdge {
 }
 export interface Workflow {
     name: string;
+    /** Human-readable display name for the UI (falls back to `name` when omitted). */
+    title?: string;
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
 }
@@ -31,7 +33,22 @@ export interface Cache {
     getCursor(k: string): string | undefined;
     setCursor(k: string, v: string): void;
     isSeen(k: string): boolean;
-    markSeen(k: string): void;
+    /** Mark a key seen, with an optional human label for the cache view. */
+    markSeen(k: string, label?: string): void;
+    /** Inspect all cache contents (seen-set with when/label + cursors) — for the dashboard's cache view. */
+    entries(): {
+        seen: Array<{
+            key: string;
+            ts?: number;
+            label?: string;
+        }>;
+        cursors: Array<{
+            key: string;
+            value: string;
+        }>;
+    };
+    /** Forget a single key (seen + cursor) so it gets reprocessed. */
+    forget(k: string): void;
     wipe(): void;
 }
 export interface Services {
@@ -55,6 +72,8 @@ export interface RunContext {
     triggerNodeId: string;
     triggerPayload?: unknown;
     services: Services;
+    /** The run observer, so handlers (e.g. agent.run) can stream live activity for a node. */
+    observer?: RunObserver;
 }
 export interface NodeResult {
     output: unknown;
@@ -68,5 +87,7 @@ export interface RunObserver {
     onRunStart?(workflow: string, payload?: unknown): void;
     onNodeStart?(nodeId: string): void;
     onNodeFinish?(nodeId: string, status: "success" | "failed", meta?: unknown): 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;
 }

package/package.json

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