CommandOptions

Type, in @jr2/orchestrator/src/effect.ts. The signature of an export, or a type that it names, names this type. The Authoring surface page lists each export. This type is not an export of @jr2/orchestrator, so a workflow module does not import it by name.

type CommandOptions = {
  slot?: string;
  timeout?: Duration;
  tail?: number;
  env?: CommandEnv;
  pin?: boolean;
};

The options of command(): the Repo Slot it runs in, how long it can run, how much of its output it keeps, its Effect secrets, and the commit it runs against.

Fields

• slot (optional): string

  The Repo Slot whose Worktree is the working directory of the command. Write it only when the Workspace has more than one Repo Slot. In a Workspace with no Repo Slot, the command starts in /work, the folder that the steps of the Workspace share.

  The command starts in the root of that Worktree. To run it in a subfolder, give the path as an argument, or write ["sh", "-c", "cd <dir> && <program>"].

  When it starts, it refuses:

  • no slot under a Workspace with more than one Repo Slot: command "<slot>" runs under a Workspace carrying more than one Repo Slot (<slots>) and names none — say which Worktree it runs in: command(argv, { slot: "<slot>" }) (ADR-0051). When env names an Effect secret, the text is command "<slot>" runs under a Workspace carrying more than one Repo Slot (<slots>) — say which: { slot: "<slot>" } (ADR-0051).
  • with an Effect secret in env, a Workspace with no Repo Slot: command "<slot>" runs under a Workspace with no Repo Slot: a command with an Effect secret runs against one commit of a Repo Slot's branch, and there is none — declare a Repo Slot, or name no secret in its env, and it runs in /work beside the Agent (ADR-0051).
  • a slot that the Workspace does not have: command "<slot>" names Repo Slot "<name>", which its Workspace does not carry (<slots>).

• timeout (optional): Duration

  How long the command can run: a number and a unit, such as "90s", "10m" or "1h". Default "10m". When the time ends, jr2 kills the process group, and the output is timeout. It refuses a value that is not a positive duration: command: timeout "<timeout>" is not a positive duration (like "90s", "10m", "1h").

• tail (optional): number

  The number of characters that tail keeps from the end of what the command wrote. Default 4096.

• env (optional): CommandEnv

  The environment variables of the command, each an Effect secret. secret("x") gives the value, and secret("x").path gives the path of a file that holds the value. When env names one, the command runs in the Sandbox Effector against one commit, not in the Worktree that the Agent changes. Without env, it runs in the Harness container, beside the Agent.

  It refuses a name that is not a variable name, and PATH, HOME and TMPDIR: command(argv, { env }): "<name>" is not a variable the author sets — PATH, HOME and TMPDIR are the Effector's (ADR-0067).

• pin (optional): boolean

  Only for a command whose env names an Effect secret. true: the input of the Effect names the commit to run against ({ sha }, a full commit id, for example one that a Gate approved). Default: the tip of the Agent's branch when the Effect starts.

  It refuses pin: true on a command that names no Effect secret: command(argv, { pin: true }) names no secret in its env: `pin` chooses the commit a credentialed command runs against in the Sandbox Effector, and a command that names no secret runs in the live Worktree (ADR-0067) — name its secret, command(argv, { env: { NAME: secret("x") }, pin: true }), or drop `pin` .

  When it starts, it refuses an input sha that is not a full commit id: command "<slot>" (pin): its input's sha is not a full commit id.