STM: agents (MVP) -- agent / send / await / agent-error / restart

mino ships agents: agent, agent?, send, send-off, await, await-for,
agent-error, restart-agent, set-error-handler!, error-handler,
set-error-mode!, error-mode, plus shutdown-agents /
release-pending-sends stubs. Watches and validators on agents go
through the same watchable_get path as atoms / refs / vars.

The MVP runs sends synchronously on the calling thread. mino's eval
loop holds a per-state mutex; a worker-pool dispatcher would
serialize on it anyway, and the synchronous shape is observably
equivalent for any program that does not race against the agent
itself. await becomes a trivial no-op.

Action throws and watch throws are both captured into agent-error
via agent_try_call -- a manual try frame in src/prim/agent.c that
swallows the throw without re-raising. mino's mino_pcall would
re-throw to any enclosing try via set_eval_diag's longjmp path,
which would defeat the catch contract here.

Type plumbing: new MINO_AGENT enum tag with a per-cell {val,
watches, validator, err, err_handler, err_mode, queue} struct.
Print form #agent[VAL]; equality is identity. Wired through GC
mark / verify, deref dispatch, watchable_get, type predicate,
clone (non-transferable), eval-form self-evaluation. Replaces
the prior core.clj `agent` stub that threw :mino/unsupported.

Test coverage: tests/agent_test.clj exercises construct / send /
send-off / watches / validators / restart / error-mode / await.
Internal suite 1512 / 7166 / 0. The agent arms of the upstream
add_watch.cljc / remove_watch.cljc tests now pass cleanly,
returning the external runner to its pre-STM-branch baseline of
1 fail + 2 errors (test-abs / test-reduce / test-short, all
pre-existing).

Documented deviations: send-via not implemented (no public
Executor type); shutdown-agents / release-pending-sends are
stubs; :fail mode rejects further sends until restart-agent.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: leifericf

CHANGELOG.md

@@ -361,6 +361,40 @@ fire watches anywhere.
 upstream, and the atom / ref / var arms pass cleanly. The agent
 arm of each still errors (out of scope until agents land).
 
+### Agents (MVP)
+
+mino now ships agents: `agent`, `agent?`, `send`, `send-off`,
+`await`, `await-for`, `agent-error`, `restart-agent`,
+`set-error-handler!`, `error-handler`, `set-error-mode!`,
+`error-mode`, plus `shutdown-agents` / `release-pending-sends`
+stubs. Watches and validators on agents go through the same
+`watchable_get` machinery as atoms / refs / vars.
+
+The MVP runs sends synchronously on the calling thread. mino's
+eval loop holds a per-state mutex so a worker-pool design would
+serialize on it anyway; running synchronously is observably
+equivalent for any program that does not race against the agent
+itself, and `await` becomes a trivial no-op (the queue is always
+drained on send return). Action throws and watch throws are both
+captured into `agent-error` via a manual try frame in
+`src/prim/agent.c` (mino's `mino_pcall` re-throws to any
+enclosing try via `set_eval_diag`'s longjmp path, which would
+defeat the catch contract here).
+
+Documented deviations: `send-via` is not implemented (no public
+Executor type); `shutdown-agents` and `release-pending-sends`
+are stubs; the `:fail` error mode is the default and rejects
+further sends until `restart-agent` clears the err.
+
+`tests/agent_test.clj` exercises construct / send / send-off /
+watches / validators / restart / error-mode / await and is in
+the internal run.clj. The agent arms of the upstream
+`add_watch.cljc` / `remove_watch.cljc` tests now pass cleanly,
+bringing the external runner to **134 / 2680, 1 fail + 2 errors**
+(matching the pre-STM baseline; remaining failures are
+pre-existing test-abs / test-reduce / test-short, unrelated to
+STM or watches).
+
 ### Equality of empty lazy seqs
 
 Fix: `(= (filter pred []) (filter pred []))` returned `false`.

lib/mino/tasks/builtin.clj

@@ -41,7 +41,7 @@
    "src/prim/sequences.c" "src/prim/lazy.c"
    "src/prim/string.c" "src/prim/io.c"
    "src/prim/reflection.c" "src/prim/meta.c" "src/prim/regex.c"
