A step's question carries options and images, and an answer carries an option, words and task files #198

Merged

agra merged 5 commits from task/3761-s3-questions-with-options-images-and-fil into master

2026-10-31 02:02:20 +02:00

agra commented

2026-10-31 01:10:11 +02:00

Owner

Tracker: #3761

Step 3 of #3672's planspec: questions with options, images and files.

What it delivers

A step's report takes options: [{key, text, recommended?}] and images: [<path in the run's home or worktree>] with an out that leads to Needs you, and STEP_REPORT_HOW tells the agent so. Reaching Needs you, the flow run keeps the options and the image files in options and images (cleared with question), needs_you answers both, and the needs_you event records them.
The runner uploads each image through POST /api/tasks/:id/files before it closes the stream, tagged reference when the project has that tag and untagged otherwise, and the report it sends names the file ids in images. An image outside the home and the worktree (links followed), one it cannot read, or one sak refuses (415, 413) is dropped and named in the report's dropped.
POST /api/flow-runs/:id/answer takes answer, option and files, at least one of answer and option; the answer event records all three. An option the question does not offer answers 400 unknown_option, a file that is not a file of the run's task 400 foreign_file.
Migration 57 gives run_request a files column: the run request the answer queues carries the files, a run queued again keeps them, and the claim answers them. The runner fetches each through GET /api/files/:id into the home's answer/ directory as <id>.<extension>, and the re-run's prompt names them there with the option's text and the words.
queue_proposer lists the question's options and PROPOSER_HOW lets the Proposer's answer name one as option; the flow run keeps it in proposal_option, the proposal event records it, needs_you.proposal answers it, and taking the proposal answers with it. An option the question does not offer is dropped and the text kept.
The web calls /propose Suggest, and its types carry needs_you.options, needs_you.images and proposal.option.
The runner console shows an answer of an option alone by the option's key.
docs/api.md (Errors table, Flow runs, Questions, Runs) and runner/README.md (One run) describe the above; the runner ships release 0.3.13.

Tests

tests/runner_core.sx's flow-run harness (check_question_options) pins each acceptance case:

an answer by option with words and a file reaches the re-run's home (answer/<id>.png, its bytes) and prompt;
a report's image outside the home is dropped and named in dropped, and the one in the home is a file of the task tagged reference that needs_you.images shows;
a proposal naming an offered option answers it in needs_you.proposal.option, and one naming an option the question does not offer keeps only its text;
400 unknown_option and 400 foreign_file, one case each.

tests/runner_flows.sx pins the console's line for an answer of an option alone. The schema-head checks move to version 57, and the tests that take a database back to an earlier version drop run_request.files. This is new behaviour, not a regression fix, so there is no fail-before case.

Goldens

The Suggest label re-records, in one full run of playwright.config.ts (chromium, darwin), the goldens that show the Needs you actions; no other snapshot changes:

work-the-flows.spec.ts: needs-you-question (light, dark), needs-you-run-limit, needs-you-proposed-stop, needs-you-stop-proposed, flow-refused (light, dark, phone light, phone dark), needs-you-proposal (light, dark);
surfaces.spec.ts: task-asks, task-run-strip (light, dark, phone light, phone dark).

The phone scenes of needs-you-question and needs-you-proposal do not show the button and are unchanged. The design check reports 0.

Gates

sak-gate full, gate run 3, at b525f16d: passed (72 sx tests, release and step9_release, deploy contract, e2e 777 passed and 1 skipped, runner e2e 10 passed).

