opencode-plugboard 0.19.0 → 0.20.0

package/src/session/caller.ts

@@ -21,7 +21,7 @@ import { raceAbort } from "../abort.js"
 import { APP_NAME_PATTERN, DEFAULT_APP, appPolicy, type AppPolicy, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CallContext, type ModelCaller, type PlugError, type PlugEvent, type PlugRequest } from "../contract.js"
 import { log, logError } from "../log.js"
-import { checkAppModel } from "../models.js"
+import { checkAppModel, type Persona } from "../models.js"
 import { RequestCollector } from "./events.js"
 import { ensureAppDir, makeTitle, renderTranscript } from "./history.js"
 import { describeError, type SessionPort } from "./host.js"
@@ -44,6 +44,11 @@ export interface SessionCallerDeps {
    * called right before `session.create`. An error ends the request without creating anything.
    */
   readonly ensureBackend?: (app: string, signal: AbortSignal) => Promise<PlugError | undefined>
+  /**
+   * What the requested name stands for beyond a plain model (`personaOf` in src/models.ts): a skill alias adds
+   * the skill's content to the system prompt, an agent runs its own system prompt and OpenCode agent.
+   */
+  readonly persona?: (model: string) => Persona | undefined
 }
 
 /** How long the request guard may outlive the response while the host has not reported the end of the execution. */
@@ -54,6 +59,8 @@ const failure = (status: number, message: string, code: string): PlugEvent => ({
   error: { status, kind: status >= 500 ? "server" : "invalid_request", message, code },
 })
 
+const notFound = (message: string): PlugError => ({ status: 404, kind: "not_found", message, code: "model_not_found", param: "model" })
+
 const countMedia = (request: PlugRequest): number =>
   request.messages.reduce((sum, message) => sum + message.content.filter((part) => part.type === "media").length, 0)
 
@@ -123,7 +130,7 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
       const policy = appPolicy({ apps }, app)
       const outOfScope = checkAppModel(policy, called.model, called.ref)
       if (outOfScope) return yield note({ type: "error", error: outOfScope })
-      const { request, stripped } = applyToolPolicy(called, policy)
+      let { request, stripped } = applyToolPolicy(called, policy)
       const tooMany = checkAppTools(request, app, policy)
       if (tooMany) return yield note({ type: "error", error: tooMany })
       if (stripped) {
@@ -166,23 +173,39 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
         if (unavailable) return yield note({ type: "error", error: unavailable })
         if (context.signal.aborted) return
 
+        // 3b. A persona (see `Persona`). A skill's content leads the system prompt; an agent's prompt replaces the
+        // caller's, and the session runs as that agent. Its permissions are still REQUEST_PERMISSIONS (deny all, then seeds).
+        const persona = deps.persona?.(called.model)
+        let prelude: ReadonlyArray<string> = []
+        if (persona?.kind === "skill") {
+          const content = await port.skill(directory, persona.skill)
+          if (content === undefined) return yield note({ type: "error", error: notFound(`Skill ${persona.skill} is not available`) })
+          prelude = [content]
+        } else if (persona?.kind === "agent") {
+          const agent = await port.agent(directory, persona.agent)
+          if (agent === undefined) return yield note({ type: "error", error: notFound(`Agent ${persona.agent} is not available`) })
+          request = { ...request, system: agent.system ? [agent.system] : [] }
+        }
+        if (context.signal.aborted) return
+
         collector = new RequestCollector({ stopTurn: interrupt, requestID })
         const created = await raceAbort(port.create({
           directory,
           model: { providerID: request.ref.providerID, id: request.ref.id, ...(request.ref.variant ? { variant: request.ref.variant } : {}) },
+          ...(persona?.kind === "agent" ? { agent: persona.agent } : {}),
           title: makeTitle(request),
           metadata: { plugboard: { app, model: request.model, requestID } },
           permissions: REQUEST_PERMISSIONS,
         }), context.signal)
         sessionID = String(created.id)
-        sessions.register({ sessionID, app, requestID, request, collector })
+        sessions.register({ sessionID, app, requestID, request, collector, prelude })
 
         context.signal.addEventListener("abort", onAbort, { once: true })
         if (context.signal.aborted) return onAbort()
 
         // The history id is known from here on: tell the front-end before the first event.
         try {
-          context.onRecord?.(sessionID)
+          context.onRecord?.(sessionID, directory)
         } catch (error) {
           logError("request.on_record_failed", { requestID, app, error: describeError(error) })
         }

package/src/session/context.ts

@@ -123,7 +123,9 @@ function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOpt
     return text("[image unavailable]")
   }
 
