Skip to content

Sessions

A session is one implementation attempt run by something other than June's own model loop: a coding agent such as headless Claude Code, given a workspace and a task and left to change files. june/session is the contract between such a session and whatever hosts it, such as the Ship Agent.

import type { ImplementationSession, SessionOutcome } from "june/session";

declare const session: ImplementationSession;

const outcome: SessionOutcome = await session.run({
  workspace: "/path/to/checkout",
  task: { id: "t1", revision: 1, attempt: 1 },
  prompt: "Keep the selected station when switching views.",
  limits: { timeoutMs: 20 * 60_000, maxTurns: 40 },
  signal: new AbortController().signal,
});

What a session returns is a claim

SessionOutcome.status says how the session ended (completed, failed, limit, canceled or interrupted), not whether the work is right, and summary and claim are the session's own account of what it did. A host decides what happened by reading the workspace: the Ship Agent captures the working tree as a candidate and runs its own checks and review on it, whatever the session said.

Capabilities, limits and usage

A session declares what it can do in capabilities:

  • limits: which of timeoutMs, maxTurns, maxModelCalls and maxCostUsd it enforces itself. A request may ask for more; the outcome lists what it couldn't enforce in unsupportedLimits, and unsupportedLimits(capabilities, limits) works that out ahead of time, so a host can refuse to start instead.
  • resume: none, or same-workspace when a session can be continued by its reference in the workspace it started in.
  • usage: exact when the session counts its own model calls, reported when it passes on what the provider said, none when it can't say. An outcome's usage is absent rather than guessed.

References

SessionReference is a JobRef from june/train: { id, kind, data: { workspace } }, plain JSON to save with the attempt. It names an external session. It is not proof that a process is alive, or that anything the session did was kept: a host reconciles the workspace, not the reference.

Cancellation and events

Aborting signal stops the session and everything it started. onEvent receives bounded progress (started, progress, tool, diagnostic) for a log or a trace.

Claude Code

claudeCode() runs the locally installed Claude Code CLI as a session:

import { claudeCode } from "june/session";

const session = claudeCode({ model: "claude-sonnet-5-5" });
  • How it runs. claude -p <prompt> by argv, in the workspace as its working directory, with --output-format stream-json, --permission-mode acceptEdits and --allowedTools set to reading, editing and running commands (allowedTools and permissionMode change them). It never skips permissions, and on a CLI that supports it, --permission-prompts none denies what nobody is there to approve, which then shows in the outcome. The request's instructions go in with --append-system-prompt. The session's environment is a minimal one (PATH, HOME, the locale, proxies, and the CLI's and its backends' own settings: CLAUDE_CODE_*, ANTHROPIC_*, AWS_*, CLAUDE_CONFIG_DIR and Vertex's) with the request's env over it, so the host's other credentials aren't passed on; leave publishing credentials out of env too, as the Ship Agent does. The environment isn't a sandbox: a session with Bash and your HOME can still use credentials kept on disk, such as a gh login or a git credential helper. Run it as a user, or in a checkout, that can't publish when that matters.
  • Limits. maxTurns and maxCostUsd are passed to the CLI, and timeoutMs is enforced here. It can't count model calls, so maxModelCalls is reported unsupported.
  • Supervision. The CLI runs in its own process group: a cancellation or a time limit sends it SIGTERM, then SIGKILL after killGraceMs, and whatever it started goes with it. Output is bounded (maxOutputBytes), and unreadable lines are reported as diagnostics rather than failing the run.
  • Outcome. The final result record becomes the outcome: completed, failed (an error result or exit), limit (turns, spend or time), canceled, or interrupted when the process ended without a result. Permission denials are reported, usage is passed on as reported when the CLI gives it, and a JSON object the session ends its answer with is its claim.
  • Resume. A reference resumes its session with --resume only in the workspace it was made in; otherwise a new session starts, with a diagnostic saying so.
  • Version. claudeCodeVersion() reads the CLI's version; an unavailable CLI is a failed outcome, not an exception.

To try it against the real CLI, logged in and on the PATH:

JUNE_CLAUDE_SMOKE=1 make test path=packages/june/src/session

That makes one small model call in a temporary directory; without the variable it is skipped.