fabro/docs/public/api-reference
fabro-sh-0530[bot] def37896cd
Expose PermissionLevel on StageProjection and add sortable run columns (#373)
## Summary

Two independent additions landed together: surfacing `PermissionLevel`
on `StageProjection` (the primary goal), and making four previously
unsortable run-list columns (`repo`, `title`, `workflow`, `changes`)
sortable.

## Permission Level on StageProjection

`PermissionLevel` (`read-only | read-write | full`) was already resolved
at session start inside `fabro-agent` but never reached the API. This
wires it through the existing `agent.session.activated` event rather
than introducing a new event.

The data flow:

```mermaid
graph TB
    A[SessionOptions.permission_level] -->|set at CLI build_tool_approval| B[Session.permission_level]
    B -->|read in api.rs| C[ActivationLeaseOptions.permission_level]
    C -->|emitted as| D[Event::AgentSessionActivated.permission_level]
    D -->|convert.rs| E[EventBody::AgentSessionActivated.permission_level]
    E -->|run_state.rs apply_event| F[StageProjection.permission_level]
    F -->|OpenAPI + TS client| G[API consumers]
```

Key decisions:
- **No new event or type.** `PermissionLevel` is reused from
`fabro_types::session` directly; `AgentSessionActivatedProps` gains one
optional field with `skip_serializing_if`, so older persisted events
deserialize cleanly to `None`.
- **`Option<PermissionLevel>` on `StageProjection`** follows the same
pattern as `provider_used` — agent stages populate it, non-agent stages
leave it `None`. No migration required.
- **`AgentSessionActivatedProps` is now a progenitor type replacement**
so the API crate and the canonical type stay in sync (verified by the
new `agent_session_activated_props_round_trip` test).

### Plan Summary

- `fabro-agent` `config.rs` / `session.rs` — store and expose
`permission_level` on `SessionOptions`
- `fabro-types` `run_event/agent.rs` — add field to
`AgentSessionActivatedProps`
- `fabro-types` `run_projection.rs` — add field to `StageProjection`
- `fabro-workflow` `api.rs` / `activation_lease.rs` / `convert.rs` /
`events.rs` — thread the value to the emission site
- `fabro-store` `run_state.rs` — fold into projection on
`AgentSessionActivated`, plus new unit test
- OpenAPI schema, `fabro-api` build.rs, TS client — all
regenerated/updated

## Sortable Run Columns

`repo`, `title`, `workflow`, and `changes` columns were rendered as
plain `<th>` elements with no sort affordance. They now use `SortHeader`
in the frontend, the server-side `RunsSortKey` enum gains the four
variants, and the OpenAPI `ListRunsSortEnum` and TS client enum are
extended to match.

Sort helpers (`run_repo_key`, `run_title_key`, `run_workflow_key`,
`run_changes_total`) normalize to lowercase strings / integer totals and
compose with the existing stable ULID tiebreak.


### Fabro Details

<details>
<summary>Ran 9 stages in 53m 42s for $18.48</summary>

| Stage | Duration | Cost | Retries |
|---|---|---|---|
| start | 0s | – | 0 |
| toolchain | 1s | – | 0 |
| preflight_compile | 2m 14s | – | 0 |
| preflight_lint | 2m 29s | – | 0 |
| implement | 20m 37s | $11.87 | 0 |
| simplify_opus | 8m 0s | $3.61 | 0 |
| simplify_gpt | 5m 11s | $2.50 | 0 |
| verify | 4m 48s | – | 0 |
| fixup | 9m 56s | $0.50 | 0 |
| **Total** | **53m 42s** | **$18.48** | **0** |

</details>

<details>
<summary>Ran <code>ImplementPlan.fabro</code> (11 nodes and 14
edges)</summary>

```dot
digraph ImplementPlan {
    graph [
        goal="Implement and simplify",
        model_stylesheet="
            * { model: claude-opus-4-7; }
        "
    ]
    rankdir=LR

    start [shape=Mdiamond, label="Start"]
    exit  [shape=Msquare, label="Exit"]

    toolchain         [label="Toolchain", shape=parallelogram, script="command -v cargo >/dev/null || { curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && sudo ln -sf $HOME/.cargo/bin/* /usr/local/bin/; }; cargo --version 2>&1", max_retries=0]
    preflight_compile [label="Preflight Compile", shape=parallelogram, script="cargo check -q --workspace 2>&1", max_retries=0]
    preflight_lint    [label="Preflight Lint", shape=parallelogram, script="cargo +nightly-2026-04-14 clippy -q --workspace --all-targets -- -D warnings 2>&1", max_retries=0]
    fix_lints         [label="Fix Lints", prompt="The preflight lint step failed. Read the build output from context and fix all clippy lint warnings.", max_visits=3]
    implement         [label="Implement", prompt="Read the plan file referenced in the goal and implement every step. Make all the code changes described in the plan. Use red/green TDD.", model="gpt-55", reasoning_effort="xhigh"]
    simplify_opus     [label="Simplify (Opus)", prompt="@prompts/simplify.md"]
    simplify_gpt      [label="Simplify (GPT-55)", prompt="@prompts/simplify.md", model="gpt-55"]
    verify            [label="Verify", shape=parallelogram, script="git fetch origin main 2>&1 && git merge --no-edit --no-stat origin/main 2>&1 && cargo +nightly-2026-04-14 fmt --all 2>&1 && cargo dev docs refresh 2>&1 && cargo +nightly-2026-04-14 fmt --check --all 2>&1 && ! rg -n 'AuthMode::Disabled|RunAuthMethod|RunSubjectProvenance|\bActorRef\b|\bActorKind\b|AuthenticatedSubject|AuthenticatedService|AuthorizeRunScoped|AuthorizeRunBlob|AuthorizeStageArtifact|AuthorizeCommandLog|auth_method\s*==\s*\"disabled\"' lib/crates apps lib/packages docs/public/api-reference/fabro-api.yaml 2>&1 && cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings 2>&1 && cargo nextest run --workspace --status-level slow --profile ci 2>&1 && cargo dev docs check 2>&1 && bun install --frozen-lockfile 2>&1 && (cd apps/fabro-web && bun run typecheck) 2>&1 && (cd apps/fabro-web && bun run test) 2>&1 && (cd lib/packages/fabro-api-client && bun run typecheck) 2>&1 && cargo dev build -- -p fabro-cli --release 2>&1", goal_gate=true, retry_target="fixup"]
    fixup             [label="Fixup", prompt="The verify step failed. Read the build output from context and fix all format, clippy, Rust test, docs, TypeScript typecheck/test, and build failures.", max_visits=3]

    start -> toolchain
    toolchain -> preflight_compile [condition="outcome=succeeded"]
    toolchain -> exit
    preflight_compile -> preflight_lint [condition="outcome=succeeded"]
    preflight_compile -> exit
    preflight_lint -> implement [condition="outcome=succeeded"]
    preflight_lint -> fix_lints
    fix_lints -> preflight_lint
    implement -> simplify_opus -> simplify_gpt -> verify
    verify -> exit  [condition="outcome=succeeded"]
    verify -> fixup
    fixup -> verify
}

```

</details>

⚒️ Generated with [Fabro](https://fabro.sh)

---------

Co-authored-by: Fabro <noreply@fabro.sh>
Co-authored-by: fabro-bot <fabro-bot@fabro.sh>
Co-authored-by: Bryan Helmkamp <bryan@brynary.com>
2026-05-23 19:41:01 -04:00
..
client-sdks.mdx docs: move published docs under docs/public 2026-04-26 21:19:46 -04:00
demo-mode.mdx feat(api): bind sessions to runs (#336) 2026-05-21 10:53:41 -04:00
fabro-api.yaml Expose PermissionLevel on StageProjection and add sortable run columns (#373) 2026-05-23 19:41:01 -04:00
overview.mdx docs: move published docs under docs/public 2026-04-26 21:19:46 -04:00