Repository navigation
Aldwin 0.0.2
[0.0.2] - 2026-10-30
Aldwin now works with your files and documents, knows good habits out of the box, and lets you pick a skill with @.
Added
- File tools with diff approval:
list_dir,glob,grep,read_file(read-only);edit_fileandwrite_file, each shown as a folded diff before anything is written to disk. - Document reading:
read_documentconverts PDF (page-range selection withpages=), Word, PowerPoint, Excel (sheet=by name or index), CSV/TSV, and HTML to markdown.download_filesaves a public URL into the workspace after approval. - Planning tools:
todokeeps a checklist for jobs of three or more steps, shown as a live view in the CLI;calculatedoes exact arithmetic and ISO date maths without a shell. - Upgraded memory:
recallnow does ranked search across notes and past conversations; notes can be corrected in place (replace=) or removed (forget, after diff approval) instead of only growing. - Nine packaged default skills (
using-aldwin,files,markdown-notes,documents,making-documents,web-research,memory,terminal,skill-creator) loaded from the install viaimportlib.resources; user skills under~/.aldwin/skills/<name>/override by name. @skill picker: type@to insert a skill into the turn;/skillsandaldwin skillslistname · source · descriptionwithdefault/user/user overridelabels, and/skills show <name>prints a skill's effective body.create_skilltool (diff approval, never session-grantable) to write or update a user skill; the host rebuilds the agent after the turn and showsskills reloaded.aldwin[docs]optional extra (python-docx,openpyxl,reportlab) for themaking-documentsskill to write Office files viarun_command.aldwin[office]optional extra (mammoth,python-pptx,openpyxl) for reading.docx,.pptx, and.xlsx. It is left out of the default install to keep the installed size within budget; without it,read_documentsays how to enable those formats. PDF, CSV/TSV, and HTML always work.- Protocol v2 (
hello(v_min, v_max)negotiation): a v2 door gets Diff-tier approvals with digests; a v1 door still completes a turn with plain y/n approvals, and any Diff-tier call from a v1 door is refused as unapprovable rather than silently downgraded. - New slash commands:
/todo(checklist view),/skills(catalogue andshow),/verbose(toggle file-tool previews),/workspace(inspect or change the workspace root). - One-time What's new panel on the first everyday launch after an upgrade, and three new idle tips pointing at the file, document, and skill-picker workflows.
- PyPI update-available nudge: a muted one-line notice under the welcome card when a newer
aldwinis published, opt out withcheck_for_updates: false.
Changed
- Policy engine: every tool call now goes through a deterministic three-tier approval pipeline (session-grantable, per-call y/n, and Diff approval that can never be session-granted) with a hard floor that denies outright before any tier is even offered.
run_commandruns with a clean, minimal environment. Secrets and API keys are no longer visible to spawned commands by default; extra variable names to pass through are opt-in viarun_command.env_allowinconfig.yaml(secret-looking names are always ignored).run_commandalways asks, with No as the default answer, and refuses outright (no prompt) a short list of privilege-escalation, interactive-program, and bare-REPL commands, and anything naming a blocked path (see Security).- Default skills are no longer copied into
~/.aldwinon first run; upgrades improve packaged skills automatically. - Skills never load code: a
tools:frontmatter key is stripped (flagged astools removedfor user skills).
Security
- Hard floor, fail closed: a fixed set of paths that commonly hold secrets (
.ssh/,.aws/,.gnupg/,.kube/,.docker/config.json,*.pem/*.key/*.p12/*.pfx, SSH private keys,.netrc,.pgpass,.npmrc,.pypirc,.git-credentials,.env*, and~/.aldwin/itself) is never readable, writable, or passed torun_command, with no config override (except read-only~/.aldwin/tmp/**forread_file). This check runs before any approval tier and cannot be session-granted away. - Approvals bound to what was shown: a Diff-tier approval carries a
sha256digest over the tool name, resolved arguments, and the diff text; if the file or digest changed since the diff was shown, Aldwin re-confirms once rather than applying a stale approval. - Every tool result is wrapped as
<untrusted>before it reaches the model, so text read from a file, page, or command output is never treated as an instruction. - Approvals log: every policy decision (approved, denied, blocked, refused) is appended as one redacted JSON line to
~/.aldwin/logs/approvals.jsonl, rotated at 10 MB. - Clean command environment: see
run_commandabove.
Upgrade notes
- Upgrading from
0.0.1runs an automatic, idempotent migration on first launch:config.yamlis backed up toconfig.yaml.bak-0.0.1(once), gainsrun_command.env_allow: []with every existing value and comment preserved,tmp/,state/, andlogs/are created or repaired to0700, andmemory/index.sqliteis built from existing notes and sessions. Nothing in~/.aldwinis deleted. A second launch is a no-op. - A command that used to see
$OPENAI_API_KEY(or any other secret-looking variable) under0.0.1no longer does; add its name torun_command.env_allowif a command genuinely needs a non-secret variable passed through. - An unmodified
0.0.1starter copy of~/.aldwin/skills/using-aldwin/is renamed tousing-aldwin.old-0.0.1/so the new packaged identity block takes effect; an edited copy is kept as a user override. - The one-time What's new panel shows once on the first launch after upgrading, then never again for that version.
Known issues
- A workspace file's contents could, in principle, be read by Aldwin and included in a URL it is asked to fetch. Review
run_commandandweb_fetchapprovals for anything that forwards file contents externally. - A hard link inside the workspace pointing to a file outside it can resolve as if it were inside, letting a file read skip the outside-workspace approval step; its own filename is still checked against the blocked-path list.
run_command's refusal checks parse the command as text, not a real shell grammar; unusual quoting or encoding could in principle evade a check meant to catch it.
Sizes
- Wheel: ~0.23 MB. Installed (no extras): ~116 MB on macOS arm64; confirmed within the 120 MB budget on Linux x86_64 (Python 3.11, 3.12, and 3.13) in CI. With
aldwin[office]: ~131 MB on macOS arm64.