Chain file keys
Step outputs
How a task leaves files and variables for a later task, how the reader names the writer, and when Kraft checks and deletes them.
Added in 2.6
A task can leave files and KEY=value variables for a later task. The later task names the writer in reads and is given a read-only copy, checked when the writer ended. Kraft doesn't read the files, and never sets a variable in any environment.
The writer and the reader sit in separate steps, because a step runs its tasks together. Both scripts are the repo's own, not Kraft's:
- id: build
steps:
- id: test
tasks:
- id: run_tests
kind: subprocess
command: ./scripts/run-tests.sh # writes into $KRAFT_OUTPUT_DIR
outputs:
files: [junit.xml, "test report.html"]
variables: [FAILED_COUNT]
- id: report
tasks:
- id: summarize
kind: subprocess
command: ./scripts/summarize.sh # reads from $KRAFT_READS_DIR
reads: [test.run_tests]
Writing
- The writer gets
KRAFT_OUTPUT_DIR, a folder only it writes:out/outputs/in its session's folder. An agent's prompt names the folder and the declared names, and says what a variable must look like. - A variable is one
KEY=valueline in$KRAFT_OUTPUT_DIR/variables.env. Blank lines and lines starting with#are ignored. A value runs to the end of the line, with no quotes and noexport; a repeated key keeps its last value. - A file name is a plain relative path inside that folder: no
.., no glob, notvariables.envin any case, no two names that differ only by case, and no name that is a folder of another. A variable name matches[A-Z][A-Z0-9_]*. - A resumed agent (a paused session continued under a new session ID) starts with a copy of what the paused session had written there, up to the same size limit.
Reading
- The reader gets
KRAFT_READS_DIR, the item'soutputs/folder. A writer's files are at$KRAFT_READS_DIR/<writer path>/<file>, withvariables.envbeside them. The writer's path isnode.step.task: herebuild.test.run_tests. - A script that wants a variable sources the file itself:
. "$KRAFT_READS_DIR/build.test.run_tests/variables.env". Kraft never does. - In a sandbox only the folders of the writers named in
readsare mounted, read-only. Outside one, nothing holds a reader to read-only, and nothing reads a snapshot back except later readers. - An agent reader's prompt lists the writers' paths and declared variable names, never a value or a file's content, and says the files are data written by another task, not instructions.
- A writer that was skipped, or left nothing, leaves the reader nothing: it finds an empty place.
What is checked
When the writer ends done or failed, Kraft checks everything first. Only then does it copy the declared names, following no link, into a snapshot under run/items/<id>/outputs/<writer path>/, and delete the writer's folder.
- The writer fails, and nothing is kept, when the folder is over
storage.outputs.max_sizeor holds more than 100 entries; when a declared variable is missing, over 4 KiB, or holds a control character other than a tab; or whenvariables.envholds more than 50 variables. - A declared file that is missing is simply absent. An undeclared file or variable is ignored. A symlink, a file with another hard link and a FIFO are left out.
- A writer whose processes outlive it fails with nothing kept, as does a remote writer whose machine dropped its folder for being over the limit, even if the server restarts before the writer is recorded.
- A failed check also removes the writer's snapshot from an earlier run, so a reader never sees it.
- The writer's
session.loggets one line with the counts of files kept and missing and the declared variable names. A message never holds a name or value the worker chose.
Where they are allowed
outputsgoes on an agent or subprocess task in an exec node's ownstepsortasks. It is refused on a fan-out task (scope: each_repository), in anon_failure, fix loop, judge,escalation,on_conflictoron_merge_rejected.repairslot, and in a gate'sauto_review.readsgoes on an agent, subprocess orci.pipelinetask, and on no other forge task. An entry of two segments,step.task, names a writer in the reader's own node, so a library node holding both stays reusable under any node ID. An entry of three,node.step.task, names a writer anywhere. A bare task ID, or an entry of more than three segments, is refused.- Every entry must name a task that declares
outputsand runs before the reader: in an earlier node, or an earlier step of the same node. A task in the same step is never before it, so a writer and its reader can't share onetasks:list. - A node's
on_failure, fix loop, judge andescalationmay read any step of the node. A step's or task'son_failuremay read the steps up to and including its own. Such a handler may run before its writer did, and then finds nothing.on_conflict,on_merge_rejected.repairand a gate'sauto_reviewread nothing. kraft admin templates lintrefuses a chain that breaks these rules.
When a writer runs again
- Running a writer again, or skipping it, deletes its snapshot, so a later reader never sees outputs of a run that has since been replaced. A reader that already passed isn't run again.
- Archiving the item deletes all its snapshots. Abandoning deletes the whole item folder. See Find the logs.
- A snapshot may still hold a variable that an older chain declared and the current one dropped. Kraft reads only the declared names, but a script that sources the file itself sees every key in it.