Tracker: [#3761](https://sak.swipelab.com/tasks/3761) Step 3 of #3672's planspec: questions with options, images and files. ## What it delivers - A step's report takes `options: [{key, text, recommended?}]` and `images: [<path in the run's home or worktree>]` with an out that leads to Needs you, and `STEP_REPORT_HOW` tells the agent so. Reaching Needs you, the flow run keeps the options and the image files in `options` and `images` (cleared with `question`), `needs_you` answers both, and the `needs_you` event records them. - The runner uploads each image through `POST /api/tasks/:id/files` before it closes the stream, tagged `reference` when the project has that tag and untagged otherwise, and the report it sends names the file ids in `images`. An image outside the home and the worktree (links followed), one it cannot read, or one sak refuses (415, 413) is dropped and named in the report's `dropped`. - `POST /api/flow-runs/:id/answer` takes `answer`, `option` and `files`, at least one of `answer` and `option`; the `answer` event records all three. An `option` the question does not offer answers `400 unknown_option`, a file that is not a file of the run's task `400 foreign_file`. - Migration 57 gives `run_request` a `files` column: the run request the answer queues carries the files, a run queued again keeps them, and the claim answers them. The runner fetches each through `GET /api/files/:id` into the home's `answer/` directory as `<id>.<extension>`, and the re-run's prompt names them there with the option's text and the words. - `queue_proposer` lists the question's options and `PROPOSER_HOW` lets the Proposer's answer name one as `option`; the flow run keeps it in `proposal_option`, the `proposal` event records it, `needs_you.proposal` answers it, and taking the proposal answers with it. An option the question does not offer is dropped and the text kept. - The web calls `/propose` Suggest, and its types carry `needs_you.options`, `needs_you.images` and `proposal.option`. - The runner console shows an answer of an option alone by the option's key. - docs/api.md (Errors table, Flow runs, Questions, Runs) and runner/README.md (One run) describe the above; the runner ships release 0.3.13. ## Tests tests/runner_core.sx's flow-run harness (`check_question_options`) pins each acceptance case: - an answer by option with words and a file reaches the re-run's home (`answer/<id>.png`, its bytes) and prompt; - a report's image outside the home is dropped and named in `dropped`, and the one in the home is a file of the task tagged `reference` that `needs_you.images` shows; - a proposal naming an offered option answers it in `needs_you.proposal.option`, and one naming an option the question does not offer keeps only its text; - `400 unknown_option` and `400 foreign_file`, one case each. tests/runner_flows.sx pins the console's line for an answer of an option alone. The schema-head checks move to version 57, and the tests that take a database back to an earlier version drop `run_request.files`. This is new behaviour, not a regression fix, so there is no fail-before case. ## Goldens The Suggest label re-records, in one full run of `playwright.config.ts` (chromium, darwin), the goldens that show the Needs you actions; no other snapshot changes: - `work-the-flows.spec.ts`: `needs-you-question` (light, dark), `needs-you-run-limit`, `needs-you-proposed-stop`, `needs-you-stop-proposed`, `flow-refused` (light, dark, phone light, phone dark), `needs-you-proposal` (light, dark); - `surfaces.spec.ts`: `task-asks`, `task-run-strip` (light, dark, phone light, phone dark). The phone scenes of `needs-you-question` and `needs-you-proposal` do not show the button and are unchanged. The design check reports 0. ## Gates - `sak-gate full`, gate run 3, at b525f16d: passed (72 sx tests, release and step9_release, deploy contract, e2e 777 passed and 1 skipped, runner e2e 10 passed).

agra added 1 commit

2026-10-31 01:10:11 +02:00

A step's question offers options and images, and an answer picks an option with words and task files dc87e02089

A step's report offers options and images with an out that leads to Needs
you; the runner uploads the images to the task and names the drops, the flow
run keeps the options and image files in needs_you, and the Proposer may pick
an option. The answer route takes answer, option and files, refusing
unknown_option and foreign_file, and the run request it queues carries the
files, which the runner fetches into the home's answer directory that the
re-run's prompt names.

agra added 4 commits

2026-10-31 01:39:03 +02:00

docs/api.md words the answer route's body as its words, an option or both, with files a6949e195d

The web calls /propose Suggest, and its types carry a question's options and images and a proposal's option aa462ecdc4

Re-records the goldens that show the Needs you actions: needs-you-question,
needs-you-run-limit, needs-you-proposal, needs-you-proposed-stop,
needs-you-stop-proposed and flow-refused in work-the-flows.spec.ts, and
task-asks and task-run-strip in surfaces.spec.ts.

release: 0.3.13 fc12bcc163

The tests that take a database back drop run_request's files, and read the schema head at 57 b525f16d3e

agra merged commit 63dd54a0df into master

2026-10-31 02:02:20 +02:00

agra referenced this pull request from a commit

2026-10-31 02:02:22 +02:00

Merge pull request 'A step's question carries options and images, and an answer carries an option, words and task files' (#198) from task/3761-s3-questions-with-options-images-and-fil into master