deepclause-sdk 0.1.3 → 0.2.2

package/dist/prolog-src/deepclause_mi.pl

@@ -93,6 +93,7 @@
     repl_memory_term/3,
     repl_get_memory/3,
     repl_set_memory/3,
+    repl_note_resumed/2,
     post_agent_result/4,
     post_exec_result/3,
     post_sample_token_result/3,
@@ -114,6 +115,9 @@
 :- discontiguous mi_call/3.
 :- discontiguous transform_task_calls/3.
 :- discontiguous var_to_name/3.
+%% `proc_request_payload/2` sits between the process-primitive clauses of
+%% `process_engine_result/4`, which is intentional.
+:- discontiguous process_engine_result/4.
 
 %% Dynamic predicates for session state (engine management only, not memory!)
 :- dynamic session_engine/2.       % session_engine(SessionId, Engine) - legacy default engine handle
@@ -148,6 +152,7 @@
 :- dynamic session_trace_log/2.    % session_trace_log(SessionId, TraceLog) - accumulated trace entries
 :- dynamic session_trace_enabled/2. % session_trace_enabled(SessionId, true/false)
 :- dynamic session_pending_signal/2. % session_pending_signal(SessionId, Signal) - fallback for engine_fetch
+:- dynamic session_proc_result/3.  % session_proc_result(SessionId, Key, Value) - process primitive results
 :- dynamic session_user_input/2.   % session_user_input(SessionId, Input) - for ask_user tool
 :- dynamic session_input_cancelled/1. % session_input_cancelled(SessionId) - input/2 should fail (non-interactive)
 
@@ -957,7 +962,11 @@ step_engine_handle(SessionId, Engine, Status, Content, Payload) :-
             )
         ),
         Error,
-        (   format(atom(ErrMsg), 'Engine error: ~w', [Error]),
+        (   Error = process_exit(_)
+        ->  Status = finished,
+            Content = '',
+            Payload = none
+        ;   format(atom(ErrMsg), 'Engine error: ~w', [Error]),
             Status = error,
             Content = ErrMsg,
             (   session_trace_enabled(SessionId, true),
@@ -1304,6 +1313,13 @@ repl_listing_output(SessionId, Filter) :-
         )
     ).
 
+%% A filter either names a predicate (`name/arity`), names a prefix, or is `all`.
+%% Anything else matches **nothing**.
+%%
+%% There used to be a final `repl_listing_match(_, _, _)` catch-all, which turned any
+%% filter it did not understand into "the whole module" — silently. `listing('alpha/1')`
+%% therefore listed every predicate, so the side view's drill-down showed the module
+%% instead of the predicate under the cursor.
 repl_listing_match(all, _, _) :- !.
 repl_listing_match(Name/Arity, Name, Arity) :- !.
 repl_listing_match(Filter, Name, _) :-
@@ -1312,7 +1328,8 @@ repl_listing_match(Filter, Name, _) :-
     (   sub_atom(Name, 0, _, _, Filter)
     ;   sub_atom(Filter, 0, _, _, Name)
     ).
-repl_listing_match(_, _, _).
+repl_listing_match(_, _, _) :-
+    fail.
 
 %% repl_user_predicate(+SessionId, +Name, +Arity)
 %% Excludes reserved and internal predicates from listing/export.
@@ -2308,6 +2325,46 @@ repl_rollback(SessionId, Source, Result) :-
         format(atom(Result), 'error(~w)', [RollbackError])
     ).
 
