apoc 0.9.1

Agentic process control for LLMs
Documentation
//! Nested Code Mode: a program invoking apoc, which runs another program, and so on.
//!
//! Composition is only worth the name if a program can reach apoc itself. The
//! hazard is re-entrancy: the outer program occupies a dispatch session while its
//! child opens another against the same daemon, so anything the outer pass holds
//! while dispatching becomes a deadlock the moment the child needs it.

use std::process::{Command, Output};

use serde_json::Value;
use tempfile::{TempDir, tempdir};

struct Fixture {
    binary: String,
    home: TempDir,
    runtime: TempDir,
}

impl Fixture {
    fn new() -> Self {
        Self {
            binary: env!("CARGO_BIN_EXE_apoc").to_string(),
            home: tempdir().unwrap(),
            runtime: tempdir().unwrap(),
        }
    }

    fn run(&self, args: &[&str]) -> Output {
        Command::new(&self.binary)
            .args(args)
            .env("APOC_HOME", self.home.path())
            .env("APOC_RUNTIME_DIR", self.runtime.path())
            .output()
            .unwrap()
    }

    /// Runs one Code Mode program and returns its parsed execution state.
    fn code_run(&self, code: &str, key: &str) -> Value {
        let output = self.run(&[
            "code",
            "run",
            code,
            "--purpose",
            "Exercising nested Code Mode invocation.",
            "--idempotency-key",
            key,
            "--format",
            "json",
        ]);
        let stdout = String::from_utf8_lossy(&output.stdout);
        serde_json::from_str(&stdout).unwrap_or_else(|error| {
            panic!(
                "expected one JSON execution state, got {error}\nstdout: {stdout}\nstderr: {}",
                String::from_utf8_lossy(&output.stderr)
            )
        })
    }
}

impl Drop for Fixture {
    fn drop(&mut self) {
        let _ = self.run(&[
            "daemon",
            "stop",
            "--purpose",
            "Stopping the nested Code Mode fixture daemon.",
            "--idempotency-key",
            "recursion-teardown",
        ]);
    }
}

/// A program that runs apoc, which runs a program, which runs apoc again.
///
/// Three levels, because two would not distinguish "nesting works" from "one
/// level of nesting is special-cased". The innermost value is carried back up
/// through both parents: asserting only that each child exited zero would pass
/// even if the innermost program never ran.
#[test]
fn code_mode_programs_nest_apoc_invocations_recursively() {
    let fixture = Fixture::new();
    let binary = serde_json::to_string(&fixture.binary).unwrap();

    // Depth 3 returns a token. Each parent runs its child, reads the child's
    // stdout, and hands the value further up, so the assertion at the top can
    // only hold if every level actually executed.
    let depth_three = serde_json::to_string("return \"INNERMOST-OK\"").unwrap();
    let depth_two = serde_json::to_string(&format!(
        r#"
        const run = await apoc.execution_command({{
          executable: {binary},
          arg: ["code", "run", {depth_three},
                "--purpose", "Innermost nested program.",
                "--idempotency-key", "depth-three",
                "--format", "json"],
          purpose: "Running the innermost nested program.",
          idempotency_key: "depth-two-spawn",
          expect_exit_code: [0]
        }});
        const logs = await apoc.execution_logs({{
          id: run.id, tail_bytes: 65536,
          purpose: "Reading the innermost program's output."
        }});
        return {{ depth: 2, outcome: run.outcome, inner: JSON.parse(logs.stdout).result }};
        "#
    ))
    .unwrap();

    let outer = format!(
        r#"
        const run = await apoc.execution_command({{
          executable: {binary},
          arg: ["code", "run", {depth_two},
                "--purpose", "Middle nested program.",
                "--idempotency-key", "depth-two",
                "--format", "json"],
          purpose: "Running the middle nested program.",
          idempotency_key: "outer-spawn",
          expect_exit_code: [0]
        }});
        const logs = await apoc.execution_logs({{
          id: run.id, tail_bytes: 65536,
          purpose: "Reading the middle program's output."
        }});
        return {{ depth: 1, outcome: run.outcome, middle: JSON.parse(logs.stdout).result }};
        "#
    );

    let state = fixture.code_run(&outer, "outer");

    assert_eq!(
        state.get("status").and_then(Value::as_str),
        Some("completed"),
        "three levels of nested apoc must complete: {state:#}"
    );
    let result = state.get("result").expect("a result");
    assert_eq!(result.get("depth").and_then(Value::as_i64), Some(1));

    let middle = result.get("middle").expect("the middle program's result");
    assert_eq!(
        middle.get("depth").and_then(Value::as_i64),
        Some(2),
        "the middle level must report itself: {result:#}"
    );
    assert_eq!(
        middle.get("inner").and_then(Value::as_str),
        Some("INNERMOST-OK"),
        "the innermost value must survive two levels of nesting: {result:#}"
    );
}

