opencode-plugboard 0.19.0 → 0.21.0

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,27 @@ 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>
+  /** Deletes a host session. Used only for a session that was created after its request was aborted (#155). */
+  remove(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>
+  /**
+   * The ids of the OpenCode tools this location offers directly to a model (`codemode: false`), the only
+   * ones a request session can call by name. CodeMode-wrapped tools are reached through `execute`, which a
+   * request session denies, so they are not listed. A tool whose permission name differs from its id is
+   * not listed either: the session's permission rules are written by id.
+   */
+  directTools(): Promise<ReadonlyArray<string>>
 }
 
 type HostSession = HostContext["session"]
@@ -45,6 +60,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 +84,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({
@@ -86,6 +121,11 @@ export function createSessionPort(ctx: HostContext): SessionPort {
       ),
     interrupt: (sessionID) =>
       run(ctx.session.interrupt({ sessionID: hostSessionID(sessionID) } satisfies Parameters<HostSession["interrupt"]>[0])).then(() => undefined),
+    remove: (sessionID) => run(ctx.session.remove({ sessionID: hostSessionID(sessionID) } satisfies Parameters<HostSession["remove"]>[0])).then(() => undefined),
+    directTools: () =>
+      run(ctx.tool.list()).then((tools) =>
+        tools.filter((tool) => tool.options?.codemode === false && (tool.options?.permission ?? tool.id) === tool.id).map((tool) => tool.id),
+      ),
   }
 }
 

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/seeds.ts

@@ -39,6 +39,16 @@ export const REQUEST_PERMISSIONS: ReadonlyArray<{ action: string; resource: stri
   { action: `${SEED_PREFIX}*`, resource: "*", effect: "allow" },
 ]
 
+/**
+ * Session permissions of a request session of an app with option `serverTools`: the same deny-all, then
+ * each listed OpenCode tool id allowed by its exact name (no wildcard). The host takes the last matching
+ * rule (`Permission.evaluate`, findLast), so the later allows win over the deny. An app without
+ * `serverTools` gets exactly `REQUEST_PERMISSIONS`.
+ */
+export function requestPermissions(serverTools: ReadonlyArray<string>): ReadonlyArray<{ action: string; resource: string; effect: "allow" | "deny" }> {
+  return [...REQUEST_PERMISSIONS, ...serverTools.map((tool) => ({ action: tool, resource: "*", effect: "allow" as const }))]
+}
+
 /** The caller tools that get a seed in the model request (`tool_choice` none offers none, a named tool only that one). */
 export function seedToolsFor(request: PlugRequest): ReadonlyArray<PlugTool> {
   const choice = request.toolChoice

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
+}

package/tui.ts

@@ -1,4 +1,5 @@
-// The `./tui` entrypoint. OpenCode resolves a package's TUI entry through `exports["./tui"]`, but a
-// plugin configured by local path is resolved as `<directory>/tui` with no `exports` lookup
-// (packages/plugin/src/host.ts in OpenCode 2.0.26), so the entry lives at the package root.
-export { default } from "./src/tui.tsx"
+// The `./tui` entrypoint for a plugin configured by local path. OpenCode resolves that as
+// `<directory>/tui` with no `exports` lookup (packages/plugin/src/host.ts in OpenCode 2.0.26), so the
+// entry lives at the package root. It re-exports the compiled file (`bun run build:tui`), not
+// src/tui.tsx: a local path under node_modules is never Solid-compiled (see build-tui.ts).
+export { default } from "./dist/tui.js"