+%% repl_harness_view(+SessionId, -Rows)
+%% One row per predicate of the harness, for the live side view:
+%%   "Name/Arity|ClauseCount|flag,flag"
+%% Text rather than terms, so the host does not have to decode compound terms through
+%% the bridge — the view needs identity (to diff) and a little detail, not structure.
+repl_harness_view(SessionId, Rows) :-
+    repl_user_predicates(SessionId, Preds),
+    findall(Row,
+        (   member(Name/Arity, Preds),
+            repl_predicate_clause_count(SessionId, Name, Arity, Clauses),
+            repl_harness_flags(SessionId, Name, Arity, Flags),
+            (   Flags == []
+            ->  FlagText = ""
+            ;   atomic_list_concat(Flags, ',', FlagText)
+            ),
+            format(atom(Row), "~w/~w|~w|~w", [Name, Arity, Clauses, FlagText])
+        ),
+        Rows).
+
+repl_predicate_clause_count(SessionId, Name, Arity, Count) :-
+    functor(Head, Name, Arity),
+    findall(x, clause(SessionId:Head, _), All),
+    length(All, Count).
+
+repl_harness_flags(SessionId, Name, Arity, Flags) :-
+    findall(Flag,
+        (   member(Flag, [entry, tool, doc, touched]),
+            repl_harness_flag(SessionId, Name, Arity, Flag)
+        ),
+        Flags).
+
+repl_harness_flag(_SessionId, agent_main, _Arity, entry).
+repl_harness_flag(SessionId, Name, _Arity, tool) :-
+    session_user_tools(SessionId, Name).
+repl_harness_flag(SessionId, Name, Arity, doc) :-
+    current_predicate(SessionId:doc/2),
+    catch(SessionId:doc(Name/Arity, _), _, fail).
+repl_harness_flag(SessionId, Name, Arity, touched) :-
+    session_edit_touched(SessionId, Name/Arity).
+
 %% repl_user_predicates(+SessionId, -Preds)
 %% Sorted Name/Arity list of the harness's own predicates.
 repl_user_predicates(SessionId, Preds) :-
@@ -2414,6 +2471,9 @@ repl_validate_docs(SessionId, Warnings) :-
     list_to_set(Raw, Warnings).
 
 doc_without_clauses(SessionId, Warning) :-
+    % A harness with no `doc/2` at all would otherwise make this call an
+    % undefined-procedure warning (`Unknown procedure: repl_x:doc/2`).
+    current_predicate(SessionId:doc/2),
     SessionId:doc(Name/Arity, _),
     (   \+ current_predicate(SessionId:Name/Arity)
     ;   functor(Head, Name, Arity),
@@ -2666,6 +2726,33 @@ repl_set_memory(SessionId, Slot, Messages) :-
         assertz(session_repl_memory(SessionId, Messages))
     ).
 
+%% repl_note_resumed(+SessionId, +Text)
+%% Record that the session was restored from a saved snapshot. Added to both
+%% memory slots so the authoring agent and every task/N see it. Any earlier
+%% note is replaced, so a session resumed many times carries one line, not a
+%% growing stack.
+repl_note_resumed(SessionId, Text) :-
+    atom_string(TextAtom, Text),
+    Note = message{role: system, content: TextAtom},
+    forall(member(Slot, [harness, meta]), (
+        repl_get_memory(SessionId, Slot, Messages),
+        exclude(is_resume_note, Messages, Kept),
+        append(Kept, [Note], Next),
+        repl_set_memory(SessionId, Slot, Next)
+    )).
+
+%% is_resume_note(+Message)
+%% True for a prior `repl_note_resumed/2` message, matched by its opening words.
+%% The content may be an atom (as first written) or a string (after a task/N
+%% round-trips the memory through the runner), so accept either.
+is_resume_note(message{role: system, content: Content}) :-
+    (   atom(Content)
+    ->  sub_atom(Content, 0, _, _, 'This session was reloaded')
+    ;   string(Content)
+    ->  sub_string(Content, 0, _, _, "This session was reloaded")
+    ;   fail
+    ).
+
 %% ---- Edit transactions ----
 
 %% repl_snapshot_save(+SessionId)
