Skip to content

Guaca v0.4.0

Choose a tag to compare

@madebywelch madebywelch released this 16 Nov 03:14
Immutable release. Only release title and notes can be modified.
bddf3f5

What's new

Guaca 0.4.0 is about agents that keep working while you are away and reach you when something needs you. The host now decides what to tell you and delivers it: a banner on the Mac, the For you list, the menu bar, and, with every window closed, a push to your phone through ntfy or to any service that takes a JSON webhook. A permission request nobody answered moves to For you instead of lapsing, answered decisions survive restarts, and a message no agent had started on is delivered again after a crash. Routines have a cap and record the slots they missed, agents are shown what they have already reported, and a group can opt in to an overnight memory tidy with a size limit.

Staying reachable

  • The host decides what interrupts you and offers each item to every open window, so it raises one banner however many windows are open. A click opens the agent's channel or For you. What arrived while no window was connected is shown on reconnect.
  • For you lists finished work under Finished, one line per run from the agent's closing note. The menu bar panel has the same list.
  • Settings → Notifications has three host-wide switches, all on by default: Things that need you, Failures, and Finished work while you are away. Finished work is gathered into one notification when you step away.
  • Send to your phone or another service (Settings → Notifications) pushes the same items to an ntfy topic or as a JSON POST while no Guaca window has had focus for two minutes. A push can include what finished or only say that something did. Failed pushes are retried for up to 24 hours, and Send a test shows what the receiver answered. The host sends the push, so it must be able to reach the address.
  • On a Mac, Guaca now asks macOS for permission to notify, banners appear while Guaca is in front, and Settings → Notifications says whether macOS allows them. A banner macOS refuses is offered to other windows, then pushed if you set an address.
  • A hidden Guaca window does not count as you being there, so banners and pushes still reach you while the app is in the background. A window that is hidden, fully covered or closed to the menu bar keeps taking deliveries however long it has been out of sight.

Work that survives restarts

  • A permission request, question, request to create an agent or settings change that nobody answers in ten minutes is filed in For you instead of expiring. Allowing it there gives that agent one use of that exact action for 24 hours; a Block rule still wins. Browser consent still expires.
  • A restart no longer marks an answered decision as interrupted once its follow-through has finished, and Try again cannot deliver an answer twice.
  • After a crash, a message no agent had started on (queued behind a busy turn, held by a paused agent, or an answer from For you) is delivered again. Work a turn had started is still reported with Try again and never repeated on its own.
  • A conversation resumed after a restart keeps its original limits and counts. Each scheduled routine occurrence fires once and is recovered after a restart, and a webhook retry carrying Idempotency-Key, webhook-id or X-GitHub-Delivery fires once.
  • When a model call fails after a turn made tool calls, those calls stay on the record and the notice says how many happened, so you can check before Try again. An unconfirmed composer send can be retried without arriving twice.

Routines

  • An agent can keep at most 20 routines. An agent's attempt to add past that is refused; changing or canceling one is not, and you can still add routines in the app.
  • A firing that caught up after the host was off says so in the routine's history: "Fired late, missed 2 times while the host was off".
  • The host keeps your time zone, so routines, the 9:00 and 16:00 decision reminders and the date an agent is told follow your clock instead of UTC. Settings → Host shows the host's zone and offers Restart Host when it differs from your Mac's.

