impl-tool:workflow
impl-tool:workflow@0.0.0
workflowRequest
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
issue | string | Yes | Id of the issue to work, as its queue entry states it; the working branch and the workspace are named from it | |
issueUuid | string | No | "" | Uuid the queue entry carries for the issue, which the records a run files are attributed to; empty where the entry has none |
title | string | Yes | Title of the issue, from its queue entry; the session's prompt states it and the pull request opens under it. Empty for a preparation that opens no session | |
prompt | string | Yes | Text of the issue from its queue entry, given to the session as its task; empty for a preparation that opens no session | |
path | path | Yes | Directory the run was asked to act on; the checkout the issue is worked in is derived from the repository it belongs to | |
repoName | string | No | Name the remote repository is created under when the directory has no remote, and the name the issue's folder is built from; absent takes the repository's own name | |
model | string | No | Model the session runs on; absent leaves the choice to the agent | |
provider | string | No | "" | Agent the session runs on; empty is the default agent |
descriptionProvider | string | No | "" | Agent the pull request descriptions are written on; empty is the session's agent |
descriptionModel | string | No | "" | Model the description agent runs; empty is that agent's own default |
createPullRequest | boolean | No | false | Whether pull requests are opened after pushing where none exist yet, for the branch and the submodules it modified; existing pull requests are refreshed either way |
headless | boolean | No | false | Whether the session runs as one non-interactive turn instead of an interactive session |
continueSession | boolean | No | false | Whether the most recent agent session is continued instead of a new one started |
skipSubmodulePullRequests | boolean | No | false | Whether opening pull requests for modified submodules is skipped |
pullRequestTemplatePath | path | No | Pull request template the bodies are written to, in place of the one the config names; a relative path resolves against path | |
branch | string | No | Branch to work and push on, taken literally; absent is impl-tool/<issue>. The workspace is named for the issue either way | |
base | string | No | "" | Branch pull requests are opened relative to; empty is the checkout's configured default branch. Nothing is reset to it |
seed | string | No | "" | Branch whose tip the working branch is reset to before the run; empty resets nothing |
skipChecks | boolean | No | false | Whether the session is told to skip the verification gate and the tests and to keep its iterations short |
skipDescribeOnPush | boolean | No | false | Whether the push made after each turn writes no pull request description |
releaseStage | enum one of dev, prod | No | "dev" | Stage the work is at, as resolved for the run from --release-stage and the repository's settings; the session's prompt states it |
autonomy | integer | No | 1 | How much the session decides without asking, from 1 to 5, as resolved for the run from --autonomy and then the config; the session's prompt states what the level means |
observe | boolean | No | false | Whether the main checkout's observer branch is pointed at this issue and kept following it |
observerPointing
finishResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
pullRequestUrl | uri | No | Link to the branch's pull request in the repository the call acted on; absent where it has none | |
created | boolean | No | false | True where this call opened that pull request; false where one was already open or none was opened |
lines | list[string] | No | [] | The branch as rendered text, one line each: the repository with its pull request and head commit, and beneath it the submodules the branch moved |
standing | list[string] | No | [] | One rendered line for each repository whose pull request this call did not simply write to: one already merged or closed and left alone, or one that merged and whose branch has committed since |
warnings | list[string] | No | [] | What a repository left out of the call still holds that its branch can no longer carry, and a pin still owed where a branch changed nothing but pins, one line each |
storedPush
prepared
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workdir | path | Yes | Checkout the issue is worked in: its worktree under the workspaces root, or the directory itself where the work is done in place | |
branch | string | Yes | Branch checked out there for the run | |
launchSha | string | Yes | Commit the branch stood at once it was prepared, before the session made any | |
remoteUrl | string | Yes | What the checkout's remote is fetched from and pushed to, as git records it and read before pushing was disabled: a url, an address such as git@host:path, or the path of a repository on this machine | |
storedPush | string | Yes | Push URL the remote had before the run disabled pushing, which the restore puts back | |
submodulePushes | list[storedPush] | No | [] | Push URL each submodule's remote had before the run disabled pushing, one entry per submodule; empty where pushing was left enabled |
sessionCommand | command | Yes | Command the agent session is started with | |
runnerStale | string | No | "" | What a self-update that failed left the run executing: the commit in use against the one its checkout holds. Empty where the update succeeded, was skipped or was not asked for |
toolRootState
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | No | "" | Directory of the issue's own tool root; empty where it was not looked for |
present | boolean | No | false | Whether that directory exists |
orphaned | boolean | No | false | True where the root exists and the source it was installed from does not, so its executable points at a directory that is gone |
notLookedFor | string | No | "" | Why the root was not looked for; empty when it was |
notOwed | string | No | "" | Why the issue was never given a tool root, where none exists and its repository holds none of impl-tool's source; empty otherwise |
issueDirectory
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | Where the directory is: inside the issue's folder under the workspaces root, or beside that folder under a name carrying the issue's id | |
kind | enum one of worktree, source, tools, earlierClone, unknown | Yes | What the directory is to the issue: worktree where it is edited, source for the tool's exported source, tools for the tool root installed from it, earlierClone for a clone an older layout installed from, and unknown for a directory impl-tool did not make | |
detail | string | No | "" | What is known beyond the kind: where and at which commit a source was exported, or whether an unknown directory is a checkout. Empty for a worktree and a tool root |
sourceExport
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
checkout | string | Yes | Absolute path of the checkout the source was exported from, and is exported from again to bring it up to date | |
commit | string | Yes | Full sha of the commit the export holds | |
toolRoot | string | No | "" | Tool root installed from this export; empty for the machine's own |
files | list[string] | No | [] | Every file the commit put in the export, as paths relative to it, sorted; the next export removes those its commit no longer tracks |
issuePrepared
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
issue | string | No | "" | Id of the issue prepared for |
workdir | string | No | "" | Worktree the issue is edited in |
branch | string | No | "" | Branch checked out in that worktree |
source | string | No | "" | Directory the tool's source is exported into for this issue; empty where the issue has none |
toolRoot | string | No | "" | Tool root the issue's executable is installed under; empty where the issue has none |
executable | string | No | "" | Path of the executable the issue's runs are launched with; empty where none was installed |
executableOk | boolean | No | false | Whether that executable starts |
installed | boolean | No | false | True where this preparation installed the executable, or reinstalled it |
alreadyCurrent | boolean | No | false | True where a working install was already standing and was left as it was |
skippedInstall | boolean | No | false | True where the preparation was asked to install nothing |
noSource | string | No | "" | Why nothing was exported or installed where no workspacesRoot is configured; empty otherwise |
noPackage | string | No | "" | Why the issue gets no executable of its own where its repository holds none of impl-tool's source; empty otherwise |
blocked | string | No | "" | Why the install was refused; empty where it was not |
blockedByTheCheckout | boolean | No | false | Which refusal blocked is: true where a trial install made from the source did not start, false where a running process holds the environment |
keptUncommitted | list[uncommittedWork] | No | [] | Uncommitted work the worktree already held and the preparation kept because it was asked to, one entry per repository; empty on a clean worktree and on a first preparation |
keptNotes | list[string] | No | [] | Issue notes kept as they were edited in the worktree instead of refreshed from the queue; deleting one takes the queue's version at the next preparation |
uncommittedWork
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
scope | string | Yes | . for the top-level repository, otherwise the submodule's path within it | |
paths | list[string] | No | [] | Changed paths of that repository alone; a submodule's changes are reported under its own scope and never as a path of its parent |
behind | boolean | No | false | True where a submodule's checkout is behind the commit its parent records; kept work is never aligned, so it stays behind until the work is committed or discarded and the preparation is run again |
closeResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
state | sessionState | No | Session record as it stood when the close began; absent where no session was open | |
finish | finishResult | No | {} | What finishing the branch produced: its pull request and tree where the session made changes, and only where the pull requests stand where it made none |
callTimings | list[timingEntry] | No | [] | Timing of each model call the close made |
modelRuns | list[modelRunSummary] | No | [] | Model calls recorded for the repository across every session, summarised per model and priced; rows are ordered as the modelTableSort config key asks |
sessionModelRuns | list[modelRunSummary] | No | [] | The same summary, restricted to the calls made since this session started |
ended | boolean | No | false | True where the close marked the session as ended; false where an error left it open or no session was open |
reached | integer | No | 0 | Highest increment number the branch carries, counted across every session that worked it |
increments | integer | No | 0 | Count of increments made during this session |
seconds | number | No | 0.0 | Seconds since the session started; 0 where there is no session or its start time cannot be read |
error | string | No | "" | Why the close-out failed or the model summaries could not be built; empty on success |
location
alignment
derivedMessage
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
summary | string | Yes | Middle of the submodule commit's title, without the issue id and the increment number | |
body | string | Yes | Commit body with its trailers removed | |
coauthors | list[string] | No | [] | Co-Authored-By: trailer lines the commit carried |
increment | integer | Yes | Increment number the commit's title carries |
resolvedMessage
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
summary | string | Yes | Middle of the commit title the ship uses: the one given, else a moved submodule commit's, else the title of the session's issue | |
body | string | Yes | Commit body the ship uses: the one given, else a moved submodule commit's, else the prompt of the session's issue | |
increment | integer | No | Increment number given, or the one a moved submodule's commit carries; absent where neither supplied one and the branch's next number is used. Numbering starts at 0 | |
coauthors | list[string] | No | [] | Co-Authored-By: trailer lines of the submodule commit the summary was read off; empty where the summary was given |
derived | boolean | No | false | True where the summary was read off a moved submodule's commit instead of given |
checkout
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
scope | string | Yes | . for the branch's own repository, otherwise the submodule's path within it | |
workdir | path | Yes | Directory of that repository's checkout | |
repo | string | No | Repository the checkout pushes to, as owner/name; absent where it has no remote | |
pullRequest | string | Yes | Link to the repository's pull request for the branch; empty where it has none |
pushResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
sections | list[followUpStateSection] | No | [] | Local follow-up state of each repository the push covered, the branch's own repository first |
updated | list[string] | No | [] | Scopes whose pull request body was rewritten, or would be on a dry run |
problems | list[string] | No | [] | What the pre-merge check would refuse about the sections, one line per item, each naming its scope; non-empty means nothing was published |
error | string | No | "" | Why the push stopped or published nothing; empty on success |
checkoutWork
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | . for the checkout the scan was pointed at, otherwise the submodule's path within it | |
state | enum one of clean, holding, missing, stale, unreadable | Yes | What the checkout holds that nothing outside it does: clean for nothing, holding for uncommitted changes or unpushed commits, stale for commits whose patches are all upstream already under other shas, missing for no checkout at the path, and unreadable where git refused | |
root | string | No | "" | Tree the row was found in, which tells rows apart when more than one tree is walked |
repo | string | No | "" | Name of the repository the checkout is of, read from its remote, so every checkout of one repository answers the same; empty where there is no checkout to ask |
branch | string | No | "" | Branch the checkout is on; empty where it has no commits yet |
uncommitted | list[string] | No | [] | Sample of the changed paths no commit holds, capped; uncommittedCount counts them all |
uncommittedCount | integer | No | 0 | Count of every uncommitted path found, not only the sample |
unpushed | list[string] | No | [] | Sample of the commits reachable from HEAD that no remote holds in any form, each as its short sha, its subject and the refs pointing at it; these are what deleting the checkout would lose |
unpushedCount | integer | No | 0 | Count of every such commit found, not only the sample |
superseded | list[string] | No | [] | Sample of the commits reachable from HEAD that no remote contains but whose patch is already upstream under another sha, as a rebase or a merge leaves them |
supersededCount | integer | No | 0 | Count of every such duplicate commit found, not only the sample |
comparedAgainst | list[string] | No | [] | Remote-tracking refs the commits were compared against for an equivalent patch: the branch's own remote copy and the branch it lands on. Empty means there was nothing to compare against, not that nothing is a duplicate |
localOnly | list[string] | No | [] | Sample of the commits no remote holds and HEAD does not reach, held by other local branches; reported and never counted into state, since every checkout of the repository shares them |
localOnlyCount | integer | No | 0 | Count of every such commit found, not only the sample |
localOnlySuperseded | list[string] | No | [] | Sample of the localOnly commits whose patch is already upstream, which the refs holding them can be deleted for |
localOnlySupersededCount | integer | No | 0 | Count of every such commit found, not only the sample |
detail | string | No | "" | What needs saying beyond the state: what git refused, why a checkout is missing, or that no remote is configured |
scanResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workdir | path | Yes | Checkout the scan was pointed at; the first tree walked where it walked several | |
checkouts | list[checkoutWork] | No | [] | One row per checkout walked: each tree's own checkout first, then its submodules |
error | string | No | "" | Why the walk never started or stopped early; empty otherwise |
submoduleAlignment
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | Path of the submodule within the superproject | |
state | enum one of aligned, moved, ahead, dirty, diverged, missing, shared | Yes | Where the checkout stood: aligned already on the branch at its pin, moved taken there, ahead on the branch with commits the superproject has not recorded, dirty left alone over uncommitted changes, diverged where git refused the move, missing where there is no checkout or no pin, and shared where another path already holds the same repository | |
pin | string | No | "" | Commit the superproject records at this path; empty where it was not read |
detail | string | No | "" | Why the submodule was not simply aligned; empty for aligned and moved |
syncResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workdir | path | Yes | Superproject checkout whose submodules were aligned | |
branch | string | No | "" | Branch the superproject is on, which every submodule is put on; empty where it could not be read |
submodules | list[submoduleAlignment] | No | [] | One entry per submodule, shallowest first |
error | string | No | "" | Why the alignment never started; empty otherwise |
pinMove
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | string | Yes | Path of the submodule within the superproject | |
state | enum one of moved, current, unmerged, nested, blocked, missing | Yes | What moving the pin came to: moved where it was taken to the merged work and staged, current where it already stood there, unmerged where the pull request has not merged, nested for a submodule of a submodule, blocked where git could not or would not take the checkout there, and missing where there is no checkout | |
pinned | string | No | "" | Commit the superproject's HEAD records at this path, read before any move; empty where it was not read |
merged | string | No | "" | Commit the pin moves to or moved to, the tip of the base branch; empty where none was found |
pullRequest | string | No | "" | Link to the pull request whose merge the move records; empty where the submodule has none |
detail | string | No | "" | Why the pin was not moved; empty for moved and current |
pinResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workdir | path | Yes | Superproject checkout whose pins were moved | |
branch | string | No | "" | Branch whose pins were moved; empty where it could not be read |
submodules | list[pinMove] | No | [] | One entry per submodule the branch moved, shallowest first |
commit | string | No | "" | Sha of the superproject commit that recorded the moves; empty where none was made, because nothing moved or no commit was asked for |
subject | string | No | "" | Subject of that commit, or of the one that could not be made; empty where none was attempted |
error | string | No | "" | Why the pins were not moved or the moves were not committed; empty otherwise |
openResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
branch | string | No | "" | Branch whose pull requests were opened |
issue | string | No | "" | Id of the issue the branch works; empty where it could not be told |
finish | finishResult | No | {} | What finishing the branch produced: its pull request, whether this call opened it, and the branch as rendered text |
callTimings | list[timingEntry] | No | [] | Timing of each model call made while opening and describing the pull requests |
error | string | No | "" | Why the pull requests could not be opened; empty on success |
runReport
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
exitCode | integer | No | 0 | Exit code of the run: 0 where it completed, 1 where git or the model provider failed |
callTimings | list[timingEntry] | No | [] | Timing of each model call the run itself made while wrapping the session up |
modelRuns | list[modelRunSummary] | No | [] | Model calls recorded for the repository across every session, summarised per model and priced; empty where the run happened inside another session, which reports the record itself |
sessionModelRuns | list[modelRunSummary] | No | [] | The same summary, restricted to the calls made since this run started |
workdir | path | No | Checkout the run acted in, which can be another directory than the one it was asked from; absent where the run failed | |
runnerStale | string | No | "" | What a self-update that failed left the run executing: the commit in use against the one its checkout holds. Empty where the update succeeded, was skipped or was not asked for |
shipRequest
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
path | path | Yes | Directory the ship was asked to act on; the checkout holding the issue's work is resolved from it | |
summary | string | No | "" | What the increment did, as the middle of the commit title; empty takes the summary a moved submodule's commit carries, then the title of the session's issue |
body | string | No | "" | Commit body, wrapped to 72 columns when it is committed; empty takes the body a moved submodule's commit carries, then the prompt of the session's issue |
increment | integer | No | Increment number to commit under; absent takes the number a moved submodule's commit carries, then the next one the branch has not spent | |
workspacesRoot | path | No | Directory the issue's folder is looked for under, as the workspacesRoot config key states it; absent ships from the directory itself | |
dryRun | boolean | No | false | Whether the ship only reports what it would commit and push, changing nothing |
pullRequestTemplatePath | path | No | Pull request template a rewritten body is conformed to; a relative path resolves against the checkout, and absent uses the packaged template |
shipCommit
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
committed | list[string] | No | [] | Paths of the submodules whose uncommitted work this ship committed, deepest first |
pushed | list[string] | No | [] | Paths of the submodules whose work was committed already and which this ship pushed |
superprojectSha | string | No | "" | Sha of the commit made in the top-level repository; empty where none was made |
nothingToCommit | boolean | No | false | True where the tree turned out to hold nothing to commit, so no commit was made |
error | string | No | "" | What stopped the commits partway; committed and pushed still name what went through before it. Empty on success |
shipPush
shipRefresh
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
refreshed | list[string] | No | [] | Repositories whose pull request body was rewritten to match what was pushed: submodule paths, and . for the top-level repository |
unopened | list[string] | No | [] | Repositories whose branch carries commits and has no pull request, named the same way |
stranded | list[string] | No | [] | Repositories whose pull request merged while the issue was still being worked and whose branch has committed since, so that work has no pull request; named as submodule paths, and . for the top-level repository |
shipFinish
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
push | shipPush | No | {} | What pushing the already-committed work reached; empty on a dry run |
refresh | shipRefresh | No | {} | Which pull request bodies were rewritten, and which repositories have no pull request to rewrite |
shipResult
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
issue | string | No | "" | Id of the issue the branch works |
title | string | No | "" | Whole title of the commit made: the issue id, the summary and the increment number; empty where no commit was made |
increment | integer | No | 0 | Increment number the commit carries, counted from 0; also 0 where no commit was made, which title tells apart |
committed | list[string] | No | [] | Paths of the submodules whose uncommitted work this ship committed, deepest first |
pushed | list[string] | No | [] | Checkouts whose already-committed work this ship pushed: submodule paths, and . for the top-level repository |
superprojectSha | string | No | "" | Sha of the commit made in the top-level repository; empty where none was made |
message | string | No | "" | Whole commit message as committed: the title, the wrapped body and the trailers; empty where no commit was made |
toolSource | string | No | "" | Directory holding the issue's exported tool source, which install is pointed at after a ship; empty where the issue has none |
toolRoot | string | No | "" | Tools directory an install from that source is placed under; empty where the issue has none |
nothingToCommit | boolean | No | false | True where the tree held nothing to commit; work committed already is still pushed |
leftUncommitted | list[string] | No | [] | What a ship given no summary found changed and left alone, having no title to commit it under: submodule paths, and . for the top-level repository's own files |
refreshed | list[string] | No | [] | Repositories whose pull request body was rewritten to match what was pushed: submodule paths, and . for the top-level repository |
unopened | list[string] | No | [] | Repositories this ship pushed a branch to that still have no pull request, named the same way |
stranded | list[string] | No | [] | Repositories whose pull request merged while the issue was still being worked and whose branch has committed since, so that work has no pull request; named as submodule paths, and . for the top-level repository |
workdir | string | No | "" | Checkout the ship acted in |
moved | boolean | No | false | True where that is a different directory from the one the ship was asked from |
error | string | No | "" | What stopped the ship; the other fields still report what reached the remotes before it. Empty on success |