Skip to content
jackin'

Stack Integration Contracts

Status: Open — design proposal (Containment track, Agent Orchestrator Research Program)

Problem

Section titled “Problem”

Jackin roles define the agent environment, but real engineering projects still have local stack details that are awkward to encode in every role:

  • read-only toolchain paths or caches that live on the operator machine
  • safe selector environment variables such as JAVA_HOME, GOPATH, or VIRTUAL_ENV
  • generated directories that should be excluded from future snapshots
  • project-specific warnings and command hints

The unsafe version of this feature is “let the repo define whatever mounts and environment it wants.” That would turn project files into policy authority and undermine jackin’s host-protection rules.

The useful version is narrower: integrations are data-only hints that improve ergonomics without widening the trust boundary.

Inspiration

Section titled “Inspiration”

Hazmat’s session integrations are a good shape. They can add read-only directories, snapshot excludes, a small safe env passthrough set, warnings, and command hints. They cannot widen project write scope, bypass credential denies, change network policy, inject arbitrary runtime flags, or reconfigure the agent runtime.

That “can help but cannot weaken containment” rule maps well to jackin.

Proposal

Section titled “Proposal”

Add stack integration contracts as a complement to role repos, not a replacement for them.

An integration can propose:

  • extra read-only mounts for toolchains or caches
  • safe env selectors from a jackin-owned allowlist
  • snapshot exclude globs for generated artifacts
  • warnings shown in the session contract
  • informational command hints for humans and future operator tools

An integration cannot:

  • widen trust compared with the resolved workspace/role policy
  • add write mounts
  • change sandbox backend
  • change network policy
  • expose credentials or credential-shaped env vars
  • convert a denied credential into an env var, file mount, command output, or helper socket
  • request env names matching credential-shaped patterns such as *_TOKEN, *_KEY, *_SECRET, *_PASSWORD, AWS_*, GITHUB_*, GH_*, OPENAI_*, or ANTHROPIC_* unless a jackin-owned credential source explicitly grants them
  • run hooks or shell commands
  • override agent runtime configuration
  • mutate host files

Suggested shape

Section titled “Suggested shape”
[integrations.rust]
detect_files = ["Cargo.toml"]
read_only = ["${env.RUSTUP_HOME}", "${env.CARGO_HOME}"]
safe_env = ["RUSTUP_HOME", "CARGO_HOME", "CARGO_TARGET_DIR"]
snapshot_excludes = ["target/"]
warnings = ["Cargo target caches can be large; prefer isolated target dirs for untrusted repos."]

Repo recommendations should reference existing integration names only:

[workspace.integrations]
recommended = ["rust", "node"]

The repo should not be able to define custom paths inline. If a repo recommendation is accepted, store the approval outside the repo keyed by canonical path plus file hash, so changes prompt again.

Phases

Section titled “Phases”

Phase 1 — Built-in readonly hints

Section titled “Phase 1 — Built-in readonly hints”
  • Define the integration schema and validation rules.
  • Add a small built-in set for common stacks (rust, node, python-uv, go) with read-only mounts and excludes only.
  • Surface active integrations in session contract and explain mode.

Phase 2 — Repo recommendations with approval

Section titled “Phase 2 — Repo recommendations with approval”
  • Let repos recommend existing integration names.
  • Prompt the operator once per canonical repo path plus recommendation hash.
  • Show recommendation source and diff in the contract before launch.

Phase 3 — User-authored integration manifests

Section titled “Phase 3 — User-authored integration manifests”
  • Load user manifests from a jackin-owned config directory.
  • Reject unknown fields, unsafe env names, paths that resolve into sensitive credential zones, and oversized manifests.
  • Add validation commands for contribution-friendly PRs.
  • Add jackin integration validate <path> output that prints accepted fields, rejected fields, resolved paths, sensitive-zone hits, safe-env decisions, and the exact contract diff a reviewer should inspect.

Host-side effects

Section titled “Host-side effects”

Activating an integration may add read-only container mounts and may store an operator approval outside the project tree. It must not repair host permissions, edit shell files, create toolchain directories, or install packages unless a future design adds an explicit host-action approval flow.

Section titled “Related files”

Source materials

Section titled “Source materials”