-  const system = systemFor(request.system, appPolicy({ apps }, state.app)).map(text)
+  // Order: the skill's content (prelude), then the app's system policy over the caller's (or an agent's) prompt,
+  // then the tool-choice steering below.
+  const system = [...(state.prelude ?? []), ...systemFor(request.system, appPolicy({ apps }, state.app))].map(text)
   // The OpenCode session API has no tool-choice control, so a forced or required tool is steered by instruction.
   const choice = request.toolChoice
   if (choice === "required") system.push(text("You must respond by calling one of the provided tools."))

package/src/session/history.ts

@@ -61,10 +61,16 @@ const CONTROLS_KEEP_LAYOUT = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u20
 /** One display line: whitespace (including line breaks) collapsed to single spaces, then control and bidi characters removed. */
 export const oneLine = (text: string): string => text.replace(/\s+/g, " ").replace(CONTROLS, "").trim()
 
-/** Session title: the first user text, one line, control and bidi characters removed, cut to 60 characters. */
+/**
+ * Session title: the end user as `[user] ` when the caller named one (#57), then the first user text, one
+ * line, control and bidi characters removed. The whole title is cut to 60 characters.
+ */
 export const makeTitle = (request: PlugRequest): string => {
+  const prefix = request.user === undefined ? "" : `[${request.user}] `
   const flat = oneLine(firstUserText(request))
-  return flat.length > TITLE_LENGTH ? flat.slice(0, TITLE_LENGTH - 1) + "…" : flat
+  const room = TITLE_LENGTH - prefix.length
+  const text = flat.length > room ? flat.slice(0, room - 1) + "…" : flat
+  return (prefix + text).trimEnd()
 }
 
 /** Readable transcript stored as the session's prompt; images are listed by attachment number. */

package/src/session/host.ts

@@ -24,12 +24,18 @@ export interface SessionPort {
   create(input: {
     readonly directory: string
     readonly model: { readonly providerID: string; readonly id: string; readonly variant?: string }
+    /** The OpenCode agent the session runs as (option `agents`); absent: the host's default agent. */
+    readonly agent?: string
     readonly title: string
     readonly metadata: { readonly [key: string]: Json }
     readonly permissions: ReadonlyArray<{ action: string; resource: string; effect: "allow" | "deny" }>
   }): Promise<{ id: string }>
   prompt(input: { readonly sessionID: string; readonly text: string; readonly files: ReadonlyArray<{ uri: string; name: string }> }): Promise<unknown>
   interrupt(sessionID: string): Promise<void>
+  /** The content of skill `id` in the Location at `directory`, or undefined when there is none. Briefly cached per directory. */
+  skill(directory: string, id: string): Promise<string | undefined>
+  /** The agent `id` in the Location at `directory` (its `system` prompt may be absent), or undefined when there is none. */
+  agent(directory: string, id: string): Promise<{ readonly system?: string } | undefined>
 }
 
 type HostSession = HostContext["session"]
@@ -45,6 +51,10 @@ const hostSessionID = (id: string): HostSessionID => id as HostSessionID
 type HostCreate = NonNullable<Parameters<HostSession["create"]>[0]>
 type HostModelRef = NonNullable<HostCreate["model"]>
 type HostDirectory = NonNullable<HostCreate["location"]>["directory"]