Memory

  • Tidy memory overnight, in the group editor, gives each agent that finished something since its last tidy one quiet turn at the hour you pick (3:00 on the host's clock by default) to correct its memory against how its work ended. It cannot message anyone or notify you, and its channel shows the memory diff. The page may not end longer than it started, or 2,000 characters, whichever is larger. Off by default.
  • An agent's prompt lists up to ten of its own closing lines from conversations older than its history window, so it is less likely to report the same thing twice. The 40-message window also counts only messages the agent reads, so an agent that uses tools sees further back.
  • An agent's memory rewrite no longer overwrites an edit you made while it worked, and a conflicting save of yours offers Save or Cancel. Memory is written atomically.
  • The stable part of the system prompt now comes first, with each provider's caching hint, so consecutive turns can be read from the provider's cache.

Permissions and safety

  • Acting in your name never has a standing yes: Always records one allow, and an existing standing grant for it is ignored.
  • A settings change an agent asks for carries only the limits it named, so allowing it later cannot undo your edits made meanwhile.
  • If the browser's sign-in list cannot be read, Guaca asks before a click or a typed line.
  • A call to a tool a plugin did not publish is refused, and MCP tool lists are read across every page.
  • Group exports leave out a custom plugin command's arguments and environment, and strip credentials from URLs.
  • An artifact approval covers only the version you were shown, and a kept page must get your confirmation of a value before sending it.
  • Agents no longer see raw provider errors, and are told when an action may have happened without confirmation. Cleanup of remote computers and browsers keeps any resource whose ownership is uncertain.
  • A browser is admitted by a revocable 30-day session. Signing out ends that session only; rotating the workspace token ends them all.

Fixes

  • Reconnecting, switching hosts and signing out no longer leave stale or half-applied state, and an expired browser session is told apart from an unreachable host.
  • Composer and memory drafts survive navigation, reloads and failed sends.
  • A host update with an unknown outcome says so and can be checked without being resent.
  • Escape closes only the topmost dialog, and stale reads no longer replace newer ones in search, notes, the notebook and side panels.
  • Menu bar faces fit their column, retrying a failed attachment no longer opens its preview, and avatar eyes stay steady at slow frame rates.

Upgrading

Back up your workspace first. The database migrates forward on first start and 0.3.0 refuses to open it afterwards. On this Mac and on a host made by the installer, Back up and update host in Settings → Host copies the whole workspace volume before replacing the host and restores it if the update fails. For Compose, stop the service and copy its stopped data volume before recreating it (never docker compose down -v); for systemd, copy the state directory.

Update the host and the app together. A 0.3.0 app cannot approve artifacts on a 0.4.0 host.

Every browser signed in to a 0.3.0 host must enter the workspace token once more, or open its invitation again: the cookie 0.3.0 issued carried the token itself and is no longer accepted. The desktop app and scripts that send the token in an Authorization header are unaffected.

Settings written by 0.3.0 load unchanged. Notification choices a window kept for itself are not carried over; set the three switches in Settings → Notifications.

Give a host that is not on this Mac your time zone. Compose reads TZ from the shell or the .env beside docker-compose.yml (for example TZ=America/New_York) and defaults to UTC; an installer host reads it from /etc/guaca/guaca.env; systemd uses the machine's zone. A host on this Mac takes the Mac's zone when the update recreates it. Routines keep their next due time and follow the new zone after that.

Removed and changed

  • The desktop's loopback event receiver, which never ran, is removed, and so is the webhook port setting, which was always 0. Events reach a routine only through the host's /events route, whose address the routine's panel shows.
  • The banner for each routine firing and the step count on finished work are gone. A finished run is announced by its closing line.
  • Notification settings belong to the host, not to each window.

Installing

The universal disk image runs on Apple silicon and Intel Macs. On this Mac needs Docker. Remote host needs a reachable host on 0.4.0. The download needs no Node, Rust or source checkout.

Build and verification

  • Source: bddf3f564a11e5d151cffd86cf799bfdd5d88ed6.
  • Host image: ghcr.io/madebywelch/guaca/guacad@sha256:34d714ad53e4291d2980eb2e57a76e1fdd631cab264a3a2d7240517526e682f5, for linux/arm64 and linux/amd64. Both were pulled without registry credentials, and the image test passed (health, token gate, bundled programs, restart persistence).
  • The full gate passed on Linux for this source: 4,170 Rust tests passed with 66 ignored, 2,649 frontend tests and 3 connector tests.
  • On the build Mac the first gate run failed one test, a sign-in test that gives itself one second and lost that race while the whole suite was running. The product's own sign-in timeout is 15 minutes and is not involved. A full rerun passed: 4,174 Rust tests passed with 66 ignored, 2,649 frontend tests and 3 connector tests.
  • The universal app and disk image are signed with Developer ID and notarized by Apple, and the disk image is stapled. Gatekeeper accepts both on the build Mac.
  • On a second Mac that did not build it (macOS 27, Apple silicon), the downloaded disk image matched its checksum and passed Gatekeeper, and a quarantined copy of the app opened with the standard first-open confirmation, reached the host chooser and quit cleanly.
  • Hidden-window delivery was checked on a Mac with a test build of this source: a question and a finished run were each claimed within half a second after six minutes hidden, six minutes fully covered by another window, and sixty minutes hidden.
  • guaca-release.json and its signature are attached, and the signature verifies against release-keys.pub.

Not tested in this release run: a launch on an Intel Mac; On this Mac setup from the release download (the second Mac has no Docker); provider sign-in end to end; a push arriving on a real phone (pushes were checked against a local listener); and macOS refusing a banner on real hardware. The app inside the disk image has no stapled ticket of its own, so the first open after copying it out relies on the check macOS makes online.