README

fugu — an OpenBSD-native AI coding agent
========================================

fugu is a personal interactive terminal program for one **Owner**: the human
who runs it and owns every model credential it consumes. It pairs a large-language-
model with local tools (file read/write/edit, shell, search,
brokered web access, and bounded read-only subagents) so a model can
work inside a project under the Owner's direction. It is
privilege-separated in the manner of OpenBSD
base daemons: every security property is enforced by pledge(2),
unveil(2), and process boundaries, never by prompt or convention.

The experimental Claude and Codex subscription adapters are deliberately
single-person. They use the Owner's personal subscription through separate,
unofficial observed HTTP profiles implemented entirely in C. Neither is an
upstream-supported third-party authentication contract; either may stop
working without notice or trigger account enforcement. Do not host fugu,
share it with another human, put it behind a service or API, or use one
subscription token for team traffic. Direct API providers are the supported
route for every shared, service, team, or customer-facing use.

fugu is OpenBSD-only, by design. There are no portability shims; a
build failing on any other system is correct behavior.

Claude Max setup
----------------

Generate a long-lived inference token while logged into the Owner's Claude Pro
or Max account:

	claude setup-token

Paste the printed token into the protected configuration, then select the
personal subscription Provider:

	provider "claude"
	model "claude-sonnet-4-6"
	oauth_token "sk-ant-oat01-..."

The `claude` command is used only to provision the token; fugu neither installs
nor executes Claude Code. At runtime the token exists only in `fugu-api`, which
adds it to a fixed Anthropic TLS request after the process has lost all file,
write, and execution authority. Every model-selected Tool still passes through
fugu's existing allowlist and kernel-confined executors.

The package has no Node.js, Python, Claude Code, or Agent SDK runtime
dependency. The active compatibility profile is `claude-code-2.1.185`; its
snapshot date is 2026-07-16. Its identifying headers and request transforms are
intentionally versioned because they are undocumented and volatile. Token
refresh and replacement are manual.

ChatGPT Codex setup
-------------------

Place one current personal ChatGPT Codex access token directly in the protected
configuration and select the fixed profile model:

	provider "codex"
	model "gpt-5.5"
	oauth_token "<personal ChatGPT Codex access token>"

The `chatgpt-codex-2026-07-17` profile talks only to
`chatgpt.com/backend-api/codex/responses` over TLS and identifies itself as
`fugu`; it does not execute Codex, impersonate the first-party client, follow
credentialed redirects, or fall back to the metered OpenAI Platform API. The
token's bounded account id is derived only inside `fugu-api`. Expiry is checked
locally, and an expired token or HTTP 401/403 requires manual replacement.

This first profile accepts exactly `gpt-5.5` and uses its raw 272,000-token
catalog window, to which Fugu applies its normal Compaction reserve. Because
the observed backend does not use the ordinary output-token request field,
`max_tokens` is a local Fugu policy rather than an exact provider-side limit;
Fugu's independent response-byte and Turn bounds still apply. The adapter adds
no Node.js, Python, SDK, Codex executable, app-server, proxy, daemon, or runtime
dependency.

Lineage
-------

fugu is a clean-room reimplementation, in behavior rather than
source, of the TypeScript agent "pi" by Mario Zechner. This tree is
additionally a clean-room reimplementation of the first fugu: it was
built from the specification in handoff/, not from the prior C
source.

Repository
----------

The canonical repository is:

	ssh://got.fugu.farm/fugu_agent.git

The OpenBSD development checkout is normally `/home/isaac/fugu`.
Clone it with an explicit destination when creating that checkout:

	git clone ssh://got.fugu.farm/fugu_agent.git /home/isaac/fugu

The current port version is 0.3.  The `v0.1` tag preserves the previous
canonical release state.

Building
--------

BSD make on OpenBSD-current or the current release:

	make obj
	make
	make regress	# run every test suite
	make check	# clean-room rebuild + full regress (pre-commit gate)
	make CHECK_JOBS=1 check	# same gate with serial regression suites
	make VERBOSE=1 check	# same gate with the complete live transcript
	make local-port	# stage clean HEAD as a checksummed local port
	make install	# PREFIX defaults to /usr/local

The default `make check` builds with four jobs, runs up to four isolated
regression suites at once, and reports concise phase and per-suite status,
check counts, and total elapsed time. `CHECK_JOBS` selects another positive
bound for both phases; `CHECK_JOBS=1` is the serial diagnostic mode. The gate
fails immediately on a compiler warning, failed test, skipped/disabled proof,
or expected/unexpected failure, cancels active sibling suites, then prints the
complete failed output and a focused rerun command. `VERBOSE=1` keeps the build
and suites serial so it can show live compiler commands and individual
assertions; other nonempty `VERBOSE` values are rejected. `make regress`
retains the ordinary detailed OpenBSD regression output.

A hardened debug build compiles with UBSan in trap mode:

	make FUGU_DEBUG=1 check

Credentialed/public-network and clean-host package checks are explicit release
targets, never part of the hermetic gate:

	make live-check-help
	make live-check
	make live-check-privileged

The required environment and safety prerequisites are documented in
`docs/release-live-checks.md`.

The checks selected by `-fsanitize=undefined` remain enabled except Clang's
function-type probe: that probe reads metadata from executable text and is
incompatible with OpenBSD's execute-only PIE mappings.  Indirect-call types
remain compile-time checked under the normal warning set.

Direct installation expects the system group `_fugu` to exist because
the front binary is installed `root:_fugu` mode 2555.  The OpenBSD port
creates that registered group automatically; a non-root staging install
may override `BINOWN` and `BINGRP` together with `DESTDIR`.

For ordinary local deployment and package-level testing, build and install
through the OpenBSD ports framework rather than running the source-tree
install target as root. `make local-port` creates the committed source archive,
stages `productivity/fugu` under `/usr/ports/mystuff`, and runs the framework's
checksum targets; package construction and installation remain explicit ports
operations. The complete checkout-to-package procedure,
including the local/remote repository topology, SSH agent forwarding,
deployment verification, rollback, and repeat installations during
development, is in
[docs/openbsd-development.md](docs/openbsd-development.md).

Layout
------

	src/fugu/	coordinator and user-facing binary
	src/common/	modules shared across programs
	src/fugu-*/	privilege-separated terminal, API, web, tool, and
			editor workers
	regress/	test suites (bsd.regress.mk); see regress/README
			for the invariant traceability table
	docs/adr/	architecture decision records
	docs/design/	milestone designs and release verification notes
	port/		staged OpenBSD port under productivity/fugu
	handoff/	the normative specification this tree implements

Vendored code
-------------

src/common/jsmn.h is jsmn (MIT, Copyright Serge Zaitsev), a
single-header JSON tokenizer, vendored per the dependency charter:
base has no JSON parser, and a hand-rolled tokenizer would be the
most attacked surface in the program.  Only src/common/json.c
includes it; the rest of the tree uses that module's API, so the
escaping and length discipline live in one place.

License
-------

ISC. Copyright (c) 2026 Isaac <isaac@itm.works>.
src/common/log.c and src/common/log.h are OpenBSD base code
(Copyright Henning Brauer, ISC) carried per the style charter.