Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 62 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,9 @@ Run the server with `go run ./cmd/server --static-dir web/dist`. Configure:

- `PLATFORM_API_URL`, `PLATFORM_PROJECT_ID`, and the platform OIDC identity settings.
- `TRACKER_DATABASE_URL` (or `DATABASE_URL`) for PostgreSQL. `TRACKER_DEV_SEED=1` enables
development seed data on an empty database: 40 issues, three closed one-week sprints
with 18/21/24-point velocities, an active two-week sprint, and a planned sprint.
development seed data on an empty database: 42 issues, three closed one-week sprints
with 18/21/24-point velocities, an active two-week sprint, a planned sprint, and
four agents with live/stalled runs, review requests, answers and mentions.
- `TRACKER_PUBLIC_URL` for the HTTPS browser origin.
- `TRACKER_DIRECTORY_URL` and `TRACKER_DIRECTORY_PUBLIC_URL` for optional Directory links.
- `TRACKER_STATIC_DIR` or `--static-dir` to override `/srv/tracker`.
Expand Down Expand Up @@ -90,11 +91,60 @@ The same 401 expires the edge's session cookies for this host
real sign-in and receives a newly minted token instead of replaying the refused
one. The SSO session and other apps' sessions are not touched.

Scripts and agents use an Access Key instead of a browser session: create a key
in the `tracker` space (`tracker:read`, `tracker:write`), exchange it with
`apth access-keys exchange`, and send the assertion as the bearer. The key acts
as its user with the Viewer role. The rules are in
[`design/API.md`](design/API.md#access-keys-v0111).
Scripts use an Access Key instead of a browser session: create a key in the
`tracker` space (`tracker:read`, `tracker:write`), exchange it with
`apth access-keys exchange`, and send the assertion as the bearer. User-subject
keys act as their user with the Viewer role. External-subject keys act as an
active registered agent whose immutable handle equals the subject.
The rules are in [`design/API.md`](design/API.md#access-keys-v0111).

### Agent protocol (0.1.13)

An Admin registers agents through `POST /api/tracker/v1/agents`, with a handle,
display name, description and accountable person owner. Keys are issued and
revoked by the platform, never by Tracker. Disabling an agent rejects all its
keys, cancels its non-terminal runs and withdraws its open requests. Names and
owners may change; handles cannot. Existing issue attribution is not rewritten.

Agents poll `/inbox` and `/events`. Initialize the event cursor without `after`,
then poll with `after=next`; sequence allocation and the represented write
commit together. Inbox assignments include Backlog and the agent's own live
run, which it should resume. A run has a ten-minute lease; stalled runs cannot
heartbeat or finish. A new start closes the expired run and its requests.

Completion defaults to `review`: successful finish opens a review to the
delegator (else owner); the person's approval completes the issue and updates
the sprint ledger. Admins may set `agentCompletion: "direct"` on the workspace
to allow agents to set completed statuses themselves. Finishing a run alone
never changes issue status. Agents may edit fields as assignee or reporter;
comments, attachments and questions/approvals can involve any issue.

`GET /api/tracker/v1/agent-guide` serves the full protocol as Markdown; its route
inventory uses the handler registration table. The public `openapi.json` includes
all agent shapes and routes. Mentions currently resolve registered `@handle`
agents only, not Directory people. Acknowledge answers by request ID and mentions
by comment ID through `/inbox/ack`; retained mentions preserve acknowledgement
when a comment is edited.

For safe retries, all JSON/non-multipart POST routes accept `Idempotency-Key`
(1–128 characters). Responses, including handler errors, are stored for 24 hours
per actor and key, atomically with successful writes. Replay requires identical
method, URI, content type and body bytes; a different request returns 409.
Authentication failures are not cached. Multipart attachment upload is excluded.
Use a fresh key for each new heartbeat. `PATCH /issues/{id}` accepts
`expectedUpdatedAt` and returns 409 when it no longer matches.

The real-server `hack/smoke.sh` also runs `hack/agents-smoke.sh` (signed assertion
fixture, isolated Postgres schema, no live services). With a disposable database:

```sh
DATABASE_URL='postgres://postgres:pg@127.0.0.1:55443/postgres?sslmode=disable' \
/home/vagrant/.codex/skills/serialize-vm-tests/scripts/serialize-vm-tests -- bash hack/smoke.sh
```

The smoke verifies the collaboration loop, gap-free events for every semantic
write, replay/conflicts, mention acknowledgement, disabling and direct completion.
Both smoke scripts remove their schema, temporary files and processes on exit.

PostgreSQL integration tests are opt-in: they skip when both
`BUILTIN_APPSERVER_TEST_DATABASE_URL` and `BUILDER_CONSOLE_TEST_DATABASE_URL` are unset.
Expand All @@ -119,14 +169,14 @@ a required BuildKit secret, never through build arguments or committed files.

## Catalog and release

The next app release is **0.1.12**, also recorded in `web/package.json`.
The next app release is **0.1.13**, also recorded in `web/package.json`.
`catalog/entry.yaml` carries no committed version: the first tag (`v0.1.0`)
created `versions[]` with `ghcr.io/appthrust/tracker@sha256:<index-digest>`,
stream `0.1`; later tags append at publication time. Do not add a version with
an unbuilt or placeholder image digest. OpenAPI's `info.version` describes the
API schema, not the app release. This repository has no hand-maintained changelog.

After the release prerequisites are available, push the SemVer tag `v0.1.12`.
After the release prerequisites are available, push the SemVer tag `v0.1.13`.
The tag workflow:

1. Performs one multi-platform build on `ubuntu-24.04` for Linux amd64 and arm64,
Expand All @@ -146,8 +196,8 @@ The tag workflow:
Publication commands used by the workflow:

```sh
bun hack/publish-entry.ts submit --version 0.1.12 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts await --version 0.1.12 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts submit --version 0.1.13 --digest sha256:<image-index-digest>
bun hack/publish-entry.ts await --version 0.1.13 --digest sha256:<image-index-digest>
```

Writers are serialized by `tracker-catalog-publish`; the workflow is guarded to
Expand All @@ -168,7 +218,7 @@ After publication, each estate's `AppCatalogSource` syncs the signed catalog.
Install Issues from the Project Marketplace (Directory is an automatic
dependency). Existing `follow` installations on stream `0.1` roll to the new
version; `pinned` installations show `UpdateAvailable` and require an explicit
version update. Confirm the installation is Ready, `/releasez` reports `0.1.12`,
version update. Confirm the installation is Ready, `/releasez` reports `0.1.13`,
the Project lists the `tracker` Access Key space as Ready, and an exchanged key reads `/api/tracker/v1/me`. These are release steps,
not actions performed by a source-only version bump.

Expand Down
165 changes: 165 additions & 0 deletions cmd/server/internal/api/actors.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,165 @@
package api

import (
"github.com/appthrust/tracker/cmd/server/internal/domain"
"github.com/appthrust/tracker/cmd/server/internal/store"
)

type actorProjection struct {
people []*domain.Person
values []struct {
person *domain.Person
value map[string]any
}
}

func responseActors(body any) actorProjection {
var p actorProjection
person := func(person *domain.Person) {
if person != nil {
p.people = append(p.people, person)
if person.Agent != nil {
p.people = append(p.people, &person.Agent.Owner)
}
}
}
run := func(run *domain.Run) {
if run != nil {
person(&run.Agent)
}
}
request := func(r *domain.Request) {
if r != nil {
person(&r.From)
person(r.To)
if r.Answer != nil {
person(&r.Answer.By)
}
}
}
comment := func(c *domain.Comment) {
if c != nil {
person(&c.Author)
for i := range c.Mentions {
person(&c.Mentions[i])
}
}
}
issue := func(i *domain.IssueSummary) {
if i != nil {
person(&i.Reporter)
person(i.Assignee)
person(i.Delegator)
run(i.ActiveRun)
}
}
value := func(raw any) {
m, ok := raw.(map[string]any)
if !ok {
return
}
sub, ok := m["sub"].(string)
if !ok {
return
}
name, _ := m["name"].(string)
who := &domain.Person{Sub: sub, Name: name}
person(who)
p.values = append(p.values, struct {
person *domain.Person
value map[string]any
}{who, m})
}
switch v := body.(type) {
case *meResponse:
person(&v.Person)
case *domain.Agent:
person(&v.Owner)
case items[domain.Agent]:
for i := range v.Items {
person(&v.Items[i].Owner)
}
case *domain.Issue:
issue(&v.IssueSummary)
case *store.Page:
for i := range v.Items {
issue(&v.Items[i])
}
case *domain.Comment:
comment(v)
case *domain.Attachment:
person(&v.Uploader)
case *domain.Run:
run(v)
case items[domain.Run]:
for i := range v.Items {
run(&v.Items[i])
}
case *domain.Request:
request(v)
case items[domain.Request]:
for i := range v.Items {
request(&v.Items[i])
}
case items[domain.InboxItem]:
for i := range v.Items {
item := &v.Items[i]
request(item.Request)
comment(item.Comment)
issue(item.Issue)
}
case *store.EventPage:
for i := range v.Items {
person(&v.Items[i].Actor)
}
case *domain.View:
person(&v.Owner)
case *items[domain.View]:
for i := range v.Items {
person(&v.Items[i].Owner)
}
case *items[domain.TimelineItem]:
for i := range v.Items {
item := &v.Items[i]
comment(item.Comment)
run(item.Run)
request(item.Request)
if item.Activity != nil {
person(&item.Activity.Actor)
if item.Activity.Field == "assignee" || item.Activity.Field == "delegator" {
value(item.Activity.From)
value(item.Activity.To)
}
if item.Activity.Field == "attachment" {
for _, raw := range []any{item.Activity.From, item.Activity.To} {
if attachment, ok := raw.(map[string]any); ok {
value(attachment["uploader"])
}
}
}
}
}
}
return p
}

func (p actorProjection) apply() {
for _, ref := range p.values {
who, m := ref.person, ref.value
m["name"], m["kind"] = who.Name, domain.ActorKind(who.Sub)
if who.Agent != nil {
m["agent"] = who.Agent
}
if who.Email != "" {
m["email"] = who.Email
}
if who.AvatarURL != "" {
m["avatarUrl"] = who.AvatarURL
} else {
delete(m, "avatarUrl")
}
if who.ProfileURL != "" {
m["profileUrl"] = who.ProfileURL
}
}
}
Loading