feat(ai): builtin ai/provider packages + @spec desugar for LLM functions

baml_language/.cargo/size-gate.toml

@@ -55,14 +55,17 @@ max_file_bytes = "22.5 MiB"
 kind = "pack"
 policy.max_delta_pct = 3.0
 
+# Bumped ~3% above the Aug 2026 baselines when the builtin ai/provider
+# stdlib packages landed (PR #4352): the packed program carries their
+# bytecode (~700 KB).
 [artifacts.packed-program.platform.aarch64-apple-darwin]
-max_file_bytes = "13.6 MiB"
+max_file_bytes = "14.3 MiB"
 
 [artifacts.packed-program.platform.x86_64-unknown-linux-gnu]
-max_file_bytes = "17.4 MiB"
+max_file_bytes = "18.3 MiB"
 
 [artifacts.packed-program.platform.x86_64-pc-windows-msvc]
-max_file_bytes = "14.5 MiB"
+max_file_bytes = "15.3 MiB"
 
 [artifacts.packed-program.pack]
 cli_package = "baml_cli"

baml_language/.ci/size-gate/aarch64-apple-darwin.toml

@@ -8,5 +8,5 @@ stripped_bytes = "20.3 MiB"
 gzip_bytes = "9.7 MiB"
 
 [artifacts.packed-program]
-file_bytes = "13.2 MiB"
-gzip_bytes = "6.1 MiB"
+file_bytes = "13.8 MiB"
+gzip_bytes = "6.3 MiB"

baml_language/.ci/size-gate/x86_64-pc-windows-msvc.toml

@@ -8,5 +8,5 @@ stripped_bytes = "21.9 MiB"
 gzip_bytes = "9.9 MiB"
 
 [artifacts.packed-program]
-file_bytes = "14.1 MiB"
-gzip_bytes = "6.2 MiB"
+file_bytes = "14.8 MiB"
+gzip_bytes = "6.4 MiB"

baml_language/.ci/size-gate/x86_64-unknown-linux-gnu.toml

@@ -8,5 +8,5 @@ stripped_bytes = "26.1 MiB"
 gzip_bytes = "11.1 MiB"
 
 [artifacts.packed-program]
-file_bytes = "16.9 MiB"
-gzip_bytes = "7.0 MiB"
+file_bytes = "17.7 MiB"
+gzip_bytes = "7.2 MiB"

baml_language/.markdown-whitelist

@@ -29,6 +29,12 @@ TYPE_SYSTEM.md
 # Speedtest workload definitions
 tools/speedtest/workloads/**/*.md
 
+# BEP planning trees (design pages + working-reference notes)
+_plan/*.md
+_plan/**/*.md
+_planv2/*.md
+_planv2/**/*.md
+
 # BEX event identity & program metadata: cross-team contract docs for the
 # paulo/bex-event-identity-metadata work (design ticket, review, response,
 # post-implementation notes) — REVIEW.md §7.8 asks for these to ship with

baml_language/_plan/ai_agents/baml.toml

@@ -0,0 +1,2 @@
+[package]
+name = "ai_agents"

baml_language/_plan/ai_agents/baml_src/ns_ai/client.baml