-   "src/prim/stateful.c" "src/prim/stm.c" "src/prim/module.c"
+   "src/prim/stateful.c" "src/prim/stm.c" "src/prim/agent.c" "src/prim/module.c"
    "src/prim/ns.c"
    "src/prim/fs.c" "src/prim/proc.c"
    "src/prim/host.c" "src/interop/syntax.c"

src/collections/clone.c

@@ -216,6 +216,7 @@ static mino_val_t *clone_val(mino_state_t *dst, const mino_val_t *v)
     case MINO_HOST_ARRAY:
     case MINO_MAP_ENTRY:
     case MINO_TX_REF:
+    case MINO_AGENT:
         return NULL;
     case MINO_UUID:
         return mino_uuid_from_bytes(dst, v->as.uuid.bytes);

src/collections/val.c

@@ -1076,6 +1076,9 @@ int mino_eq(const mino_val_t *a, const mino_val_t *b)
     case MINO_TX_REF:
         /* Identity equality matches atoms and Clojure's JVM Ref. */
         return a == b;
+    case MINO_AGENT:
+        /* Identity equality matches atoms and JVM Agent. */
+        return a == b;
     }
     return 0;
 }

src/core.clj

@@ -2056,21 +2056,12 @@
       (:mino/message ex)
       (:message ex))))
 
-(defn agent [& _]
-  (throw (ex-info
-           (str "agent is not supported on mino — use atoms for"
-                " synchronous mutable state or core.async for async"
-                " dispatch")
-           {:mino/unsupported :agent})))
-
-(defn send-to [& _]
-  (throw (ex-info
-           "send-to is not supported on mino — see (atom) and core.async"
-           {:mino/unsupported :send-to})))
-
-(defn agent-error [& _]
-  (throw (ex-info "agent-error is not supported on mino"
-                  {:mino/unsupported :agent-error})))
+;; agent / send / send-off / await / agent-error / restart-agent /
+;; set-error-handler! / error-handler / set-error-mode! / error-mode /
+;; agent? / await-for / shutdown-agents / release-pending-sends are
+;; provided by mino_install_agent (src/prim/agent.c). mino's MVP runs
+;; sends synchronously on the calling thread, so await is a no-op.
+;; See /documentation/stm/ for the full deviation list.
 
 ;; ---------------------------------------------------------------------------
 ;; Host threads.

src/eval/print.c

@@ -471,6 +471,13 @@ void mino_print_to(mino_state_t *S, FILE *out, const mino_val_t *v)
         S->print_depth--;
         fputc(']', out);
         return;
+    case MINO_AGENT:
+        fputs("#agent[", out);
+        S->print_depth++;
+        mino_print_to(S, out, v->as.agent.val);
+        S->print_depth--;
+        fputc(']', out);
+        return;
     case MINO_HOST_ARRAY: {
         /* Mirror Clojure JVM's #object[...] form for arrays since
          * arrays don't round-trip through the reader. */

src/eval/special.c

@@ -719,6 +719,7 @@ mino_val_t *eval_impl(mino_state_t *S, mino_val_t *form, mino_env_t *env, int ta
     case MINO_HOST_ARRAY:
     case MINO_MAP_ENTRY:
     case MINO_TX_REF:
+    case MINO_AGENT:
         return form;
     case MINO_SYMBOL:
         return eval_symbol(S, form, env);

src/gc/driver.c

@@ -531,6 +531,13 @@ void gc_trace_children(mino_state_t *S, gc_hdr_t *h)
             gc_mark_child_push(S, v->as.tx_ref.watches);
             gc_mark_child_push(S, v->as.tx_ref.validator);
             break;
+        case MINO_AGENT:
+            gc_mark_child_push(S, v->as.agent.val);
+            gc_mark_child_push(S, v->as.agent.watches);
+            gc_mark_child_push(S, v->as.agent.validator);
+            gc_mark_child_push(S, v->as.agent.err);
+            gc_mark_child_push(S, v->as.agent.err_handler);
+            break;
         default:
             break;
         }

src/gc/minor.c

@@ -331,6 +331,13 @@ static void gc_verify_remset_complete(mino_state_t *S)
                 gc_verify_check(S, h, v->as.tx_ref.watches);
                 gc_verify_check(S, h, v->as.tx_ref.validator);
                 break;
+            case MINO_AGENT:
+                gc_verify_check(S, h, v->as.agent.val);
+                gc_verify_check(S, h, v->as.agent.watches);
+                gc_verify_check(S, h, v->as.agent.validator);
+                gc_verify_check(S, h, v->as.agent.err);
+                gc_verify_check(S, h, v->as.agent.err_handler);
+                break;
             default: break;
             }
             break;

