feat(core): API-managed per-session context entries (#34941)

packages/core/src/database/migration.gen.ts

@@ -40,5 +40,6 @@ export const migrations = (
     import("./migration/20260622142730_simplify_session_context_epoch"),
     import("./migration/20260622170816_reset_v2_session_state"),
     import("./migration/20260622202450_simplify_session_input"),
+    import("./migration/20260702134641_add_session_context_entry"),
   ])
 ).map((module) => module.default) satisfies DatabaseMigration.Migration[]

packages/core/src/database/migration/20260702134641_add_session_context_entry.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect"
+import type { DatabaseMigration } from "../migration"
+
+export default {
+  id: "20260702134641_add_session_context_entry",
+  up(tx) {
+    return Effect.gen(function* () {
+      yield* tx.run(`
+        CREATE TABLE \`session_context_entry\` (
+          \`session_id\` text NOT NULL,
+          \`key\` text NOT NULL,
+          \`value\` text NOT NULL,
+          \`time_created\` integer NOT NULL,
+          \`time_updated\` integer NOT NULL,
+          CONSTRAINT \`session_context_entry_pk\` PRIMARY KEY(\`session_id\`, \`key\`),
+          CONSTRAINT \`fk_session_context_entry_session_id_session_id_fk\` FOREIGN KEY (\`session_id\`) REFERENCES \`session\`(\`id\`) ON DELETE CASCADE
+        );
+      `)
+    })
+  },
+} satisfies DatabaseMigration.Migration

packages/core/src/database/schema.gen.ts

@@ -154,6 +154,17 @@ export default {
           CONSTRAINT \`fk_session_context_epoch_session_id_session_id_fk\` FOREIGN KEY (\`session_id\`) REFERENCES \`session\`(\`id\`) ON DELETE CASCADE
         );
       `)