/// A program reaches apoc without opening a socket back to its own daemon.
///
/// The program moves the daemon's socket out of the way, then runs a command
/// through apoc. Dispatched over that socket the call cannot connect at all;
/// dispatched in-process it succeeds. The command is a daemon call rather than
/// a process read, because process reads never touch the daemon and would pass
/// either way.
#[test]
fn a_program_reaches_apoc_without_a_socket_back_to_its_own_daemon() {
    let fixture = Fixture::new();
    let socket = fixture.runtime.path().join("apoc.sock");
    let aside = fixture.runtime.path().join("apoc.sock.aside");
    let code = format!(
        r#"
        const purpose = "Proving a program's apoc calls do not use the socket.";
        const moved = await apoc.execution_command({{
          executable: "/bin/mv", arg: [{socket:?}, {aside:?}],
          idempotency_key: "socket-aside", purpose }});
        let ran;
        try {{
          const result = await apoc.execution_command({{
            executable: "/usr/bin/true", idempotency_key: "without-socket", purpose }});
          ran = result.outcome;
        }} catch (error) {{
          ran = "threw: " + String(error);
        }}
        const restored = await apoc.execution_command({{
          executable: "/bin/mv", arg: [{aside:?}, {socket:?}],
          idempotency_key: "socket-back", purpose }});
        return {{ moved: moved.outcome, ran, restored: restored.outcome }};
        "#,
        socket = socket.to_str().unwrap(),
        aside = aside.to_str().unwrap(),
    );
    let state = fixture.code_run(&code, "no-loopback");
    // Put the socket back whatever happened, so teardown can reach the daemon.
    if aside.exists() {
        std::fs::rename(&aside, &socket).unwrap();
    }

    let result = &state["result"];
    assert_eq!(result["moved"], "passed", "state: {state}");
    assert_eq!(
        result["ran"], "passed",
        "a call made with the socket gone must still reach apoc; state: {state}"
    );
    assert_eq!(result["restored"], "passed", "state: {state}");
}

/// A command a program starts for its own lifetime is canceled when the
/// program ends.
///
/// The cancellation is itself an apoc call made from inside the daemon, so it
/// is the path most likely to break when that dispatch changes; nothing else
/// asserts it.
#[test]
fn a_program_owned_command_is_canceled_when_the_program_ends() {
    let fixture = Fixture::new();
    let state = fixture.code_run(
        r#"
        const started = await apoc.execution_start({
          executable: "/bin/sleep", arg: ["60"], owner: "execution",
          idempotency_key: "owned-sleep",
          purpose: "Starting a command that lives only as long as this program." });
        return { id: started.id };
        "#,
        "owned-child",
    );
    let id = state["result"]["id"]
        .as_str()
        .unwrap_or_else(|| panic!("program should return the child id; state: {state}"))
        .to_string();

    let deadline = std::time::Instant::now() + std::time::Duration::from_secs(15);
    let status = loop {
        let output = fixture.run(&[
            "execution",
            "get",
            &id,
            "--purpose",
            "Checking whether the program-owned command was canceled.",
            "--verbosity",
            "trace",
            "--format",
            "json",
        ]);
        let record: Value = serde_json::from_slice(&output.stdout).unwrap_or_default();
        let status = record["status"].as_str().unwrap_or_default().to_string();
        if status != "running" && status != "starting" && !status.is_empty() {
            break status;
        }
        if std::time::Instant::now() > deadline {
            break status;
        }
        std::thread::sleep(std::time::Duration::from_millis(200));
    };
    assert_eq!(
        status, "canceled",
        "a command owned by a finished program must not keep running"
    );
}