+type HostAgent = NonNullable<HostCreate["agent"]>
+
+/** How long a directory's skill list is reused: a skill edit is seen within this window (per plugin generation). */
+const SKILL_CACHE_MS = 30_000
 
 /**
  * Branded model ref and directory. Same kind of cast as the session ID: the values are the
@@ -65,17 +75,33 @@ const hostDirectory = (directory: string): HostDirectory => directory as HostDir
  */
 export function createSessionPort(ctx: HostContext): SessionPort {
   const run = <A>(effect: Effect.Effect<A, unknown>): Promise<A> => Effect.runPromise(effect)
+  const skillsByDirectory = new Map<string, { readonly at: number; readonly skills: ReadonlyMap<string, string> }>()
   return {
     create: (input) =>
       run(
         ctx.session.create({
           model: hostModel(input.model),
+          ...(input.agent === undefined ? {} : { agent: input.agent as HostAgent }),
           title: input.title,
           metadata: input.metadata,
           permissions: input.permissions,
           location: { directory: hostDirectory(input.directory) },
         } satisfies HostCreate),
       ).then((created) => ({ id: String(created.id) })),
+    skill: async (directory, id) => {
+      const now = Date.now()
+      let held = skillsByDirectory.get(directory)
+      if (held === undefined || now - held.at >= SKILL_CACHE_MS) {
+        const listed = await run(ctx.skill.list({ location: { directory } }))
+        held = { at: now, skills: new Map(listed.data.map((skill): [string, string] => [skill.id, skill.content])) }
+        skillsByDirectory.set(directory, held)
+      }
+      return held.skills.get(id)
+    },
+    agent: async (directory, id) => {
+      const listed = await run(ctx.agent.list({ location: { directory } }))
+      return listed.data.find((agent) => agent.id === id)
+    },
     prompt: (input) =>
       run(
         ctx.session.prompt({

package/src/session/link.ts

@@ -0,0 +1,33 @@
+/**
+ * Links from a response to the OpenCode session page of its request (#77). The host exposes no UI URL
+ * to a plugin, so option `historyUrl` is a template the operator fills in for how they reach OpenCode:
+ * `{id}` is the session id, `{directory}` the app directory (URL-encoded). With the option set, a
+ * response that carries `x-plugboard-session` also carries `x-plugboard-session-url` with the filled
+ * link, and the request log line gains `session_url=`.
+ *
+ * Pure: no node imports. The routes call `setSessionLink` from their `onRecord` callback, after they
+ * set the session header, so a link is only ever sent for a session that was named.
+ */
+
+export const SESSION_URL_HEADER = "x-plugboard-session-url"
+
+/** The template with `{id}` and `{directory}` filled (both URL-encoded). */
+export function sessionUrl(template: string, recordID: string, directory = ""): string {
+  return template.replaceAll("{id}", encodeURIComponent(recordID)).replaceAll("{directory}", encodeURIComponent(directory))
+}
+
+/**
+ * Sets `x-plugboard-session-url` for one history record and the log field, when a template is set.
+ * Nothing happens without a template, so a route calls this unconditionally.
+ */
+export function setSessionLink(
+  response: { setHeader(name: string, value: string): unknown },
+  info: { sessionUrl?: string },
+  template: string | undefined,
+  recordID: string,
+  directory?: string,
+): void {
+  if (template === undefined) return
+  info.sessionUrl = sessionUrl(template, recordID, directory)
+  response.setHeader(SESSION_URL_HEADER, info.sessionUrl)
+}

package/src/session/state.ts

@@ -32,6 +32,8 @@ export interface RequestState {
   readonly requestID: string
   readonly request: PlugRequest
   readonly collector: EventSink
+  /** System parts placed before the app's and the caller's (a skill's content, option `skill:` alias). Empty or absent for a plain model. */
+  readonly prelude?: ReadonlyArray<string>
 }
 
 export interface Retirement {

package/src/usage.ts

@@ -29,6 +29,7 @@ import { errorMessage, log, logError } from "./log.js"
 import type { Outcome } from "./metrics.js"
 import { parseModelRef } from "./models.js"
 import type { StoragePort } from "./session/host.js"
+import { sanitizeEndUser } from "./user.js"
 
 /** Upper bounds of the latency buckets in ms; one more bucket holds everything above the last. */
 export const LATENCY_BOUNDS_MS: ReadonlyArray<number> = [100, 250, 500, 1_000, 2_500, 5_000, 10_000, 30_000, 60_000, 120_000, 300_000, 600_000]
@@ -123,9 +124,19 @@ export interface UsageCounts<Latency = LatencyHistogram> {
   lastRequestAt?: string
 }
 
+/** One end user's counts (src/user.ts, #57): HTTP requests on the model routes, tokens and cost of the answered calls. */
+export interface UserUsage {
+  requests: number
+  /** Total tokens of those calls (the five kinds summed). */
+  tokens: number
+  costUsd: number
+}
+
 /** One stored day, at `usage/<app>/<date>`. */
 export interface DayRecord extends UsageCounts {
   perModel: Record<string, ModelUsage>
+  /** Per end user (see `USERS_PER_DAY`). Older stored days have none. */
+  users: Record<string, UserUsage>
 }
 
 /** Counters with latency percentiles, as a report carries them. */
@@ -153,6 +164,8 @@ export interface UsageAppReport {
   totals: UsageTotals
   /** Per model, summed over the range. The key is `provider/model`; the variant is not part of it. */
   models: Record<string, ModelUsage>
+  /** Per end user, summed over the range (src/user.ts). Past `USERS_PER_DAY` a day's extra users are under `_other`. With `user`, only that user. */
+  users?: Record<string, UserUsage>
   /** Days with any record in the range, oldest first. */
   days: UsageDay[]
   /** The app's budget state, when option `budgets` sets one for it. Read from the current window, not from the range. */
@@ -179,6 +192,8 @@ export interface UsageQuery {
   readonly to?: string
   /** One app. Absent: every app. */
   readonly app?: string
+  /** One end user (src/user.ts): `users` of each app then lists only that user. Absent: every user. */
+  readonly user?: string
 }
 
 // ---------------------------------------------------------------- pure helpers
@@ -213,6 +228,7 @@ export function emptyDay(): DayRecord {
     limited: 0,
     unpricedRequests: 0,
     perModel: {},
+    users: {},
   }
 }
 
@@ -296,9 +312,22 @@ export function sumDays(parts: ReadonlyArray<DayRecord>): DayRecord {
       total.perModel[model] = { requests: sum.requests + usage.requests, tokens: sum.tokens + usage.tokens, costUsd: sum.costUsd + usage.costUsd }
     }
   }
+  total.users = sumUsers(parts)
   return total
 }
 
+/** Per end user, summed over the day records (`only`: that user alone). */
+function sumUsers(parts: ReadonlyArray<DayRecord>, only?: string): Record<string, UserUsage> {
+  const out: Record<string, UserUsage> = {}
+  for (const part of parts)
+    for (const [user, usage] of Object.entries(part.users ?? {})) {
+      if (only !== undefined && user !== only) continue
+      const sum = out[user] ?? { requests: 0, tokens: 0, costUsd: 0 }
+      out[user] = { requests: sum.requests + usage.requests, tokens: sum.tokens + usage.tokens, costUsd: sum.costUsd + usage.costUsd }
+    }
+  return out
+}
+
 /** A day's counters with latency percentiles, as a report carries them. */
 export function summaryOf(day: DayRecord): UsageTotals {
   return {
@@ -329,6 +358,11 @@ export function fromJson(value: unknown): DayRecord {
     const usage = object(item)
     perModel[model] = { requests: nonNegative(usage.requests), tokens: nonNegative(usage.tokens), costUsd: nonNegative(usage.costUsd) }
   }
+  const users: Record<string, UserUsage> = {}
+  for (const [user, item] of Object.entries(object(raw.users))) {
+    const usage = object(item)
+    users[user] = { requests: nonNegative(usage.requests), tokens: nonNegative(usage.tokens), costUsd: nonNegative(usage.costUsd) }
+  }
   return {
     requests: nonNegative(raw.requests),
     errors: { client: nonNegative(errors.client), server: nonNegative(errors.server), timeout: nonNegative(errors.timeout), disconnected: nonNegative(errors.disconnected) },
@@ -348,6 +382,7 @@ export function fromJson(value: unknown): DayRecord {
     unpricedRequests: nonNegative(raw.unpricedRequests),
     ...(typeof raw.lastRequestAt === "string" ? { lastRequestAt: raw.lastRequestAt } : {}),
     perModel,
+    users,
   }
 }
 
@@ -395,6 +430,8 @@ export interface RequestUsage {
   readonly status: number
   readonly outcome: Outcome
   readonly ms: number
+  /** The end user of the request, when kept (src/user.ts). */
+  readonly user?: string
 }
 
 /** One model call, when it ended. `answered` when its stream finished with an answer; `cache` when the response cache applied. */
@@ -405,6 +442,8 @@ export interface CallUsage {
   readonly answered: boolean
   readonly cache?: "hit" | "miss"
   readonly usage?: PlugUsage
+  /** The end user of the call, when kept (src/user.ts). */
+  readonly user?: string
 }
 
 export interface UsageRecorder {
@@ -444,6 +483,18 @@ async function readDay(storage: StoragePort, key: string): Promise<DayRecord | u
   }
 }
 
+/** Distinct end users a day keeps per app. Later users count under `_other` (the key cannot be an end user: no `_`). */
+export const USERS_PER_DAY = 200
+const OTHER_USER = "_other"
+
+/** The counts of one end user in a day, created on first use; past the cap the request counts under `_other`. */
+function userSlot(day: DayRecord, user: string): UserUsage {
+  if (day.users[user]) return day.users[user]
+  const distinct = Object.keys(day.users).length - (day.users[OTHER_USER] ? 1 : 0)
+  const key = distinct < USERS_PER_DAY ? user : OTHER_USER
+  return (day.users[key] ??= { requests: 0, tokens: 0, costUsd: 0 })
+}
+
 const addTokens = (into: UsageTokens, from: UsageTokens): UsageTokens => ({
   input: into.input + from.input,
   cacheRead: into.cacheRead + from.cacheRead,
@@ -558,6 +609,7 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
         day.latency.sumMs += ms
         day.latency.buckets[bucketIndex(ms)] = (day.latency.buckets[bucketIndex(ms)] ?? 0) + 1
         day.lastRequestAt = new Date(at).toISOString()
+        if (input.user !== undefined) userSlot(day, input.user).requests++
       })
     },
 
@@ -595,6 +647,11 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
           day.tokens = addTokens(day.tokens, tokens)
           day.costUsd += price
           if (unpriced) day.unpricedRequests++
+          if (input.user !== undefined) {
+            const slot = userSlot(day, input.user)
+            slot.tokens += totalTokens(tokens)
+            slot.costUsd += price
+          }
         })
       })().catch((error) => logError("usage.record_failed", { app: input.app, error: errorMessage(error) }))
     },
