feat: Add HTTP trigger alongside Discord — unified broker for scheduler + Discord

[howie]

Summary

OpenAB is great as a Discord-to-Claude bridge, but there's a broader use case: using OpenAB as a unified agent broker for both human (Discord) and machine (scheduler/CI) triggers, sharing the same session pool and ACP pipeline.

This issue proposes adding an HTTP trigger option so that automated tasks (cron jobs, schedulers, CI pipelines) can invoke the same agent backend that Discord users interact with — without needing Discord as a dependency.

---

Motivation

Current state

Discord @mention ──▶ OpenAB ──▶ ACP stdio ──▶ Claude Code / Kiro / Codex

Works perfectly for human-driven interactions. But for automated tasks (e.g. "generate a daily newsletter digest at 07:12 every morning"), Discord is an awkward dependency:

• Scheduler must send a Discord message and poll the thread for completion
• No structured return value (exit code, output text)
• Internet dependency for what is essentially a local task

Proposed state

Discord @mention ──┐
                   ├──▶ OpenAB ──▶ ACP stdio ──▶ Claude Code / Kiro / Codex
HTTP POST /v1/prompt ──┘  (shared session pool)

Both triggers share the same session pool and ACP backend. HTTP callers get a synchronous JSON response; Discord users get the existing streaming thread experience.

---

Proposed Design

New [http] config block

[http]
enabled = true
port = 7865
bind = "127.0.0.1"          # localhost-only by default
token = "${ACP_HTTP_TOKEN}"  # Bearer token auth (64-char hex)
timeout_ms = 300000

New endpoint: POST /v1/prompt

Request:

{
  "prompt": "Generate a summary of today's newsletters",
  "timeout_ms": 300000,
  "caller": "my-scheduler/v1"
}

Response:

{
  "output": "## Daily Digest\n...",
  "success": true,
  "duration_ms": 8432,
  "timed_out": false
}

Auth: Authorization: Bearer <token>

Health check: GET /health (no auth required)

Implementation sketch

// src/http.rs (new file, ~80 lines)
use axum::{routing::{get, post}, Router, Json, extract::State};
use crate::acp::pool::SessionPool;

async fn handle_prompt(
    State(pool): State<Arc<SessionPool>>,
    headers: HeaderMap,
    Json(req): Json<PromptRequest>,
) -> Json<PromptResponse> {
    // 1. verify Bearer token
    // 2. acquire session from pool (or create ephemeral one)
    // 3. submit prompt via ACP stdio
    // 4. collect response until "done" event
    // 5. return JSON
}

pub fn router(pool: Arc<SessionPool>, token: String) -> Router {
    Router::new()
        .route("/v1/prompt", post(handle_prompt))
        .route("/health", get(health))
        .with_state(pool)
}

// src/main.rs — spawn HTTP server alongside Discord gateway
if config.http.enabled {
    let http_router = http::router(pool.clone(), config.http.token.clone());
    tokio::spawn(axum::serve(
        TcpListener::bind(format!("{}:{}", config.http.bind, config.http.port)).await?,
        http_router,
    ));
}

---

Additional use case: SSH/OpenShell backend

For users running OpenAB locally (Mac mini, home server) with OpenShell sandboxes, it would be useful to support an SSH-based backend in addition to direct subprocess spawning:

[agent]
command = "ssh"
args = ["openshell-claude-dev", "claude-agent-acp"]
working_dir = "/sandbox"

OpenShell auto-manages SSH config (~/.ssh/config), so no key management is needed. This gives sandboxed execution (Landlock filesystem + network policy) without changing OpenAB's ACP stdio protocol.

---

Benefits

	Current (Discord only)	With HTTP trigger
Scheduler/CI invocation	❌ Need Discord message + polling	✅ POST /v1/prompt
Return value	❌ Parse Discord thread	✅ Structured JSON
Internet dependency	✅ Required	✅ HTTP works localhost-only
Multi-turn (human)	✅ Discord threads	✅ Unchanged
Session pool sharing	N/A	✅ Both triggers share pool
Auth	Discord OAuth	Bearer token (localhost)

---

Scope

This is intentionally minimal:

• New file: src/http.rs (~80 lines)
• Modified: src/config.rs (add [http] block), src/main.rs (spawn HTTP server)
• No changes to existing Discord behavior
• No new dependencies beyond axum (already common in Rust ecosystem)

---

Questions for maintainers

1. Is this direction aligned with OpenAB's goals? (universal agent broker vs. Discord-specific tool)
2. Would you prefer a separate crate/binary for the HTTP server, or integrated?
3. Any concerns about the Bearer token auth model for localhost use?

Happy to submit a PR if the direction looks good.

[chaodu-agent]

Great proposal — the direction of turning OpenAB into a unified agent broker (not just a Discord bot) makes a lot of sense. A few questions/concerns I'd love to see addressed before a PR:

1. Session lifecycle for HTTP calls — The implementation sketch mentions "acquire session from pool (or create ephemeral one)", but it would be helpful to clarify: will HTTP callers be able to specify a session_id for multi-turn conversations? Single-turn-only would limit usefulness for complex tasks. Maybe something like an optional session_id field in the request body, with ephemeral as the default?

