feat(api): GET /runs — list runs filtered by status + initial_input fields

[viktor-shcherb]

Goal

Let an agent discover the right run_id for a user's natural-language request like "add Stripe to jobseek" without needing the user to manually paste a run_id.

Why

Companion to murmur#75. The end-user workflow on jobseek will be:

1. User clicks "request company" on jseek.co, types a name + URL.
2. Backend calls POST /pipelines/jobseek-add-company/runs, stores the run_id in a UI card, and shows the user a prompt they can copy to their own Claude session.
3. (This issue) The user's Claude session resolves the run_id from a company name by calling list_runs (or its HTTP equivalent), then proceeds with pull_task({run_id}).

Without a list endpoint, the agent has no way to find pending runs.

Scope

1. New publisher route GET /runs mounted alongside the existing GET /runs/{id}.
2. Query params (all optional):
   • status — one of running, completed (?status=running is the demo-load-bearing case).
   • pipeline_id — exact match (e.g. jobseek-add-company).
   • initial_input — JSON-string fragment matched against runs.initial_input_json via JSON_EXTRACT. For the demo we need at least company-name search; spec a single field path syntax (e.g. ?initial_input.company_name=Stripe) or accept a raw JSON object body and match keys.
3. Pagination: hard cap at 100, limit + offset query params. No total count needed for the demo.
4. Response shape: { ok: true, data: { runs: [{run_id, pipeline_id, status, initial_input, created_at, webhook_status}] } }.

Interfaces

GET /runs?status=running&pipeline_id=jobseek-add-company&initial_input.company_name=Stripe&limit=10
→ {
  ok: true,
  data: {
    runs: [
      { run_id, pipeline_id, status, initial_input, created_at, webhook_status }
    ]
  }
}

Verification

• ?status=running returns only runs whose status == running, ordered by created_at DESC.
• ?pipeline_id=jobseek-add-company&status=running AND-combines the filters.
• ?initial_input.company_name=Stripe matches runs whose initial_input_json has that field equal to that value (case-insensitive optional).
• ?limit=5&offset=10 paginates.
• Bearer auth required (uses existing middleware).
• Unauthed → 401, schema validation errors → 400, transport errors → 5xx.
• Listing returns {runs: []} when no rows match (NOT 404).

Definition of done

• Tests above all green.
• pnpm typecheck && pnpm lint && pnpm test && pnpm grep:all clean.
• PR opened, reviewer APPROVE.
• docs/contracts.md describes the route shape.

Out of scope

• Mutation endpoints (PATCH /runs/{id} to abort/retry — separate issue post-demo).
• Listing runs the calling user "owns" (post-demo authz issue).
• Full-text search on the entire initial_input blob — only specific field-path equality for the demo.

Blocked by

None. Independent of murmur#75.

[viktor-shcherb]

Claimed by orchestrator-developer until 2026-04-30T13:52:06Z.

[viktor-shcherb]

Implementation sketch

Approach: Add a new GET /runs route alongside the existing GET /runs/{id} in src/api/publisher/runs.ts (so both share the bearer-auth gate from createPublisherApp). The handler parses status, pipeline_id, optional limit/offset, and any query keys prefixed initial_input.<field> (validated against ^[A-Za-z0-9_]+$). It builds a parameterised SQL query: a base SELECT ... FROM runs with conjunctive WHERE clauses, ordered created_at DESC. Each initial_input.<field> becomes JSON_EXTRACT(initial_input_json, '$.<field>') = ? with the value bound; the field path is interpolated only after regex-validation, the value is always bound. Server clamps limit to [1, 100] (default 25) and offset to >= 0 (default 0); invalid params return 400. Response envelope is Ok<{ runs: RunListItem[] }>.

Files to add/edit:

• src/api/publisher/runs.ts — add mountRunListRoute exporting RunListItem type + the GET /runs handler. Keep mountRunRoutes calling both internally so index.ts stays unchanged in spirit.
• src/api/publisher/runs.test.ts — new test file for GET /runs covering all verification cases below.
• docs/contracts.md — append a brief subsection describing the GET /runs shape under §-publisher routes (or a new appendix entry).

Key types/interfaces:

• interface RunListItem { run_id: string; pipeline_id: string; status: string; initial_input: unknown; created_at: string; webhook_status: string | null }
• interface RunListView { runs: ReadonlyArray<RunListItem> }
• Internal parseListQuery(c.req.query()) -> { ok: true; filters } | { ok: false; errors } helper (file-local, not exported).

Risks / unknowns:

• SQL-injection vector via $.<field> interpolation — mitigated by strict ^[A-Za-z0-9_]+$ regex.
• JSON_EXTRACT on rows whose initial_input_json is a non-object yields NULL (won't match) — fine for our equality semantics.
• status enumeration: per the issue, running and completed are documented; we accept any non-empty string but only those two are exercised. No DB-side check constraint exists so we don't whitelist server-side.
• limit/offset numeric parsing — reject non-integers with 400 (limit_invalid / offset_invalid).
• No DB schema change needed; runs.created_at already exists. Existing index does not cover created_at DESC global ordering, but the demo dataset is tiny — an index can come later if needed.

Test list (from the issue's Verification):

• ?status=running returns only running runs ordered by created_at DESC.
• ?pipeline_id=...&status=running AND-combines filters.
• ?initial_input.company_name=Stripe matches runs with that JSON field equal to that value.
• ?limit=5&offset=10 paginates.
• Bearer auth required: missing Authorization → 401.
• Schema validation errors → 400 (e.g. limit=abc, initial_input.bad-field).
• No matching rows → 200 with { runs: [] } (NOT 404).
• limit clamped at server-side cap of 100 regardless of caller.

[viktor-shcherb]

Implementation complete. PR #78, ready for review.