@@ -614,6 +671,8 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
       const at = now()
       if (input.app !== undefined && !APP_NAME_PATTERN.test(input.app))
         return { status: 400, kind: "invalid_request", code: "invalid_app", param: "app", message: "`app` must be an app name from the keys configuration" }
+      if (input.user !== undefined && sanitizeEndUser(input.user) === undefined)
+        return { status: 400, kind: "invalid_request", code: "invalid_user", param: "user", message: "`user` must be 1 to 64 characters of A-Z, a-z, 0-9, `.`, `_`, `@`, `:` or `-`" }
       const range = resolveRange(input, at)
       if (isPlugError(range)) return range
       const prefix = input.app === undefined ? KEY_PREFIX : keyOf(input.app, "")
@@ -646,7 +705,7 @@ export function createUsageRecorder(deps: UsageRecorderDeps): UsageRecorder {
         const total = sumDays(rows.map((row) => row.day))
         appTotals.push(total)
         const days: UsageDay[] = rows.map((row) => ({ date: row.date, ...summaryOf(row.day), perModel: { ...row.day.perModel } }))
-        apps[app] = { totals: summaryOf(total), models: { ...total.perModel }, days }
+        apps[app] = { totals: summaryOf(total), models: { ...total.perModel }, users: sumUsers(rows.map((row) => row.day), input.user), days }
       }
       return { from: range.from, to: range.to, generatedAt: new Date(at).toISOString(), totals: summaryOf(sumDays(appTotals)), apps }
     },