2. Streaming support — Discord users get a streaming thread experience, but HTTP callers would wait up to 300s for a single JSON blob with no progress visibility. Have you considered supporting SSE (Server-Sent Events) as an optional response mode (e.g. Accept: text/event-stream)? This would be especially valuable for long-running agent tasks.

3. Concurrency / rate limiting — Binding to 127.0.0.1 by default is good, but if someone changes it to 0.0.0.0, there is no rate limiting mentioned in the proposal. Worth adding a max_concurrent or rate_limit config option to prevent the session pool from being exhausted.

4. Scope suggestion — The OpenShell/SSH backend section feels like a separate concern. I would suggest splitting it into its own issue to keep this one focused on the HTTP trigger. It would make both easier to review and implement independently.

Looking forward to seeing this move forward!

[howie]

Thanks for the detailed feedback! Here's how I'd address each point, with a few additional considerations from a broader design review.

---

1. Session lifecycle — session_id + namespace isolation

I'll add an optional session_id field:

{ "prompt": "...", "session_id": "my-scheduler-job-abc123" }

• Omitted → ephemeral UUID session, evicted after idle TTL
• Provided → reuse existing session from pool (multi-turn context)

session_id will be validated against [A-Za-z0-9_-] to prevent pool key injection.

Since session_id is caller-supplied and SessionPool is shared with Discord, pool keys will be namespaced by source:

Source    Pool key
────────  ──────────────────────────
HTTP      http:{session_id or uuid}
Discord   discord:{channel_id}

This prevents accidental cross-source session collisions even if IDs happen to coincide. Internally I'll represent this as enum SessionKey { Http(String), Discord(u64) } rather than raw string concatenation, so the compiler enforces correct key construction.

Session TTL: HTTP sessions will use idle-based eviction (default: 30 min since last request) rather than absolute TTL, since schedulers may have multi-hour gaps between runs. Discord sessions keep the existing 24 h TTL.

Session security: For this PR, the HTTP endpoint is localhost-only (bind = "127.0.0.1" by default). Multi-turn session hijacking is not a concern in that threat model. If the bind address is opened to a network, callers should rotate session_id values or use a separate authentication mechanism — happy to track that as a follow-up issue.

---

2. Streaming — SSE support

Accept: text/event-stream as opt-in:

POST /v1/prompt                         POST /v1/prompt
Accept: text/event-stream               (default)
         │                                       │
         ▼                                       ▼
  SSE stream (bounded ch, cap=32)        wait for completion
  data: {"chunk": "..."}    ×N           {"output": "...",
  data: {"done": true,                    "success": true,
         "success": true,                 "duration_ms": N}
         "duration_ms": N}

Three implementation details:

• Bounded channel (capacity = 32): replaces UnboundedReceiver to get natural backpressure — if the HTTP client reads slowly, the ACP reader pauses rather than buffering unboundedly in memory.

• Cancellation safety: when the HTTP client disconnects, axum drops the Receiver. The ACP task detects SendError on its next send() (not the other way around — it's the Receiver drop that signals the Sender). On detection, the task sends SIGTERM to the Claude subprocess via kill_on_drop, preventing zombie processes.

  client drops → Receiver drops → sender.send() = Err(SendError)
                                → ACP task aborts → subprocess killed
  

• Mid-stream errors: once SSE starts, HTTP status is fixed at 200. Errors surfaced as data: {"error": "connection reset"} in the body.

SSE format kept simple for now. OpenAI-compatible format (data: {"choices":[{"delta":{"content":"..."}}]}) is an option if ecosystem compatibility matters — flagging the trade-off for the maintainer to decide.

---

3. Concurrency + pool isolation

Three-layer approach:

[http] config                  [pool] config
─────────────────────          ──────────────────────────
max_concurrent = 4             max_http_sessions = 8
request_timeout_ms = 300000    max_discord_sessions = 10

• max_concurrent (HTTP-layer Semaphore) — 429 when exhausted, before touching the pool
• request_timeout_ms — per-request deadline; HTTP callers have no heartbeat to detect stalled Claude subprocesses
• Per-source pool quotas (max_http_sessions / max_discord_sessions): separate Semaphores rather than a single shared counter with a "reserved" carve-out. This is both simpler to implement and has cleaner semantics — Discord and HTTP each have their own ceiling, with no shared quota to reason about.

---

4. Scope

Fully agreed — SSH/OpenShell will be a separate issue. This PR stays focused on the HTTP trigger.

---

Happy to follow up with the concrete Rust struct sketch for [http] and [pool] config, or a draft src/http.rs skeleton, whichever is more useful for the review.

[chaodu-agent]

Hi @howie,

Good proposal — HTTP trigger alongside Discord makes openab a more versatile agent broker. The design is clean: shared session pool, minimal scope, no impact on existing Discord behavior.

This is a meaningful architectural addition, so we'd like to discuss with the team before committing to a direction. We also welcome inputs from the community — if others have use cases or opinions on the API design, please chime in.

Related: PR #94 (multi-platform adapter RFC) is exploring similar themes.