modelcontext

Documentation

Overview

Package modelcontext owns product-generated context projected into model requests without adding fake user messages to the agent's canonical transcript.

Index

• Constants
• type Attachment
• type AttachmentKind
• type Manager
  • func New(epoch uint64, baseRevision string, baseRendered string, skillRevision string, ...) *Manager
  • func (m *Manager) CancelStagedContextUpdate()
  • func (m *Manager) CancelStagedSkillsUpdate()
  • func (m *Manager) Commit(prepared PreparedStep)
  • func (m *Manager) PrepareStep(input llm.Context) PreparedStep
  • func (m *Manager) ProjectedAttachments() []Attachment
  • func (m *Manager) RestoreActivatedSkills(attachments []Attachment)
  • func (m *Manager) StageActivatedSkill(name, revision, rendered string)
  • func (m *Manager) StageContextUpdate(revision, rendered string)
  • func (m *Manager) StageSkillsUpdate(revision, rendered string)
  • func (m *Manager) StageTaskStatus(rendered string)
  • func (m *Manager) State() State
• type Placement
• type PreparedStep
• type State

Constants

const (
	BaseContext    AttachmentKind = "base"
	SkillListing   AttachmentKind = "skill_listing"
	SkillsUpdate   AttachmentKind = "skills_update"
	ActivatedSkill AttachmentKind = "activated_skill"
	ContextUpdate  AttachmentKind = "context_update"
	TaskStatus     AttachmentKind = "task_status"

	Prefix       Placement = "prefix"
	AfterCurrent Placement = "after-current"
)

Types

type Attachment

type Attachment struct {
	ID        string
	Epoch     uint64
	Kind      AttachmentKind
	Placement Placement
	Path      string
	Revision  string
	Rendered  string
}

Attachment is one hidden, product-generated context block. Rendered is the provider-visible text; the remaining fields are durable product metadata.

type AttachmentKind

type AttachmentKind string

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns one process context epoch. The Base Context and the initial skill listing are projected before canonical conversation messages so the provider prompt-cache prefix stays stable. Refreshes of either resource are projected after canonical messages as self-contained blocks that supersede the prefix, which keeps the cached prefix intact across a change.

func New

func New(
	epoch uint64,
	baseRevision string,
	baseRendered string,
	skillRevision string,
	skillListingRendered string,
) *Manager

New constructs an epoch from independently rendered Base Context and initial skill listing. Empty renderings produce no message or durable attachment.

func (*Manager) CancelStagedContextUpdate

func (m *Manager) CancelStagedContextUpdate()

CancelStagedContextUpdate removes a context update that has not reached a persistence checkpoint.

func (*Manager) CancelStagedSkillsUpdate

func (m *Manager) CancelStagedSkillsUpdate()

CancelStagedSkillsUpdate removes an update that has not reached a persistence checkpoint. The active, already durable update remains projected.

func (*Manager) Commit

func (m *Manager) Commit(prepared PreparedStep)

Commit marks exactly the attachments included in prepared as durable. A staged update becomes the sole active update of its kind only after its checkpoint succeeds.

func (*Manager) PrepareStep

func (m *Manager) PrepareStep(input llm.Context) PreparedStep

PrepareStep creates a detached provider input. Prefix attachments come before canonical messages; the latest context and skills updates come after them. Attachments remain provider-visible on every request but appear in Pending only until their transcript checkpoint succeeds.

func (*Manager) ProjectedAttachments

func (m *Manager) ProjectedAttachments() []Attachment

ProjectedAttachments returns the hidden context blocks that the next provider request would receive, in projection order. The returned values are detached from the Manager's mutable tracking state.

func (*Manager) RestoreActivatedSkills

func (m *Manager) RestoreActivatedSkills(attachments []Attachment)

RestoreActivatedSkills installs durable Skill instructions recovered from the transcript. The first activation of a name wins so a Skill edit cannot change the instructions already governing an in-flight conversation.

func (*Manager) StageActivatedSkill

func (m *Manager) StageActivatedSkill(name, revision, rendered string)

StageActivatedSkill protects one loaded Skill body from transcript compaction. Repeated activation is a no-op; the session keeps the exact first body snapshot until the conversation ends.

func (*Manager) StageContextUpdate

func (m *Manager) StageContextUpdate(revision, rendered string)

StageContextUpdate prepares a complete replacement of the environment and instruction files for the next provider request. It supersedes the Base Context without disturbing the cached request prefix.

func (*Manager) StageSkillsUpdate

func (m *Manager) StageSkillsUpdate(revision, rendered string)

StageSkillsUpdate prepares a complete replacement skill snapshot for the next provider request. It replaces an uncheckpointed staged update. A revision already active or staged is a no-op.

func (*Manager) StageTaskStatus

func (m *Manager) StageTaskStatus(rendered string)

StageTaskStatus prepares the latest bounded background-task snapshot for the next provider request. Each snapshot replaces the previous one entirely.

func (*Manager) State

func (m *Manager) State() State

type Placement

type Placement string

type PreparedStep

type PreparedStep struct {
	Input   llm.Context
	Pending []Attachment
}

PreparedStep is the immutable model input for one request plus any context attachments that must become durable before that request reaches a provider.

type State

type State struct {
	Epoch                 uint64
	HasBase               bool
	BaseRevision          string
	BaseCommitted         bool
	HasSkillListing       bool
	SkillListingRevision  string
	SkillListingCommitted bool
	ActiveSkillsRevision  string
	StagedSkillsRevision  string
	ActiveContextRevision string
	StagedContextRevision string
	ActiveTaskRevision    string
	StagedTaskRevision    string
	ActivatedSkillCount   int
	PendingSkillCount     int
}

State is a detached diagnostic snapshot.