@@ -704,7 +763,7 @@ export function withUsage(inner: ModelCaller, recorder: UsageRecorder | undefine
           }
         } finally {
           const ref = served ? parseModelRef(served.model) : request.ref
-          recorder.call({ app: context.app, ...(ref ? { ref } : {}), answered, ...(cache ? { cache } : {}), ...(usage ? { usage } : {}) })
+          recorder.call({ app: context.app, ...(ref ? { ref } : {}), answered, ...(cache ? { cache } : {}), ...(usage ? { usage } : {}), ...(request.user === undefined ? {} : { user: request.user }) })
         }
       })()
     },

package/src/user.ts

@@ -0,0 +1,55 @@
+/**
+ * The end user of a request (#57): the caller's own id for one of its users, read from the body
+ * (OpenAI `user`, Anthropic `metadata.user_id`; Gemini has none). It labels a session title, the
+ * request log line and the per-user usage counts. It never names a path: a value is only ever a
+ * string key in a record.
+ *
+ * A value is kept only when it is trimmed and at most 64 characters of `A-Z a-z 0-9 . _ @ : -`.
+ * Anything else is dropped, and the response says so with `x-plugboard-user-dropped: 1`. A blank
+ * value is no user at all (neither kept nor reported).
+ *
+ * Pure: no node imports, so the request decoders (`request.ts` files) can use it (I20).
+ */
+
+export const USER_DROPPED_HEADER = "x-plugboard-user-dropped"
+
+const END_USER = /^[A-Za-z0-9._@:-]{1,64}$/
+
+/** The user id to keep, or undefined when the value is absent, blank or not allowed. */
+export function sanitizeEndUser(raw: unknown): string | undefined {
+  if (typeof raw !== "string") return undefined
+  const trimmed = raw.trim()
+  return END_USER.test(trimmed) ? trimmed : undefined
+}
+
+/** True when the caller sent a value that is not kept. Absent and blank values are not dropped. */
+export function endUserDropped(raw: unknown): boolean {
+  if (raw === undefined || raw === null) return false
+  if (typeof raw === "string" && raw.trim() === "") return false
+  return sanitizeEndUser(raw) === undefined
+}
+
+/** `body.user`, the OpenAI-shaped field. */
+export const bodyUser = (body: unknown): unknown => (typeof body === "object" && body !== null ? (body as { user?: unknown }).user : undefined)
+
+/** `body.metadata.user_id`, the Anthropic-shaped field. */
+export function bodyUserId(body: unknown): unknown {
+  const metadata = typeof body === "object" && body !== null ? (body as { metadata?: unknown }).metadata : undefined
+  return typeof metadata === "object" && metadata !== null ? (metadata as { user_id?: unknown }).user_id : undefined
+}
+
+/** The `user` member of a `PlugRequest` (spread into it), empty when no user is kept. */
+export const userField = (raw: unknown): { user?: string } => {
+  const user = sanitizeEndUser(raw)
+  return user === undefined ? {} : { user }
+}
+
+/**
+ * For a route, after the body is read: sets `x-plugboard-user-dropped` when the value is not kept (the
+ * headers are still open then), and names the kept user in the request log fields.
+ */
+export function noteEndUser(response: { setHeader(name: string, value: string): unknown }, info: { user?: string }, raw: unknown): void {
+  if (endUserDropped(raw)) response.setHeader(USER_DROPPED_HEADER, "1")
+  const user = sanitizeEndUser(raw)
+  if (user !== undefined) info.user = user
+}