src/mino.h

@@ -171,7 +171,7 @@ typedef enum {
                      * seq over the elements. Equality is identity.
                      * Constructed via object-array, int-array,
                      * long-array, etc. */
-    MINO_TX_REF     /* Software transactional memory ref: identity cell
+    MINO_TX_REF,    /* Software transactional memory ref: identity cell
                      * holding a single committed value plus per-cell
                      * watches and validator. Mutations are confined to
                      * `dosync` transactions and serialized through a
@@ -182,6 +182,15 @@ typedef enum {
                      * was already taken by the embedder rooting handle
                      * (mino_ref_t), so the enum tag is MINO_TX_REF; the
                      * Clojure-level type keyword is `:ref`. */
+    MINO_AGENT      /* Asynchronous mutable cell with per-agent action
+                     * queue. send / send-off enqueue (fn args); a worker
+                     * thread drains the queue serially, applying actions
+                     * to the state. Watches and validators on agents
+                     * follow the atom/ref shape. Equality is identity.
+                     * Constructed via `(agent v)`. Requires the host
+                     * to grant threads (mino_set_thread_limit > 1) for
+                     * the worker to spawn; with grant=1 send is a
+                     * synchronous-but-deferred no-op equivalent. */
 } mino_type_t;
 
 typedef struct mino_val    mino_val_t;
@@ -373,6 +382,20 @@ struct mino_val {
                                           * itself outlives all its refs
                                           * and is not a GC value. */
         } tx_ref;
+        struct {          /* MINO_AGENT: async mutable cell + queue */
+            mino_val_t *val;          /* current state */
+            mino_val_t *watches;      /* MINO_MAP key->callback, or NULL */
+            mino_val_t *validator;    /* validator fn, or NULL */
+            mino_val_t *err;          /* last failed action's exception,
+                                       * or NULL. Set when the worker
+                                       * caught a throw; cleared by
+                                       * restart-agent. */
+            mino_val_t *err_handler;  /* on-error callback (fn agent ex)
+                                       * or NULL */
+            int         err_mode;     /* 0=:fail, 1=:continue */
+            void       *queue;        /* opaque agent_queue_t * (heap-
+                                       * allocated; freed via finalizer) */
+        } agent;
     } as;
 };
 
@@ -525,6 +548,16 @@ mino_val_t *mino_map_entry(mino_state_t *S, mino_val_t *k, mino_val_t *v);
  * monotonic ID) is unique within S. */
 mino_val_t *mino_tx_ref(mino_state_t *S, mino_val_t *val);
 
+/* Construct an asynchronous agent holding the given initial state.
+ * Watches, validator, and error handler all start NULL; install them
+ * via add-watch / set-validator! / set-error-handler! on the returned
+ * cell. The agent's action queue is heap-allocated and freed via the
+ * GC sweep finalizer when the agent becomes unreachable. */
+mino_val_t *mino_agent(mino_state_t *S, mino_val_t *initial);
+
+/* Return 1 if v is an agent, 0 otherwise. NULL-safe. */
+int         mino_is_agent(const mino_val_t *v);
+
 /* Return 1 if v is an STM ref (MINO_TX_REF), 0 otherwise. NULL-safe. */
 int         mino_is_tx_ref(const mino_val_t *v);
 
@@ -940,6 +973,15 @@ void        mino_install_proc(mino_state_t *S, mino_env_t *env);
  */
 void        mino_install_stm(mino_state_t *S, mino_env_t *env);
 
+/*
+ * Install the agent surface: agent / agent? / send / send-off / await
+ * / await-for / agent-error / restart-agent / set-error-handler! /
+ * error-handler / set-error-mode! / error-mode / shutdown-agents /
+ * release-pending-sends. mino_install_all calls this; embedders
+ * calling only mino_new keep agents opt-out.
+ */
+void        mino_install_agent(mino_state_t *S, mino_env_t *env);
+
 /*
  * Evaluate one form. Returns NULL on error and writes a message via
  * mino_last_error(). Returns mino_nil() for an explicit nil result.