Skip to content

V2: decide session context / guidance / instructions terminology #35057

Closed

Description

@kitlangton

Split out of #35017 / #35021. The vocabulary around model-visible ambient context is inconsistent and needs one deliberate decision before the event/API names freeze for beta:

Current overlapping terms

  • SystemContext — the source/reconcile algebra (packages/core/src/system-context)
  • SessionContextEntry — API-provided keyed entries (api/<key> sources, session/context-entry.ts)
  • SessionContextCheckpoint — the durable per-source Applied baseline (session/context-checkpoint.ts)
  • session.next.context.updated — the event narrating drift as System updates (projected as SessionMessage.System)
  • "guidance" — the name V2: add structured guidance/context update summaries #35017 proposed for the event (session.guidance.updated), already used by skill/reference/mcp source modules (skill/guidance.ts etc.)
  • "instructions" — candidate rename for session context entries (also currently SessionInstructions = AGENTS.md loading, and instruction-context.ts = ambient instructions source)

To decide

  1. One name for the model-facing ambient layer: context vs guidance vs instructions — and which existing modules adopt it.
  2. The event name: the V2: event audit tracker #35021 audit renames session.next.context.updated → session.context.updated (mechanical prefix drop only). If a different final name wins, it lands with this issue's follow-through.
  3. Whether the projected message type stays "system".
  4. Whether SessionContextEntry / its /api/session/:id/context surface rename accordingly.

Deferred alongside: #35017's structured changes payload (additive later; parked head-start branch system-context in worktree opencode-system-context).

Activity

  1. self-assigned this
    on Jul 3, 2026
  2. added
    coreAnything pertaining to core functionality of the application (opencode server stuff)
    on Jul 3, 2026
  3. kitlangton commented on Jul 7, 2026

    @kitlangton
    ContributorAuthor

    Resolved by #35583, which chose Instructions for the model-visible ambient layer and renamed the related modules, durable event, entry API, tables, and generated client surfaces. It also documents the distinction between Model Context and Instructions.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

2.0coreAnything pertaining to core functionality of the application (opencode server stuff)

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions