impl-tool session start

Record the issue being worked, and start its increment count

Command version
0.0.0
Command configuration
impl-tool:impl-tool.session.start@0.0.0

Arguments

ArgumentTypeRequiredDefaultDescription
--issueissueRunConfigYesThe issue to work, as its queue entry: its id, title and prompt. Where the complex input source type is filepath, the path of the entry's file, or the issue's bare id where exactly one entry in the queue is filed under it; otherwise the entry itself, inline
--modelstringNoModel to run the session on. Without it, a model argDefaults names for this command in cli.config.yml, and otherwise the session command's own default
--providerstringNo""Agent the session runs on -- one that can host an interactive session. Its settings are the sessionProviderOptions config key. Empty is the default agent; an agent that does not exist, or hosts no session, is refused by name
--description-providerstringNo""Agent the pull request descriptions are written on, for the run's pushes and its wrap-up. Its settings are the prDescriptionProviderOptions config key. Empty is the session's agent
--description-modelstringNo""Model the description agent runs. Empty is the model that agent offers for a one-off call
--branchstringNoBranch to work and push on, taken literally -- for sessions whose commits must stay off the issue's own branch. Defaults to impl-tool/<issue>, created off the target directory's current tip when the issue has never run. The workspace worktree keeps the issue's name either way
--basestringNoBranch pull requests are opened relative to (the checkout's configured default branch when not given). Purely about where the pull request points -- it never resets anything; that is --seed's job, and the two combine freely (based off X, seeded off Y)
--seedstringNoBranch whose tip the working branch is reset to before the run -- stage the state you want on the seed branch and every run starts exactly there. The working branch's push may then rewrite its remote copy (force-with-lease). Without it nothing is ever reset
--create-pull-request,
--no-create-pull-request
booleanNofalseLet the session's commits open pull requests where none exist yet, for the branch and its modified submodules
--skip-checks,
--no-skip-checks
booleanNofalseTell the session to skip the verification gate and the test suite, and to keep iterations short
--continue-session,
--no-continue-session
booleanNofalseContinue the most recent agent session instead of starting fresh
--skip-submodule-pull-requests,
--no-skip-submodule-pull-requests
booleanNofalseSkip creating pull requests for modified submodules during the session; existing ones are still refreshed
--repo-namestringNoName the remote repository is created under when the directory has no remote (default: the directory's name)
--pull-request-template-pathpathNoPath to a custom PR template for the session's pull requests (overrides the config file setting)
--skip-describe-on-push,
--no-skip-describe-on-push
booleanNofalseLeave pull request descriptions alone on every push and write them once when the session ends, saving one model call per repository per iteration. Without it the skipDescribingOnPush config key decides, and by default descriptions are written
--end-session-on-close,
--no-end-session-on-close
booleanNofalseRun session end the moment the session finishes -- close out the branch, describe it, and stamp the session closed, without a second command. Combines with --headless, which finishes when its turn does
--headless,
--no-headless
booleanNofalseRun the issue in one non-interactive turn instead of opening an interactive session. The branch is prepared and the session recorded either way, and ending is session end's either way
--pathpathNo"."Directory to act on (default: current directory)
--reset-increment,
--no-reset-increment
booleanNofalseStart the count fresh rather than continuing from where the last session left it. A standing answer is a resetIncrement entry under the command's argDefaults in cli.config.yml; without either the count continues
--incrementintegerNoThe count to start from; the session's next commit takes the one after it. Defaults to the sessionStartIncrement config key
--release-stageenum one of dev, prodNoThe stage the work is at, which sets what a backwards-incompatible change may be -- dev allows one without a shim and has it named, prod requires a feature flag or a contract-version bump. Recorded with the session, so ending it describes under the same stage (overrides the manifest's releaseStage and the releaseStage config key)
--autonomyintegerNoHow much the session decides without asking, from 1 (asks about anything uncertain) to 5 (asks only before an irreversible or outward-facing act); overrides the autonomy config key
--observe,
--no-observe
booleanNofalsePoint the main checkout's observer branch at this issue and keep it there -- a branch named for the bare issue id, created in the superproject and every submodule and advanced on every later run of this issue. Asked for once; a standing answer is an observe entry under the command's argDefaults in cli.config.yml, and by default the main checkout is left alone

It also takes the global arguments.

Output

It answers with a start.sessionStartSummary.

Examples

impl-tool session start --issue .plan-tool/PROJ-0000123-add-login.yml

Record the issue a queue entry describes as the one being worked here, continuing its increment count.

impl-tool session start --issue PROJ-0000123 --reset-increment

Record it and start the increment count again from nought.

Errors

CodeMeaningRemedy
TARGET_PATH_NOT_DIRECTORYThe path --path names is not a directory.Pass --path naming the checkout to act on, or leave it out to act on the current directory.
AUTONOMY_INVALIDThe autonomy level given is not one the runner knows.Give a level the message lists, a whole number from 1 to 5.
ISSUE_FORMAT_INVALIDThe issue id does not match the format the configuration's issueFormat requires.Give the issue id as issueFormat spells one, such as CMD-0000002.
SESSION_START_FAILEDThe issue's branch could not be prepared, so no session was started; the message carries the failure.Repair what the message names and run session start again.
SESSION_ENDED_EARLYThe session's provider did not start, or the session was interrupted before it finished.Run session start again; where the provider failed, repair what the message names first.
SESSION_CLOSE_OUT_FAILEDClosing the session out -- committing what it left, shipping and describing the increment -- failed; the message names the step.Repair what the message names and run session end in the workspace to close it out again.
Also every code of cli:cli
CodeMeaningRemedy
REPO_ROOT_VALIDATION_FAILEDThe repository root the run was given, by --repo-root or by the directory it was started in, is not a directory that can be acted on.Run the command from inside the repository, or pass --repo-root naming its root.
RUNTIME_CONFIG_FAILEDA runtime configuration file the run reads -- the application's cli.config.yml at one of its scopes -- does not load, or sets an argument default a scope may not set.Correct the file the message names; config init writes one that loads.
COMMAND_CONFIG_FAILEDThe configuration the command itself is declared by does not load, so the command cannot be run. This is a fault in the application as it was built, not in anything the person running it supplied.Report it against the application's release, with the message; reinstalling the release with update --force replaces a damaged copy.
MANIFEST_VALIDATION_FAILEDThe command reads the repository's manifest.yml, and none was found at the root, or the one found does not load.Run the command in a repository that has a manifest, pass --manifest naming one, or correct the manifest where the message says it does not load.
APP_CONFIG_FAILEDThe application's own configuration file in the repository does not load against the type the application declares for it.Correct the file the message names; config init writes one that loads.
INPUT_VALIDATION_FAILEDAn argument the command line gave is not one the command accepts once it is read -- the wrong type, a value outside its choices, or one a rule on the input refuses.Give the argument as the command's --help describes it.
OUTPUT_VALIDATION_FAILEDThe command answered with data that does not match the output it declares, so the answer was withheld. This is a fault in the command, not in how it was run.Report it against the application's release, with the command line that produced it.
PIPE_STDIN_NOT_PIPEDThe command was asked to take its input from stdin, by --from-stdin or by - as a document input's value, and nothing is piped to it -- stdin is a terminal, or there is none.Pipe in the output of a command run with --response-format json, or give the input another value.
SECRET_NOT_GIVENThe command takes a secret input, which is never typed on the command line, and nothing was typed at its prompt or piped to its standard input.Run the command at a terminal and type the value at the prompt, or pipe it to the command's standard input, one line for each secret it takes.
SECRET_STDIN_CLAIMEDThe command takes a secret input from standard input, and standard input already carries its piped inputs -- --from-stdin, or a document input given - -- so there is nothing to read the secret from.Run the command at a terminal to be asked for the secret, or give its other inputs on the command line.
PIPE_STDIN_CLAIMED_TWICE--from-stdin was given beside a document input given - or -:<path>, so the piped answer would be both the command's inputs and one of them.Keep one of the two forms.
PIPE_FIELD_NOT_FOUNDA document input given -:<path> names a field the piped answer does not hold -- a key no mapping on the way has, or an index past the end of a list or into something that is no list -- or the text after -: is no path.Name a field the command before the pipe answers with, as keys joined by . with [<n>] picking an item from a list, as releases[0].notes.
ENVELOPE_UNREADABLEWhat was piped to the command is not an envelope a command writes, so there is no answer in it to take as input.Run the command before the pipe with --response-format json, and pipe nothing else between the two.
PIPE_UPSTREAM_FAILEDThe command before the pipe refused, so there is no answer to take as input and this command did not run. Its own errors follow this one in the envelope.Repair what the errors after this one name, in the command before the pipe, and run the pipeline again.
PIPE_ANSWER_NOT_INPUTS--from-stdin takes the piped answer as the command's inputs by name, and the answer is no mapping, or carries a field the command declares no input for.Pipe in a command whose answer holds only this command's inputs, or give the answer to one document input with - instead.
UNHANDLED_EXCEPTIONThe command failed in a way nothing anticipated, and the message is the failure's own text.Report it against the application's release, with the command line and the message.
APPLICATION_RELEASE_NAME_UNKNOWNThe application could not tell which release it is -- the project it was released with, or which of that project's applications it is -- so it cannot look its releases up.Run the application as it was installed, from the directory toolchain install placed it in, or report it against the release.

Exit codes

CodeMeaning
0The command answered; the envelope's status is success and errors is empty.
1The command or the framework refused; the envelope's status is error and errors names each code, with its message.
2The command line could not be read -- an unknown command, a missing or unknown argument -- so nothing ran and no envelope was written; the usage is printed instead.

Types

start.sessionStartSummary

FieldTypeRequiredDefaultDescription
issuestringYesThe id of the issue the session works
titlestringYesThe issue's title, as its entry states it
incrementintegerYesThe increment number the session opened at: the highest the branch has spent, counted from zero. Below zero means none is spent yet and the next commit carries (0)
statePathstringYesPath of the session state file that was written. Empty where the branch could not be prepared
replacedbooleanYesTrue where a session was already open in the workspace and this one took its place
startedAtstringYesWhen the session opened, in local time to the second, as the session state records it. Empty where the branch could not be prepared
continuedbooleanYesTrue where the branch already carried numbered commits or a session record, so the numbering continues from them. False for a fresh branch, and with --reset-increment
launchedbooleanYesTrue where an interactive session was opened. False with --headless, which makes one headless call instead, and where the branch could not be prepared
endedOnClosebooleanNofalseTrue where the session was also ended as it closed, which --end-session-on-close asks for. The pull request, tree and table fields are filled only by that ending, and report what impl-tool session end would
pullRequeststringNo""Where the session was ended on close, the URL of the pull request for the branch. Empty otherwise, and where there is none
treelist[string]No[]Where the session was ended on close, the repository and the submodules the branch moved, drawn as a tree of text lines, each entry with its pull request and commit links
standinglist[string]No[]Where the session was ended on close, one line for each repository whose pull request the ending did not simply write to: one already merged or closed, which is left alone, and one whose pull request merged and which has committed since
warningslist[string]No[]Where the session was ended on close, what was found in a repository whose pull request has already merged or closed that its branch can no longer carry, one line each
callTimingslist[timingEntry]No[]Where the session was ended on close, one row for each timed model call the ending made: its label, how long it took, and the repository it was made for
modelTimingslist[modelTiming]No[]Where the session was ended on close, the model-call record across sessions, one row per task and model, ordered by modelTableSort
sessionModelTimingslist[modelTiming]No[]Where the session was ended on close, the same rows counted over the calls made since this session opened
checkAverageslist[checkAverage]No[]Where the session was ended on close, what each check and test run has cost over the issue and how often it passed, as the runner measured them from the commands' own records
timingslist[recordedMeasurement]No[]Where the session was ended on close, the durations the session chose to report for its own actions, each with the increment it was reported in
planWeeklyCostnumberNo0Where the session was ended on close, what the configured planMonthlyCost comes to over one seven-day window, in the same currency, which the session's model-call table prices plan usage against. 0 where no price is configured
workdirstringYesThe checkout the session ran in and its state was written in: the issue's workspace where one was made for it
movedToWorkspacebooleanNofalseTrue where the session ran in a different directory from the one the issue was launched in; the output then ends with a cd line naming workdir
branchstringYesThe branch the session works on. Empty where it could not be prepared