Documentation
¶
Overview ¶
Package notes stores markdown notes attached to a ticket or to a single session, one JSON file per note.
Notes are what carries knowledge across sessions. When an agent loses the thread and you open a fresh session on the same ticket, the notes are what the new session can read to pick up where the last one left off — written by a person or by the agent itself.
Note bodies are deliberately NOT injected into the system prompt: a ticket accumulates notes for as long as the work lasts, and a growing prompt would charge that cost on every turn forever. Sessions get a one-line pointer ("3 notes, read them with the tickets connector") and the agent reads what it needs through MCP.
One file per note, rather than an array inside ticket.json, because agents edit notes concurrently: two writers touching different notes must not clobber each other.
Layout:
projects/<projectID>/tickets/<ticketID>/notes/<noteID>.json sessions/<sessionID>/notes/<noteID>.json
Index ¶
- Constants
- func Delete(layout config.Layout, sc Scope, id string) error
- func MoveForSession(layout config.Layout, sessionID, fromTicketID, toTicketID string) error
- func ValidAudience(a string) bool
- type AddOptions
- type Count
- type Note
- func Add(layout config.Layout, sc Scope, opt AddOptions) (Note, error)
- func Check(layout config.Layout, sc Scope, id string, done bool) (Note, error)
- func Get(layout config.Layout, sc Scope, id string) (Note, error)
- func List(layout config.Layout, sc Scope) ([]Note, error)
- func ListForAgent(layout config.Layout, sc Scope) ([]Note, error)
- func Update(layout config.Layout, sc Scope, id string, opt UpdateOptions) (Note, error)
- type Scope
- type UpdateOptions
Constants ¶
const ( AudienceAI = "ai" AudienceHuman = "human" AudienceBoth = "both" )
Audience records who a note was WRITTEN FOR. It is a label, not an access rule: the agent reads every audience and sees this field, so it knows whether it is looking at a hint for itself or a handover message for the next person — and can help improve either.
To keep a note away from the agent entirely, hide it (see Note.Hidden).
Variables ¶
This section is empty.
Functions ¶
func MoveForSession ¶
MoveForSession carries a session's notes across when the session changes ticket: attach (from "" to a ticket), move (ticket to ticket), or detach (ticket back to ""). Wired into the ticket package at boot via ticket.SetNotesMover.
Without this a move would silently orphan notes — the scope a session resolves to changes, so everything written before it becomes invisible with no way for a reader to tell it ever existed.
On a DETACH only the notes this session authored travel back; notes written from other sessions on that ticket stay with the ticket, which is whose work they describe. On an ATTACH or a MOVE everything in the session's own scope goes to the destination, because a loose session's notes are all its own by definition.
Each moved note keeps its id and timestamps, and gains a provenance line so a reader can see where it came from — a note whose context silently changed is worse than one that says so.
func ValidAudience ¶
ValidAudience reports whether a is a known audience label.
Types ¶
type AddOptions ¶
type AddOptions struct {
Body string
Checkable bool
Audience string // defaults to both
Author string
// SessionID records which session wrote the note, even when it lands
// in a ticket's scope. Needed so detaching that session can take its
// own notes back without stripping the ticket of everyone else's.
SessionID string
}
AddOptions describes a new note.
type Count ¶
type Count struct {
// Visible counts notes the agent can actually read (hidden excluded),
// so the pointer never advertises something it cannot fetch.
Visible int
// OpenTasks counts checkable notes not yet done.
OpenTasks int
}
Count summarises a scope for the session-start pointer.
type Note ¶
type Note struct {
ID string `json:"id"`
Body string `json:"body"`
// Checkable renders the note as a checkbox. This is not a todo with a
// deadline — it is a note that happens to have a done state, e.g.
// "confirmed the retry fix on staging".
Checkable bool `json:"checkable,omitempty"`
Done bool `json:"done,omitempty"` // only meaningful when Checkable
Audience string `json:"audience"`
// Hidden removes a note from the MCP surface: the agent never receives
// it. The UI keeps showing it, blurred, behind an eye toggle — hiding
// is not deleting, and it can be undone.
Hidden bool `json:"hidden,omitempty"`
Author string `json:"author,omitempty"` // user ID, or "agent"
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
// SourceSessionID records which session wrote this note. Set when the
// note was written from a session (rather than on the ticket itself),
// and it is what lets a DETACH take back only that session's notes and
// leave the rest of the ticket's history in place.
SourceSessionID string `json:"source_session_id,omitempty"`
// MovedAt marks a note that travelled here with its session. A reader
// seeing a note out of its original context should be able to tell.
MovedAt time.Time `json:"moved_at,omitempty"`
}
Note is one markdown note.
func Check ¶
Check sets the done state of a checkable note. Refused on a plain note: silently marking something done that has no done state would leave the caller believing it recorded a fact it did not.
func List ¶
List returns every note in the scope, oldest first — notes read as a running log, so chronological order is the useful one. Hidden notes ARE included: this is the UI's view. Use ListForAgent for the MCP surface.
func ListForAgent ¶
ListForAgent is the MCP view: every audience, minus hidden notes, OLDEST first. The filter lives here rather than in the connector handlers so no future op can forget to apply it.
The order is deliberately the opposite of List's. These are read as a running record of what has been learned, and a record reads forwards — "then we found X, so we tried Y". The panel leads with the newest instead, because a person opening a ticket is looking for what just happened.
type Scope ¶
Scope says where a note lives: a ticket (shared by every session on that ticket) or one loose session. Exactly one of TicketID/SessionID must be set — see Resolve for turning a session into its effective scope.
func Resolve ¶
Resolve returns the notes scope a session reads and writes.
A session attached to a ticket resolves to the TICKET's scope, so every session on that ticket shares one set of notes. That sharing is the whole point: when an agent loses the thread you start a fresh session on the same ticket, and the notes are already there.
A session attached to nothing resolves to its own scope.
The session's TicketID is only a hint. It is confirmed against the ticket's own Sessions list, and a pointer the ticket does not claim is ignored — reading another ticket's notes because of a stale field would be worse than reading none.