+      yield* tx.run(`
+        CREATE TABLE \`session_context_entry\` (
+          \`session_id\` text NOT NULL,
+          \`key\` text NOT NULL,
+          \`value\` text NOT NULL,
+          \`time_created\` integer NOT NULL,
+          \`time_updated\` integer NOT NULL,
+          CONSTRAINT \`session_context_entry_pk\` PRIMARY KEY(\`session_id\`, \`key\`),
+          CONSTRAINT \`fk_session_context_entry_session_id_session_id_fk\` FOREIGN KEY (\`session_id\`) REFERENCES \`session\`(\`id\`) ON DELETE CASCADE
+        );
+      `)
       yield* tx.run(`
         CREATE TABLE \`session_input\` (
           \`id\` text PRIMARY KEY,

packages/core/src/location-services.ts

@@ -38,6 +38,7 @@ import { SkillGuidance } from "./skill/guidance"
 import { Snapshot } from "./snapshot"
 import { InstructionContext } from "./instruction-context"
 import { SystemContextBuiltIns } from "./system-context/builtins"
+import { SessionContextEntry } from "./session/context-entry"
 import { SessionInstructions } from "./session/instructions"
 import { BuiltInTools } from "./tool/builtins"
 import { McpTool } from "./tool/mcp"
@@ -81,6 +82,7 @@ export const locationServices = LayerNode.group([
   SkillGuidance.node,
   ReferenceGuidance.node,
   SessionTodo.node,
+  SessionContextEntry.node,
   QuestionV2.node,
   Generate.node,
   ReadToolFileSystem.node,

packages/core/src/session/context-entry.ts

@@ -0,0 +1,108 @@
+export * as SessionContextEntry from "./context-entry"
+
+import { and, asc, eq } from "drizzle-orm"
+import { Context, Effect, Layer, Schema } from "effect"
+import { SessionContextEntry } from "@opencode-ai/schema/session-context-entry"
+import { Database } from "../database/database"
+import { makeLocationNode } from "../effect/app-node"
+import { SystemContext } from "../system-context/index"
+import { SessionSchema } from "./schema"
+import { SessionContextEntryTable } from "./sql"
+
+export const Key = SessionContextEntry.Key
+export type Key = typeof Key.Type
+export const Info = SessionContextEntry.Info
+export type Info = typeof Info.Type
+
+export interface Interface {
+  readonly list: (sessionID: SessionSchema.ID) => Effect.Effect<ReadonlyArray<Info>>
+  readonly put: (input: {
+    readonly sessionID: SessionSchema.ID
+    readonly key: Key
+    readonly value: Schema.Json
+  }) => Effect.Effect<void>
+  readonly remove: (input: { readonly sessionID: SessionSchema.ID; readonly key: Key }) => Effect.Effect<void>
+  /** Produces one SystemContext source per stored entry, keyed `api/<key>`. */
+  readonly load: (sessionID: SessionSchema.ID) => Effect.Effect<SystemContext.SystemContext>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/v2/SessionContextEntry") {}
+
+const renderValue = (value: Schema.Json) => (typeof value === "string" ? value : JSON.stringify(value, null, 2))
+
+const renderBlock = (key: Key, value: Schema.Json) =>
+  [`<context key="${key}">`, renderValue(value), "</context>"].join("\n")
+
+const source = (entry: Info) =>
+  SystemContext.make({
+    key: SystemContext.Key.make(`api/${entry.key}`),
+    codec: Schema.toCodecJson(Schema.Json),
+    load: Effect.succeed(entry.value),
+    baseline: (value) =>
+      [
+        `An API client attached the following context to this session under "${entry.key}":`,
+        renderBlock(entry.key, value),
+      ].join("\n"),
+    update: (_previous, value) =>
+      [
+        `The attached context "${entry.key}" changed. This value supersedes the previous one:`,
+        renderBlock(entry.key, value),
+      ].join("\n"),
+    removed: () => `The attached context "${entry.key}" was removed. Disregard it.`,
+  })
+
+const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const { db } = yield* Database.Service
+
+    const list = Effect.fn("SessionContextEntry.list")(function* (sessionID: SessionSchema.ID) {
+      const rows = yield* db
+        .select()
+        .from(SessionContextEntryTable)
+        .where(eq(SessionContextEntryTable.session_id, sessionID))
+        .orderBy(asc(SessionContextEntryTable.key))
+        .all()
+        .pipe(Effect.orDie)
+      return rows.map((row) => ({ key: row.key, value: row.value }))
+    })
+
+    const put = Effect.fn("SessionContextEntry.put")(function* (input: {
+      readonly sessionID: SessionSchema.ID
+      readonly key: Key
+      readonly value: Schema.Json
+    }) {
+      yield* db
+        .insert(SessionContextEntryTable)
+        .values({ session_id: input.sessionID, key: input.key, value: input.value })
+        .onConflictDoUpdate({
+          target: [SessionContextEntryTable.session_id, SessionContextEntryTable.key],
+          set: { value: input.value, time_updated: Date.now() },
+        })
+        .run()
+        .pipe(Effect.orDie)
+    })
+
+    const remove = Effect.fn("SessionContextEntry.remove")(function* (input: {
+      readonly sessionID: SessionSchema.ID
+      readonly key: Key
+    }) {
+      yield* db
+        .delete(SessionContextEntryTable)
+        .where(
+          and(eq(SessionContextEntryTable.session_id, input.sessionID), eq(SessionContextEntryTable.key, input.key)),
+        )
+        .run()
+        .pipe(Effect.orDie)
+    })
+
+    const load = Effect.fn("SessionContextEntry.load")(function* (sessionID: SessionSchema.ID) {
+      const entries = yield* list(sessionID)
+      return SystemContext.combine(entries.map(source))
+    })
+
+    return Service.of({ list, put, remove, load })
+  }),
+)
+
+export const node = makeLocationNode({ service: Service, layer, deps: [Database.node] })

packages/core/src/session/runner/llm.ts

@@ -23,6 +23,7 @@ import { InstructionContext } from "../../instruction-context"
 import { SkillGuidance } from "../../skill/guidance"
 import { ReferenceGuidance } from "../../reference/guidance"
 import { McpGuidance } from "../../mcp/guidance"
+import { SessionContextEntry } from "../context-entry"
 import { ToolRegistry } from "../../tool/registry"
 import { ToolOutputStore } from "../../tool-output-store"
 import { SessionContextCheckpoint } from "../context-checkpoint"
@@ -108,6 +109,7 @@ const layer = Layer.effect(
     const skillGuidance = yield* SkillGuidance.Service
     const referenceGuidance = yield* ReferenceGuidance.Service
     const mcpGuidance = yield* McpGuidance.Service
+    const contextEntries = yield* SessionContextEntry.Service
     const snapshots = yield* Snapshot.Service
     const db = (yield* Database.Service).db
     const compaction = yield* SessionCompaction.Service
@@ -171,7 +173,7 @@ const layer = Layer.effect(
     const continueAfterOverflowCompaction = (step: number) =>
       new TurnTransitionError({ _tag: "ContinueAfterOverflowCompaction", step })
 
-    const loadSystemContext = (agent: AgentV2.Selection) =>
+    const loadSystemContext = (agent: AgentV2.Selection, sessionID: SessionSchema.ID) =>
       Effect.all(
         [
           builtins.load(),
@@ -179,6 +181,7 @@ const layer = Layer.effect(
           skillGuidance.load(agent),
           referenceGuidance.load(),
           mcpGuidance.load(agent),
+          contextEntries.load(sessionID),
         ],
         { concurrency: "unbounded" },
       ).pipe(Effect.map(SystemContext.combine))
@@ -195,7 +198,12 @@ const layer = Layer.effect(
       const agent = yield* agents.select(session.agent)
       // Establish what the model knows before admitting what the user said, so
       // a blocked first turn leaves pending inputs untouched.
-      const checkpoint = yield* SessionContextCheckpoint.prepare(db, events, loadSystemContext(agent), session.id)
+      const checkpoint = yield* SessionContextCheckpoint.prepare(
+        db,
+        events,
+        loadSystemContext(agent, session.id),
+        session.id,
+      )
       const toolFibers = yield* FiberSet.make<void, ToolOutputStore.Error>()
       let needsContinuation = false
       let currentStep = step
@@ -437,18 +445,15 @@ const layer = Layer.effect(
             Effect.gen(function* () {
               const failure =
                 Exit.isFailure(exit) && !Cause.hasInterrupts(exit.cause) ? Cause.squash(exit.cause) : undefined
-              yield* events.publish(
-                SessionEvent.ExecutionSettled,
-                {
-                  sessionID: input.sessionID,
-                  timestamp: yield* DateTime.now,
-                  outcome: Exit.isSuccess(exit) ? "success" : Cause.hasInterrupts(exit.cause) ? "interrupted" : "failure",
-                  error:
-                    failure !== undefined
-                      ? { type: "unknown", message: failure instanceof Error ? failure.message : String(failure) }
-                      : undefined,
-                },
-              )
+              yield* events.publish(SessionEvent.ExecutionSettled, {
+                sessionID: input.sessionID,
+                timestamp: yield* DateTime.now,
+                outcome: Exit.isSuccess(exit) ? "success" : Cause.hasInterrupts(exit.cause) ? "interrupted" : "failure",
+                error:
+                  failure !== undefined
+                    ? { type: "unknown", message: failure instanceof Error ? failure.message : String(failure) }
+                    : undefined,
+              })
             }).pipe(
               Effect.catchCause(() => Effect.void),
               Effect.asVoid,
@@ -479,6 +484,7 @@ export const node = makeLocationNode({
     SkillGuidance.node,
     ReferenceGuidance.node,
     McpGuidance.node,
+    SessionContextEntry.node,
     SessionCompaction.node,
     SessionTitle.node,
     Config.node,

packages/core/src/session/sql.ts

@@ -14,6 +14,7 @@ import { Timestamps } from "../database/schema.sql"
 import type { SystemContext } from "../system-context/index"
 import { AgentV2 } from "../agent"
 import type { Revert } from "@opencode-ai/schema/revert"
+import type { Schema } from "effect"
 
 type SessionMessageData = Omit<(typeof SessionMessage.Message)["Encoded"], "type" | "id">
 type V1MessageData = Omit<SessionV1.Info, "id" | "sessionID">
@@ -165,6 +166,20 @@ export const SessionInputTable = sqliteTable(
   ],
 )
 
+export const SessionContextEntryTable = sqliteTable(
+  "session_context_entry",
+  {
+    session_id: text()
+      .$type<SessionSchema.ID>()
+      .notNull()
+      .references(() => SessionTable.id, { onDelete: "cascade" }),
+    key: text().notNull(),
+    value: text({ mode: "json" }).notNull().$type<Schema.Json>(),
+    ...Timestamps,
+  },
+  (table) => [primaryKey({ columns: [table.session_id, table.key] })],
+)
+
 export const SessionContextCheckpointTable = sqliteTable("session_context_epoch", {
   session_id: text()
     .$type<SessionSchema.ID>()