@@ -2922,6 +3009,25 @@ process_engine_result(request_agent_loop(Desc, Vars, Tools, Memory), request_age
     payload{taskDescription: Desc, outputVars: Vars, userTools: Tools, memory: Memory, toolScope: none, reasoningEffort: none, recipeContext: ""}) :- !.
 process_engine_result(request_exec(Tool, Args), request_exec, '',
     payload{toolName: Tool, args: Args}) :- !.
+%% Process primitives (spawn/send/receive/...) are yielded to the host, which
+%% owns identity, mailboxes, links, monitors, and naming.
+process_engine_result(request_proc(Request), request_proc, '', Payload) :-
+    proc_request_payload(Request, Payload).
+
+%% proc_request_payload(+Request, -Payload)
+proc_request_payload(self, payload{op: self}) :- !.
+proc_request_payload(spawn(Goal), payload{op: spawn, goal: Goal}) :- !.
+proc_request_payload(spawn(Goal, Options), payload{op: spawn, goal: Goal, options: Options}) :- !.
+proc_request_payload(send(To, Message), payload{op: send, to: To, message: Message}) :- !.
+proc_request_payload(receive(Timeout), payload{op: receive, timeout: Timeout}) :- !.
+proc_request_payload(requeue(Message), payload{op: requeue, message: Message}) :- !.
+proc_request_payload(wait(Pid), payload{op: wait, pid: Pid}) :- !.
+proc_request_payload(exit(Reason), payload{op: exit, reason: Reason}) :- !.
+proc_request_payload(exit(Pid, Reason), payload{op: exit, pid: Pid, reason: Reason}) :- !.
+proc_request_payload(process_info(Pid), payload{op: process_info, pid: Pid}) :- !.
+proc_request_payload(register(Name, Pid), payload{op: register, name: Name, pid: Pid}) :- !.
+proc_request_payload(whereis(Name), payload{op: whereis, name: Name}) :- !.
+proc_request_payload(sleep(Milliseconds), payload{op: sleep, ms: Milliseconds}) :- !.
 process_engine_result(request_sample_token(Prompt, Allowed, ModelSpec), request_sample_token, '',
     payload{prompt: Prompt, allowedTokens: Allowed, modelSpec: ModelSpec}) :- !.
 process_engine_result(request_sample_token(Prompt, Allowed), request_sample_token, '',
@@ -3010,6 +3116,13 @@ post_exec_result(SessionId, Status, Result) :-
     assertz(session_exec_result(SessionId, result{status: Status, result: Result})),
     post_signal_to_engine(SessionId, exec_done).
 
+%% post_proc_result(+SessionId, +Key, +Value)
+%% Reply to a process primitive (spawn/send/receive/...). Key names the result.
+post_proc_result(SessionId, Key, Value) :-
+    retractall(session_proc_result(SessionId, Key, _)),
+    assertz(session_proc_result(SessionId, Key, Value)),
+    post_signal_to_engine(SessionId, proc_done).
+
 %% post_sample_token_result(+SessionId, +Status, +TokenOrError)
 post_sample_token_result(SessionId, Status, TokenOrError) :-
     retractall(session_sample_token_result(SessionId, _)),
@@ -3459,6 +3572,10 @@ process_tool_engine_result(request_agent_loop(Desc, Vars, Tools, Memory, ToolSco
 %% Legacy 4-arg format (no tool scope)
 process_tool_engine_result(request_agent_loop(Desc, Vars, Tools, Memory), request_agent_loop, '',
     payload{taskDescription: Desc, outputVars: Vars, userTools: Tools, memory: Memory, toolScope: none, reasoningEffort: none, recipeContext: ""}) :- !.
+%% Process primitives (self/send/receive/spawn/...) reached inside a DML tool
+%% are yielded to the host exactly as in the main engine.
+process_tool_engine_result(request_proc(Request), request_proc, '', Payload) :-
+    proc_request_payload(Request, Payload).
 process_tool_engine_result(output(Text), output, Text, none) :- !.
 process_tool_engine_result(log(Text), log, Text, none) :- !.
 process_tool_engine_result(Other, error, Msg, none) :-
@@ -4144,6 +4261,410 @@ mi_call(exec(ToolCall, Output), StateIn, StateOut) :-
         fail
     ).
 
+%% ============================================================
+%% Process Primitives (session-scoped subagents)
+%% ============================================================
+%% These yield to the TypeScript host, which owns process identity, mailboxes,
+%% links, monitors, and naming. See docs/DML_REPL_PROCESSES_SPEC.md.
+%% Goals and messages cross the boundary as canonical term strings, so a
+%% process never shares a variable with its spawner (invariant A).
+
+%% mi_call(self(?Pid), +StateIn, -StateOut)
+mi_call(self(Pid), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    engine_yield(request_proc(self)),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, self, Pid),
+    retract(session_proc_result(SessionId, self, _)).
+
+%% mi_call(spawn(+Goal, -Pid), +StateIn, -StateOut)
+mi_call(spawn(Goal, Pid), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    copy_term(Goal, GoalCopy),
+    term_string(GoalCopy, GoalText),
+    engine_yield(request_proc(spawn(GoalText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, spawn, SpawnResult),
+    retract(session_proc_result(SessionId, spawn, _)),
+    (   SpawnResult = ok(Pid)
+    ->  true
+    ;   throw(error(process_spawn_failed(SpawnResult), spawn/2))
+    ).
+
+%% mi_call(spawn_opt(+Goal, -Pid, +Options), +StateIn, -StateOut)
+mi_call(spawn_opt(Goal, Pid, Options), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    copy_term(Goal, GoalCopy),
+    term_string(GoalCopy, GoalText),
+    (   is_dict(Options) -> term_string(Options, OptionsText) ; OptionsText = "{}" ),
+    engine_yield(request_proc(spawn(GoalText, OptionsText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, spawn, SpawnResult),
+    retract(session_proc_result(SessionId, spawn, _)),
+    (   SpawnResult = ok(Pid)
+    ->  true
+    ;   throw(error(process_spawn_failed(SpawnResult), spawn_opt/3))
+    ).
+
+%% mi_call(send(+Target, +Message), +StateIn, -StateOut)
+mi_call(send(To, Message), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(To, ToText),
+    term_string(Message, MessageText),
+    engine_yield(request_proc(send(ToText, MessageText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, send, SendResult),
+    retract(session_proc_result(SessionId, send, _)),
+    (   SendResult == ok
+    ->  true
+    ;   throw(error(process_send_failed(SendResult), send/2))
+    ).
+
+%% mi_call(receive(?Message), +StateIn, -StateOut)
+mi_call(receive(Message), StateIn, StateIn) :-
+    !,
+    mi_call(receive(Message, 0), StateIn, StateIn).
+
+%% mi_call(receive(?Message, +TimeoutMs), +StateIn, -StateOut)
+%% Fails on timeout, so a caller can branch on it.
+mi_call(receive(Message, TimeoutMs), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    engine_yield(request_proc(receive(TimeoutMs))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, receive, ReceiveResult),
+    retract(session_proc_result(SessionId, receive, _)),
+    ReceiveResult = ok(Message).
+
+%% mi_call(receive_match(+Template, ?Message, +TimeoutMs), +StateIn, -StateOut)
+%% Selective receive: skip messages that do not unify with Template, requeue
+%% them in order, and fail on timeout. The template unifies in this process.
+mi_call(receive_match(Template, Message, TimeoutMs), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    proc_now_ms(Start),
+    receive_match_loop(Template, Message, TimeoutMs, Start, SessionId, []).
+
+%% A plain monotonic clock for helpers (now_ms/1 is a mi_call special predicate).
+proc_now_ms(Milliseconds) :-
+    get_time(Seconds),
+    Milliseconds is round(Seconds * 1000).
+
+receive_match_loop(Template, Message, TimeoutMs, Start, SessionId, Skipped) :-
+    proc_now_ms(Now),
+    (   TimeoutMs > 0
+    ->  Left is TimeoutMs - (Now - Start)
+    ;   Left = 0
+    ),
+    (   TimeoutMs > 0, Left =< 0
+    ->  requeue_skipped(Skipped, SessionId),
+        fail
+    ;   engine_yield(request_proc(receive(Left))),
+        get_next_signal(SessionId, _),
+        session_proc_result(SessionId, receive, Result),
+        retract(session_proc_result(SessionId, receive, _)),
+        (   Result = ok(Term),
+            (   copy_term(Template, Copy), Copy = Term
+            ->  requeue_skipped(Skipped, SessionId),
+                Template = Term,
+                Message = Term
+            ;   receive_match_loop(Template, Message, TimeoutMs, Start, SessionId, [Term|Skipped])
+            )
+        ;   requeue_skipped(Skipped, SessionId),
+            fail
+        )
+    ).
+
+requeue_skipped(Skipped, SessionId) :-
+    requeue_reversed(Skipped, [], Reversed),
+    requeue_all(Reversed, SessionId).
+
+%% Build the reversed list without library(lists) (deepclause_mi may not have it).
+requeue_reversed([], Acc, Acc).
+requeue_reversed([X|Xs], Acc, Out) :- requeue_reversed(Xs, [X|Acc], Out).
+
+requeue_all([], _).
+requeue_all([Message|Messages], SessionId) :-
+    term_string(Message, Text),
+    engine_yield(request_proc(requeue(Text))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, requeue, _),
+    retract(session_proc_result(SessionId, requeue, _)),
+    requeue_all(Messages, SessionId).
+
+%% mi_call(exit(+Reason), +StateIn, -StateOut)
+%% Terminate this process. The host marks it killed; the frame is stopped by
+%% the throw below, which the runner maps to a clean termination.
+mi_call(exit(Reason), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Reason, ReasonText),
+    engine_yield(request_proc(exit(ReasonText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, exit, _),
+    retract(session_proc_result(SessionId, exit, _)),
+    throw(process_exit(Reason)).
+
+%% mi_call(exit(+Pid, +Reason), +StateIn, -StateOut)
+%% Terminate another process. Unlike exit/1 this returns; the target is killed.
+mi_call(exit(Pid, Reason), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Pid, PidText),
+    term_string(Reason, ReasonText),
+    engine_yield(request_proc(exit(PidText, ReasonText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, exit, ExitResult),
+    retract(session_proc_result(SessionId, exit, _)),
+    (   ExitResult == ok
+    ->  true
+    ;   throw(error(process_exit_failed(ExitResult), exit/2))
+    ).
+
+%% mi_call(process_info(+Pid, -Info), +StateIn, -StateOut)
+mi_call(process_info(Pid, Info), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Pid, PidText),
+    engine_yield(request_proc(process_info(PidText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, process_info, Info),
+    retract(session_proc_result(SessionId, process_info, _)).
+
+%% mi_call(register(+Name, +Pid), +StateIn, -StateOut)
+mi_call(register(Name, Pid), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Name, NameText),
+    term_string(Pid, PidText),
+    engine_yield(request_proc(register(NameText, PidText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, register, RegisterResult),
+    retract(session_proc_result(SessionId, register, _)),
+    (   RegisterResult == ok
+    ->  true
+    ;   throw(error(process_register_failed(RegisterResult), register/2))
+    ).
+
+%% mi_call(whereis(+Name, ?Pid), +StateIn, -StateOut)
+mi_call(whereis(Name, Pid), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Name, NameText),
+    engine_yield(request_proc(whereis(NameText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, whereis, WhereResult),
+    retract(session_proc_result(SessionId, whereis, _)),
+    WhereResult = ok(Pid).
+
+%% mi_call(sleep(+Milliseconds), +StateIn, -StateOut)
+mi_call(sleep(Milliseconds), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    engine_yield(request_proc(sleep(Milliseconds))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, sleep, _),
+    retract(session_proc_result(SessionId, sleep, _)).
+
+%% mi_call(make_ref(-Ref), +StateIn, -StateOut)
+mi_call(make_ref(Ref), StateIn, StateIn) :-
+    !,
+    gensym(ref_, Ref).
+
+%% mi_call(now_ms(-Milliseconds), +StateIn, -StateOut)
+mi_call(now_ms(Milliseconds), StateIn, StateIn) :-
+    !,
+    get_time(Seconds),
+    Milliseconds is round(Seconds * 1000).
+
+%% mi_call(serve(+Name, +Goal), +StateIn, -StateOut)
+%% Spawn a session-scoped process and register it under Name. Sugar over
+%% spawn/2 + register/2; the goal decides the process's shape.
+mi_call(serve(Name, Goal), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    copy_term(Goal, GoalCopy),
+    term_string(GoalCopy, GoalText),
+    engine_yield(request_proc(spawn(GoalText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, spawn, SpawnResult),
+    retract(session_proc_result(SessionId, spawn, _)),
+    SpawnResult = ok(Pid),
+    term_string(Name, NameText),
+    term_string(Pid, PidText),
+    engine_yield(request_proc(register(NameText, PidText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, register, _),
+    retract(session_proc_result(SessionId, register, _)).
+
+%% mi_call(service_cast(+Target, +Message), +StateIn, -StateOut)
+mi_call(service_cast(Target, Message), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Target, TargetText),
+    term_string(Message, MessageText),
+    engine_yield(request_proc(send(TargetText, MessageText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, send, _),
+    retract(session_proc_result(SessionId, send, _)).
+
+%% mi_call(service_call(+Target, +Request, -Reply), +StateIn, -StateOut)
+mi_call(service_call(Target, Request, Reply), StateIn, StateOut) :-
+    !,
+    mi_call(service_call(Target, Request, Reply, 300000), StateIn, StateOut).
+
+%% mi_call(service_call(+Target, +Request, -Reply, +TimeoutMs), ...)
+%% Request/reply against a process using the request(From, Ref, Request) /
+%% reply(Ref, Value) protocol. Unrelated messages are ignored while waiting.
+mi_call(service_call(Target, Request, Reply, Timeout), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    gensym(reply_ref_, Ref),
+    engine_yield(request_proc(self)),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, self, Me),
+    retract(session_proc_result(SessionId, self, _)),
+    term_string(Target, TargetText),
+    term_string(request(Me, Ref, Request), RequestText),
+    engine_yield(request_proc(send(TargetText, RequestText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, send, _),
+    retract(session_proc_result(SessionId, send, _)),
+    service_await_reply(Ref, Reply, Timeout).
+
+%% service_await_reply(+Ref, -Reply, +TimeoutMs)
+service_await_reply(Ref, Reply, Timeout) :-
+    get_session_id(SessionId),
+    engine_yield(request_proc(receive(Timeout))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, receive, Result),
+    retract(session_proc_result(SessionId, receive, _)),
+    (   Result = ok(reply(Ref, Reply))
+    ->  true
+    ;   Result = ok(_)
+    ->  service_await_reply(Ref, Reply, Timeout)
+    ;   fail
+    ).
+
+%% mi_call(wait(+Pid[, -Outcome]), +StateIn, -StateOut)
+%% Block until a process terminates. Outcome is ok(Result), failed(Error), or
+%% killed(Reason); Result is the process's terminal text as a Prolog string.
+%% `wait/1` is semidet: it succeeds only on a successful finish.
+mi_call(wait(Pid), StateIn, StateIn) :-
+    !,
+    mi_call(wait(Pid, Outcome), StateIn, _),
+    Outcome = ok(_).
+
+mi_call(wait(Pid, Outcome), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    term_string(Pid, PidText),
+    engine_yield(request_proc(wait(PidText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, wait, Outcome),
+    retract(session_proc_result(SessionId, wait, _)).
+
+%% ============================================================
+%% Swarm / pmap: fan a worker over a list concurrently
+%% ============================================================
+%% Each item runs in its own process (spawned through the host), calling
+%% call(Worker, Item, Value). Results preserve input order. `Concurrency` is
+%% accepted for compatibility and not yet enforced (the host's process limit is).
+
+proc_self(SessionId, Me) :-
+    engine_yield(request_proc(self)),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, self, Me),
+    retract(session_proc_result(SessionId, self, _)).
+
+%% mi_call(swarm(+Worker, +Items, -Results), ...)
+mi_call(swarm(Worker, Items, Results), StateIn, StateOut) :-
+    !,
+    mi_call(swarm(Worker, Items, Results, 4), StateIn, StateOut).
+
+%% mi_call(swarm(+Worker, +Items, -Results, +Concurrency), ...)
+%% Windowed fan-out: at most Concurrency items run at once.
+mi_call(swarm(Worker, Items, Results, Concurrency), StateIn, StateIn) :-
+    !,
+    get_session_id(SessionId),
+    proc_self(SessionId, Me),
+    (   integer(Concurrency), Concurrency > 0 -> Conc = Concurrency ; Conc = 4 ),
+    swarm_loop(Items, 1, [], Conc, Worker, Me, SessionId, [], Pairs),
+    keysort(Pairs, Sorted),
+    swarm_values(Sorted, Results).
+
+%% Accumulate `Acc`, bind the collected pairs to `Pairs` at the base.
+swarm_loop(Pending, NextIndex, InFlight, Conc, Worker, Me, SessionId, Acc, Pairs) :-
+    (   Pending = [Item|Rest],
+        length(InFlight, K), K < Conc
+    ->  swarm_spawn_one(Item, NextIndex, Worker, Me, SessionId, SpawnResult),
+        Next is NextIndex + 1,
+        (   SpawnResult = ok(_Pid)
+        ->  swarm_loop(Rest, Next, [NextIndex|InFlight], Conc, Worker, Me, SessionId, Acc, Pairs)
+        ;   % The host refused the spawn (e.g. the live-process limit): fail only
+            % this item, so the swarm still completes and the reason is visible
+            % instead of the whole call failing silently.
+            swarm_loop(Rest, Next, InFlight, Conc, Worker, Me, SessionId,
+                       [NextIndex-failed(SpawnResult)|Acc], Pairs)
+        )
+    ;   InFlight = [_|_]
+    ->  swarm_receive(Index, Value, SessionId),
+        selectchk(Index, InFlight, Rest),
+        swarm_loop(Pending, NextIndex, Rest, Conc, Worker, Me, SessionId, [Index-Value|Acc], Pairs)
+    ;   Pairs = Acc
+    ).
+
+swarm_spawn_one(Item, Index, Worker, Me, SessionId, SpawnResult) :-
+    term_string(deepclause_mi:dc_swarm_item(Worker, Item, Me, Index), GoalText),
+    engine_yield(request_proc(spawn(GoalText))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, spawn, SpawnResult),
+    retract(session_proc_result(SessionId, spawn, _)).
+
+swarm_receive(Index, Value, SessionId) :-
+    engine_yield(request_proc(receive(0))),
+    get_next_signal(SessionId, _),
+    session_proc_result(SessionId, receive, R),
+    retract(session_proc_result(SessionId, receive, _)),
+    R = ok(swarm_result(Index, Value)).
+
+swarm_values([], []).
+swarm_values([_-Value|Rest], [Value|Values]) :- swarm_values(Rest, Values).
+
+%% dc_swarm_item(+Worker, +Item, +Parent, +Index) — the child goal.
+%% Catch a thrown error (an undefined worker, a budget, a tool failure) and
+%% report it as `failed(Error)`. Without the catch the child process crashes and
+%% never sends a result, so the parent's `swarm_receive` waits forever.
+%%
+%% The `call` must stay inline in this clause: a helper predicate defined in
+%% `deepclause_mi` is reached via the meta-interpreter's raw-Prolog fallback, and
+%% then `call(Worker, ...)` resolves in `deepclause_mi` instead of the session
+%% module (so every worker looked undefined).
+dc_swarm_item(Worker, Item, Parent, Index) :-
+    catch(
+        (   call(Worker, Item, Result)
+        ->  Outcome = ok(Result)
+        ;   Outcome = failed
+        ),
+        Error,
+        Outcome = failed(Error)
+    ),
+    send(Parent, swarm_result(Index, Outcome)).
+
+%% mi_call(pmap(+Worker, +Items, -Values), ...)
+%% Like swarm/3, but fails if any item failed.
+mi_call(pmap(Worker, Items, Values), StateIn, StateIn) :-
+    !,
+    mi_call(swarm(Worker, Items, Results), StateIn, _),
+    pmap_ok(Results, Values).
+
+pmap_ok([], []).
+pmap_ok([ok(Value)|Rest], [Value|Values]) :- pmap_ok(Rest, Values).
+
 %% ============================================================
 %% Tool Scoping Predicates
 %% ============================================================
@@ -5477,6 +5998,30 @@ is_mi_special_predicate(task_named(_,_,_)).   %% Transformed form of task/N
 is_mi_special_predicate(sample_token(_,_)).
 is_mi_special_predicate(sample_token(_,_,_)).
 is_mi_special_predicate(exec(_,_)).
+is_mi_special_predicate(spawn(_,_)).
+is_mi_special_predicate(spawn_opt(_,_,_)).
+is_mi_special_predicate(self(_)).
+is_mi_special_predicate(send(_,_)).
+is_mi_special_predicate(receive(_)).
+is_mi_special_predicate(receive(_,_)).
+is_mi_special_predicate(receive_match(_,_,_)).
+is_mi_special_predicate(exit(_)).
+is_mi_special_predicate(exit(_,_)).
+is_mi_special_predicate(process_info(_,_)).
+is_mi_special_predicate(register(_,_)).
+is_mi_special_predicate(whereis(_,_)).
+is_mi_special_predicate(sleep(_)).
+is_mi_special_predicate(make_ref(_)).
+is_mi_special_predicate(now_ms(_)).
+is_mi_special_predicate(serve(_,_)).
+is_mi_special_predicate(service_cast(_,_)).
+is_mi_special_predicate(service_call(_,_,_)).
+is_mi_special_predicate(service_call(_,_,_,_)).
+is_mi_special_predicate(swarm(_,_,_)).
+is_mi_special_predicate(swarm(_,_,_,_)).
+is_mi_special_predicate(pmap(_,_,_)).
+is_mi_special_predicate(wait(_)).
+is_mi_special_predicate(wait(_,_)).
 is_mi_special_predicate(param(_,_)).
 is_mi_special_predicate(param(_,_,_)).
 %% Prompt predicates (like task but with fresh memory)

package/dist/repl/backend.d.ts

@@ -318,4 +318,13 @@ export interface ResolvedBackend {
  * provider/model so the runner builds the SDK provider backend.
  */
 export declare function resolveLlmBackend(options?: ResolveBackendOptions): Promise<ResolvedBackend>;
+/**
+ * Wrap a backend so at most `maxConcurrent` model calls are in flight at once.
+ *
+ * A `swarm`/fan-out otherwise fires one provider call per item simultaneously,
+ * which trips rate limits and bursts cost. The wrapper is created once (in
+ * `createHarnessRepl`) and shared by every child session, so the limit is per
+ * session tree. `maxConcurrent <= 0` returns the backend unchanged.
+ */
+export declare function createLimitedBackend(backend: LLMBackend, maxConcurrent: number): LLMBackend;
 //# sourceMappingURL=backend.d.ts.map