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 oftimeoutMs,maxTurns,maxModelCallsandmaxCostUsdit enforces itself. A request may ask for more; the outcome lists what it couldn't enforce inunsupportedLimits, andunsupportedLimits(capabilities, limits)works that out ahead of time, so a host can refuse to start instead.resume:none, orsame-workspacewhen a session can be continued by itsreferencein the workspace it started in.usage:exactwhen the session counts its own model calls,reportedwhen it passes on what the provider said,nonewhen it can't say. An outcome'susageis 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 acceptEditsand--allowedToolsset to reading, editing and running commands (allowedToolsandpermissionModechange them). It never skips permissions, and on a CLI that supports it,--permission-prompts nonedenies what nobody is there to approve, which then shows in the outcome. The request'sinstructionsgo 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_DIRand Vertex's) with the request'senvover it, so the host's other credentials aren't passed on; leave publishing credentials out ofenvtoo, 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 aghlogin or a git credential helper. Run it as a user, or in a checkout, that can't publish when that matters. - Limits.
maxTurnsandmaxCostUsdare passed to the CLI, andtimeoutMsis enforced here. It can't count model calls, somaxModelCallsis reported unsupported. - Supervision. The CLI runs in its own process group: a cancellation or a time limit sends it
SIGTERM, thenSIGKILLafterkillGraceMs, 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, orinterruptedwhen the process ended without a result. Permission denials are reported, usage is passed on asreportedwhen the CLI gives it, and a JSON object the session ends its answer with is itsclaim. - Resume. A reference resumes its session with
--resumeonly 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 afailedoutcome, 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.