feat(plugin): expose session instruction entries to plugins - #56550

Why

OpenCode V2 already supports durable, keyed per-session instruction entries (session.instructions.entry.{list,put,remove}), which render as <context key="..."> blocks and announce updates or removals at the next step boundary without queuing inbox work or waking execution. However, SessionDomain on the plugin context omitted instructions, leaving plugins without access to the keyed-context API. As a result, plugins such as GenUI fell back to session.synthetic to persist session reminders, which admits a steered inbox item and triggered an unintended extra model turn.

What Changes

Both Effect and Promise plugins can now manage keyed session instruction entries through ctx.session.instructions.entry:

await ctx.session.instructions.entry.put({
  sessionID,
  key: "deploy-target",
  value: "production",
})

const entries = await ctx.session.instructions.entry.list({ sessionID })

await ctx.session.instructions.entry.remove({
  sessionID,
  key: "deploy-target",
})

Surface Naming Convention

Although the underlying HTTP routes live under /api/experimental/session/:sessionID/instructions/entries, the endpoints belong to the server.session protocol group (session.instructions.entry.{list,put,remove}) and are generated onto SessionApi["instructions"]["entry"]. Following the existing convention in SessionDomain—where session.wait (/api/experimental/session/:sessionID/wait) is picked directly from SessionApi onto ctx.session.wait, while ctx.experimental is reserved for the separate server.experimental HTTP group and experimental.ws.* for plugin-only hook names—instructions is picked directly onto SessionDomain.

Scope

This PR exposes ctx.session.instructions.entry.{list,put,remove} on the Effect and Promise plugin contexts, wires PluginHost to InstructionEntry.Service, and documents the plugin surface. Migrating GenUI or Plan mode onto instruction entries is handled separately. Merge #56689 first so Effect plugin writes also validate instruction entry keys in Core; Promise plugins already decode keys through the protocol schemas.

Verification

taskpolicy -c utility bun --cwd packages/core test test/plugin/session-instructions.test.ts
taskpolicy -c utility bun --cwd packages/plugin typecheck
taskpolicy -c utility bun --cwd packages/core typecheck

• packages/core/test/plugin/session-instructions.test.ts: 2 passed, 26 assertions. Both plugin APIs put, list, and remove entries observed by request-history assembly without enqueuing inbox items; the Effect test also verifies updates. Both preserve Session.NotFoundError and InstructionEntry.ValueTooLargeError. Promise tests verify invalid-key decoding for put and remove, missing-session failures for all three methods, and void write results.
• packages/plugin and packages/core typechecks passed with 0 errors (and the pre-push workspace sdk-docs, oxlint, ast-grep, and turbo typecheck hooks passed across all 34 packages).

Added by the opencode bot (AI-generated).

Public API: adds ctx.session.instructions.entry.{list,put,remove} to the Effect and Promise plugin contexts (backwards compatible)