@@ -0,0 +1,57 @@
+// A client is a stateless codec + transport for one provider wire format.
+// Mirrors _plan/pages/02_guides/04_models.md.
+
+class ProviderRequest {
+    url: string,
+    headers: map<string, string>,
+    body_json: string,
+}
+
+class ProviderResponse {
+    status: int,
+    body_json: string,
+}
+
+// Duties: render (journal -> provider-native request), invoke (one
+// stateless call), ingest (response -> events, raw payload preserved).
+// Clients render any event union but only ever PRODUCE built-in events.
+interface Client {
+    type Ev = Event
+
+    function id(self) -> string throws never
+    function render(self, j: Journal<Self.Ev>, tb: Toolbox, output_schema: string) -> ProviderRequest throws unknown
+    function invoke(self, req: ProviderRequest) -> ProviderResponse throws unknown
+    function ingest(self, resp: ProviderResponse) -> Event[] throws unknown
+}
+
+//# A fake provider: drives the whole loop deterministically in tests.
+
+// Mirrors _plan/pages/04_advanced/02_evals.md.
+class ScriptedClient<X> {
+    turns: Event[][], // what "the model" does on call 1, 2, 3...
+    i: int,
+
+    implements Client {
+        type Ev = Event | X
+
+        function id(self) -> string {
+            "scripted"
+        }
+        function render(
+            self,
+            j: Journal<Event | X>,
+            tb: Toolbox,
+            output_schema: string,
+        ) -> ProviderRequest {
+            ProviderRequest { url: "", headers: {}, body_json: "" }
+        }
+        function invoke(self, req: ProviderRequest) -> ProviderResponse {
+            ProviderResponse { status: 200, body_json: "" }
+        }
+        function ingest(self, resp: ProviderResponse) -> Event[] {
+            let batch: Event[] = self.turns.at(self.i) ?? [];
+            self.i += 1;
+            batch
+        }
+    }
+}

baml_language/_plan/ai_agents/baml_src/ns_ai/errors.baml

@@ -0,0 +1,22 @@
+// User-defined session errors — the typed catalog from the BEP's
+// errors-and-retries guide, expressed as ordinary classes.
+// `throw X { ... }` + typed `catch` arms + `throws X` signatures all work.
+
+class StepBudgetExceeded {
+    message: string,
+    steps: int,
+}
+
+class CostBudgetExceeded {
+    message: string,
+    spent_usd: float,
+}
+
+// Thrown by the async runner when a run() blocked on cancelled work is
+// torn down (`baml.session.Interrupted` in the BEP's error catalog). The
+// synchronous reference never throws it: an interrupt is recorded as an
+// Interrupted event and the default policy lets the model react
+// (04_steering.md); CancelAll only fires cancel tokens.
+class SessionInterrupted {
+    reason: string,
+}

baml_language/_plan/ai_agents/baml_src/ns_ai/events.baml

@@ -0,0 +1,216 @@
+// The journal: an append-only log of typed events. One per session.
+// Mirrors _plan/pages/02_guides/10_journal.md.
+
+class SessionStarted {
+    function_name: string,
+    args_json: string,
+}
+
+class UserMessage {
+    content: string,
+}
+
+class AssistantMessage {
+    content: string,
+    raw_json: string?,
+    provider: string,
+}
+
+class ToolRequested {
+    call_id: string,
+    tool: string,
+    args_json: string,
+}
+
+class ToolCompleted {
+    call_id: string,
+    result_json: string,
+}
+
+class ToolFailed {
+    call_id: string,
+    error: string,
+}
+
+class FinalProduced {
+    result_json: string,
+}
+
+class ToolsChanged {
+    names: string[],
+}
+
+class StepCompleted {
+    call_id: string,
+    step: string,
+    result_json: string,
+}
+
+class ChildSpawned {
+    child_id: string,
+    goal: string,
+}
+
+class ChildFinished {
+    child_id: string,
+    result_json: string,
+}
+
+class Interrupted {
+    reason: string,
+}
+
+// A setter changed the session's client (03_configuration.md). Journal-only.
+class ClientChanged {
+    client_id: string,
+}
+
+// A setter changed the session's policy. Journal-only. Records that the
+// change happened, not the value: a policy is a runtime value (often
+// closing over state), so resume takes the policy from the caller and
+// this event is audit history (see reference notes, spec issues).
+// The literal field is a wire discriminant: an EMPTY class in a journaled
+// union structurally matches any JSON object on resume and swallows every
+// variant after it (see reference notes).
+class PolicyChanged {
+    kind: "policy_changed",
+}
+
+class Usage {
+    input_tokens: int,
+    output_tokens: int,
+}
+
+class Compacted {
+    summary: string,
+    through_seq: int,
+}
+
+type Event = SessionStarted
+    | UserMessage
+    | AssistantMessage
+    | ToolRequested
+    | ToolCompleted
+    | ToolFailed
+    | FinalProduced
+    | ToolsChanged
+    | ClientChanged
+    | PolicyChanged
+    | StepCompleted
+    | ChildSpawned
+    | ChildFinished
+    | Interrupted
+    | Usage
+    | Compacted;
+
+// Custom events are invisible to the model unless they implement this.
+// Mirrors `baml.session.Promptable` in 11_journal.md.
+interface Promptable {
+    function to_prompt(self) -> string? throws never
+}
+
+class Entry<E> {
+    seq: int,
+    event: E,
+    // true = written by a policy via record(): journal-only history that was
+    // never folded live, so refold skips it too (see refold in session.baml)
+    recorded: bool,
+}
+
+class Journal<E> {
+    entries: Entry<E>[],
+    replaying: bool, // set by refold; suppresses record()
+
+    // runner-side: append an event that IS folded through the policy
+    function append(self, e: E) -> void {
+        self.entries.push(Entry { seq: self.entries.length(), event: e, recorded: false });
+    }
+
+    // policy-side: record a journal-only decision (e.g. PermissionRequested).
+    // Never folded; suppressed during refold, so replay cannot duplicate it.
+    // This is the ONLY journal write allowed inside Policy.update.
+    function record(self, e: E) -> void {
+        if (!self.replaying) {
+            self.entries.push(Entry { seq: self.entries.length(), event: e, recorded: true });
+        }
+    }
+
+    function read_from(self, seq: int) -> Entry<E>[] {
+        // .filter() infers Entry<never>[] here (see reference notes); build manually
+        let out: Entry<E>[] = [];
+        for (let en in self.entries) {
+            if (en.seq >= seq) {
+                out.push(en);
+            }
+        }
+        out
+    }
+
+    function last_seq(self) -> int {
+        self.entries.length() - 1
+    }
+
+    function snapshot(self) -> string {
+        baml.json.to_string(self)
+    }
+}
+
+function new_journal<E>() -> Journal<E> {
+    Journal<E> { entries: [], replaying: false }
+}
+
+function resume_journal<E>(snap: string) -> Journal<E> {
+    baml.json.from_string<Journal<E>>(snap)
+}
+
+//# The transcript is a rendering of the journal, not storage.
+
+// The real feature (${ctx.transcript}) lowers provider-natively; this
+// library fold renders to text.
+function render_transcript<E>(j: Journal<E>) -> string {
+    j.entries
+        .map((en) -> {
+            match (en.event) {
+                let s: SessionStarted => `[briefing] ${s.args_json}`,
+                let u: UserMessage => `[user] ${u.content}`,
+                let a: AssistantMessage => `[assistant] ${a.content}`,
+                let t: ToolRequested => `[calling] ${t.tool}(${t.args_json})`,
+                let t: ToolCompleted => `[result] ${t.result_json}`,
+                let t: ToolFailed => `[tool error] ${t.error}`,
+                let c: Compacted => `[earlier, summarized] ${c.summary}`,
+                let p: Promptable => p.to_prompt() ?? "", // custom events opt in
+                _ => "",
+            }
+        })
+        .filter((s) -> {
+            s != ""
+        })
+        .join("\n")
+}
+
+// Event factories — the library form of `baml.session.user(...)`.
+// Also the workaround for qualified struct literals inside array literals
+// (see _plan/reference_notes.md).
+function user(content: string) -> Event {
+    UserMessage { content: content }
+}
+
+function assistant(content: string, provider: string = "test", raw_json: string? = null) -> Event {
+    AssistantMessage { content: content, raw_json: raw_json, provider: provider }
+}
+
+function tool_requested(call_id: string, tool: string, args_json: string) -> Event {
+    ToolRequested { call_id: call_id, tool: tool, args_json: args_json }
+}
+
+function tool_completed(call_id: string, result_json: string) -> Event {
+    ToolCompleted { call_id: call_id, result_json: result_json }
+}
+
+function final_produced(result_json: string) -> Event {
+    FinalProduced { result_json: result_json }
+}
+
+function usage_of(input_tokens: int, output_tokens: int) -> Event {
+    Usage { input_tokens: input_tokens, output_tokens: output_tokens }
+}